在 RIOT OS 上使用 GD32VF103C-START 开发板RISC-V 平台硬件特性、烧录与调试全指南【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT导读GD32VF103C-START 是 GigaDevice兆易创新官方推出的 GD32VF103CBT6 入门开发板也是 RIOT OS 支持的首批基于 RISC-V 内核带 ECLIC 中断控制器的板卡之一。本文以 boards/gd32vf103c-start/doc.md 为核心结合仓库内该板卡的源码配置periph_conf.h、arduino_iomap.h、Makefile.*等系统讲解该板卡的硬件规格、外设支持情况、两种烧录方式OpenOCD 与 DFU-Util、串口终端连接方法以及 Arduino UNO 兼容引脚的映射细节帮助你在 RIOT OS 下快速上手并定位常见问题。板卡概览一块官方但缺乏官方文档的入门开发板GD32VF103C-START 是 GigaDevice 为 GD32VF103CBT6 MCU 推出的官方入门套件有趣的是RIOT 的维护者在文档中特别指出这块板卡缺少官方文档despite the lack of official documentation因此仓库中这份板卡说明本身就是最可靠的参考之一。其核心特性包括GD32VF103CBT6 RISC-V MCU主频 108 MHz板载 GD-Link 编程器/调试器中间的 mini-USB 接口USB-OTG 接口左侧 mini-USB 接口集成 USB 转 UART 桥右侧 mini-USB 接口1 颗用户 LED、1 颗用户按键、1 颗复位按键Arduino UNO 兼容排针ISP 排针除外硬件规格与外设支持根据 boards/gd32vf103c-start/doc.md 的硬件表GD32VF103CBT6 的资源与 RIOT 的支持情况如下MCUGD32VF103CBT6支持情况内核RISC-V带 ECLIC—厂商GigaDevice—RAM32 KiB—Flash128 KiB—主频108 MHz—电源模式3 种Sleep、Deep Sleep、Standby支持GPIO37 个支持定时器5 × 16-bit支持RTC1 × 32-bit 计数器20-bit 预分频支持WDT2 × 12-bit 计数器3-bit 预分频支持ADC2 × 12-bit 单元16 通道 1 Msps支持DAC2 × 12-bit 通道支持UART—支持USART3支持SPI3支持I2C2 × Fast Mode 400 kHz支持I2S2不支持CAN2 × CAN 2.0B最高 1 Mbps不支持PWM6 通道支持USB1 × USB FS OTG GD-Link UART 桥支持Vcc3.0V – 3.6V—注意I2S 与 CAN 两项在 RIOT 中标注为不支持no这意味着当前版本无法通过 RIOT 的外设 API 使用这两类外设选型时需留意。从源码确认板级功能特性板卡的 Makefile 系统同样印证了上述支持矩阵。boards/gd32vf103c-start/Makefile.features 中将CPU_MODEL声明为gd32vf103cbt6并提供如下FEATURES_PROVIDEDperiph_adc / periph_i2c / periph_pwm / periph_spi periph_timer / periph_uart / periph_usbdev / sdcard_spi同时该板卡声明了完整的 Arduino 兼容特性arduino_analog、arduino_i2c、arduino_pins、arduino_pwm、arduino_shield_uno、arduino_spi、arduino_uart以及highlevel_stdio与tinyusb_device。其中highlevel_stdio意味着可以选用基于 USB CDC ACM 的高层 stdio详见下文串口章节tinyusb_device则提供了 TinyUSB 设备栈支持。此外 boards/gd32vf103c-start/Makefile.dep 在启用saul_default时自动引入saul_gpio将板载 LED 与按键注册到 SAUL 传感器/执行器抽象层便于用统一的 SAUL API 读取按键、控制 LED具体映射见 gpio_params.h其中按键名称为Wakeup、LED 名称为LED0。引脚与板载外设映射板载 LED 与按键在 boards/gd32vf103c-start/include/board.h 中定义了板载外设的引脚LED0GPIO_PIN(PORT_A, 7)PA7低电平点亮通过GPIOA-BC置位实现 ONGPIOA-BOP实现 OFF按键 BTN0GPIO_PIN(PORT_A, 0)PA0内部上拉GPIO_IN_PU下降沿触发中断GPIO_FALLING在应用代码中可直接使用LED0_ON、LED0_OFF、LED0_TOGGLE宏与BTN0_PIN。外设引脚配置periph_conf.hboards/gd32vf103c-start/include/periph_conf.h 给出了各外设的默认引脚分配I2C使用I2C1SCLPB10、SDAPB11对应 Arduino D14/D15速度I2C_SPEED_NORMAL。文档注释提醒该板可能需要外部上拉电阻才能正常进行 I2C 通信。ADCPA1–PA6 依次对应 ADC 通道 1–6即 Arduino A0–A5另含两个内部通道温度通道chan 16与 VREF 通道chan 17它们使用GPIO_UNDEF占位。定时器TIMER0APB2、TIMER1 与 TIMER4APB1均为 16-bit 满量程max 0x0000ffffTIMER2 与 TIMER3 预留给 PWM 使用。PWM两路 PWM 设备——TIMER2 输出 PB5通道 1、PB0通道 2TIMER3 输出 PB7通道 1、PB8通道 2共 4 个有效通道文档所称6 Channels以 MCU 数据手册为准。USART由 boards/common/gd32v/include/cfg_uart_default.h 提供使用USART0TXPA9、RXPA10挂载在 APB2 总线上。Arduino UNO 兼容引脚映射boards/gd32vf103c-start/include/arduino_iomap.h 定义了完整的 Arduino 引脚映射。这里有一个非常重要的警告原文档专门用warning强调丝印上的模拟引脚标注为 A1–A6而不是 Arduino 标准命名 A0–A5。但 RIOT 的 Arduino 引脚映射采用正确的 Arduino 命名A0–A5因此为其他板卡编写、期望兼容 Arduino UNO 扩展板的应用程序可以原样复用无需改动。即板卡丝印的 A1 实际对应 RIOT 的ARDUINO_PIN_A0依此类推。数字引脚方面D0–D15 映射到 PA10/PA9/PB4/PB5/PB6/PB7/PB8/PB9/PB1/PB0/PB12/PB15/PB14/PB13/PB11/PB10模拟引脚 A0–A5 映射到 PA1/PA2/PA3/PB4/PC5/PC6。PWM 引脚 D3、D5、D6、D9 分别映射到PWM_DEV(0)通道 0、PWM_DEV(1)通道 0/1、PWM_DEV(0)通道 1默认 PWM 频率为KHZ(100)100 kHz。串口方面D0/D1 对应UART_DEV(0)SPI 复用引脚为 D11/D12/D13I2C 位于 D14/D15UNO 扩展板期望的位置。烧录固件Flashing方式一OpenOCD 板载 GD-Link默认默认情况下烧录通过OpenOCD 配合板载 GD-Link 编程器/调试器完成命令如下make BOARDgd32vf103c-start -C path/to/app flash从 boards/gd32vf103c-start/Makefile.include 可以看到相关默认值PROGRAMMER ? openocd、OPENOCD_DEBUG_ADAPTER ? dap使用 DAP 协议访问 GD-Link、OPENOCD_TRANSPORT : default。默认 Linux 串口为/dev/ttyACM0PORT_LINUX ? /dev/ttyACM0并使用MOST_RECENT_PORT1自动选择串口时按 CH340 驱动、USB2.0-Serial型号过滤。⚠️ 烧录警告原文档提示当有 Arduino UNO 兼容扩展板插在排针上时烧录可能失败。遇到这种情况请先移除扩展板再重试。方式二DFU-Util 烧录也可以绕过 GD-Link通过DFU-Util走 USB-OTG 接口烧录步骤如下将 mini-USB 线连接到标注为OTG的 USB 接口给板卡供电例如再连一根 mini-USB 线到 GD-Link 接口——即使本次烧录并不会用到它进入 DFU 引导模式将JP4 跳线位于 BOOT 字样下方拨到H位置然后按下复位按键执行烧录命令make BOARDgd32vf103c-start PROGRAMMERdfu-util -C path/to/app flash烧录完成后将 JP4 跳线恢复到L位置再次按下复位按键即可从 Flash 启动新固件。连接串口输出Serial Output默认方式UART stdio 板载 USB 转 UART 桥RIOT 默认使用UART 作为stdio。要将板载 USB 转 UART 桥标注为USART的接口接到主机串口将 mini-USB 线连接到标注为USART的接口在 JP2 跳线上放置跳线帽并置于 Usart 位置——否则 RIOT 的 TXDPA9不会连接到板载 USB 转 UART 桥的 RXD串口将收不到任何输出运行make BOARDgd32vf103c-start -C path/to/app termmake term会使用PORT_LINUX默认/dev/ttyACM0打开终端方便直接观察 printf 输出与调试交互。备选方式stdio_cdc_acmUSB CDC ACM如果不想用 UART可以改用stdio_cdc_acm模块此时 mini-USB 线需要连接到标注为OTG的接口通过 USB 虚拟串口输出。这正是该板卡在 Makefile.features 中声明highlevel_stdio与tinyusb_device的用武之地。关于 JP2 跳线的一个实用说明原文档特别补充了一条操作提示把 JP2 保持在 Usart 位置是安全的甚至在 RIOT 运行时直接移除该跳线也没有问题——因为 PA9 仍然作为 UART TXD 使用而 VBUS 检测本身已被禁用VBUS sensing is disabled anyway。这意味着你可以放心地保持默认状态无需为烧录/串口切换反复拨动跳线。上手示例点亮板载 LED结合前面介绍的源码一个最小示例只需引用board.h即可操作 LED#include board.h #include xtimer.h int main(void) { while (1) { LED0_TOGGLE; /* PA7 电平翻转 */ xtimer_sleep(1); /* 1 秒间隔 */ } return 0; }在应用目录下执行make BOARDgd32vf103c-start flash term即可烧录并打开串口终端观察运行。若希望按键唤醒/触发中断可使用BTN0_PIN与gpio_init_int()注册GPIO_FALLING沿中断回调而通过 SAUL 层启用saul_default后LED 与按键会自动暴露为LED0与Wakeup两个 SAUL 设备。常见问题速查现象排查方向烧录失败移除 Arduino UNO 兼容扩展板后重试确认使用的是 GD-Link中间接口串口无输出确认 JP2 跳线位于 Usart 位置确认线接在USART接口而非 OTGDFU 模式进不去确认 JP4 在H位置后按过复位键烧完记得恢复L位置I2C 通信异常该板可能需要为 SCL/SDAPB10/PB11外接上拉电阻模拟引脚读数偏移丝印标 A1–A6RIOT 内按 Arduino 标准命名为 A0–A5注意一一对应延伸阅读板卡源码与配置boards/gd32vf103c-start/含 periph_conf.h、board.h、arduino_iomap.hGD32V 系列公共配置boards/common/gd32v/doc.md 与 boards/common/gd32v/include/若要自行移植或加深理解可参考 CPU 支持代码cpu/gd32v/RISC-V 公共部分见 cpu/riscv_common/文档中引用的 Datasheet、User Manual 与 Board Manual 以原文档末尾链接为准boards/gd32vf103c-start/doc.md【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考