diff --git a/rt-thread-version/rt-thread-standard/_sidebar.md b/rt-thread-version/rt-thread-standard/_sidebar.md index 3effa3e8b387785095cf89ba7fff2b18cf4163a0..498f849a981ef717e1b250d78f3b919d3981eea5 100644 --- a/rt-thread-version/rt-thread-standard/_sidebar.md +++ b/rt-thread-version/rt-thread-standard/_sidebar.md @@ -19,6 +19,7 @@ - [RT-Thread Titan-Board](/rt-thread-version/rt-thread-standard/hw-board/ra8p1-titan-board/ra8p1-titan-board.md) - [RT-Thread Edgi-Talk](/rt-thread-version/rt-thread-standard/hw-board/psoc-e84-edgi-talk/psoc-e84-edgi-talk.md) - [RT-thread Edgi-X](/rt-thread-version/rt-thread-standard/hw-board/psoc-e83-edgi-x/psoc-e83-edgi-x.md) + - [GINO Pi](/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/gd32h77d-gino.md) - [英飞凌PSOC62评板](/rt-thread-version/rt-thread-standard/hw-board/ifx-eval-kit/ifx-eval-kit.md) - [NXP FRDM-MCXA346](/rt-thread-version/rt-thread-standard/tutorial/quick-start/frdm_mcxa346/quick-start.md) - [NXP FRDM-MCXA366](/rt-thread-version/rt-thread-standard/tutorial/quick-start/frdm_mcxa366/quick-start.md) diff --git a/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/board.png b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/board.png new file mode 100644 index 0000000000000000000000000000000000000000..efe2fce856801414743d861843fb17afef922942 Binary files /dev/null and b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/board.png differ diff --git a/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/rt-thread-studio-project.png b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/rt-thread-studio-project.png new file mode 100644 index 0000000000000000000000000000000000000000..b349f779be9d8d92897132cd39ea16d0c1a22912 Binary files /dev/null and b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/rt-thread-studio-project.png differ diff --git a/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/wifi-env.png b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/wifi-env.png new file mode 100644 index 0000000000000000000000000000000000000000..bef0ef4298b81e7bb9073e1f42df622d99570f7b Binary files /dev/null and b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/wifi-env.png differ diff --git a/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/wifi-studio.png b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/wifi-studio.png new file mode 100644 index 0000000000000000000000000000000000000000..e84674912d3f47967b290aabaeb211e6c7726b64 Binary files /dev/null and b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/figures/wifi-studio.png differ diff --git a/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/gd32h77d-gino.md b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/gd32h77d-gino.md new file mode 100644 index 0000000000000000000000000000000000000000..5d6d372871b054c8f8c1344b02c7d8c1212131e9 --- /dev/null +++ b/rt-thread-version/rt-thread-standard/hw-board/gd32h77d-gino/gd32h77d-gino.md @@ -0,0 +1,359 @@ +# GINO 开发板快速上手：从平台认识到 RT-Thread 固件编译烧录 + +图形界面、图像采集和网络通信，正在成为嵌入式设备中越来越常见的功能。GINO 是一款基于兆易创新 GD32H77DIW 的开发板，搭载最高 600 MHz 的 Arm Cortex-M7 内核，提供显示、触摸、摄像头、以太网、Wi-Fi 和外部存储等资源，适合用于人机交互、物联网终端和嵌入式应用原型开发。 + +GINO 配套 SDK 基于 RT-Thread 5.3.0，提供 RT-Thread Studio、Env 和 MDK5 开发方式。本文从开发板资源开始，介绍如何获取 SDK、创建工程、编译下载固件，并通过 LED、串口和应用示例完成首次运行验证。 + +![GINO 开发板实物](./figures/board.png) + +## 一、平台介绍 + +GINO 将高性能 MCU、外部存储和多种交互接口集成在同一块开发板上。开发者既可以从 GPIO、I2C、SPI 等基础外设开始学习，也可以利用 LCD、摄像头和网络接口，进一步搭建带图形界面的联网设备。 + +开发板及配套显示、摄像头资源如下： + +| 项目 | 配置 | +| --- | --- | +| 主控芯片 | GD32H77DIW，Arm Cortex-M7，最高主频 600 MHz | +| 外部晶振 | 25 MHz HXTAL | +| 外部 SDRAM | 32 MiB，起始地址 `0xC0000000` | +| QSPI Flash | 8 MiB GD25Q64E，连接 OSPI0 | +| 显示屏 | 720 x 720 MIPI DSI LCD，FL7707N，RGB565 | +| 电容触摸 | GT911，使用 I2C3 | +| 摄像头 | OV7670，支持 QVGA RGB565 采集与 LCD 预览 | +| 以太网 | ENET1，RMII 接口 | +| Wi-Fi | GD32VW553 AT 模块，通过 UART4 与主控通信 | +| 存储扩展 | SD 卡接口、USB Host U 盘支持 | +| 其他接口 | UART、I2C、SPI、CAN、PWM、USB Device/Host | +| 调试接口 | SWD | +| 默认控制台 | UART1，TX 为 PA2，RX 为 PA3，115200-8-N-1 | +| 运行指示灯 | PC4，模板工程中每 500 ms 翻转一次 | + +板上可以看到标有 `DEBUG` 的调试接口，以及 `USB_Device`、`USB_HOST`、`ETH`、`DCI` 和 `MIPI_LCD` 等接口。首次上手时先完成供电、SWD 和串口连接；运行显示或摄像头示例时，再连接对应的屏幕和摄像头。 + +## 二、软件资源与已有功能概况 + +GINO SDK 采用共享源码、多工程的组织方式：RT-Thread 内核、GD32 库、板级驱动和离线软件包集中放置，各示例保留独立的应用代码与配置。这样既方便单独验证外设，也便于在模板工程上逐步添加功能。 + +SDK 共提供 16 个工程，包括 1 个基础模板和 15 个示例工程： + +| 工程 | 功能 | 运行观察或验证方式 | +| --- | --- | --- | +| `Gino_template` | LED 闪烁与二次开发模板 | PC4 LED 闪烁，串口可执行 `list_device` | +| `Gino_driver_i2c` | I2C1 硬件总线 | 连接 I2C 设备后执行 `i2c scan hwi2c1 08 78` | +| `Gino_driver_spi` | SPI3 总线 | 使用 `list_device` 查看 `spi3`，按从设备协议编写收发代码 | +| `Gino_driver_qspi_flash` | GD25Q64E、FAL 与 FatFs | 挂载后执行 `ls /flash` | +| `Gino_driver_sdcard` | SDIO1 与 SD 卡文件系统 | 插入 FAT/FAT32 SD 卡后执行 `ls /sd` | +| `Gino_driver_can` | CAN1 总线 | 配置通信对端后，通过 `can1` 进行收发 | +| `Gino_driver_pwm` | 双路 PWM 输出 | 执行 `pwm_dual_test start`，观察 PA7、PG7 波形 | +| `Gino_driver_rtc` | RTC 与 Alarm | 执行 `date` 查看时间 | +| `Gino_driver_sdram` | 外部 SDRAM 与扩展堆 | 执行 `free`、`list_memheap` 查看内存 | +| `Gino_driver_usb_device` | USBHS0 Device | 连接电脑，检查配置的 USB 设备类是否枚举成功 | +| `Gino_driver_usb_host` | USBHS1 Host 与 U 盘 | 插入 FAT U 盘后执行 `ls /udisk` | +| `Gino_driver_eth` | ENET1 RMII 以太网 | 执行 `ifconfig`，获取 IP 后测试 `ping` | +| `Gino_display_lvgl` | LCD、GT911 与 LVGL | 上电显示 LVGL 演示界面，通过触摸操作 | +| `Gino_display_camera` | OV7670 采集与 LCD 预览 | 观察摄像头画面，使用 `ov7670_preview` 控制预览 | +| `Gino_component_mqtt` | Wi-Fi 与 MQTT 发布订阅 | 配置网络后执行 `gd32vw553_mqtt_start` | +| `Gino_factory` | 显示、摄像头、网络与外设综合演示 | 使用触摸界面和串口控制台体验各项功能 | + +首次开发建议选择 `Gino_template`，先确认编译、下载和串口通信正常，再切换到需要的示例。每个工程目录中的 `README_zh.md` 提供了对应的硬件连接、命令和预期运行效果。 + +## 三、开发资料与环境准备 + +开发所需的软件和资料可以从以下入口获取： + +- GINO SDK 仓库：[sdk-bsp-gd32h77d-realthread-ginopi](https://github.com/CYFS3/sdk-bsp-gd32h77d-realthread-ginopi)。 +- RT-Thread Studio：[下载页面](https://www.rt-thread.org/page/studio.html)。 +- RT-Thread Env：[下载页面](https://www.rt-thread.org/download.html#download-rt-thread-env-tool)，建议使用 2.0 或更新版本。 +- RT-Thread Studio 使用说明：[用户手册](/development-tools/rtthread-studio/um/studio-user-manual.md)。 + +SDK 内的 `README_zh.md` 介绍开发板和工程概况，`docs/PROJECT_GUIDE_zh.md` 提供引脚、内存布局与工程操作说明，`docs/ARCHITECTURE_zh.md` 介绍系统启动、设备驱动和应用组件的工作原理。 + +硬件方面，准备 GINO 开发板、符合板卡要求的电源、DAP-Link 下载器和串口连接线。使用独立 USB 转串口模块时，选择与板卡兼容的 3.3 V TTL 电平，将模块 RX 接到 PA2、TX 接到 PA3，并连接 GND；按板卡接口定义连接 SWDIO、SWCLK、GND 和参考电压，必要时连接复位信号。 + +使用 Studio 时，在 SDK 管理器中准备以下支持包： + +| 支持包 | 版本或型号 | +| --- | --- | +| 开发板支持包 | `GD32H77D-Gino`，v1.0.0 | +| GNU Arm 工具链 | GNU Tools for ARM Embedded Processors 13.3 | +| 调试器支持包 | PyOCD 0.2.9，配合 DAP-Link 使用 | + +如果使用 Env 命令行开发，还需要 Git 和 GNU Arm 工具链；使用 MDK5 时，需要 Arm Compiler 6、GigaDevice `GD32H77x_78x_DFP` 0.6.1 器件支持包和 J-Link。 + +## 四、如何获取 GINO SDK + +使用 Git 克隆 SDK。下面将本地目录统一命名为 `sdk-bsp-gd32h77d-gino`，后续命令均以此目录为例： + +```bash +git clone https://github.com/CYFS3/sdk-bsp-gd32h77d-realthread-ginopi.git sdk-bsp-gd32h77d-gino +cd sdk-bsp-gd32h77d-gino +``` + +也可以在仓库页面选择 `Code -> Download ZIP`，下载并解压到本地。建议将 SDK 放在不含中文和空格的路径中，便于命令行工具和 IDE 识别。 + +SDK 的主要目录如下： + +```text +sdk-bsp-gd32h77d-gino/ + rt-thread/ RT-Thread 内核与组件 + libraries/ GD32 库、芯片驱动和板级驱动 + packages/ 离线软件包 + projects/ 模板与示例工程 + Gino_template/ + Gino_display_lvgl/ + Gino_display_camera/ + Gino_component_mqtt/ + Gino_factory/ + ... + docs/ 开发指南和架构说明 + tools/mdk_pack/ MDK 器件支持包 + sdk-bsp-gd32h77d-gino.yaml Studio 开发板支持包描述 +``` + +使用仓库中的工程时，应保留上述目录关系。各工程通过 `mklinks.bat` 建立共享源码目录链接；显示、摄像头和网络等工程还会链接其依赖的软件包。 + +## 五、如何使用 RT-Thread Studio 创建并编译工程 + +### 第一步：安装开发板支持包 + +打开 RT-Thread Studio，在 SDK 管理器中安装 `GD32H77D-Gino` v1.0.0 开发板支持包，以及对应的 GNU Arm 13.3 和 PyOCD 支持包。使用离线支持包时，通过 SDK 管理器的离线导入功能安装。 + +### 第二步：创建模板工程 + +选择 `文件 -> 新建 -> RT-Thread 项目`，在向导中填写工程名称，并按以下内容选择： + +- 创建方式：基于开发板。 +- 开发板：`GD32H77D-Gino`。 +- BSP：`1.0.0`。 +- 类型：模板工程，对应 SDK 中的 `Gino_template`。 +- RT-Thread：`5.3.0`。 +- 调试器：`DAP-LINK`。 +- 接口：`SWD`。 + +![RT-Thread Studio 创建 GINO 工程](./figures/rt-thread-studio-project.png) + +创建完成后，Studio 会将模板所需的共享源码加入新工程。若要体验 LCD、摄像头或 MQTT，可在新建向导中将类型切换为示例工程，并选择对应示例。 + +### 第三步：编译工程 + +首次验证模板时保持默认配置即可。选中工程，点击工具栏的构建按钮，等待编译完成。 + +默认 Debug 配置的输出文件位于： + +```text +Debug/rtthread.elf +``` + +后续需要增减外设和组件时，打开工程中的 `RT-Thread Settings` 修改配置，保存后重新构建。编译成功后，按照第七节连接下载器并烧录固件。 + +## 六、如何使用 Env 或 MDK5 编译工程 + +### 方式一：Env 与 GCC + +在 Env 的 PowerShell 终端中打开 SDK 根目录，进入模板工程并建立共享目录链接： + +```powershell +cd projects\Gino_template +.\mklinks.bat +``` + +配置 GCC 工具链路径，然后生成配置头文件并编译： + +```powershell +$env:RTT_CC = "gcc" +$env:RTT_EXEC_PATH = "C:\Toolchains\arm-gnu-toolchain-13.3.rel1-mingw-w64-i686-arm-none-eabi\bin" +& "$env:RTT_EXEC_PATH\arm-none-eabi-gcc.exe" --version +scons --pyconfig-silent +scons -j8 +``` + +将 `RTT_EXEC_PATH` 改为本机包含 `arm-none-eabi-gcc.exe` 的 `bin` 目录。上述写法适用于 PowerShell，版本查询命令用于确认该目录中的工具链可以正常运行。 + +编译完成后，工程目录中会生成： + +```text +rt-thread.elf +rtthread.hex +rtthread.bin +``` + +这里的 `rt-thread.elf` 与 Studio 默认输出的 `Debug/rtthread.elf` 文件名不同。烧录时选择当前开发方式实际生成的文件。 + +如需调整配置，在该工程目录中执行 `menuconfig`，保存退出后执行 `scons --pyconfig-silent`，再重新编译。切换到其他示例时，进入对应的 `projects/Gino_*` 目录，先运行该目录下的 `mklinks.bat`，再按相同步骤操作。 + +### 方式二：MDK5 与 Arm Compiler 6 + +安装 Keil MDK5 和 Arm Compiler 6，并安装 SDK 中的器件支持包： + +```text +tools/mdk_pack/GigaDevice.GD32H77x_78x_DFP.0.6.1.pack +``` + +在 Env PowerShell 终端中，从 SDK 根目录进入模板工程并生成 MDK5 工程： + +```powershell +cd projects\Gino_template +.\mklinks.bat +$env:RTT_CC = "keil" +$env:RTT_EXEC_PATH = "C:\Keil_v5" +scons --pyconfig-silent +scons --target=mdk5 --project-name=project +``` + +将 `RTT_EXEC_PATH` 调整为实际 MDK 安装根目录。打开生成的 `project.uvprojx`，选择与工程目录同名的 target，使用 Arm Compiler 6 编译。 + +MDK 输出文件位于： + +```text +Objects/rt-thread.axf +Objects/rt-thread.hex +``` + +修改外设、软件包配置或源码选择后，需要重新执行 `scons --target=mdk5 --project-name=project` 更新工程文件。 + +## 七、如何烧录固件 + +### 使用 Studio 与 DAP-Link + +给开发板供电，将 DAP-Link 连接到板上的 `DEBUG` 接口，并将下载器连接电脑。在 Studio 中检查下载配置： + +| 配置项 | 选择 | +| --- | --- | +| 下载器 | DAP-Link / PyOCD | +| 调试接口 | SWD | +| 目标芯片 | `GD32H77DIW` | +| 下载模式 | ELF | +| 默认 Debug 固件 | `Debug/rtthread.elf` | + +确认配置后点击“下载程序”，等待下载完成。若下载后停在调试状态，继续运行程序，或退出调试后按下开发板复位按键。 + +### 使用 MDK5 与 J-Link + +连接 J-Link 与 SWD 接口，在 MDK 工程的调试和下载设置中选择 J-Link，并确认已安装 GD32H77x/78x 器件支持包。工程使用以下两个 Flash 算法： + +```text +GD32H77x_78x_CNVM_2M.FLM +GD32H77x_78x_ECNVM_7M_512K.FLM +``` + +使用 MDK 的下载功能烧录当前编译生成的 AXF 镜像，完成后复位运行。 + +### 注意固件的加载地址 + +GINO BSP 的应用向量表位于 `0x08010000`，同时在 `0x08000000` 放置用于兼容不同芯片版本的启动入口。这些内容由工程的启动文件和链接脚本统一处理。 + +下载时优先使用 ELF、AXF 或 Intel HEX，让下载工具读取镜像中记录的加载地址。首次上手不要将裸 BIN 文件直接按单一应用地址烧录，以免遗漏启动入口或破坏镜像布局。 + +## 八、运行验证 + +### 第一步：查看串口启动信息 + +打开串口工具，选择连接到 UART1 的串口号，设置波特率为 `115200`、数据位为 `8`、停止位为 `1`、无校验、无硬件流控。复位开发板后，应看到 RT-Thread 启动信息。 + +模板工程的应用入口还会输出以下两行信息： + +```text +Gino_template is running. +Use list_device and gino_device_probe from the MSH console. +``` + +按回车进入 `msh >` 控制台，执行： + +```text +help +list_device +pin read 36 +``` + +`help` 用于查看当前固件支持的命令，`list_device` 中应能看到 `uart1` 和 `pin` 等已注册设备。`pin read 36` 读取 PC4 的当前电平，PIN 编号按 `端口序号 x 16 + 引脚号` 计算，PC4 对应 `2 x 16 + 4 = 36`。 + +### 第二步：观察 LED 闪烁 + +模板工程在 `applications/main.c` 中配置 PC4 为输出，并在线程中反复切换电平： + +```c +rt_pin_write(GINO_LED_PIN, PIN_HIGH); +rt_thread_mdelay(500); +rt_pin_write(GINO_LED_PIN, PIN_LOW); +rt_thread_mdelay(500); +``` + +正常情况下，LED 每 500 ms 翻转一次，完整亮灭周期约为 1 s。串口命令可正常响应且 LED 持续闪烁，说明基础启动、控制台、GPIO 和系统节拍已经可以正常工作。 + +## 九、进一步体验显示、摄像头和网络 + +以下功能分别在对应的示例工程中启用。切换示例后需要重新编译、下载，不能直接在模板工程中执行未启用功能的命令。 + +### 1. LCD 与触摸 + +创建或打开 `Gino_display_lvgl`，断电连接配套 LCD 和触摸接口，然后编译、下载并复位。工程会自动启动 LVGL 演示界面，可通过触摸检查显示和输入是否正常。 + +该工程同时依赖 LCD、GT911 和 SDRAM。若串口工作正常但屏幕无显示，先检查屏幕连接、背光和外设初始化日志。 + +### 2. 摄像头预览 + +选择 `Gino_display_camera`，连接 OV7670 和 LCD。工程在显示初始化后请求启动摄像头预览，也可以在串口控制台中控制预览： + +```text +ov7670_preview stop +ov7670_preview start +``` + +停止和重新启动后，观察 LCD 画面是否恢复刷新。摄像头采集格式为 QVGA RGB565，采集通过 DCI 与 DMA 完成。 + +### 3. Wi-Fi 与 MQTT + +选择 `Gino_component_mqtt`，打开 `RT-Thread Settings` 的“硬件”页签，展开 `Board extended module Drivers -> Enable GD32VW553 AT Wi-Fi module`，填写自己的 `Wi-Fi SSID` 和 `Wi-Fi password`。AT 串口默认波特率为 `115200`，需与模块固件一致。 + +![Studio 中配置 GINO Wi-Fi](./figures/wifi-studio.png) + +使用 Env 时，执行 `menuconfig`，进入以下菜单修改相同配置： + +```text +Hardware Drivers Config + -> Board extended module Drivers + -> Enable GD32VW553 AT Wi-Fi module +``` + +![Env 中配置 GINO Wi-Fi 和 MQTT](./figures/wifi-env.png) + +截图中的网络信息仅作示例，请按自己的环境填写。保持 `Enable GD32VW553 MQTT demo` 启用，并配置 MQTT Broker 地址、端口、订阅主题、发布主题、client ID 及按需使用的用户名和密码。若模块固件不支持 `AT+CIPDOMAIN` 域名查询，Broker 地址使用数字 IPv4 地址。 + +保存配置；使用 Env 时，再执行 `scons --pyconfig-silent` 更新 `rtconfig.h`。重新编译、下载并复位，在串口执行 `ifconfig`，确认 `wifi0` 已联网且 IP 地址不是 `0.0.0.0`，再启动 MQTT 示例： + +```text +gd32vw553_mqtt_start +``` + +等待连接和订阅成功后发布消息： + +```text +gd32vw553_mqtt_pub rtt/gino hello +``` + +在 Broker 或另一个订阅 `rtt/gino` 的客户端上确认收到 `hello`。主题可以按自己的应用修改，验证完成后执行 `gd32vw553_mqtt_stop` 断开连接。 + +### 4. 综合出厂演示 + +选择 `Gino_factory`，可以通过触摸界面和串口体验显示、摄像头、存储、网络与常用外设。使用 Wi-Fi 和 MQTT 前，同样需要在该工程中填写网络参数；不同示例的配置相互独立。 + +综合工程同时提供以太网 `e0` 和 Wi-Fi `wifi0`。执行 `ifconfig` 时要分别检查接口状态，确认 Wi-Fi 已就绪后再运行对应的 MQTT 功能。 + +## 十、常见问题 + +| 现象 | 检查方法 | +| --- | --- | +| Studio 新建向导中没有 GINO | 在 SDK 管理器中检查 `GD32H77D-Gino` 支持包是否已安装，离线包是否导入成功 | +| 编译提示找不到共享源码或软件包 | 在当前示例目录执行 `mklinks.bat`，检查 SDK 目录结构及该示例依赖的链接 | +| Env 找不到 GCC | 检查 `RTT_CC` 和 `RTT_EXEC_PATH`，后者应指向包含 `arm-none-eabi-gcc.exe` 的目录 | +| 下载工具无法识别芯片 | 检查供电、SWD 接线、下载器连接和目标型号 `GD32H77DIW` | +| 下载完成但复位后不运行 | 确认烧录的是完整 ELF、AXF 或 HEX，加载地址与链接脚本一致 | +| 串口没有输出或出现乱码 | 检查串口号、PA2/PA3 的 TX/RX 交叉连接、共地及 115200-8-N-1 参数 | +| 控制台提示找不到示例命令 | 执行 `help`，确认下载的是对应示例且已启用相关功能 | +| Wi-Fi 没有获得 IP | 检查该工程的 SSID、密码、热点状态、模块供电、复位及 AT 串口波特率 | +| MQTT 无法连接 | 先确认 `wifi0` 联网，再检查 Broker 地址、端口、认证信息和模块 DNS 支持情况 | + +## 结语 + +GINO 将 GD32H77D 的 Cortex-M7 计算能力与 RT-Thread 的设备框架、软件包和开发工具结合起来，提供了从基础外设到图形、图像和联网应用的开发起点。完成模板工程的 LED 与串口验证后，可以按应用需求逐个体验独立示例，再参考综合出厂工程，将所需功能加入自己的项目。