Arc Gauge

Lab 9: Real Arc Gauge (Roll Angle)

1. โครงสร้างภาพรวมของ Lab

Why? - ทำไมต้องเรียนรู้เรื่องนี้

• Sensor Fusion: รวม Accelerometer + Gyroscope ด้วย Complementary Filter

• Tilt Measurement: วัดการเอียงของบอร์ด (Roll = เอียงซ้าย/ขวา)

• Real Application: ใช้ในหุ่นยนต์ทรงตัว, flight controller, gesture recognition

What? - จะได้เรียนรู้อะไร

1. Complementary Filter: สูตร angle = 0.98*(angle+gyro*dt) + 0.02*accel_angle

2. Tilt API: aic_tilt_init(), aic_tilt_update_from_imu(), aic_tilt_get_roll()

3. Angle to Percentage: แปลง -180°...+180° เป็น 0%...100%

4. Visual Feedback: Arc gauge แสดง Roll angle

How? - จะทำอย่างไร

1. Initialize Tilt Analysis ด้วย aic_tilt_init()

2. Timer callback เรียก aic_tilt_update_from_imu()

3. อ่าน Roll angle และแสดงบน Arc

---

2. หลักการทำงานและ Flowchart

2.1 Why Complementary Filter?

┌─────────────────────────────────────────────────────────────┐
│         SENSOR CHARACTERISTICS                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ACCELEROMETER:                                            │
│   ┌─────────────────────────────────────────┐               │
│   │  + Measures gravity direction           │               │
│   │  + Stable over time (no drift)          │               │
│   │  - Noisy (vibration sensitive)          │               │
│   │  - Slow response                        │               │
│   │  = Good for LOW frequency               │               │
│   └─────────────────────────────────────────┘               │
│                                                             │
│   GYROSCOPE:                                                │
│   ┌─────────────────────────────────────────┐               │
│   │  + Fast response                        │               │
│   │  + Smooth readings                      │               │
│   │  - Drifts over time (integration error) │               │
│   │  = Good for HIGH frequency              │               │
│   └─────────────────────────────────────────┘               │
│                                                             │
│   COMPLEMENTARY FILTER = Best of both!                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2 Complementary Filter Formula

┌─────────────────────────────────────────────────────────────┐
│         COMPLEMENTARY FILTER                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   angle = α × (angle + gyro × dt) + (1-α) × accel_angle     │
│                                                             │
│   where:                                                    │
│     α = 0.98 (trust gyro 98%)                               │
│     dt = time delta (e.g., 0.01 sec at 100Hz)               │
│     gyro = angular velocity (rad/s → deg/s)                 │
│     accel_angle = atan2(ay, az) for Roll                    │
│                 = atan2(ax, az) for Pitch                   │
│                                                             │
│   ┌───────────────────────────────────────────────────────┐ │
│   │   HIGH PASS FILTER        LOW PASS FILTER             │ │
│   │   (Gyro: fast changes)    (Accel: slow/stable)        │ │
│   │                                                       │ │
│   │   0.98 × gyro_angle   +   0.02 × accel_angle          │ │
│   │        ↓                       ↓                      │ │
│   │   Quick response         Drift correction             │ │
│   └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.3 Roll Angle Measurement

┌─────────────────────────────────────────────────────────────┐
│              ROLL ANGLE (Left-Right Tilt)                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Top View of Board:                                        │
│                                                             │
│         Roll = 0°              Roll = +45°                  │
│       (Level)                (Tilt Right)                   │
│                                                             │
│       ┌─────────┐              ┌─────────┐                  │
│       │  PSOC   │              │  PSOC  ╲│                  │
│       │  EDGE   │              │  EDGE   ╲                  │
│       │  E84    │              │  E84    │                  │
│       └─────────┘              └─────────╱                  │
│                                         ╱                   │
│                                                             │
│   Formula: roll = atan2(ay, az) × 180/π                     │
│                                                             │
│   Range:                                                    │
│     -180° (tilt far left) to +180° (tilt far right)          │
│     0° = level                                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.4 UI Layout

┌─────────────────────────────────────────────────────────────┐
│       "Week 4 Ex9: Arc Gauge (Roll Angle)"                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                    ╭━━━━━━━━━━━━━╮                          │
│                  ╱                 ╲                        │
│                ╱                     ╲                      │
│               │         50%           │  ← Value Label      │
│               │                       │                     │
│                ╲                     ╱                      │
│                  ╲                 ╱                        │
│                    ╰━━━━━━━━━━━━━╯                          │
│                                                             │
│                   Roll: 0.0 deg  ← Raw Angle Label          │
│                                                             │
│     "[Part II] Complementary Filter (Accel + Gyro)"         │
│     "Tilt board left/right to change gauge"                 │
└─────────────────────────────────────────────────────────────┘

---

3. ฟังก์ชันสำคัญ

3.1 Tilt API Functions

Function	Description
aic_tilt_init(NULL)	Initialize tilt analysis with defaults
aic_tilt_update_from_imu()	Update tilt from sensor data
aic_tilt_get_roll()	Get roll angle (-180° to +180°)
aic_tilt_get_pitch()	Get pitch angle (-90° to +90°)
aic_tilt_get_roll_percent()	Get roll as 0-100%
aic_tilt_get_pitch_percent()	Get pitch as 0-100%

3.2 Angle to Percentage Mapping

/* Roll: -180° to +180° → 0% to 100% */
float roll = -90.0f;  /* Example: -90° */
uint8_t pct = (uint8_t)((roll + 180.0f) * (100.0f / 360.0f));  /* = 25% */

/* Or use built-in API */
uint8_t pct = aic_tilt_get_roll_percent();

---

4. Code Example

4.1 Timer Callback

static void ex9_timer_cb(lv_timer_t * timer)
{
    (void)timer;

    /* Update tilt estimation from IMU */
    if(!aic_tilt_update_from_imu()) {
        return;  /* IMU not ready */
    }

    /* Get roll angle and percentage */
    float roll = aic_tilt_get_roll();        /* -180 to +180 degrees */
    uint8_t pct = aic_tilt_get_roll_percent();  /* 0 to 100% */

    /* Update Arc */
    lv_arc_set_value(ex9_arc, pct);
    lv_label_set_text_fmt(ex9_value_label, "%d%%", (int)pct);
    lv_label_set_text_fmt(ex9_raw_label, "Roll: %.1f deg", (double)roll);
}

4.2 Main Function

void week4_ex9_real_arc_gauge(void)
{
    /* ===== HARDWARE INITIALIZATION ===== */
    aic_sensors_init();
    aic_tilt_init(NULL);  /* Initialize with default config */

    /* ===== UI (Same as Part I Ex2) ===== */

    /* Background */
    lv_obj_set_style_bg_color(lv_screen_active(),
                              lv_color_hex(0x0f0f23), LV_PART_MAIN);

    /* Title */
    lv_obj_t * title = lv_label_create(lv_screen_active());
    lv_label_set_text(title, "Week 4 Ex9: Arc Gauge (Roll Angle)");
    lv_obj_set_style_text_color(title, lv_color_hex(0xFFFFFF), 0);
    lv_obj_align(title, LV_ALIGN_TOP_MID, 0, 10);

    /* Create Arc */
    ex9_arc = lv_arc_create(lv_screen_active());
    lv_obj_set_size(ex9_arc, 200, 200);
    lv_arc_set_rotation(ex9_arc, 135);
    lv_arc_set_bg_angles(ex9_arc, 0, 270);
    lv_arc_set_range(ex9_arc, 0, 100);
    lv_arc_set_value(ex9_arc, 50);
    lv_obj_center(ex9_arc);

    /* Style */
    lv_obj_set_style_arc_width(ex9_arc, 20, LV_PART_MAIN);
    lv_obj_set_style_arc_width(ex9_arc, 20, LV_PART_INDICATOR);
    lv_obj_set_style_arc_color(ex9_arc,
                               lv_palette_main(LV_PALETTE_CYAN),
                               LV_PART_INDICATOR);

    /* Remove knob for read-only */
    lv_obj_remove_style(ex9_arc, NULL, LV_PART_KNOB);
    lv_obj_remove_flag(ex9_arc, LV_OBJ_FLAG_CLICKABLE);

    /* Value label in center */
    ex9_value_label = lv_label_create(lv_screen_active());
    lv_label_set_text(ex9_value_label, "50%");
    lv_obj_set_style_text_color(ex9_value_label, lv_color_hex(0xFFFFFF), 0);
    lv_obj_set_style_text_font(ex9_value_label, &lv_font_montserrat_24, 0);
    lv_obj_center(ex9_value_label);

    /* Roll angle label */
    ex9_raw_label = lv_label_create(lv_screen_active());
    lv_label_set_text(ex9_raw_label, "Roll: 0.0 deg");
    lv_obj_set_style_text_color(ex9_raw_label, lv_color_hex(0x00FF00), 0);
    lv_obj_align(ex9_raw_label, LV_ALIGN_CENTER, 0, 130);

    /* Timer */
    ex9_timer = lv_timer_create(ex9_timer_cb, 100, NULL);
}

---

5. องค์ความรู้และเทคนิค

5.1 Filter Alpha Value

/* Alpha controls filter response:
 *
 * α = 0.98 (default)
 *   - 98% trust gyro (fast response)
 *   - 2% trust accelerometer (drift correction)
 *
 * Higher α (0.99):
 *   - Smoother output
 *   - Slower to correct drift
 *
 * Lower α (0.90):
 *   - More responsive to accel
 *   - More noise in output
 */

aic_tilt_config_t config = {
    .alpha = 0.98f,     /* Filter coefficient */
    .sample_rate = 100  /* Hz */
};
aic_tilt_init(&config);

5.2 Understanding Roll vs Pitch

┌─────────────────────────────────────────────────────────────┐
│   ROLL (X-axis rotation)     PITCH (Y-axis rotation)        │
│                                                             │
│        ↑ Z                        ↑ Z                       │
│        │                          │                         │
│   ╔════╪════╗               ╔═════╪═════╗                   │
│   ║    │    ║ → Y           ║     │     ║ → X               │
│   ║  BOARD  ║               ║   BOARD   ║                   │
│   ╚═════════╝               ╚═══════════╝                   │
│        │                          │                         │
│        ▼ X                        ▼ Y                       │
│                                                             │
│   Tilt left/right              Tilt forward/backward        │
│   roll = atan2(ay, az)         pitch = atan2(ax, az)        │
│   -180° to +180°               -90° to +90°                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

5.3 Why Read-Only Arc?

/* For tilt display, we want read-only gauge:
 * 1. Remove knob - no visual clutter
 * 2. Disable click - user can't accidentally change value
 */

/* Remove knob */
lv_obj_remove_style(arc, NULL, LV_PART_KNOB);

/* Disable interaction */
lv_obj_remove_flag(arc, LV_OBJ_FLAG_CLICKABLE);

---

6. แบบฝึกหัด

Exercise 1: Color by Tilt

เปลี่ยนสี Arc ตาม Roll angle:

• Green: -30° to +30° (level)

• Yellow: ±30° to ±60° (tilting)

• Red: > ±60° (extreme tilt)

Exercise 2: Dual Arc (Roll + Pitch)

แสดง Arc 2 อันสำหรับ Roll และ Pitch พร้อมกัน

---

7. References

• Complementary Filter Explained

• LVGL Arc

• BMI270 IMU Datasheet

---

Previous Lab: Lab 8: Real Sensor Dashboard Next Lab: Lab 10: Real Scale Gauge