GD32F103点灯与串口调试：用STM32CubeMX辅助配置的完整教程

嵌入式圈子里有句玩笑话说我们这帮搞单片机的人本质都是“点灯工程师”。仔细想想还真没毛病——点灯和串口几乎是每块板子逃不掉的过门石也是最快验证一套工具链能不能用的试金石。这篇文章要写的就是怎么把手上的GD32F103点灯、把串口调通并且坚持用STM32CubeMX来辅助配置。注意是“辅助”配置不是直接把HAL库烧进去因为GD32这颗芯片用不了ST那套HAL库但引脚又和STM32F103高度兼容。所以我们可以让CubeMX负责画引脚、算时钟、生成工程骨架再用GD32官方固件库写真正跑在芯片上的代码。这条路线我完整跑过一遍工程稳定运行文中所有代码和步骤照着做就行。这个教程适合谁手里有GD32F103C8T6或者RCT6/VET6核心板、之前学过STM32、想快速上手GD32的人也适合要做项目替换、需要把STM32代码迁移到GD32的工程师。如果你是完全没有接触过Cortex-M的新手建议先能独立搭一个Keil工程再来读这篇会轻松很多。1. 写在前面为什么用CubeMX来搞GD32F103先回答一个你可能已经在嘀咕的问题CubeMX不是ST自己的工具吗它根本不识别GD32F103型号列表里压根没有这颗芯片怎么用没错CubeMX确实不直接支持GD32。但GD32F103偏偏和STM32F103引脚兼容、大部分外设寄存器兼容这就给了一条非常顺滑的路径用CubeMX做图形化规划用GD32官方固件库写工程。两件事拆开各取所长。为什么要拆开因为甜头很明显CubeMX的引脚视图是真的好用。你可以在图形界面上直接点选引脚派生出GPIO、USART、SPI这些功能不用对着数据手册一个个查引脚复用表。CubeMX的时钟树很直观。APB1、APB2、PLL倍频系数鼠标点两下就能看到系统主频的变化比自己手动翻RCU寄存器舒服得多。CubeMX生成工程的速度快。把工程骨架、启动文件、链接脚本这些基础设施先搭好后面替换成GD32的启动文件和库文件比从零手写Keil工程要省事。但关键的一点也要说清楚CubeMX生成的HAL代码不能直接烧进GD32F103跑。原因很简单GD32官方提供的固件库不是ST的HAL/LL库而是基于标准外设库风格的一套独立库函数命名、寄存器映射都跟ST不完全一样。虽然GPIO这种简单外设你魔改一下HAL代码可能也能点亮但一旦用到USART中断、DMA、Flash编程这类复杂外设时序差异和寄存器细节就会开始折磨你。所以我这篇文章采用的方式是CubeMX负责选STM32F103C8T6型号、画引脚、配时钟、生成MDK工程骨架。手动替换把STM32的启动文件、system文件、标准头文件换掉换成GD32固件库对应的文件。手动重写把CubeMX生成的main.c重写成GD32固件库风格的点灯串口代码。这样干既保留了CubeMX的可视化优势又保证了代码是真正为GD32准备的跑起来心里踏实。2. 准备工作与基础认知2.1 硬件和软件清单动手之前先盘点一下需要的东西。我实际用的配置如下不一定非要一模一样但有参考价值。硬件清单GD32F103C8T6核心板或者其他GD32F103系列开发板。ST-Link V2下载器。J-Link也行接线方式类似GD32的SWD接口和STM32完全一致。USB转TTL模块板上大概率是CH340或CP2102用于串口通信。杜邦线若干接线最好用母对母。软件清单STM32CubeMX版本随意我用的6.x。Keil MDK55.30以上版本AC5和AC6都能用。CH340驱动如果电脑设备管理器识别不了USB转TTL先装驱动。串口调试助手推荐XCOM或sscom网上都能找到。GD32F10x固件库从GD32官网下载选GD32F10x系列下载标准外设库。这些软件里CubeMX和Keil是主力CH340驱动和串口助手负责和板子通信。固件库一定要提前下载好后面替换工程文件全靠它。2.2 关键认知GD32F103和STM32F103到底哪里兼容、哪里不同这是整篇文章的地基理解了这一节后面的操作就不会迷惑。我总结成三点引脚和内存布局基本兼容。GD32F103C8T6和STM32F103C8T6一样都是LQFP48封装64KB Flash、20KB SRAM。大部分开发板上的LED、串口、SPI等外设引脚两者可以直接对应。外设编号是错位的。这一点特别坑很多人第一次用GD32都栽在这里。GD32的USART0对应STM32的USART1GD32的USART1对应STM32的USART2以此类推。你在GD32固件库里操作的是USART0但脑子里想的却是STM32的USART1。中断服务函数名字也一样GD32的USART0_IRQHandler对应STM32的USART1_IRQHandler。如果照抄STM32的习惯写中断函数名编译不会报错但中断永远进不去。库完全不同。GD32官方提供的是标准外设库函数名风格更接近老版的STM32 Standard Peripheral Library而不是ST主推的HAL库。比如GPIO初始化HAL库是HAL_GPIO_Init配合GPIO_InitTypeDef结构体GD32库直接是gpio_init传参数。这意味着CubeMX生成的HAL代码不能直接复用必须用GD32库的方式重写。2.3 CubeMX安装与固件包获取CubeMX从ST官网下载Windows安装包一路Next装完。新版CubeMX已经内置了JRE环境不用再单独装Java。真正麻烦的是固件包。在CubeMX里打开Help - Manage embedded software packages网络不好的时候经常下载失败。我的处理方式是去GitHub搜STM32CubeF1离线包手动下载zip文件解压后放入CubeMX的本地仓库目录然后在CubeMX的Help - Updater settings里设置Local repository path指向这个目录。这样建工程时固件包秒加载不用傻等网络。GD32官方固件库下载后解压目录结构大概长这样GD32F10x_Firmware_Library/ ├── Board ├── CMSIS │ ├── GD32F10x │ └── Include ├── Firmware │ ├── GD32F10x_standard_peripheral │ └── GD32F10x_standard_peripheral/Include └── Template建议先花十分钟把Template目录下的工程结构看一遍后面替换文件就知道该从哪里拿了。3. 用CubeMX做图形化配置的思路与实战3.1 选型与时钟规划打开CubeMX新建工程在Part Number搜索框输入STM32F103C8T6选择LQFP48封装的型号。这里看似反直觉但正是GD32和STM32引脚兼容的红利——你在CubeMX里给STM32F103画好的引脚分配、时钟树绝大部分可以直接对应到GD32F103上。进入主界面后先做三件事第一配置RCC。在System Core - RCC里把HSE选为Crystal/Ceramic Resonator表示使用外部晶振。如果开发板用的是内部RC可以选ByPass但我建议用外部晶振GD32F103的外部晶振通常和STM32开发板一样是8MHz。第二配置Debug。在System Core - SYS里把Debug设为Serial Wire。这一步非常重要如果不设置生成的工程默认没有使能SWD引脚ST-Link/J-Link可能搜不到芯片。第三配置时钟树。在Clock Configuration页面HSE填8PLL倍频和分频系数自动算好HCLK目标设72MHzAPB1和APB2保持默认分频。GD32F103最高可以跑到108MHz但刚上手我建议先按72MHz跑和STM32F103的逻辑完全一致等外设都调通了再考虑超频。3.2 引脚分配配置引脚是整个流程里最直观的地方。点灯用的引脚一般看核心板原理图。大多数STM32F103C8T6蓝色板子上的LED接在PC13也有板子接PB0或PB1。我在CubeMX的引脚图上点击PC13选择GPIO_Output配置里把GPIO output level设为High。如果板子上是PB0/PB1照葫芦画瓢选择对应引脚就行。串口用的引脚USART1_TX和USART1_RX默认在PA9和PA10。在左侧Categories里找到USART1Mode设为Asynchronous参数区波特率115200、8位数据、1停止位、无校验。这就是串口的最常用配置也是最标准的调试串口配置。这里要注意CubeMX默认给你配的是ST的USART1但在GD32的世界里这个外设叫USART0。你只需要记住引脚位置PA9/PA10就行真正写GD32代码时用USART0。3.3 生成工程以及“换芯”操作Project Manager里填项目名、工程路径Toolchain选MDK-ARM生成后打开Keil工程会看到一堆HAL_xxx的函数。按我们之前说的思路这些代码不能直接使用需要进行“换芯”操作。我把这个过程总结成四步。第一步把GD32固件库的必要文件加进来。从GD32F10x_Firmware_Library里找到CMSIS目录下的gd32f10x.h、system_gd32f10x.c/h以及Firmware目录下的标准外设库源文件比如gd32f10x_gpio.c、gd32f10x_usart.c、gd32f10x_rcu.c、gd32f10x_misc.c用到哪个外设就加哪个。把这些文件添加到Keil工程的对应组里同时把CubeMX生成的stm32f1xx_hal_xxx.c/h这些文件全部移出工程或者直接删掉。第二步替换启动文件。删除startup_stm32f103xb.s换成GD32固件库Template里的startup_gd32f103xb.s。具体文件名可能因固件库版本略有差异比如有的叫startup_gd32f10x_md.s对应中等容量产品选对就行。这一步很关键中断向量表、堆栈初始化都靠它。第三步替换CMSIS核心头文件。把Keil工程的Include路径指向GD32固件库的CMSIS目录和标准外设库Include目录同时把ST的头文件从包含路径里移除。替换后肯定会报一堆HAL相关的错误这是正常的因为我们正要重写main.c把HAL的函数调用全部换成GD32库函数。第四步重写main.c。下面两节我会分别给出点灯和串口的完整代码你直接把CubeMX生成的main.c整体替换成我们的代码就行。main.c不需要包含任何HAL头文件只用GD32库的头文件。这四步做完工程就从“STM32 HAL工程”变成了“GD32标准外设库工程”。CubeMX在整个流程里扮演的是引脚规划、时钟估算和生成工程骨架的角色真正跑在芯片上的代码是GD32官方的东西。3.4 完整工程目录参考一个可以顺畅编译的工程目录结构大概长这样GD32_Demo/ ├── Libraries/ │ ├── CMSIS/ │ │ ├── GD32F10x/ (core_cm3.h, system_gd32f10x.c/h ...) │ │ └── Include/ (gd32f10x.h等) │ └── GD32F10x_standard_peripheral/ │ ├── inc/ (gd32f10x_gpio.h, gd32f10x_usart.h ...) │ └── src/ (gd32f10x_gpio.c, gd32f10x_usart.c ...) ├── Project/ │ ├── startup_gd32f103xb.s │ ├── test.uvprojx ├── User/ │ ├── main.c │ ├── gd32f10x_it.c │ └── system_gd32f10x.c └── Doc/这个结构不是唯一答案但至少包含三块启动文件、固件库、主程序。实际搭建时我会建议直接把GD32官方固件库里的Template工程复制一份然后在此基础上改这样编译器的设置、启动文件、链接脚本都是现成的省去很多麻烦。4. 点灯GPIO配置从原理到代码4.1 推挽输出和开漏输出LED到底怎么点亮点灯的关键是搞懂GPIO输出的两种模式。大多数核心板的LED都是低电平点亮比如PC13引脚通过一个电阻接到LED再到3.3V那么GPIO输出低电平时电流从3.3V经LED和电阻流入引脚LED亮输出高电平时两边电位接近LED灭。这就解释了为什么很多例程里点亮LED用的是gpio_bit_reset拉低而不是gpio_bit_set拉高。如果你改了代码还是点不亮先看看LED接法是低电平点亮还是高电平点亮。GPIO模式上推挽输出GPIO_MODE_OUT_PP是LED的标准玩法。它能主动输出高电平和低电平驱动能力强适合驱动LED这类负载。开漏输出GPIO_MODE_OUT_OD不带内部上拉输出高电平时引脚是悬空的LED不会亮通常用在I2C这种需要线与逻辑的场合。新手一上来就用推挽输出不要乱换模式。GD32固件库里GPIO初始化的函数是gpio_init它一次把模式、速度、引脚都配好比起HAL库先填结构体再调用要简洁直接。4.2 时钟使能为什么点亮前要先开RCU时钟嵌入式外设工作的前提是时钟。GD32的时钟控制单元缩写叫RCU对应库函数是rcu_periph_clock_enable。很多“LED就是不亮”的案例八成是忘了开时钟或者开错了外设对应的时钟宏。GPIO都是挂在总线上的具体哪个GPIO对应哪个RCU宏从函数名就能看出来要操作GPIOC就用rcu_periph_clock_enable(RCU_GPIOC)要操作GPIOA就用rcu_periph_clock_enable(RCU_GPIOA)。这个环节无法靠猜打开gd32f10x_rcu.h查一下宏名一秒钟就确认了。我还见过一种情况代码逻辑完全正确时钟也开了但LED就是不亮最后发现是工程里没把gd32f10x_gpio.c编译进去。这种低级错误编译期往往不报错因为库函数声明在但链接时就会出现函数未定义。如果你点了灯没反应先检查工程文件有没有加全。4.3 点灯完整代码与延时实现直接上代码。这个main.c是完整可用的点灯部分跑通后串口部分可以继续加进来。#include gd32f10x.h static void led_config(void); static void delay_ms(uint32_t ms); int main(void) { // 建议保留GD32库模板的时钟配置方式 // 如果版本里没有 system_clock_config()删掉这行即可 system_clock_config(); led_config(); while (1) { gpio_bit_reset(GPIOC, GPIO_PIN_13); // 拉低点亮LED delay_ms(500); gpio_bit_set(GPIOC, GPIO_PIN_13); // 拉高熄灭LED delay_ms(500); } } static void led_config(void) { rcu_periph_clock_enable(RCU_GPIOC); // 开GPIOC时钟 gpio_init(GPIOC, GPIO_MODE_OUT_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_13); // 推挽输出 gpio_bit_set(GPIOC, GPIO_PIN_13); // 默认熄灭 } static void delay_ms(uint32_t ms) { uint32_t i; SysTick-LOAD (uint32_t)(SystemCoreClock / 1000U) - 1U; SysTick-VAL 0U; SysTick-CTRL SysTick_CTRL_CLKSOURCE_Msk | SysTick_CTRL_ENABLE_Msk; for (i 0; i ms; i) { while ((SysTick-CTRL SysTick_CTRL_COUNTFLAG_Msk) 0U); } SysTick-CTRL 0U; }这段代码里led_config做了三件事开时钟、配置GPIO模式、初始化为高电平。main主循环里拉低延时再拉高实现呼吸灯式的点亮实际上就是LED闪烁。delay_ms用的是SysTick轮询方式不依赖中断代码自包含。SysTick是Cortex-M3内核自带的一个24位向下计数器SystemCoreClock / 1000计算出1ms需要的时钟周期数填入LOAD寄存器后计数器自动递减到0COUNTFLAG位会被置1。轮询这个标志位就能实现毫秒级延时。如果SystemCoreClock没有在system_gd32f10x.c里正确初始化延时时间会不对所以前面时钟配置不能省。5. 串口从初始化到printf重定向5.1 串口通信的基础概念串口UART是全双工异步通信标准发送端TX接接收端RX双方必须共地并且约定相同的波特率、数据位、停止位、校验位然后才能正常通信。嵌入式调试里最常见的硬伤就是TX接TX两个设备都想说话没人听。正确的接法是USB转TTL模块的RX接板子的TXUSB转TTL的TX接板子的RX。另外别忘共地否则电平参考点不一致乱码就是家常便饭。5.2 USART初始化GPIO复用、波特率与中断串口初始化的第一步是配置引脚。PA9作为USART0_TX要配置成复用推挽输出GPIO_MODE_AF_PP由外设控制引脚输出PA10作为USART0_RX配置成浮空输入GPIO_MODE_IN_FLOATING等待外部信号进入。代码先开时钟再配GPIO然后初始化USART。不同固件库版本的函数名略有差异但大致流程一样。我这里用的是常见的GD32F10x固件库写法#include gd32f10x.h #include stdio.h static void usart_config(void); int main(void) { // 如果版本里没有 system_clock_config()删掉这行即可 system_clock_config(); usart_config(); printf(GD32F103 USART0 initialized.\r\n); while (1) { } } static void usart_config(void) { rcu_periph_clock_enable(RCU_GPIOA); rcu_periph_clock_enable(RCU_USART0); // PA9 TX: 复用推挽输出 gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_9); // PA10 RX: 浮空输入 gpio_init(GPIOA, GPIO_MODE_IN_FLOATING, GPIO_OSPEED_50MHZ, GPIO_PIN_10); usart_deinit(USART0); usart_baudrate_set(USART0, 115200U); usart_word_length_set(USART0, USART_WL_8BIT); usart_stop_bit_set(USART0, USART_STB_1BIT); usart_parity_config(USART0, USART_PM_NONE); usart_hardware_flow_config(USART0, USART_HFC_NONE); usart_receive_config(USART0, USART_RECEIVE_ENABLE); usart_transmit_config(USART0, USART_TRANSMIT_ENABLE); // 使能接收中断 nvic_irq_enable(USART0_IRQn, 0, 0); usart_interrupt_enable(USART0, USART_INT_RBNE); usart_enable(USART0); }波特率为什么是115200因为这是串口调试最常用的标准速率。波特率生成原理USART的发送时钟由PCLK分频得到以72MHz的PCLK2为例要产生115200波特率分频系数大约是39.0625这个值会被换算成分数和整数部分写入波特率寄存器。所以如果外部晶振频率不是8MHz或者时钟树配置错误波特率真实值和预期不一致接收端就会出现乱码。这也是为什么我前面强调要先确认时钟树配置。5.3 中断接收怎么处理串口最常用的接收方式是中断接收。GD32的接收中断对应RBNE标志即接收缓冲非空类似STM32的RXNE使能后只要收到一字节数据就会触发USART0_IRQHandler中断服务函数。中断服务函数的名字必须和启动文件里的向量表一致。GD32F103的USART0中断服务函数叫USART0_IRQHandler如果你照抄STM32的习惯写USART1_IRQHandler编译不会报错但中断永远进不来。在实际操作中这可能是最隐蔽的坑。中断里收到数据后要及时读取数据寄存器因为RBNE标志在读取数据后自动清除。然后做个回环把收到的字节再发送回去方便用串口助手验证收发链路是否正常。void USART0_IRQHandler(void) { uint8_t ch; if (SET usart_interrupt_flag_get(USART0, USART_INT_FLAG_RBNE)) { ch usart_data_receive(USART0); usart_data_transmit(USART0, ch); while (RESET usart_flag_get(USART0, USART_FLAG_TBE)); } }这段代码逻辑很清晰判断接收中断标志读取数据回显发送等待发送缓冲空。不过要提醒一句中断里做发送并在循环里等待TBE标志如果系统高频接收大量数据可能会在中断里耗时过长造成丢数据。简单验证回环没问题正式工程建议用环形缓冲区接收把数据处理挪到主循环或独立任务里。5.4 printf重定向的两种写法调试嵌入式程序printf几乎是必备利器。GD32标准外设库和STM32标准外设库一样默认printf是往屏幕或者文件描述符输出的必须重定向到串口才能真正打印。MDK里最省事的方式是勾选Use MicroLIB微库。勾选后printf的底层实现会变小很多然后我们只要自己实现一个fputc把字符一个个写进串口就行int fputc(int ch, FILE *f) { usart_data_transmit(USART0, (uint8_t)ch); while (RESET usart_flag_get(USART0, USART_FLAG_TBE)); return ch; }这段代码在Keil的MicroLIB环境下可以直接编译。头文件记得加#include stdio.h。如果你不想用MicroLIB非要自己在AC6编译环境下实现完整重定向做法是定义_sys_exit这类半主机模式退出函数工作量大很多。对绝大多数调试场景来说用MicroLIB就够了稳定、省内存、也没那么多幺蛾子。别在这上面内耗。顺便提一句写fputc时判断发送完成标志很多人习惯用USART_FLAG_TC发送完成但实际更顺手的是USART_FLAG_TBE发送缓冲空。两者在低速发送时差别不明显高速发送时TBE更贴合适时写入下一个字节的节奏。我一般都用TBE。6. 常见问题与排查技巧实录代码看着没问题下载也能成功但上电就是不干活这种经历谁都有。我把实际调试中遇到过的问题整理成了一张速查表方便你对照排查。现象可能原因排查思路Keil能编译但下载时找不到芯片SWD接线错误或Debug没配成Serial Wire检查SWDIO/SWCLK接线CubeMX里SYS的Debug必须选Serial Wire芯片之前被锁死连接不上Flash保护或代码卡在低功耗Keil的Flash菜单里执行Erase或按住复位键同时点击下载串口输出乱码波特率不符、外部晶振频率不对、时钟树配错先用逻辑分析仪或示波器看TX引脚波形核对8MHz晶振和PCLK频率换一个可靠的USB转TTL模块printf打印不出来没勾选MicroLIB、fputc没写、串口助手的RX/TX接反三连查设置里勾MicroLIB、代码里有fputc、TX/RX对调测试中断收不到数据NVIC没使能、中断函数名和向量表不一致、RBNE标志被忽略查看启动文件的向量表确认使用的是USART0_IRQHandler而不是USART1_IRQHandlerLED不亮引脚编号错、高低电平逻辑反、GPIO时钟没开对照原理图确认LED接的是哪个引脚试试gpio_bit_set和gpio_bit_reset对调确认rcu_periph_clock_enable宏对应正确GPIOUSB转TTL识别不了CH340驱动没装好、模块芯片不是CH340查看设备管理器里的未知设备硬件ID装对应驱动Win11下老版CH340可能需要禁用驱动签名强制安装工程编译报大量HAL错误替换启动文件后Include路径还指向ST头文件清空Include路径只保留GD32固件库的CMSIS和标准外设库目录这里的经验基本是一条一条踩出来的。特别是GD32和STM32外设编号错位的问题我第一次用GD32的USART0时愣是以为中断向量表写错了后来才发现是芯片本身的编号逻辑和ST不一样。遇到这种“明明代码都对但就是不行”的情况可以先不怀疑编译器回头翻一翻芯片数据手册和库文件里的中断向量表往往答案就在那里。另外一个操作细节下载程序时如果Keil提示RDDI-DAP Error或者类似的连接错误多半是接线问题或者目标板供电不足。检查ST-Link的3.3V和GND是否接到了板子的电源引脚有些板子用ST-Link的3.3V供电电流不够就会出现这种诡异问题。最后再分享一个我实际调试时很管用的习惯把CubeMX生成的引脚配置图导出成PDF存进工程目录。以后改板、画原理图、接线甚至同事合作开发直接看图就行不用在代码里翻gpio配置函数省下大量沟通成本。这颗GD32F103跑通点灯和串口之后你还可以继续往深处扩展。比如用DMA加串口空闲中断接收不定长数据或者做IAP升级功能把Bootloader和App分开基本原理都是我上面讲这套时钟和串口初始化的流程打底。从点灯工程师到能独当一面的嵌入式开发者就是从一个一个这样的小功能开始垒上来的。