C in ModusToolBox (MTB)

1. ภาพรวมของ LVGL

LVGL คืออะไร?

LVGL (Light and Versatile Graphics Library) เป็น Open-source Graphics Library สำหรับระบบ Embedded ที่ต้องการสร้าง UI บนหน้าจอ

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│              (Your Code - GPIO, ADC, Sensors)               │
├─────────────────────────────────────────────────────────────┤
│                      LVGL Library                           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │
│  │ Widgets │ │ Events  │ │ Styles  │ │Animation│            │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │
├─────────────────────────────────────────────────────────────┤
│                    Display Driver                           │
│              (Frame Buffer, VG-Lite GPU)                    │
├─────────────────────────────────────────────────────────────┤
│                      Hardware                               │
│              (LCD Display, Touch Panel)                     │
└─────────────────────────────────────────────────────────────┘

---

2. สถาปัตยกรรมของ LVGL

2.1 Object Model

องค์ประกอบ	คำอธิบาย	ตัวอย่าง
Screen	หน้าจอหลัก (Container สูงสุด)	lv_screen_active()
Object	วัตถุพื้นฐาน (Base class)	lv_obj_t *
Widget	วัตถุที่มี function เฉพาะทาง	Button, Label, Slider
Part	ส่วนประกอบย่อยของ Widget	MAIN, INDICATOR, KNOB
State	สถานะของ Object	DEFAULT, PRESSED, CHECKED

WHY: ทำไมต้องเข้าใจ Object Model?

• UI ทุกตัวใน LVGL เป็น Object ที่มี Parent-Child relationship

• การจัดการ Memory และ Layout ขึ้นอยู่กับโครงสร้างนี้

• Event จะ propagate ตาม hierarchy

HOW: การประยุกต์ใช้จริง

┌─ Screen (lv_screen_active()) ─────────────────────────┐
│                                                       │
│  ┌─ Container (Parent) ───────────────────────────┐   │
│  │                                                │   │
│  │  ┌─ Button (Child 1) ─┐  ┌─ Label (Child 2) ─┐ │   │
│  │  │    "ON"            │  │   "LED Status"    │ │   │
│  │  └────────────────────┘  └───────────────────┘ │   │
│  │                                                │   │
│  └────────────────────────────────────────────────┘   │
│                                                       │
└───────────────────────────────────────────────────────┘

CAUTION: ข้อควรระวัง

• ห้าม delete parent ก่อน children (จะ crash)

• Object ที่สร้างแล้วจะถูก LVGL จัดการ Memory (ห้าม free เอง)

• Screen เดียวกันไม่ควรมี Object เกิน ~100 ตัว (performance)

---

3. Basic Widgets

3.1 Label - แสดงข้อความ

ตัวอย่างจาก: examples/get_started/lv_example_get_started_1.c

void lv_example_get_started_1(void)
{
    /* เปลี่ยนสีพื้นหลังของ Screen */
    lv_obj_set_style_bg_color(lv_screen_active(),
                              lv_color_hex(0x003a57),
                              LV_PART_MAIN);

    /* สร้าง Label */
    lv_obj_t * label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, "Hello world");

    /* ตั้งค่าสีข้อความ */
    lv_obj_set_style_text_color(lv_screen_active(),
                                lv_color_hex(0xffffff),
                                LV_PART_MAIN);

    /* จัดตำแหน่งไว้กลางจอ */
    lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
}

Function	หน้าที่	Parameter
lv_label_create()	สร้าง Label widget	parent object
lv_label_set_text()	ตั้งค่าข้อความ	object, string
lv_label_set_text_fmt()	ตั้งค่าข้อความแบบ format	object, format, ...
lv_obj_align()	จัดตำแหน่ง	object, alignment, x_offset, y_offset

WHY: ทำไม Label สำคัญ?

• ใช้แสดงค่าจาก Sensor (ADC, IMU, Temperature)

• Debug output บนหน้าจอแทน UART

• Status message ให้ผู้ใช้

CAUTION: ข้อควรระวัง Label

• ข้อความยาวเกินไปจะ overflow (ใช้ lv_label_set_long_mode())

• lv_label_set_text() จะ copy string ทุกครั้ง (memory allocation)

• ใช้ lv_label_set_text_static() ถ้า string เป็น constant

---

3.2 Button - ปุ่มกด

ตัวอย่างจาก: examples/get_started/lv_example_get_started_2.c

static void btn_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * btn = lv_event_get_target(e);

    if(code == LV_EVENT_CLICKED) {
        static uint8_t cnt = 0;
        cnt++;

        /* ดึง Label ที่เป็น child ของ Button */
        lv_obj_t * label = lv_obj_get_child(btn, 0);
        lv_label_set_text_fmt(label, "Button: %d", cnt);
    }
}

void lv_example_get_started_2(void)
{
    /* สร้าง Button */
    lv_obj_t * btn = lv_button_create(lv_screen_active());
    lv_obj_set_pos(btn, 10, 10);           /* กำหนดตำแหน่ง */
    lv_obj_set_size(btn, 120, 50);         /* กำหนดขนาด */

    /* ลงทะเบียน Event callback */
    lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_ALL, NULL);

    /* สร้าง Label ใน Button */
    lv_obj_t * label = lv_label_create(btn);
    lv_label_set_text(label, "Button");
    lv_obj_center(label);
}

WHY: ทำไม Button สำคัญ?

• เป็น input หลักสำหรับ user interaction

• ใช้ควบคุม GPIO (ON/OFF LED, Motor)

• Trigger การทำงานต่างๆ (Start measurement, Reset)

HOW: เชื่อมโยงกับ GPIO จากสัปดาห์ที่ 1

/* Button บน UI → ควบคุม LED จริง */
static void btn_led_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);

    if(code == LV_EVENT_CLICKED) {
        /* Toggle LED - เชื่อมโยงกับ Week 1 GPIO */
        Cy_GPIO_Inv(CYBSP_USER_LED1_PORT, CYBSP_USER_LED1_PIN);
    }
}

---

3.3 Switch - สวิตช์เปิด/ปิด

ตัวอย่างจาก: examples/widgets/switch/lv_example_switch_1.c

static void switch_event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);

    if(code == LV_EVENT_VALUE_CHANGED) {
        /* ตรวจสอบสถานะ Switch */
        bool is_on = lv_obj_has_state(obj, LV_STATE_CHECKED);

        if(is_on) {
            printf("Switch: ON\n");
        } else {
            printf("Switch: OFF\n");
        }
    }
}

void create_switch_example(void)
{
    lv_obj_t * sw = lv_switch_create(lv_screen_active());
    lv_obj_center(sw);
    lv_obj_add_event_cb(sw, switch_event_handler, LV_EVENT_VALUE_CHANGED, NULL);
}

WHY: ทำไม Switch เหมาะกับ GPIO?

• แสดงสถานะ ON/OFF ชัดเจน

• เหมาะกับการควบคุม Binary Output (LED, Relay, Motor)

• User-friendly กว่า Button สำหรับ toggle state

---

3.4 LED Widget - แสดงสถานะ

ตัวอย่างจาก: examples/widgets/led/lv_example_led_1.c

void lv_example_led_1(void)
{
    /* LED ปิด */
    lv_obj_t * led1 = lv_led_create(lv_screen_active());
    lv_obj_align(led1, LV_ALIGN_CENTER, -80, 0);
    lv_led_off(led1);

    /* LED สีแดง ความสว่าง 150 */
    lv_obj_t * led2 = lv_led_create(lv_screen_active());
    lv_obj_align(led2, LV_ALIGN_CENTER, 0, 0);
    lv_led_set_brightness(led2, 150);
    lv_led_set_color(led2, lv_palette_main(LV_PALETTE_RED));

    /* LED เปิด */
    lv_obj_t * led3 = lv_led_create(lv_screen_active());
    lv_obj_align(led3, LV_ALIGN_CENTER, 80, 0);
    lv_led_on(led3);
}

Function	หน้าที่
lv_led_create()	สร้าง LED widget
lv_led_on()	เปิด LED (สว่างสุด)
lv_led_off()	ปิด LED (มืด)
lv_led_set_brightness()	ตั้งความสว่าง 0-255
lv_led_set_color()	ตั้งสี

WHY: ทำไมต้องมี Virtual LED?

• แสดงสถานะ Hardware LED บนหน้าจอ

• ใช้เมื่อ Physical LED ไม่พอ

• สื่อสาร Status ให้ผู้ใช้ (Error, Warning, OK)

---

4. Event Handling

4.1 Event Callback Pattern

/* รูปแบบมาตรฐานของ Event Callback */
static void my_event_cb(lv_event_t * e)
{
    /* 1. ดึงประเภท Event */
    lv_event_code_t code = lv_event_get_code(e);

    /* 2. ดึง Object ที่เกิด Event */
    lv_obj_t * target = lv_event_get_target(e);

    /* 3. ดึง User Data (ถ้ามี) */
    void * user_data = lv_event_get_user_data(e);

    /* 4. Handle แต่ละ Event Type */
    switch(code) {
        case LV_EVENT_CLICKED:
            /* ผู้ใช้คลิก */
            break;
        case LV_EVENT_VALUE_CHANGED:
            /* ค่าเปลี่ยน (Slider, Switch) */
            break;
        case LV_EVENT_PRESSED:
            /* กดค้าง */
            break;
        case LV_EVENT_RELEASED:
            /* ปล่อย */
            break;
    }
}

4.2 Event Types ที่สำคัญ

Event Code	เมื่อไหร่ถูกเรียก	ใช้กับ Widget
LV_EVENT_CLICKED	Click (Press + Release)	Button, Image
LV_EVENT_VALUE_CHANGED	ค่าเปลี่ยน	Slider, Switch, Arc
LV_EVENT_PRESSED	กดค้าง	ทุก Object
LV_EVENT_LONG_PRESSED	กดค้างนาน (>400ms)	ทุก Object
LV_EVENT_RELEASED	ปล่อย	ทุก Object

WHY: ทำไม Event-Driven สำคัญ?

• ไม่ต้อง Polling สถานะ (ประหยัด CPU)

• แยก Logic ออกจาก UI (Maintainable)

• รองรับ Multiple Events บน Object เดียว

HOW: ส่ง User Data ผ่าน Event

/* ส่ง GPIO Port/Pin ผ่าน User Data */
typedef struct {
    GPIO_PRT_Type *port;
    uint32_t pin;
} gpio_info_t;

static gpio_info_t led1_info = {
    .port = CYBSP_USER_LED1_PORT,
    .pin = CYBSP_USER_LED1_PIN
};

static void led_toggle_cb(lv_event_t * e)
{
    gpio_info_t *gpio = (gpio_info_t *)lv_event_get_user_data(e);

    if(lv_event_get_code(e) == LV_EVENT_CLICKED) {
        Cy_GPIO_Inv(gpio->port, gpio->pin);
    }
}

void setup_led_button(void)
{
    lv_obj_t * btn = lv_button_create(lv_screen_active());
    lv_obj_add_event_cb(btn, led_toggle_cb, LV_EVENT_CLICKED, &led1_info);
}

CAUTION: ข้อควรระวัง Event

• User Data ต้อง valid ตลอด lifetime ของ Object

• ห้ามใช้ local variable เป็น User Data (จะหาย)

• หลาย Event อาจเกิดพร้อมกัน (ต้องกรองด้วย code)

Functions สำหรับการวางตำแหน่ง (LVGL v9.2 API)

/*==========================================================================
 * 1. lv_obj_set_pos() - กำหนดตำแหน่งแบบ Absolute (จาก parent's content area)
 *    ใช้เมื่อ: ต้องการวางตำแหน่งที่แน่นอน เช่น grid layout
 *==========================================================================*/
lv_obj_set_pos(obj, x, y);        /* x, y เป็น pixels จาก top-left ของ parent */

/*==========================================================================
 * 2. lv_obj_set_x() / lv_obj_set_y() - กำหนดทีละแกน
 *    ใช้เมื่อ: ต้องการปรับแกนเดียว
 *==========================================================================*/
lv_obj_set_x(obj, 100);           /* ตั้ง x เป็น 100px */
lv_obj_set_y(obj, 50);            /* ตั้ง y เป็น 50px */

/*==========================================================================
 * 3. lv_obj_align() - จัดตำแหน่งตาม alignment พร้อม offset
 *    ใช้เมื่อ: วาง widget โดยอ้างอิงจาก parent (แนะนำ)
 *==========================================================================*/
lv_obj_align(obj, LV_ALIGN_CENTER, x_offset, y_offset);
/*                    ↑                ↑          ↑
            ประเภท alignment        เลื่อน X     เลื่อน Y

    ตัวอย่าง:
    - LV_ALIGN_CENTER, 0, 0     → กลางจอพอดี
    - LV_ALIGN_CENTER, 0, -50   → กลางจอ แต่ขยับขึ้น 50px
    - LV_ALIGN_TOP_MID, 0, 20   → กลางบน แต่ขยับลง 20px (สำหรับ title)
*/

/*==========================================================================
 * 4. lv_obj_align_to() - จัดตำแหน่งโดยอ้างอิงจาก object อื่น
 *    ใช้เมื่อ: วาง widget สัมพันธ์กับ widget อื่น
 *==========================================================================*/
lv_obj_align_to(obj, base_obj, LV_ALIGN_OUT_BOTTOM_MID, x_offset, y_offset);
/*               ↑      ↑              ↑                   ↑          ↑
              widget   อ้างอิง    วางใต้ base_obj           เลื่อน X     เลื่อน Y */

/*==========================================================================
 * 5. lv_obj_center() - วางกลาง parent อย่างง่าย
 *    ใช้เมื่อ: ต้องการวางกลางโดยไม่มี offset
 *==========================================================================*/
lv_obj_center(obj);               /* เทียบเท่า lv_obj_align(obj, LV_ALIGN_CENTER, 0, 0) */

Functions สำหรับการกำหนดขนาด (Size Functions)

/*==========================================================================
 * 1. lv_obj_set_size() - กำหนดทั้ง width และ height พร้อมกัน
 *==========================================================================*/
lv_obj_set_size(obj, width, height);

/* ค่าพิเศษที่ใช้ได้:
   - pixels (เช่น 200, 100)           → ขนาดคงที่
   - lv_pct(50)                       → 50% ของ parent
   - LV_SIZE_CONTENT                  → ขยายตาม content ข้างใน */

/*==========================================================================
 * 2. lv_obj_set_width() / lv_obj_set_height() - กำหนดทีละด้าน
 *==========================================================================*/
lv_obj_set_width(obj, 200);       /* กว้าง 200px */
lv_obj_set_height(obj, 100);      /* สูง 100px */
lv_obj_set_width(obj, lv_pct(80)); /* กว้าง 80% ของ parent */

/*==========================================================================
 * 3. lv_obj_set_style_pad_*() - กำหนด padding (ช่องว่างภายใน)
 *    ใช้เมื่อ: ต้องการขยายขนาด widget โดยอัตโนมัติ
 *==========================================================================*/
lv_obj_set_style_pad_hor(btn, 30, 0);  /* padding ซ้าย-ขวา 30px */
lv_obj_set_style_pad_ver(btn, 15, 0);  /* padding บน-ล่าง 15px */
/* หมายเหตุ: ดีกว่า lv_obj_set_size() สำหรับ Button เพราะขยายตาม text อัตโนมัติ */

Layout Pattern สำหรับ 480x320 Screen

Pattern 1: Vertical Stacking (ใช้บ่อยที่สุด)

/* Title → Main Content → Description → Footer */
void create_vertical_layout(void)
{
    /* 1. Title - ชิดบน */
    lv_obj_t * title = lv_label_create(lv_screen_active());
    lv_label_set_text(title, "Example Title");
    lv_obj_align(title, LV_ALIGN_TOP_MID, 0, 20);        /* y=20 จากขอบบน */

    /* 2. Main content - กลางจอ */
    lv_obj_t * widget = lv_led_create(lv_screen_active());
    lv_obj_align(widget, LV_ALIGN_CENTER, 0, -30);       /* y=-30 ขยับขึ้นเล็กน้อย */

    /* 3. Description - ล่างสุด */
    lv_obj_t * desc = lv_label_create(lv_screen_active());
    lv_label_set_text(desc, "Description text");
    lv_obj_align(desc, LV_ALIGN_BOTTOM_MID, 0, -50);     /* y=-50 จากขอบล่าง */
}

Pattern 2: Multiple Widgets at CENTER with Y-offset

/* วาง widgets หลายตัวจากกลางจอ โดยใช้ y_offset */
void create_center_stacked_layout(void)
{
    /* LED - อยู่เหนือกลางจอ */
    lv_obj_t * led = lv_led_create(lv_screen_active());
    lv_obj_align(led, LV_ALIGN_CENTER, 0, -70);          /* ขึ้นไป 70px จากกลาง */

    /* Label - กลางจอพอดี */
    lv_obj_t * label = lv_label_create(lv_screen_active());
    lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);          /* กลางจอพอดี */

    /* Buttons - ล่างกลางจอ */
    lv_obj_t * btn1 = lv_button_create(lv_screen_active());
    lv_obj_align(btn1, LV_ALIGN_CENTER, -60, 50);        /* ซ้าย, ลง 50px */

    lv_obj_t * btn2 = lv_button_create(lv_screen_active());
    lv_obj_align(btn2, LV_ALIGN_CENTER, 60, 50);         /* ขวา, ลง 50px */

    /* Slider - ล่างสุดของกลุ่ม */
    lv_obj_t * slider = lv_slider_create(lv_screen_active());
    lv_obj_align(slider, LV_ALIGN_CENTER, 0, 110);       /* ลง 110px จากกลาง */
}

Pattern 3: Container with Grid Layout

/* ใช้ container เมื่อมี widgets หลายตัวที่ต้องจัดเป็นกลุ่ม */
void create_container_grid_layout(void)
{
    /* Container - ขนาด 420x200 pixels */
    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 420, 200);
    lv_obj_align(cont, LV_ALIGN_CENTER, 0, 10);
    lv_obj_clear_flag(cont, LV_OBJ_FLAG_SCROLLABLE);  /* ปิด scroll */

    /* วาง items ใน container ด้วย absolute position */
    for(int i = 0; i < 4; i++) {
        int x_pos = (i % 2) * 200 + 20;   /* 2 columns: x = 20 หรือ 220 */
        int y_pos = (i / 2) * 80 + 20;     /* 2 rows: y = 20 หรือ 100 */

        lv_obj_t * led = lv_led_create(cont);
        lv_obj_set_pos(led, x_pos, y_pos);
    }
}

Widget Sizing Guidelines (แนะนำสำหรับ 480x320)

Widget Type	Recommended Size	Notes
Title Label	Auto (text length)	Font: montserrat_24
Button	Padding 30x15	ใช้ padding แทน set_size
LED	40x40 to 80x80	ขึ้นกับความสำคัญ
Switch	60x30 to 80x40	Default size ก็ใช้ได้
Slider	Width 200-300	Height auto
Bar	300x25	ปรับ width ตาม layout
Arc	140x140 to 200x200	ควรเป็น square
Chart	400x260 max	ลดถ้ามี labels ด้านข้าง
Container	420x200 typical	สำหรับ dashboard 4 items

Common Background Colors (จาก Course Examples)

/* Primary backgrounds */
#define BG_DARK_NAVY    0x003a57    /* Week3 Ex1: Hello World */
#define BG_DARK_BLUE    0x1a1a2e    /* Week3 Ex2,5: Button, Dashboard */
#define BG_DARKER       0x0f0f23    /* Week3 Ex3: LED Control */
#define BG_MIDNIGHT     0x16213e    /* Week3 Ex4, Week4: Switch, Chart */

/* Panel/Container backgrounds */
#define BG_PANEL        0x0f0f23    /* Container background */
#define BG_BORDER       0x444444    /* Container border */

/* Text colors */
#define TEXT_WHITE      0xFFFFFF    /* Main text */
#define TEXT_GRAY       0xAAAAAA    /* Description text */
#define TEXT_GREEN      0x00FF00    /* Status text */

CAUTION: ข้อควรระวังในการวาง Layout

1. ห้ามวาง Widget นอกขอบจอ: ค่า y ที่เกิน 319 หรือ x ที่เกิน 479 จะทำให้ widget หายไป

2. ลำดับการสร้างสำคัญ: Widget ที่สร้างทีหลังจะอยู่ด้านบน (z-order)

3. align_to ต้องทำหลัง base object ถูก position แล้ว:

   /* ✅ ถูก */
   lv_obj_align(slider, LV_ALIGN_CENTER, 0, 50);   /* position slider ก่อน */
   lv_obj_align_to(label, slider, LV_ALIGN_OUT_BOTTOM_MID, 0, 5);  /* แล้วค่อย align label */
   
   /* ❌ ผิด */
   lv_obj_align_to(label, slider, ...);   /* slider ยังไม่มี position! */
   lv_obj_align(slider, ...);

4. ใช้ padding แทน set_size สำหรับ Button:

   /* ✅ ดี - text ไม่ถูก clip */
   lv_obj_set_style_pad_hor(btn, 30, 0);
   lv_obj_set_style_pad_ver(btn, 15, 0);
   
   /* ⚠️ ระวัง - อาจ clip text ถ้าขนาดเล็กเกินไป */
   lv_obj_set_size(btn, 80, 30);  /* ต้องแน่ใจว่า text พอดี */

5. Container ควรปิด scroll flag:

   lv_obj_clear_flag(cont, LV_OBJ_FLAG_SCROLLABLE);  /* ป้องกัน content เลื่อนได้ */