Skip to content
TESA Open Knowledge

Gyro, the complementary filter and the level code

Module 3 — Sensor Visualization on HMI · Slides: slides.md · Module overview · Course page

See how the gyro and the accelerometer fail in different ways (drift versus jitter), where a complementary filter and dsp.EMA help, then read the digital-level code pose by pose from sensor warm-up to the zero button.

Objectives

Section titled “Objectives”

By the end of this lesson you will be able to:

  1. Compute the angle drift caused by a gyro bias (e.g. 0.05 deg/s for 60 s gives 3°) and explain how a complementary filter trusts the gyro short-term and the accelerometer long-term
  2. Compute time constants from loop values for dsp.EMA (τ ≈ Ts/α: 0.2 s with α 0.2 gives about 1 s) and for the complementary filter (τ = aΔt/(1−a): a 0.98 gives 9.8 s), and state that a high alpha does opposite things in the two formulas
  3. Explain the reasons behind the digital-level code: no sensors.init() but a warm-up inside try/except, ui.Bar set to min=-90 max=90, filter before subtracting the zero, and ui.poll() on every loop
  4. Run 05_madgwick_and_pedometer.py and point out which units must be converted before feeding dsp.Madgwick and dsp.Pedometer (gyro in rad/s, acceleration in g, fs equal to the real loop rate)

Before you start

Section titled “Before you start”

Following on from lesson 3.1: you must remember that dsp.tilt() returns (roll, pitch), and that all six axes come from a single call to motion(). Review dsp.EMA from lessons 2.7–2.9 (the new value carries weight α, and the rest is memory of the old value), because today it comes back as the level’s filter. Keep lesson 3.3’s practice file s06_digital_level.py open next to you; the “code walk-through” slides go through that file pose by pose.

Concepts

Section titled “Concepts”

A gyro only knows how fast it is spinning right now — it does not know what angle it is at. A structure inside the chip is driven to vibrate constantly along one direction. When the chip rotates, Coriolis force pushes the vibrating mass sideways, at a right angle; a circuit measures that deflection and converts it to deg/s. To get an angle, you must add up ω·Δt yourself — and this is exactly where the trouble begins.

The two sensors fail in different ways. The accelerometer is right in the long run but jittery in the short run, because it measures all the force at once and cannot tell gravity apart from a shaking hand, a fan, or a knock on the table. The gyro is steady and responsive short-term but drifts long-term. On the Eva Kit, lying still, gz still reads 0.03–0.05 deg/s. With a bias of 0.05 deg/s, the accumulated angle is wrong by 3° after 60 seconds and 30° after 600 seconds. This phenomenon is called drift.

A complementary filter joins the strengths of both: θ = a(θ + ωΔt) + (1−a)θ_accel. The first half is a high-pass on the gyro, the second half a low-pass on the accelerometer, and the two halves add up to exactly one. The dividing line is τ = aΔt/(1−a), which at a = 0.98, Δt = 0.2 s gives 9.8 s. But this set of lessons uses only one half: dsp.tilt() (accelerometer alone) followed by dsp.EMA(alpha=0.2), giving τ ≈ Ts/α = 1.0 s — a steady line with no drift at all, since nothing is being integrated, at the price of about one second of lag. And do not trust parameter names by their shape: a high alpha in dsp.EMA means trusting the new value a lot (more responsive, more jittery), while a high a in a complementary filter means trusting the old value plus the gyro a lot (steadier).

The IMU family has fourteen names: sensors.bmi270 has five (temperature() and chip_id() raise OSError on the Eva Kit but work on the Dev Kit), sensors.bmm350 has five that work on both boards, and dsp has four more. If you want full fusion and yaw, there is dsp.Madgwick(beta=, fs=), which must be fed gyro in radians per second (math.radians(gx)), and fs must equal the real loop rate (a 200 ms loop is fs=5.0, not the default of 100). dsp.Pedometer has a default threshold=1.5 in units of g. Neither class has .value(). The compass has bmm350.heading(), which uses atan2(x, y), and dsp.compass(), which uses atan2(y, x), so they return different angles, and dsp.compass() discards mz, so it does not yet compensate for tilt. The field-strength number the board reads (about 1532) has no confirmed conclusion yet, whether it is a constant or a wrongly labelled µT unit — do not record it as fact.

The zero button exists because lying flat almost never gives exactly 0.0° (the table is not perfectly flat, the chip is not mounted perfectly straight, and there is a factory zero-g offset). We remember the angle at the moment you press it and subtract it every round afterward — for example, press at 1.8°, and 4.3° afterward shows as 2.5°. The level code has six moves:

  1. Warm-up — no sensors.init() on either board (the Eva rejects it with OSError; the Dev Kit does not need it). Read motion() once inside try/except and discard it, because the first read after a reset on the Eva can take up to 16 seconds
  2. The screen — ui.Bar(..., min=-90, max=90), because the default 0–100 range would round −30 to 0 and freeze the bar; ui.Scale laid horizontally is a ruler that does not accept .value(); ui.Spinbox needs +/- buttons beside it, because a touch only picks a digit
  3. Read and convert — motion() then dsp.tilt(), wrapped in try/except OSError, because a failed read is a normal event
  4. Filter, then subtract zero — roll_f = ema_roll.update(roll) first, then roll_f - roll_zero
  5. Take events — ui.poll() every round, because about two seconds of silence hides every widget on the page; then compare ev['handle'] against the stored .id(). When zeroing, store the filtered roll_f, never the raw value
  6. Display — int(clamp90(...)) before feeding the bar. The bar and lamp move every round (5 times a second), while the Seg7 is rewritten at most once per second

Worked example

Section titled “Worked example”

These two files sit outside this set of lessons’ passing criteria, but they are the only place you get to try the rest of the IMU family.

  • 05_madgwick_and_pedometer.py — predict before running: there are two step counters, one fed g, the other using the default and fed m/s² directly — which one will start counting on its own while the board sits still? · run it and set the board down still, watching the orange one · explore by comparing the Madgwick column with dsp.tilt() while still and while jerked, and notice that yaw exists only on the Madgwick side · modify by removing the three math.radians() lines temporarily and see how wildly the angle spins (this file loops every 100 ms, so it sets fs=10.0)
  • 04_compass_and_magnetometer.py — compare heading() with dsp.compass(), which are not equal, and that is correct. Press the clear button and rotate the board slowly through a full turn to see the calibration status, then tilt the board and watch the heading from dsp.compass() go wrong immediately
File What this file teaches
examples/04_compass_and_magnetometer.py A compass on the board, and one number nobody has answered yet
examples/05_madgwick_and_pedometer.py dsp’s two remaining IMU classes, and the units that trap them both

The slides for this lesson also refer to files that live in other lessons:

Screens from the BENTO Emulator for this lesson’s examples (click a file name to open the code)

examples/04_compass_and_magnetometer.py running in the BENTO Emulator: A compass on the board, and one number nobody has answered yet
04_compass_and_magnetometer.py A compass on the board, and one number nobody has answered yet
examples/05_madgwick_and_pedometer.py running in the BENTO Emulator: dsp's two remaining IMU classes, and the units that trap them both
05_madgwick_and_pedometer.py dsp's two remaining IMU classes, and the units that trap them both

Check your understanding

Section titled “Check your understanding”

The same questions are in quiz.yaml for automatic marking.

  1. A board lies still and its gyro reads gz of 0.05 deg/s (bias). If ω·Δt is accumulated into an angle continuously, after 10 minutes about how far off will the angle be? (choose one · objective 1)

    • A) 30°
    • B) 3°
    • C) 0.05°
    • D) 0°, because the board is not rotating
    Solution

    A — 0.05 deg/s × 600 s = 30°. A tiny error accumulates every round with nothing pulling it back — this is drift, and it is why the accelerometer must keep pulling it back over the long run.

  2. A loop runs every 200 ms and uses dsp.EMA(alpha=0.2). About how far does the filtered value lag the raw value in tilting? (choose one · objective 2)

    • A) About 1 second
    • B) About 0.04 seconds
    • C) About 9.8 seconds
    • D) No lag at all, because EMA integrates nothing
    Solution

    A — τ ≈ Ts/α = 0.2/0.2 = 1.0 second. 9.8 seconds is the complementary filter’s dividing line at a = 0.98. Not integrating removes drift, but lag remains.

  3. A friend says “set alpha=0.98 and the line will always get steadier.” Which statement is correct? (choose one · objective 2)

    • A) True only for the complementary filter, where a high a means trusting the old value plus the gyro a lot; in dsp.EMA, alpha 0.98 means trusting the new value a lot, so it gets faster and more jittery
    • B) True for both formulas, because the parameter names are the same
    • C) False for both formulas — a high alpha always makes it more jittery
    • D) alpha has no effect on steadiness, only on drift
    Solution

    A — In dsp.EMA, the new value carries weight α; in the complementary filter, the old value plus the gyro carry weight a. The same number gives opposite effects, so check the equation itself and never trust a parameter name.

  4. Which are correct reasons behind the digital-level code? Choose every correct one. (choose all that apply · objective 3)

    • A) ui.Bar must be set to min=-90, max=90, or the default 0–100 range would round −30 degrees to 0 and freeze the bar even though the calculation is correct
    • B) When zeroing, you must store the filtered roll_f, not the raw roll, which might be jittering right at that instant
    • C) sensors.init() must be called before motion() on the Eva Kit, or values cannot be read
    • D) ui.poll() only needs to be called on the round someone actually presses a button
    Solution

    A, B — On the Eva Kit, sensors.init() is rejected with OSError, and the Dev Kit does not need it either. ui.poll() must be called every round, because the CM55 side uses it as a signal the program is still alive; about two seconds of silence hides every widget on the page.

  5. From 05_madgwick_and_pedometer.py, which are unit traps you must handle yourself? Choose every correct one. (choose all that apply · objective 4)

    • A) Madgwick.update() needs gyro in radians per second, but motion() returns degrees per second, so you must call math.radians() yourself
    • B) Pedometer’s default threshold=1.5 is in units of g; feeding it m/s² would make it count steps continuously even while the board sits still
    • C) Madgwick’s fs must equal the real loop rate; a 200 ms loop is fs=5.0
    • D) Madgwick and Pedometer both have .value() to read the result, like the six filters in lessons 2.7–2.9
    Solution

    A, B, C — Forgetting to convert gyro means feeding it a value about 57 times too large, spinning the angle wildly with no error, and 9.81 m/s² crosses the 1.5 threshold before anything even moves. Neither class has .value(); you must store the value .update() returns yourself.

Going further

Section titled “Going further”

Lesson 3.3 is the lab: fill six blanks in s06_digital_level.py following the six moves just walked through, then check against the MVP checkpoint. While testing, lay the board flat, press zero, and tilt slowly — never hold the board in the air and wave it around, because the acceleration from swinging mixes with gravity.

Next lesson: Lesson 3.3 — Hands-on: the digital level

Reflect

Section titled “Reflect”
  • A kitchen scale has the same kind of button as the zero button. What else around you lets the user set its own reference point?
  • If you had to change the loop period from 200 ms to 50 ms, which numbers would you have to rethink?

Review questions

Answer on your own first, then open the answer.

  1. The board lies still and gz reads a 0.05 deg/s bias. If you keep integrating ω·Δt into an angle, how wrong is it after 10 minutes? (Objective 1)

    1. 30°
    2. 3°
    3. 0.05°
    4. 0° เพราะบอร์ดไม่ได้หมุน
    Show answer

    Answer: A. 30°

    0.05 deg/s × 600 s = 30° ความผิดพลาดจิ๋วถูกบวกสะสมทุกรอบโดยไม่มีอะไรดึงกลับ นี่คือ drift และเป็นเหตุผลที่ต้องให้ accelerometer คอยดึงกลับในระยะยาว

  2. The loop runs every 200 ms with dsp.EMA(alpha=0.2). Roughly how far does the filtered value lag the raw one? (Objective 2)

    1. ราว 1 วินาที
    2. ราว 0.04 วินาที
    3. ราว 9.8 วินาที
    4. ไม่มี lag เพราะ EMA ไม่ได้อินทิเกรตอะไร
    Show answer

    Answer: A. ราว 1 วินาที

    τ ≈ Ts/α = 0.2/0.2 = 1.0 วินาที ส่วน 9.8 วินาทีคือเส้นแบ่งของ complementary ที่ a = 0.98 การไม่อินทิเกรตทำให้ไม่มี drift แต่ยังมี lag

  3. A teammate says "setting alpha=0.98 always makes the line smoother". Which is correct? (Objective 2)

    1. จริงเฉพาะ complementary ที่ a สูงแปลว่าเชื่อค่าเดิมกับ gyro มาก ส่วน dsp.EMA ที่ alpha 0.98 แปลว่าเชื่อค่าใหม่มาก จึงไวและสั่นขึ้น
    2. จริงทั้งสองสูตร เพราะชื่อพารามิเตอร์เหมือนกัน
    3. ไม่จริงทั้งสองสูตร alpha สูงทำให้สั่นขึ้นเสมอ
    4. alpha ไม่มีผลกับความนิ่ง มีผลแค่กับ drift
    Show answer

    Answer: A. จริงเฉพาะ complementary ที่ a สูงแปลว่าเชื่อค่าเดิมกับ gyro มาก ส่วน dsp.EMA ที่ alpha 0.98 แปลว่าเชื่อค่าใหม่มาก จึงไวและสั่นขึ้น

    ใน dsp.EMA ค่าใหม่มีน้ำหนัก α ส่วนใน complementary ค่าเดิมบวก gyro มีน้ำหนัก a ตัวเลขเดียวกันจึงให้ผลตรงข้ามกันสุดขั้ว ให้เปิดดูสมการ อย่าเชื่อชื่อพารามิเตอร์

  4. Which are correct reasons behind the digital-level code? Choose all that apply. (Objective 3)

    1. ต้องตั้ง ui.Bar เป็น min=-90, max=90 ไม่งั้นช่วงปริยาย 0–100 จะปัด −30 องศาเป็น 0 แล้วแถบนิ่งสนิททั้งที่โค้ดคำนวณถูก
    2. ตอนกดตั้งศูนย์ต้องเก็บ roll_f ที่กรองแล้ว ไม่ใช่ roll ดิบที่อาจกำลังสั่นอยู่พอดี
    3. ต้องเรียก sensors.init() ก่อน motion() บน Eva Kit ไม่งั้นอ่านค่าไม่ได้
    4. เรียก ui.poll() เฉพาะรอบที่มีคนกดปุ่มก็พอ
    Show answer

    Answer: A. ต้องตั้ง ui.Bar เป็น min=-90, max=90 ไม่งั้นช่วงปริยาย 0–100 จะปัด −30 องศาเป็น 0 แล้วแถบนิ่งสนิททั้งที่โค้ดคำนวณถูก · B. ตอนกดตั้งศูนย์ต้องเก็บ roll_f ที่กรองแล้ว ไม่ใช่ roll ดิบที่อาจกำลังสั่นอยู่พอดี

    บน Eva Kit sensors.init() ถูกปฏิเสธด้วย OSError และบน Dev Kit ก็ไม่จำเป็น ส่วน ui.poll() ต้องเรียกทุกรอบ เพราะฝั่ง CM55 ใช้มันเป็นสัญญาณว่าโปรแกรมยังมีชีวิต เงียบราวสองวินาที widget จะถูกซ่อนทั้งหน้า

  5. From 05_madgwick_and_pedometer.py, which unit traps must you handle yourself? Choose all that apply. (Objective 4)

    1. Madgwick.update() ต้องการ gyro เป็นเรเดียนต่อวินาที แต่ motion() คืนองศาต่อวินาที จึงต้อง math.radians() เอง
    2. Pedometer ค่าตั้งต้น threshold=1.5 เป็นหน่วย g ถ้าป้อน m/s² มันจะนับก้าวขึ้นเรื่อย ๆ ทั้งที่บอร์ดวางนิ่ง
    3. fs ของ Madgwick ต้องเท่าอัตราของลูปจริง ลูป 200 ms คือ fs=5.0
    4. Madgwick กับ Pedometer มี .value() ให้อ่านผลเหมือนตัวกรองหกตัวในบทเรียน 2.7–2.9
    Show answer

    Answer: A. Madgwick.update() ต้องการ gyro เป็นเรเดียนต่อวินาที แต่ motion() คืนองศาต่อวินาที จึงต้อง math.radians() เอง · B. Pedometer ค่าตั้งต้น threshold=1.5 เป็นหน่วย g ถ้าป้อน m/s² มันจะนับก้าวขึ้นเรื่อย ๆ ทั้งที่บอร์ดวางนิ่ง · C. fs ของ Madgwick ต้องเท่าอัตราของลูปจริง ลูป 200 ms คือ fs=5.0

    ลืมแปลง gyro เท่ากับป้อนใหญ่เกินจริงราว 57 เท่า มุมหมุนติ้วโดยไม่มี error และ 9.81 m/s² ข้ามเกณฑ์ 1.5 ตั้งแต่ยังไม่ขยับ ทั้งสองคลาสไม่มี .value() ต้องเก็บค่าที่ .update() คืนมาเอง

Cite this lesson

If you teach from this lesson or reuse it in slides or documents, credit it with the text below. If you changed it, add (adapted) after the title.

"Gyro, the complementary filter and the level code" from TESA Open Knowledge by the Thai Embedded Systems Association (TESA), https://github.com/tesaiot/tesa-qualification-program, licensed under CC BY-NC 4.0

Thai attribution: "gyro ฟิลเตอร์ complementary และโค้ดเครื่องวัดระดับ" จาก TESA Open Knowledge โดยสมาคมสมองกลฝังตัวไทย (Thai Embedded Systems Association: TESA) https://github.com/tesaiot/tesa-qualification-program สัญญาอนุญาต CC BY-NC 4.0

Lesson link: https://tesaiot.github.io/tesa-qualification-program/en/courses/aiot-micropython/m03-sensor-hmi/l02-gyro-fusion/

This lesson adapts the source below; keep its credit too.
https://github.com/Advance-Innovation-Centre-AIC/embedded-systems-for-aiot-developer/blob/a80bbe88a34bcb9bb8d991f42f9252b77cdab079/session-06.html (slides 13–32)

Full guide: how to cite TESA

TESA Open Knowledge · © 2026 สมาคมสมองกลฝังตัวไทย (TESA) · CC BY-NC 4.0

Content is licensed CC BY-NC 4.0. Reuse it non-commercially and credit the Thai Embedded Systems Association (TESA) every time. · How to cite TESA