GD32F303VCT6开发板资料包使用指南：从原理图到例程迁移

简介面向GD32F303VCT6开发者的Demo板软硬件资料包覆盖PDF原理图、中文使用说明、23个基础例程以及GD固件库构成从电路理解到代码移植的完整开发链路适合嵌入式入门工程师和电子爱好者进行单片机评估与原型验证。压缩包内共480个文件以C/H源码文件、Keil与IAR工程文件、PDF文档和文本说明为主整体仅3.84MB目录按例程编号组织便于按需检索和对照实验。23个例程覆盖GPIO按键中断/轮询、USART打印与DMA收发、ADC双通道采集、DAC输出电压、I2C EEPROM、SPI Flash、I2S音频播放、EXMC扩展NAND Flash与触摸屏、SDIO读写SD卡、CAN组网、RCU时钟输出、CTC校准、PMU低功耗唤醒等典型外设场景并配有中文说明与原理图读者可以结合硬件电路学习初始化代码和中断配置思路加深对GD32库函数风格与外设寄存器配置的理解。GD固件库代码同样可用于其他GD32F30x系列项目减少重复移植工作提升开发效率。目前已有484人学习下载资料完整且体积小巧非常适合嵌入式开发学习者对照动手实践。1. GD32F303VCT6 Demo 板资料包的打开方式拆开快递袋时桌上通常有两样东西一块 GD32F303VCT6 Demo 板和一个名为“GD固件库资料.zip”的压缩包。包里装着 PDF 原理图、中文使用说明、23 个开发板例程和整套 GD 固件库。这套资料要解决的核心问题只有一个在尽可能短的时间里确认这颗 Cortex-M4 内核、120MHz 主频、256KB Flash、96KB SRAM 的国产 MCU能不能在硬件和软件两个层面平替手上的 STM32F103 方案。Demo 板例程提供的是“能跑的最小工程”固件库解决的是“API 从哪来”而原理图则回答了“复刻这块板需要带走哪些电路”。适读人群是准备换料评估的硬件工程师、从 ST 标准库转过来的嵌入式工程师以及需要拿例程给客户做方案验证的 FAE。下面按拿到资料包之后最常见的操作顺序展开先读原理图再跑例程最后把例程改到自己板子上。2. 先看 PDF 原理图BOOT、时钟、SWD 三个网络决定硬件能不能跑原理图在压缩包的硬件资料目录下打开后不用急着逐脚核对 MCU 的每个网络。先看三组网络BOOT0/BOOT1、OSC_IN/OSC_OUT、SWDIO/SWCLK/NRST。它们决定了一件事——这块板能不能烧录、能不能启动、能不能把主频配到 120MHz。把这几个网络在 PDF 里用文本搜索定位比肉眼在整张图上追线快得多。2.1 BOOT0/BOOT1 跳线启动介质选择与烧录模式切换原理图上 BOOT 引脚旁边通常有一组排针或跳线帽丝印写着 BOOT0、BOOT1。GD32F303 的启动模式表和 STM32F103 基本一致只是芯片内部 bootloader 存放位置不同。Demo 板默认把跳线帽插在主 Flash 启动位置对应 BOOT0 拉低。启动来源BOOT0BOOT1典型用途主 Flash0任意正常运行System Memorybootloader10串口 ISP 下载SRAM11调试可执行加载到 SRAM 的程序烧录后复位不进 main先检查这个跳线帽是不是从“ISP 模式”拨回了“Flash 模式”。用串口 ISP 做固件升级时把 BOOT0 置 1、BOOT1 置 0上电后由 bootloader 接管串口下载完成再拨回 0。BOOT0 为 0 时 BOOT1 电平被忽略所以日常运行时不用纠结 BOOT1 的状态。顺着丝印“BT0”“BT1”找到引脚后用万用表量一下实际电平和跳线位置是否一致能排除排针接触不良的隐性故障。2.2 外部 8MHz 晶振与 HXTAL 等待没有它就没有 120MHz原理图里晶振附近标注 8MHz两脚分别接 OS_IN/OS_OUT 或 PD0/PD1具体以 PDF 网络标号为准。GD32F303 上电后默认从内部 IRC8M 启动此时内核只有约 8MHz。想要跑到 120MHz必须由外部高速晶振 HXTAL 作为 PLL 输入源固件库里对应的配置函数会先等待 HXTAL 起振再配置倍频器。while (0U (RCU_CTL RCU_CTL_HXTALSTB)) { /* wait until HXTAL ready */ }这段代码逻辑上等价于固件库里 system_gd32f30x.c 的 HXTAL 等待循环RCU_CTL 是时钟控制寄存器RCU_CTL_HXTALSTB 位为 1 表示外部高速晶振已经起振。如果自己画的板子晶振虚焊、负载电容不匹配程序会卡在这个 while 里表现为主循环完全不跑。快速定位方法示波器探头点 OSC_OUT 引脚看不到波形就先把两个负载电容换成原理图推荐值再查晶振两脚到 MCU 引脚的走线。常见时钟源对照如下。时钟源频率上电默认用途HXTAL8MHz原理图常见否需软件使能PLL 输入120MHz 系统时钟的基础IRC8M约 8MHz是最小系统启动、无晶振设计IRC28M约 28MHz否不需要外部晶振的场景2.3 SWD 调试口与供电路径三线连接失败的常见解SWD 调试口在原理图上只画三根线SWDIO、SWCLK、GND。三线能应对大部分连接场景但连接失败时不要第一时间怀疑调试器先回到原理图查两个东西NRST 网络和 VDDA 去耦电路。把 NRST 也接到调试器并在 MDK 的 Debug 设置里选择 Connect under Reset能绕过已经跑飞或把 SWD 引脚复用成 GPIO 的程序。调试器与 Demo 板各自独立供电时GND 必须先连通再上电否则第一次握手大概率失败共地之后SWDIO/SWCLK 两脚旁边通常有 10k 量级的上拉电阻不要在这两条线上再并联强下拉否则信号电平会被压到识别阈值以下。提示原理图里如果用网络标号而不是连线画法直接在 PDF 搜索框输入 SWDIO、NRST、VBAT几秒钟就能定位相关引脚省去整图肉眼的追踪时间。3. 固件库与 23 个例程把最小链路跑通例程的价值不是让你全部看一遍而是让你用最少的调试工作量验证开发环境、烧录链路和外设时钟树。23 个例程对应 23 个外设场景其中真正高频用到的是 GPIO、USART、TIMER 三组。先把这三组跑通后面迁移到自己的板子时才有一个干净对照物。3.1 固件库资料.zip 解压后目录结构决定工程能否打开拿到 zip 第一件事是解压到无中文、无空格的纯英文路径比如D:\gd32f303_demo。中文路径在 MDK 工程里偶尔会触发头文件包含失败报错形式五花八门最容易误导人。解压后典型目录结构如下。GD32F303_Demo/ ├── Demo_Code/ │ ├── 01_GPIO_LED/ │ ├── 02_USART_Printf/ │ └── ... ├── Doc/ │ ├── GD32F303_Demo_User_Guide_CN.pdf │ └── GD32F303VCT6_Demo_原理图.pdf └── GD32F303_Firmware_Library/ ├── Firmware/ # 标准外设库源码 ├── CMSIS/ # 内核头文件与启动文件 └── Examples/ # 官方外设示例目录名可能略有出入但大致是应用工程、文档、固件库三层。MDK 打开.uvprojx后报找不到头文件通常不是文件缺失而是uvprojx里的相对路径假设 Demo_Code 和 Firmware_Library 在同一父目录下。只把例程文件夹拷走、固件库留在原地工程当然打不开。23 个例程共用同一个固件库正确做法是让每个工程都指回这份公共库路径而不是往单个工程里复制代码。工程选项里 C/C 页面的 Preprocessor Symbols 需要确认GD32F303和USE_STDPERIPH_DRIVER两个宏都在少了宏会出现外设寄存器定义缺失的编译错误。3.2 23 个例程怎么挑先跑 GPIO_LED、USART、TIMER按依赖顺序挑三个例程就能覆盖最小系统、外设时钟树、中断这三个基础链路。GPIO 例程验证最小系统和推挽输出USART 例程验证系统时钟配置、串口波特率和 printf 重定向TIMER 例程验证外设时钟分频和 NVIC 中断路径。这三个跑通后I2C、SPI、ADC 这些例程会顺很多。建议顺序例程常见命名验证点需要的外部设备1GPIO_LED最小系统、GPIO 推挽输出、时钟配置板载 LED2USART_Printf串口波特率、printf 重定向、发送标志位USB 转串口线3TIMER_TimeBase定时器外设时钟、NVIC 中断逻辑分析仪或示波器LED 不亮先查 GPIOB 等引脚对应的 RCU 时钟有没有使能串口输出乱码查波特率分频和外部晶振频率是否匹配定时器中断不触发查 RCU_APB1/APB2 分频系数。如果 Demo 板原理图上 LED 网络标号不是 PB0/PB1改一下 main.c 里的引脚宏即可例程里通常已经把引脚定义放在头文件顶部方便统一修改。3.3 编译、烧录的最短命令路径MDK 需要先安装 GD32F30x 系列的 Device Pack否则 Device 下拉列表里找不到 GD32F303VC。安装后在 Options for Target 的 Device 页选择 GD32F303VCDebug 页按实际调试器选择 J-LINK 或 CMSIS-DAP编译用 F7下载用 F8。不想每次开 IDE也可以把烧录命令收敛成一个脚本JLinkExe -device GD32F303VC -if SWD -speed 4000 -autoconnect 1 \ -CommanderScript flash.jlinkflash.jlink里放烧录动作loadfile ./build/app.hex r g exit参数说明-device要与工程选择的型号一致GD32F303VC 对应 LQFP100、256KB Flash-if SWD指定调试接口-speed 4000表示 4MHz SWD 时钟线长超过 10cm 时降到 1000 更可靠loadfile会根据后缀自动识别 hex/bin 格式烧录后r复位、g运行。连接失败就回到 2.3 节把 NRST 接上用 Connect under Reset 模式再试一次。4. 把例程迁到自己板子系统时钟、引脚复用与 printf 三个坑Demo 板例程能在官方板上跑换到自己画的板子上通常不会一次成功问题集中在三处系统时钟配置宏、GPIO 复用方式、printf 重定向。这三个坑按顺序排查就能把官方例程改造成自定义硬件的底层驱动模板。4.1 system_gd32f30x.c 里的时钟宏120MHz 还是 72MHzGD32F303 的系统时钟初始化在system_gd32f30x.c中完成具体行为由文件顶部预定义的宏决定。下载到的例程可能默认开启 120MHz 配置也可能是 72MHz 兼容配置直接烧录到板上表现不同。预定义宏系统时钟适用场景__SYSTEM_CLOCK_120M_PLL_8M_HXTAL120MHz外接 8MHz 晶振__SYSTEM_CLOCK_120M_PLL_25M_HXTAL120MHz外接 25MHz 晶振__SYSTEM_CLOCK_72M_PLL_8M_HXTAL72MHz想与 STM32F103 保持一致__SYSTEM_CLOCK_IRC8M8MHz无外部晶振调试void system_clock_config(void) { #if defined(__SYSTEM_CLOCK_120M_PLL_8M_HXTAL) if (HXTAL_STATUS_OK hxtal_state_wait()) { system_clock_120m_hxtal(); } #elif defined(__SYSTEM_CLOCK_72M_PLL_8M_HXTAL) system_clock_72m_hxtal(); #else system_clock_irc8m(); #endif }宏开关只需要保留一个多个同时定义会导致第一个分支始终生效读代码时容易误判。自画板卡在 PLL 等待时临时把宏改成__SYSTEM_CLOCK_IRC8M让内核先跑起来就能区分是软件配置问题还是外部晶振硬件问题。GD32F303 的 120MHz 配置与 STM32F103 的 72MHz 配置在 PLL 倍频寄存器和等待周期上不同不能直接拿 ST 标准库的 SystemInit 来用。4.2 GPIO 初始化与重映射不是只改一个引脚号从 ST 标准库转过来的代码通常会写GPIO_InitStructure.GPIO_Mode GPIO_Mode_AF_PP。GD 固件库 V2.0 把这套结构体初始化拆成了gpio_mode_set和gpio_output_options_set两个函数参数含义不变但调用方式变了。以串口 USART1 的引脚初始化为例void usart1_pin_init(void) { rcu_periph_clock_enable(RCU_GPIOA); rcu_periph_clock_enable(RCU_USART1); rcu_periph_clock_enable(RCU_AFIO); gpio_mode_set(GPIOA, GPIO_MODE_AF_PP, GPIO_PIN_2); /* TX */ gpio_output_options_set(GPIOA, GPIO_OTYPE_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_2); gpio_mode_set(GPIOA, GPIO_MODE_IN_FLOATING, GPIO_PIN_3); /* RX */ usart_deinit(USART1); usart_baudrate_set(USART1, 115200U); usart_receive_config(USART1, USART_RECEIVE_ENABLE); usart_transmit_config(USART1, USART_TRANSMIT_ENABLE); usart_enable(USART1); }TX 引脚配成复用推挽GPIO_MODE_AF_PPRX 引脚配成输入浮空这是串口引脚最常见配置。RCU_AFIO时钟只有在调用gpio_pin_remap_config改变默认引脚映射时才必须使能默认映射下写上也不影响。注意 GD32F303 的 USART1 默认引脚在 PA2/PA3与 STM32F103 习惯用的 PA9/PA10 不同换芯片型号时先翻资料包里芯片手册的引脚复用表别直接依据 ST 记忆连线。4.3 printf 重定向TBE 标志与 MicroLIB 缺一不可例程里 printf 能输出是因为工程里已经重写了fputc。自己建工程时最容易漏掉这一步int fputc(int ch, FILE *f) { while (RESET usart_flag_get(USART1, USART_FLAG_TBE)); usart_data_transmit(USART1, (uint8_t)ch); return ch; }等待标志用USART_FLAG_TBE而不是USART_FLAG_TC。TBE 表示发送数据寄存器已空可以立刻写入下一个字符TC 表示整个发送移位过程结束用 TC 会让每个字符额外等待一位传输时间。MDK 环境下如果编译器没勾选 Use MicroLIB这个fputc会触发半主机模式调试请求程序在第一次 printf 后跑飞。重定向的串口要和实际外设对应若把 USART1 换成 USART0usart_flag_get和usart_data_transmit里的USART1参数也要同步替换。5. 三个验证技巧SysTick 校时、固件库版本差异、读回校验5.1 用 SysTick 翻转 LED 校准 120MHz 主频volatile uint32_t tick_ms 0; void SysTick_Handler(void) { tick_ms; } int main(void) { SystemInit(); systick_clock_source_config(SYSTICK_CLOCKSOURCE_HCLK); SysTick_Config(SystemCoreClock / 1000); while (1) { if (tick_ms 1000U) { tick_ms 0U; gpio_bit_toggle(GPIOB, GPIO_PIN_0); /* 板载 LED */ } } }systick_clock_source_config把 SysTick 计数源设为 HCLKSystemCoreClock在固件库中与实际主频同步更新。120MHz 配置下SysTick_Config的重装值是 120000LED 每秒翻转一次。用示波器看这个引脚方波周期应该是 2 秒。周期明显偏长说明 SetCoreClock 宏和实际 PLL 配置不一致周期异常短则要检查是否误用了 IRC8M 配置。这个验证不依赖串口板子只接电源和地就能完成。5.2 固件库 V1.x 与 V2.x 差异报错别先怀疑自己网上的 GD32 老例程很多基于 V1.x 库函数名是GPIO_Init、USART_Init的 ST 风格V2.0 固件库改成分段式 API并把外设前缀统一成小写命名。例程编译报“未定义标识符 GPIO_Init”时先确认 zip 里固件库版本而不是逐行改调用处。诊断方法在工程里搜索usart_baudrate_set能搜到说明已经切到 V2.0 API。迁移老代码时把新旧库的gd32f30x_usart.h头文件并排打开按函数功能对照替换改动量比想象中小得多。5.3 下载完成后做一次 Flash 读回校验MDK 的 Flash Download 页面勾选 Verify Code Download每次下载结束会自动读回比较。勾选后下载变慢通常是校验范围覆盖了整个 Flash 而不是程序实际占用区域。命令行下单独执行校验更直接JLinkExe -device GD32F303VC -if SWD -speed 4000 -autoconnect 1在 JLink 控制台输入verifybin app.bin 0x08000000程序区域与 bin 文件一致时返回校验通过。读回校验通过只代表内容一致不保证业务逻辑正确但能快速暴露 Flash 下载算法与芯片型号不匹配的问题。量产阶段把这个校验步骤写进烧录脚本比依赖下载器界面上的绿色对勾更可靠。本文还有配套的精品资源点击获取