Scale Gauge

Lab 10: Real Scale Gauge (Pitch Angle)

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

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

• Scale Gauge: การใช้ Scale widget กับ needle line

• Pitch Measurement: วัดการเอียงหน้า/หลัง (Forward/Backward)

• Visual Needle: เข็มชี้ตำแหน่งค่าปัจจุบัน

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

1. Scale Widget: สร้าง round gauge พร้อม tick marks

2. Needle Line: ใช้ lv_scale_set_line_needle_value()

3. Section Styling: แบ่งโซนสีต่างๆบน scale

4. Pitch Angle: การคำนวณ pitch จาก accelerometer

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

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

2. สร้าง Scale gauge พร้อม sections และ needle

3. Timer callback อัพเดท needle position จาก pitch angle

---

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

2.1 Pitch Angle Measurement

┌─────────────────────────────────────────────────────────────┐
│              PITCH ANGLE (Forward-Backward Tilt)            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Side View of Board:                                       │
│                                                             │
│       Pitch = 0°            Pitch = +45°                    │
│       (Level)              (Tilt Forward)                   │
│                                                             │
│       ─────────              ╱────────                      │
│       │ PSOC  │            ╱  PSOC  │                       │
│       │ EDGE  │          ╱    EDGE  │                       │
│       ─────────        ╱──────────                          │
│                                                             │
│   Formula: pitch = atan2(ax, az) × 180/π                    │
│                                                             │
│   Range:                                                    │
│     -90° (tilt backward) to +90° (tilt forward)             │
│     0° = level                                              │
│                                                             │
│   Note: Pitch range is smaller than Roll because            │
│         at ±90° the Z-axis becomes horizontal               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2 Scale Widget Structure

┌─────────────────────────────────────────────────────────────┐
│                 SCALE WIDGET STRUCTURE                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                      LV_PART_MAIN                           │
│                   (Arc background)                          │
│                         ╱╲                                  │
│                        ╱  ╲                                 │
│                       ╱    ╲                                │
│               100    ╱      ╲    0                          │
│                ┃    │        │    ┃   LV_PART_INDICATOR     │
│             75 ┃    │   50   │    ┃ 25  (Major ticks)       │
│                ┃    │   ▲    │    ┃                         │
│                 ╲   │ NEEDLE │   ╱    LV_PART_ITEMS         │
│                  ╲  │        │  ╱      (Minor ticks)        │
│                   ╲ │        │ ╱                            │
│                    ╲│        │╱                             │
│                                                             │
│   Sections:                                                 │
│     Blue: 0-75 (Normal zone)                                │
│     Red: 75-100 (High alert zone)                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.3 UI Layout

┌─────────────────────────────────────────────────────────────┐
│       "Week 4 Ex10: Scale Gauge (Pitch Angle)"              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                   100    75                                 │
│                    ╲     │     ╱ 25                         │
│                     ╲    │    ╱                             │
│                      ╲   │50 ╱                              │
│                       ╲  │  ╱                               │
│                        ╲ ▲ ╱      ← Needle (orange)         │
│                         ─┴─                                 │
│                          0                                  │
│                                                             │
│                        "50"  ← Value Label                  │
│                                                             │
│                 Pitch: 0.0 deg ← Raw Angle Label            │
│                                                             │
│     "[Part II] Complementary Filter (Accel + Gyro)"         │
│     "Tilt board forward/backward to move the needle"        │
└─────────────────────────────────────────────────────────────┘

---

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

3.1 Scale Functions

Function	Description
lv_scale_create(parent)	สร้าง scale widget
lv_scale_set_mode(scale, LV_SCALE_MODE_ROUND_OUTER)	โหมด gauge กลม
lv_scale_set_range(scale, min, max)	กำหนด value range
lv_scale_set_total_tick_count(scale, count)	จำนวน tick ทั้งหมด
lv_scale_set_major_tick_every(scale, n)	tick ใหญ่ทุก n อัน
lv_scale_add_section(scale)	เพิ่ม colored section

3.2 Needle Functions

Function	Description
lv_line_create(scale)	สร้าง line ใน scale
lv_scale_set_line_needle_value(scale, needle, len, val)	ตั้งค่า needle

3.3 Pitch API

Function	Description
aic_tilt_get_pitch()	Get pitch (-90° to +90°)
aic_tilt_get_pitch_percent()	Get pitch as 0-100%

---

4. Code Example

4.1 Timer Callback

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

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

    /* Get pitch angle and percentage */
    float pitch = aic_tilt_get_pitch();       /* -90 to +90 degrees */
    uint8_t pct = aic_tilt_get_pitch_percent();  /* 0 to 100% */

    /* Update labels */
    lv_label_set_text_fmt(ex10_value_label, "%d", (int)pct);
    lv_label_set_text_fmt(ex10_raw_label, "Pitch: %.1f deg", (double)pitch);

    /* Update needle position */
    lv_scale_set_line_needle_value(ex10_scale, ex10_needle_line,
                                    ex10_needle_length, pct);
}

4.2 Create Scale with Sections

void create_scale_gauge(void)
{
    /* Create Scale */
    ex10_scale = lv_scale_create(lv_screen_active());
    lv_obj_set_size(ex10_scale, 200, 200);
    lv_scale_set_label_show(ex10_scale, true);
    lv_scale_set_mode(ex10_scale, LV_SCALE_MODE_ROUND_OUTER);
    lv_obj_align(ex10_scale, LV_ALIGN_CENTER, 0, 0);

    /* Range and ticks */
    lv_scale_set_total_tick_count(ex10_scale, 21);    /* 0, 5, 10...100 */
    lv_scale_set_major_tick_every(ex10_scale, 5);     /* Major at 0,25,50,75,100 */
    lv_scale_set_range(ex10_scale, 0, 100);

    /* Custom labels */
    static const char * labels[] = {"0", "25", "50", "75", "100", NULL};
    lv_scale_set_text_src(ex10_scale, labels);

    /* Tick length styling */
    lv_obj_set_style_length(ex10_scale, 5, LV_PART_ITEMS);      /* Minor */
    lv_obj_set_style_length(ex10_scale, 10, LV_PART_INDICATOR); /* Major */

    /*=========================================================
     * Main Style (Blue default)
     *=========================================================*/
    static lv_style_t main_style;
    lv_style_init(&main_style);
    lv_style_set_arc_color(&main_style, lv_palette_darken(LV_PALETTE_BLUE, 3));
    lv_style_set_arc_width(&main_style, 3);
    lv_obj_add_style(ex10_scale, &main_style, LV_PART_MAIN);

    /*=========================================================
     * High Section (75-100) - Red
     *=========================================================*/
    lv_scale_section_t * high_section = lv_scale_add_section(ex10_scale);
    lv_scale_section_set_range(high_section, 75, 100);

    static lv_style_t high_main_style;
    lv_style_init(&high_main_style);
    lv_style_set_arc_color(&high_main_style, lv_palette_main(LV_PALETTE_RED));
    lv_style_set_arc_width(&high_main_style, 3);
    lv_scale_section_set_style(high_section, LV_PART_MAIN, &high_main_style);

    static lv_style_t high_indicator_style;
    lv_style_init(&high_indicator_style);
    lv_style_set_line_color(&high_indicator_style,
                            lv_palette_darken(LV_PALETTE_RED, 3));
    lv_style_set_text_color(&high_indicator_style,
                            lv_palette_darken(LV_PALETTE_RED, 3));
    lv_scale_section_set_style(high_section, LV_PART_INDICATOR,
                               &high_indicator_style);
}

4.3 Create Needle

void create_needle(void)
{
    /* Create line inside scale */
    ex10_needle_line = lv_line_create(ex10_scale);

    /* Needle style */
    static lv_style_t needle_style;
    lv_style_init(&needle_style);
    lv_style_set_line_width(&needle_style, 2);
    lv_style_set_line_color(&needle_style, lv_palette_main(LV_PALETTE_ORANGE));
    lv_style_set_line_rounded(&needle_style, true);
    lv_obj_add_style(ex10_needle_line, &needle_style, 0);

    /* Set initial position */
    ex10_needle_length = 85;  /* Length from center to near ticks */
    lv_scale_set_line_needle_value(ex10_scale, ex10_needle_line,
                                    ex10_needle_length, 50);
}

4.4 Main Function

void week4_ex10_real_scale_gauge(void)
{
    /* ===== HARDWARE INITIALIZATION ===== */
    aic_sensors_init();
    aic_tilt_init(NULL);

    /* ===== BACKGROUND ===== */
    lv_obj_set_style_bg_color(lv_screen_active(),
                              lv_color_hex(0x1a1a2e), LV_PART_MAIN);

    /* ===== TITLE ===== */
    lv_obj_t * title = lv_label_create(lv_screen_active());
    lv_label_set_text(title, "Week 4 Ex10: Scale Gauge (Pitch Angle)");
    lv_obj_set_style_text_color(title, lv_color_hex(0xFFFFFF), 0);
    lv_obj_align(title, LV_ALIGN_TOP_MID, 0, 10);

    /* ===== CREATE SCALE AND NEEDLE ===== */
    create_scale_gauge();
    create_needle();

    /* ===== VALUE LABELS ===== */
    ex10_value_label = lv_label_create(lv_screen_active());
    lv_label_set_text(ex10_value_label, "50");
    lv_obj_set_style_text_color(ex10_value_label, lv_color_hex(0xFFFFFF), 0);
    lv_obj_set_style_text_font(ex10_value_label, &lv_font_montserrat_24, 0);
    lv_obj_align(ex10_value_label, LV_ALIGN_CENTER, 0, 0);

    ex10_raw_label = lv_label_create(lv_screen_active());
    lv_label_set_text(ex10_raw_label, "Pitch: 0.0 deg");
    lv_obj_set_style_text_color(ex10_raw_label, lv_color_hex(0x00FF00), 0);
    lv_obj_align(ex10_raw_label, LV_ALIGN_CENTER, 0, 120);

    /* ===== TIMER ===== */
    ex10_timer = lv_timer_create(ex10_timer_cb, 100, NULL);
}

---

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

5.1 Scale Modes

/* LV_SCALE_MODE_HORIZONTAL_TOP/BOTTOM */
/* Linear scale (like ruler) */

/* LV_SCALE_MODE_VERTICAL_LEFT/RIGHT */
/* Vertical scale */

/* LV_SCALE_MODE_ROUND_INNER */
/* Round gauge with ticks inside */

/* LV_SCALE_MODE_ROUND_OUTER */
/* Round gauge with ticks outside (most common) */

5.2 Needle Length Calculation

/* Needle length should reach near the ticks but not overlap labels
 *
 * Scale size: 200x200
 * Radius: 100
 * Tick length: 10 (major)
 * Label offset: ~15
 *
 * Needle length = 100 - 10 - 5 = 85 (safe margin)
 */
int32_t needle_length = 85;

5.3 Section Styling

/* Each section can have independent styles for:
 * - LV_PART_MAIN: Arc line
 * - LV_PART_INDICATOR: Major ticks + labels
 * - LV_PART_ITEMS: Minor ticks
 */

/* Example: Red warning zone */
lv_scale_section_t * section = lv_scale_add_section(scale);
lv_scale_section_set_range(section, 75, 100);
lv_scale_section_set_style(section, LV_PART_MAIN, &red_arc_style);
lv_scale_section_set_style(section, LV_PART_INDICATOR, &red_tick_style);

---

6. แบบฝึกหัด

Exercise 1: Triple Zone Scale

สร้าง Scale 3 zones:

• Green: 0-33% (Safe)

• Yellow: 34-66% (Caution)

• Red: 67-100% (Danger)

Exercise 2: Needle Color Change

เปลี่ยนสี needle ตามค่า:

• Blue: Normal zone

• Red: High alert zone

---

7. References

• LVGL Scale

• lv_example_scale_4

• Complementary Filter Tutorial

---

Previous Lab: Lab 9: Real Arc Gauge Next Lab: Lab 11: Real Chart Dashboard