移植一款小巧的GUI SGL---AI-M61-32S

[hsb689]

📖 前言

最近在准备第 11 期电子 DIY，一直在想用什么 GUI。偶然碰到这个 GUI，大概看了一下，发现这个 GUI 非常的好用，在这里也十分推荐大家：

一个轻量、好用、适合嵌入式 DIY 的 GUI 库

---

话不多说，直接开始。

---

第一步：获取 SGL 源码

首先前往 SGL 仓库，把源码克隆下来：

git clone https://github.com/sgl-org/sgl.git

---

第二步：工程准备

2.1 复制一个模板工程

把这个工程复制一遍，当作我们的模板工程用。工程名字随便取。

2.2 把 SGL 源码放进工程

然后直接把 SGL 的文件放过去，像这样：

2.3 对接显示屏驱动

然后对接一下显示屏的驱动。这边我用的是 ST7789，1.4 寸的一个屏幕。

屏幕驱动使用的是附件 LCD 1.3，在以前安信可论坛里面有个大佬发的。
LCD1.3.zip

把压缩包下载下来，放到刚刚创建的那个工程里面，然后打开截图里的那个文件，修改引脚定义。

Warning

注意看芯片规格书，确认引脚是不是属于 SPI 引脚。

2.4 编写 CMakeLists.txt

然后编写 CMakeLists.txt，将 SGL 和我们刚刚放进去的 LCD 驱动加入到构建。

find_package(bouffalo_sdk REQUIRED HINTS $ENV{BL_SDK_BASE})
sdk_add_include_directories(.)
# Collect sources explicitly per directory. Only include the lwmem mm backend
# because CONFIG_SGL_HEAP_ALLO is set to lwmem in sgl_config.h. This prevents
# compiling tlsf/other mm implementations and avoids duplicate symbol errors.
file(GLOB lcd_sources "${CMAKE_CURRENT_SOURCE_DIR}/LCD1.3/*.c")
file(GLOB lcd_spi_sources "${CMAKE_CURRENT_SOURCE_DIR}/LCD1.3/spi/*.c")
file(GLOB sgl_core_sources "${CMAKE_CURRENT_SOURCE_DIR}/sgl/core/*.c")
file(GLOB sgl_draw_sources "${CMAKE_CURRENT_SOURCE_DIR}/sgl/draw/*.c")
file(GLOB sgl_fonts_sources "${CMAKE_CURRENT_SOURCE_DIR}/sgl/fonts/*.c")
file(GLOB sgl_mm_lwmem_sources "${CMAKE_CURRENT_SOURCE_DIR}/sgl/mm/lwmem/*.c")
file(GLOB sgl_widgets_sources "${CMAKE_CURRENT_SOURCE_DIR}/sgl/widgets/*/*.c")
file(GLOB sgl_root_sources "${CMAKE_CURRENT_SOURCE_DIR}/sgl/*.c")
file(GLOB easyflash_sources "${CMAKE_CURRENT_SOURCE_DIR}/components/esay_flash/*.c")

sdk_add_include_directories(APP LCD1.3 LCD1.3/spi sgl sgl/core sgl/draw sgl/fonts sgl/mm/lwmem sgl/widgets sgl/include components/esay_flash systemConfig)
target_sources(app PRIVATE ${app_sources})

# Add LCD sources
target_sources(app PRIVATE ${lcd_sources} ${lcd_spi_sources})

# Add sgl implementation sources. Only include the root sgl .c files, core,
# draw, fonts, widgets and the lwmem mm backend (not tlsf/other).
target_sources(app PRIVATE ${sgl_root_sources} ${sgl_core_sources} ${sgl_draw_sources} ${sgl_fonts_sources} ${sgl_widgets_sources} ${sgl_mm_lwmem_sources})

target_sources(app PRIVATE
                ./LCD1.3/lcd_conf.h
                ./LCD1.3/lcd.c
                ./LCD1.3/lcd_conf_user.h
                ./LCD1.3/lcd.h

                ./LCD1.3/spi/bl_spi_hard_4.h
                ./LCD1.3/spi/bl_spi_hard_4.c
                ./LCD1.3/spi/st7789v_spi.h
                ./LCD1.3/spi/st7789v_spi.c
                   )
target_sources(app PRIVATE
                ./sgl/sgl.c
                ./sgl/sgl.h
                ./sgl/sgl_config.h
                ./sgl/include/sgl_core.h
                   )

# Add easyflash sources
target_sources(app PRIVATE ${easyflash_sources})

sdk_set_main_file(main.c)

# 设置编译优化等级
# 可选的优化等级包括:
# -O0: 无优化，便于调试
# -O1: 基本优化
# -O2: 标准优化，平衡性能和大小
# -O3: 最大优化，可能增大代码体积
# -Os: 优化代码大小
# -Ofast: 不考虑IEEE标准的高性能优化
set(OPTIMIZATION_LEVEL "-O2")

# 启用调试信息 + 生成 map 文件
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${OPTIMIZATION_LEVEL} -g -Wl,-Map=output.map")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OPTIMIZATION_LEVEL} -g -Wl,-Map=output.map")

project(AiPi_Eyes_DU)

---

第三步：先编译验证

到这里可以先编译一下。如果没有报错的话，再继续下一步。

Tip

如果编译报错，优先检查：

1. LCD1.3 和 sgl 的目录名、路径是否和 CMakeLists.txt 一致；
2. sgl_config.h 中堆分配后端是否与加入构建的 mm 后端一致；
3. ST7789 的 SPI 引脚定义是否和实际接线一致；
4. 芯片规格书中对应引脚是否支持 SPI 复用。

---

第四步：将我们的绘图接口对接 SGL

Important

这一步把 屏幕刷新、DMA 完成回调、SGL 任务和 tick 接起来，让 SGL 真正能在 ST7789 上跑起来。

---

4.1 屏幕刷新接口：panel_flush_area

#define PANEL_BUFFER_SIZE (240 * 12)

static void panel_flush_area(sgl_area_t *area, sgl_color_t *src)
{
    st7789v_spi_draw_picture_nonblocking(area->x1, area->y1, area->x2, area->y2, (st7789v_spi_color_t *)src);
}

Note

SGL 会把需要刷新的区域和颜色数据传进来，我们直接调用 ST7789 的非阻塞绘制接口，把数据交给 SPI / DMA 发送。

---

4.2 DMA 完成回调

static void dma_callback(void)
{
    sgl_fbdev_flush_ready();
}

Tip

当 DMA 把一块区域发送完成后，调用 sgl_fbdev_flush_ready() 告诉 SGL 可以继续刷新下一块。

---

4.3 SGL 主任务与 tick 任务

static void sgl_task_thread(void *arg)
{
    while (1)
    {
        sgl_task_handle();
        // sgl_obj_set_dirty(sgl_screen_act());
        vTaskDelay(pdMS_TO_TICKS(1));
    }
}

static void anim_tick_thread(void *arg)
{
    while (1)
    {
        sgl_tick_inc(1);
        vTaskDelay(pdMS_TO_TICKS(1));
    }
}

Note

sgl_task_thread 负责处理 SGL 内部任务；anim_tick_thread 每 1ms 给 SGL 提供 tick，用于动画和定时器。

---

4.4 日志输出

void log_stdout(const char *str)
{
    printf(str);
}

Tip

把 SGL 的日志重定向到 printf，方便调试。

---

4.5 帧缓冲与初始化

#if (CONFIG_SGL_DRAW_USE_DMA)
/* allocate SGL_DRAW_BUFFER_MAX buffers when DMA is enabled */

sgl_color_t panel_buffer0[PANEL_BUFFER_SIZE];
sgl_color_t panel_buffer1[PANEL_BUFFER_SIZE];

#else
static sgl_color_t panel_buffer0[PANEL_BUFFER_SIZE];
#endif

void sgl_start_demo(void)
{
    st7789v_spi_init();
    lcd_init();

    // bflb_dma_channel_irq_attach(spi_dma_hd, spi_dma_callback, NULL);
    // 注册回调函数，在 DMA 传输完成时调用 sgl_fbdev_flush_ready
    st7789v_spi_async_callback_register(dma_callback);
    // 启用异步回调
    st7789v_spi_async_callback_enable(true);

    sgl_fbinfo_t fbinfo = {
        .xres = CONFIG_SGL_PANEL_WIDTH,
        .yres = CONFIG_SGL_PANEL_HEIGHT,
        .flush_area = panel_flush_area,
        .buffer[0] = panel_buffer0,
        .buffer[1] = panel_buffer1,
        .buffer_size = SGL_ARRAY_SIZE(panel_buffer0),
    };

    sgl_logdev_register(log_stdout);
    sgl_fbdev_register(&fbinfo);

    sgl_init();

    xTaskCreate(sgl_task_thread, "sgl_task", 1024 * 8, NULL, 3, NULL);
    xTaskCreate(anim_tick_thread, "anim_tick", 256, NULL, 3, NULL);
}

Warning

• 非 DMA 模式下，panel_buffer1 未定义，fbinfo 中的 .buffer[1] 需要条件编译处理，否则会编译报错。
• PANEL_BUFFER_SIZE 可根据屏幕宽度和可用 RAM 调整，这里取 240 * 12。
• 如果 DMA 回调没有触发，检查 st7789v_spi_async_callback_enable(true) 是否生效，以及 SPI DMA 中断是否正常。

---

4.6 完整代码

#define PANEL_BUFFER_SIZE (240 * 12)

static void panel_flush_area(sgl_area_t *area, sgl_color_t *src)
{
    st7789v_spi_draw_picture_nonblocking(area->x1, area->y1, area->x2, area->y2, (st7789v_spi_color_t *)src);
}

static void dma_callback(void)
{
    sgl_fbdev_flush_ready();
}

static void sgl_task_thread(void *arg)
{
    while (1)
    {
        sgl_task_handle();
        // sgl_obj_set_dirty(sgl_screen_act());
        vTaskDelay(pdMS_TO_TICKS(1));
    }
}

static void anim_tick_thread(void *arg)
{
    while (1)
    {
        sgl_tick_inc(1);
        vTaskDelay(pdMS_TO_TICKS(1));
    }
}

void log_stdout(const char *str)
{
    printf(str);
}

#if (CONFIG_SGL_DRAW_USE_DMA)
/* allocate SGL_DRAW_BUFFER_MAX buffers when DMA is enabled */

sgl_color_t panel_buffer0[PANEL_BUFFER_SIZE];
sgl_color_t panel_buffer1[PANEL_BUFFER_SIZE];

#else
static sgl_color_t panel_buffer0[PANEL_BUFFER_SIZE];
#endif

void sgl_start_demo(void)
{
    st7789v_spi_init();
    lcd_init();

    // bflb_dma_channel_irq_attach(spi_dma_hd, spi_dma_callback, NULL);
    // 注册回调函数，在 DMA 传输完成时调用 sgl_fbdev_flush_ready
    st7789v_spi_async_callback_register(dma_callback);
    // 启用异步回调
    st7789v_spi_async_callback_enable(true);

    sgl_fbinfo_t fbinfo = {
        .xres = CONFIG_SGL_PANEL_WIDTH,
        .yres = CONFIG_SGL_PANEL_HEIGHT,
        .flush_area = panel_flush_area,
        .buffer[0] = panel_buffer0,
        .buffer[1] = panel_buffer1,
        .buffer_size = SGL_ARRAY_SIZE(panel_buffer0),
    };

    sgl_logdev_register(log_stdout);
    sgl_fbdev_register(&fbinfo);

    sgl_init();

    xTaskCreate(sgl_task_thread, "sgl_task", 1024 * 8, NULL, 3, NULL);
    xTaskCreate(anim_tick_thread, "anim_tick", 256, NULL, 3, NULL);
}

---

Note

到这里，SGL 的绘图接口就已经和 ST7789 对接完成。下一步可以开始创建控件、写 UI 了。

第五步：创建控件并在 SGL 上显示

Important

最后一步就是把控件创建出来，然后让 SGL 把它显示到屏幕上。
如果不想手动写控件代码，可以直接用 SGL UI 设计器。

---

5.1 SGL UI 设计器

SGL 官方有一个 UI 设计器，开源链接在这里：

👉 https://github.com/jialiangbo/sgl-ui-designer

不想手动创建控件的话，可以使用这个工具。

---

5.2 先创建一个按钮

我们就直接先在这里创建一个按钮。

Warning

记得前往 sgl_config.h 里面随便开启一个字体。
默认是带了 3 个字体，但是都没有开启使用。如果不开启，按钮可能没有字体可用。

---

5.3 复制生成的按钮代码

直接在这个代码窗口把我们创建按钮的代码复制下来：

/* === Page: 主页面 === */
void ui_page_page1_create(void)
{
    sgl_obj_t *page_page1 = sgl_screen_act();
    sgl_page_set_color(page_page1, sgl_rgb(255, 255, 255));

    /* 按钮 */
    sgl_obj_t *button1 = sgl_button_create(page_page1);
    sgl_obj_set_pos(button1, 0, 0);
    sgl_obj_set_size(button1, 120, 40);
    sgl_button_set_font(button1, &song23);
    sgl_button_set_text(button1, "button");
    sgl_button_set_color(button1, sgl_rgb(255, 255, 255));
    sgl_button_set_text_color(button1, sgl_rgb(0, 0, 0));
    sgl_button_set_border_color(button1, sgl_rgb(0, 0, 0));
    sgl_button_set_border_width(button1, 2);
    sgl_button_set_radius(button1, 0);
    sgl_button_set_text_align(button1, SGL_ALIGN_CENTER);
    sgl_button_set_alpha(button1, 255);
}

Tip

自带的测试字体没有中文，这里手动修改一下成 Button。
在创建的时候，UI 设计器是可以自己改显示文本的。
由于我们在生成代码的时候没有选择字体，所以按钮这边它是没有字体的，这里也是手动添加。
如果不添加的话，SGL 会自动跑飞。
如果你在 sgl_config.h 里面开启了日志打印的话，就能够看到相关错误。

---

5.4 初始化 UI

然后编写 ui_init，调用页面创建函数：

/* === UI Initialization === */
void ui_init(void)
{
    ui_page_page1_create();
    sgl_screen_load(page1);
}

Note

然后调用一下这个函数就行了。

---

5.5 实验现象

实验现象就是在屏幕中间显示一个按钮。
因为我这边已经把东西组装好了，所以直接演示，我用 SGL 设置的一个 UI。

UI稍微有一点点难看,还在优化中

Note

到这里，SGL 的控件创建和显示就完成了。

✅ 小结

SGL 这个 GUI 库用起来非常顺手，适合我们这种电子 DIY 项目。后面会继续更新第 11 期电子 DIY 的进展。

如果大家也在用 SGL，欢迎一起交流～

[Yaqing-Zheng]

咦哟，交作业了~