GD32E10x官方例程入门：从点灯到外设调试全流程

简介这份GD32E10x系列官方例程面向使用兆易创新GD32E10x系列MCU的嵌入式开发者与初学者基于ARM Cortex-M3内核集合了从基础外设到通信、电机控制等场景的示例代码可用于快速理解芯片用法并搭建工程。压缩包共935个文件约11.16MB包含288个h头文件、261个c源文件、37个uvproj与36个ewp等Keil/IAR工程文件另有20个s启动汇编、6个pdf文档及少量hex、pack等兼顾源码阅读、工程编译与烧录验证。已有880人学习说明其在GD32入门与项目移植中具有一定参考价值。例程覆盖GPIO、SPI、I2C、UART、ADC、DAC、定时器、CAN、USB及低功耗模式等模块读者可据此学习系统时钟配置、外设初始化、中断服务与驱动编写方法并对照工程结构掌握Keil MDK、IAR环境下的编译调试流程从而缩短开发周期、提升项目落地效率。1. 从一块「不会说话的芯片」说起GD32E10x 官方例程是什么新手拿到一块 GD32E10x 开发板最常见的困惑是插上电屏幕不亮、灯不闪、一点动静都没有我怎么知道这块芯片是活的GD32E10x 官方例程就是原厂随芯片一起放出来的整套示范代码一个例程对应芯片内部一个外设的最小可运行版本——点亮一个灯、用串口打印一句话、让定时器数个数、用 ADC 采一次电压。它解决的正是这个困惑把「我知道有这么个外设」变成「我亲眼看到它动了」。适合的人很明确刚接触单片机、手里正好有 GD32E10x 板子、想从「看懂」走到「跑通」的新手。别急着满世界找视频课先把这份例程里最基础的几个文件夹挨个跑一遍你对硬件的实感会比看十个小时视频来得快。2. 为什么新手该从官方例程入手三个比抄代码更实在的理由我带过几个刚入门的同学几乎每个人上来做的第一件事都是去搜「GD32 点灯代码」然后复制粘贴然后编译报错一整屏然后开始怀疑人生。这不是能力问题是路径问题。例程这个东西看着朴素甚至有点土一堆文件夹、一堆 .c 文件没有一个字教你「怎么学」。但它恰好是新手最缺的那块地基。这一章就把「为什么」讲透讲完你就知道该按什么顺序打开它们。2.1 例程是芯片的「随箱说明书」不会和你的板子打架网上流传的绝大多数单片机代码源头是 STM32 的。STM32 和 GD32 在引脚和思路上确实很像很多人也就默认「差不多改改就能用」。真改起来你会发现根本不是改改的事函数名换了、宏定义换了、时钟的打开方式换了、连启动文件的名字都不一样。举个最直观的例子。STM32 标准外设库里打开 GPIOB 时钟是这么写的/* STM32 标准外设库写法函数名前缀是 RCC_参数是 RCC_APB2Periph_xxx */ RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOB, ENABLE);而在 GD32E10x 的固件库里同样一件事写出来是这样/* GD32E10x 固件库写法函数名前缀是 rcu_参数是 RCU_xxx风格也从小驼峰变成了下划线 */ rcu_periph_clock_enable(RCU_GPIOB);同一个动作两种写法一个字都对不上。新手把 STM32 的代码贴进 GD32 的工程编译器的第一反应就是「rcu_periph_clock_enable 未定义」「RCC_APB2PeriphClockCmd 未定义」然后就是几十条红色报错。这时候大部分人不会意识到是平台差异只会觉得自己不适合干这行。官方例程最大的价值就在这里里面的每一个函数名、每一个宏、每一个启动文件、每一份时钟配置都是针对这颗芯片写的你抄它、改它、拆它都不会在「名字对不对」这种事上翻车。新手前期最宝贵的注意力应该花在理解逻辑上而不是花在跟编译器的报错搏斗上。我第一次学的时候就是死磕网上的 STM32 教程折腾了整整两天一直以为是环境装错了血泪经验就是入门阶段代码来源比代码质量重要得多。2.2 一个文件夹 一个最小可运行单元学习颗粒度刚刚好新手容易犯的第二个错是试图去读懂「一整个工程」。打开别人给的或者自己下载的大项目几万行代码几百个文件main 函数里全是函数调用点进去一层套一层看一眼就想关掉。官方例程的设计思路正好相反一个外设一个文件夹一个文件夹就是一个能独立编译、独立下载、独立看到现象的最小单元。GPIO 那个文件夹里全部的代码加起来可能就一两百行去掉注释和头文件真正干活的就十几行。你把这十几行看明白这个外设的基本用法就掌握了不需要理解整个系统的其他部分。这个颗粒度对新手特别友好因为它给了你一个明确的「完成信号」灯亮了这个例程就过关了串口助手上打出字了这个例程就过关了。学习最怕的就是不知道什么时候算学会例程帮你把这个标准具象化成一个个可以看见的现象。顺带说一句例程里的注释密度通常比商业代码高不少很多关键寄存器位旁边都写着「为什么这么配」。这种注释在正式项目里是奢侈品在例程里是标配。2.3 先看哪几个给新手排一条 GPIO → USART → TIMER → ADC 的顺序例程文件夹往往有十几个甚至二十几个一股脑全打开只会更迷茫。入门阶段真正需要先跑的其实就四个顺序也别乱后一个会用到前一个的成果。顺序例程类别你在这个过程中会学到跑通后的现象1GPIO时钟怎么开、引脚怎么配、怎么输出高低电平板上的 LED 亮起来或闪起来2USART串口初始化、波特率、发送一个字节电脑串口助手上出现一行字3TIMER定时器计数、中断是什么、周期怎么算灯按固定节奏闪或串口定时打印4ADC模拟量采样、通道选择、结果换算串口打印出电压值为什么是这么排的GPIO 最简单而且现象最直观眼睛就能验证不需要任何外部设备配合USART 排第二是因为它是后面所有调试的「眼睛」一旦串口能通你就能让芯片把内部状态打印出来给你看排查问题的效率完全不一样TIMER 放第三是因为它是新手第一次正经接触中断理解了这个后面 ADC、串口接收中断都会顺很多ADC 放最后是因为它开始涉及模拟电路和数值换算稍微抽象一点但有了前面串口打印的基础你就能直接把采到的数字打出来看。这四步走完你对这颗芯片的运转方式就有了一个完整的骨架。剩下的 I2C、SPI、DMA、USB 这些都是在这个骨架上长出来的枝节学起来的心理负担会小得多。3. 把第一个灯点亮环境准备到下载运行的全流程上一章讲的是「为什么」这一章开始动手。我见过太多新手卡在第一步例程下载好了压缩包解压了然后盯着满屏文件夹发呆不知道从哪下手。这一章把从装工具到看见灯亮的每一步拆开讲按顺序做就行不用跳步。3.1 三件套准备编译工具、器件支持、下载器在碰代码之前先确认三样东西齐了。缺任何一样后面都会卡住。第一样是编译工具。GD32E10x 的官方例程工程文件通常是给 Keil MDK 准备的部分也提供 IAR 工程你装好对应版本之后还需要额外装一个器件支持包也就是常说的 Pack。这个包的作用是告诉编译工具「GD32E10x 这类型号长什么样」——有多少 Flash、多少 RAM、启动文件用哪个。不装的话你打开工程会看到器件型号那一栏是空的或者带感叹号编译时会报找不到启动文件。这是新手第一个高频卡点装完编译工具别急着打开工程先把 Pack 装上。第二样是下载器。板上一般有 SWD 接口四根线电源、地、SWCLK、SWDIO。下载器类型看手头有什么各种常见调试器基本都能用接法都是这两根信号线加供电。接线的时候注意一点板子自己供电的时候下载器的电源线不要再接两路电源顶在一起轻则下载不稳定重则烧东西。第三样是串口工具。第一个例程用不上但到第二个 USART 例程就要用了提前装好省事。另外确认一下板子上有没有 USB 转串口的芯片没有的话需要一个外接的转接小板接线是 TX 接对方的 RX、RX 接对方的 TX地要共。提示三样东西里器件支持包是最容易被忽略的。如果你打开工程第一眼就看到器件型号那栏不对先回去把 Pack 装上别怀疑例程有问题。3.2 例程文件夹里都是什么一份能看懂的目录导航解压之后你会看到一堆文件夹每个文件夹对应一个外设或者一个功能比如 GPIO、USART、TIMER、ADC、I2C、SPI、DMA 之类另外还会有一个 Template 模板文件夹。先用 Template 练手它是空架子只保证工程能编译能下载适合用来验证工具链是不是通的。点进任意一个例程文件夹里面的文件构成大同小异认识这几个就够用了文件名它负责什么新手要不要动main.c程序入口例程的主逻辑都在这里要动重点看这个gd32e10x_it.c中断服务函数的集合先别动学 TIMER 时再看gd32e10x_libopt.h外设库的开关决定编译哪些模块别动删一行可能就编译不过system_gd32e10x.c系统时钟初始化先别动但值得读一遍startup_gd32e10x.s启动文件汇编写的完全不用看工程文件Keil 或 IAR告诉工具怎么编译这一堆文件别动新手的注意力应该 90% 放在 main.c 上剩下 10% 给 system 文件。其他文件在入门阶段属于「知道它在就行」的范畴。这一点很重要很多人拿到例程之后从启动文件的第一行汇编开始逐行研究研究了三天还没点到灯热情基本就耗光了。3.3 从 Template 到 GPIO 例程六步跑通第一个程序下面这六步每一步做完都有一个可以检查的结果。做完一步确认一步出问题的时候你才知道是哪一步出的。第一步打开 Template 工程。双击工程文件等工具加载完。加载完之后先看器件型号那一栏确认显示的是你这块板子上实际焊的型号。型号对不上后面全是白费。第二步编译一次。点编译按钮等它跑完。正常结果是「0 Error(s)」警告可能有几个入门阶段可以先不管。如果这里就报错八成是器件支持包没装好或者路径里有中文。工程路径带中文是老牌翻车点建议整个例程包放在纯英文路径下。第三步接下载器给板子上电然后点下载。下载成功的标志一般是工具的输出窗口里出现类似「Programming Done」「Verify OK」的字样。如果这里失败先查三件事下载器驱动装没装、SWD 四根线接没接对、板子供电正不正常。第四步按一下板子上的复位键。Template 例程本身就是个空循环所以按完之后什么现象都不会有。这是正常的说明程序确实在跑只是没让它干任何事。第五步关掉 Template打开 GPIO 例程的工程重新编译下载。这一次按完复位板上那颗 LED 应该就有反应了。具体是亮还是闪取决于例程本身写的是什么。第六步对照现象看代码。找到 main.c 里操作引脚的那几行把例程里的引脚编号改成你板子上 LED 实际连的那个引脚这个信息在板子的原理图里或者板子上丝印会标。改完重新编译下载如果现象跟着变了恭喜你你已经完成了从「跑别人的」到「改自己的」的第一次跨越。这六步里最容易出问题的是第三步和第六步。第三步是硬件连接问题第六步是引脚找错的问题——很多人照着例程改了个引脚号灯不亮就以为代码写错了其实是自己板子上的 LED 压根不接在那个脚上。遇到这种情况先去看原理图别急着改代码。4. 读懂而不是照抄一行一行拆开那个点灯例程灯亮了只是开始。如果就此停住你只是「跑通了一个例程」换个外设还是不会。这一章我们把这个点灯例程拆开看看它到底做了什么为什么每一步都省不掉。拆完之后你会发现GD32E10x 上几乎所有外设的初始化都是同一个套路学会一个就等于学会了模板。4.1 为什么时钟永远是第一件事这是新手最容易忽略、也最容易吃亏的一点。芯片为了省电默认状态下绝大部分外设的时钟是关着的。时钟不开你去配置那个外设的寄存器写进去的值会被直接丢弃读出来全是 0而且不会有任何报错。这就是典型的黑匣子行为代码看着没错编译也过了下载也成功了就是没反应。打个比方外设是一间间房间时钟就是每间房的总闸。你不推闸进去按开关当然没反应而且开关本身也没通电。所以例程里rcu_periph_clock_enable()永远出现在配置之前这不是风格问题是硬性顺序。/* 打开 GPIOB 的时钟。不开这一句下面所有对 GPIOB 的配置都是无效操作 */ rcu_periph_clock_enable(RCU_GPIOB);这个函数的参数是一个宏代表某一路外设时钟的总闸比如RCU_GPIOB是 B 口RCU_GPIOA是 A 口RCU_USART0是串口 0。用哪个外设就开哪一路别图省事一次全开——虽然能跑但你会养成一个很坏的習慣等以后做低功耗项目的时候找漏掉的时钟能耗掉你一整天。顺带提醒一句不同外设挂的总线不一样有的挂在高速总线上有的挂在低速总线上例程里的宏已经帮你封好了你不用记但要知道「不同的外设开时钟的写法可能长得不一样」这件事。4.2 引脚配置那三个参数到底在说什么时钟开完下一步是告诉芯片「这个引脚要当输出用输出方式是这样这样的」。GD32E10x 固件库里这件事用一个gpio_init()就干完了但它有四个参数新手经常是照抄不理解为啥。/* 参数依次是端口、模式、速度、引脚号 */ gpio_init(GPIOB, GPIO_MODE_OUT_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_0); /* 把 PB0 拉高输出高电平 */ gpio_bit_set(GPIOB, GPIO_PIN_0);四个参数逐个说清楚参数位置例程里的值含义与怎么改第 1 个GPIOB用哪个端口A/B/C/D 看板子接线第 2 个GPIO_MODE_OUT_PP推挽输出。推挽能主动输出高和低开漏OUT_OD只能拉低高电平要靠外部上拉第 3 个GPIO_OSPEED_50MHZ引脚翻转速度。点灯用最低档都够配高速是为了驱动信号质量速度越高功耗和干扰越大第 4 个GPIO_PIN_0第 0 号引脚。要配多个可以按位或比如GPIO_PIN_0 | GPIO_PIN_1gpio_bit_set()和gpio_bit_reset()是一对一个输出高、一个输出低。这里有个新手常踩的坑灯亮到底是高电平还是低电平取决于板子上 LED 的接法。有些板子是「引脚 → 电阻 → LED → 地」那引脚给高电平灯才亮有些是「电源 → 电阻 → LED → 引脚」那引脚给低电平灯才亮。所以如果你照着例程写灯不亮反而不灭别急着改代码先试试把set和reset换一下。4.3 改一改从「常亮」到「闪灯」的第一次改动例程给的通常是一个静态输出灯一直亮或者一直灭。真正让你开始理解程序在跑的是什么是让灯闪起来。改动很小就是在主循环里加一个延时和一次翻转。#include gd32e10x.h /* 一个粗糙的软件延时靠空转消耗时间入门阶段够用 */ static void delay_loops(uint32_t n) { volatile uint32_t i; for (i 0; i n; i) { __NOP(); /* 空操作指令防止编译器把整个循环优化掉 */ } } int main(void) { /* 第 1 步开时钟缺了这句后面全白搭 */ rcu_periph_clock_enable(RCU_GPIOB); /* 第 2 步把 PB0 配成推挽输出 */ gpio_init(GPIOB, GPIO_MODE_OUT_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_0); /* 第 3 步主循环里反复翻转电平 */ while (1) { gpio_bit_set(GPIOB, GPIO_PIN_0); /* 输出高电平 */ delay_loops(800000); /* 亮一会儿数值越大停得越久 */ gpio_bit_reset(GPIOB, GPIO_PIN_0); /* 输出低电平 */ delay_loops(800000); /* 灭一会儿 */ } }这段代码有几个地方值得说清楚。delay_loops()里的volatile不是装饰品如果不加编译器一看这个循环除了空转什么都没干会直接把它优化掉结果就是灯闪得飞快甚至看起来一直亮着。__NOP()是芯片指令集里的空操作配合volatile一起保证循环真的被执行了。这个延时方法很粗糙实际耗时跟主频、编译优化等级都有关调参只能靠试——但它足够让你在十分钟内看到「程序在循环」这件事比一开始就上定时器中断友好得多。while (1)是嵌入式程序的标准形态。单片机没有操作系统来接管main 函数一旦返回芯片就不知道该干嘛了所以主循环必须是个死循环。这不是偷懒是这类程序的正常结构。改完这段你会看到灯一闪一闪。这时候试着改一下delay_loops的参数从 800000 改成 100000再改成 5000000观察闪烁节奏的变化。这个动作看着幼稚但它是你第一次亲手调一个参数、亲眼看到硬件行为跟着变比读十页文档建立的联系都牢固。做到这一步你对「时钟 → 引脚配置 → 输出」这条链路已经有了肌肉记忆。后面学串口、学定时器、学 ADC开头两句话几乎一模一样只是把gpio_init换成对应的初始化函数而已。5. 新手常见问题排查灯不亮的五种典型情形例程跑不通是常态不是你笨。区别在于有人卡住之后能顺着现象往下查有人只能反复重装环境。这一章列的五种情形覆盖了入门阶段九成以上的翻车现场每一条都按「看到什么 → 为什么 → 怎么办」写遇到问题时按顺序对号入座就行。5.1 现象编译一堆红色报错提示某个函数未定义原因通常是代码来自别的芯片平台或者工程里少了对应的库文件。GPIO 例程能编译你复制了一段网上找的代码进去编译就炸了——八成是那段代码用的是另一套库的命名。另一种情况是工程路径里有中文或者空格工具读文件的时候出错报出一堆莫名其妙的错。解决方式很直接先确认报错的那个函数名是不是rcu_或gpio_开头的这套命名。如果不是说明这段代码不适用于 GD32E10x要么找对应写法要么干脆放弃这段代码回例程里找等价功能。路径问题更好判断把整个例程包挪到「D:\work\gd32\」这种纯英文无空格的路径下重新打开工程编译一次。如果报错消失了那之前就是路径问题。5.2 现象编译通过下载失败工具提示连接不上目标原因集中在硬件连接。SWD 的四根线里地没接是最常见的——很多人觉得信号线接对了就行实际上没有共地电平参考点都不一样通信根本建立不起来。其次是供电板子没上电或者供电不足芯片压根没启动自然连不上。还有一种隐蔽情况芯片被设置成了低功耗模式或者引脚复用把 SWD 口占了导致调试口失效。解决顺序是先用万用表确认板子供电正常再检查地和两根信号线有没有接反或虚接然后确认下载器驱动装了、工具里选的下载器型号对得上。如果还不行试试把板子的启动方式改成从内部 Flash 启动然后按住复位键点下载、看到工具开始连接再松开复位。这一招在 SWD 口被占用的场景下经常管用。5.3 现象下载成功程序也跑了但灯就是不亮原因有好几种得一层层排。第一层是引脚号搞错了例程里写的是 PB0你板子上的 LED 可能接在 PC13 上代码跑得再好也点不亮那颗灯。第二层是电平极性反了板子上的 LED 是低电平点亮你一直在给高电平。第三层是时钟没开代码里少了rcu_periph_clock_enable()或者开错了端口比如配置的是 GPIOB时钟开的是 RCU_GPIOA。排查的办法是从现象倒推先在gpio_bit_set()后面加一句gpio_bit_reset()或者干脆把两个函数对调看现象有没有变化以此判断极性再去看板子原理图确认 LED 到底接在哪个脚最后把时钟那一行的宏和gpio_init里的端口对一遍看是不是同一路。这三步走完九成的不亮问题都能定位。5.4 现象串口助手打开一片乱码或者什么都收不到乱码基本只有一个原因波特率对不上。例程里配的是 115200你的串口助手开的是 9600收到的东西当然是一堆看不懂的字符。改一致就好注意两边都要改别只改一边。什么都收不到问题就多一些。先确认串口线是不是接反了芯片的 TX 要接转接板或者下载器的 RX这个交叉很容易搞错。再确认板子和电脑共地了没有只接两根信号线不接地通信是不稳定的。还有一种情况是例程用的是串口 0但你板子上的 USB 转串口接的是串口 1那自然收不到。翻一下原理图确认对应关系比盲目改代码快得多。5.5 现象例程原样能跑自己改了一行就崩或者没反应原因往往是改到了不该改的地方。新手最常见的操作是把gd32e10x_libopt.h里某个#include注释掉觉得「这个外设我没用到删了清爽」结果那个头文件里连带定义了一堆宏删完之后某个结构体类型就找不到了。另一种是改了中断服务函数的名字编译能过但中断进来之后找不到对应函数程序直接跑飞。解决思路是养成「改之前先备份」的习惯。改一个例程之前把整个文件夹复制一份重命名成GPIO_test在副本上改改坏了直接删掉重来成本几乎为零。另外动手改的时候一次只改一处改完立刻编译下载看现象效果不对就能马上定位到是哪一处改动引起的。一次改五处然后一起调试是新手的经典翻车姿势我自己也踩过找了半天最后发现是自己把分号删了。6. 下一步学什么从点灯到做出第一个小项目的路线跑通点灯之后很多人会陷入第二个迷茫期接下来干什么例程文件夹里还有十几个没打开视频课程还有几十集没看到底该往哪走。我的建议是别再单个刷例程了找一个具体的小目标让它逼着你去学东西。比较适合新手的目标是做一个「按键控制灯 串口报告状态」的小玩意。听起来简单但它会强制你把 GPIO 输入、按键消抖、串口发送这三块串起来跨文件组织代码这对从「跑单个例程」到「写自己的程序」这一步很关键。再往前一步就是把串口打印的值换成 ADC 采到的电压用按键控制采样频率——一个迷你采集器就成了。按照学习顺序我给它排成一张表阶段目标用到的例程判断过关的标准第 1 阶段会用 GPIO 输出GPIO能自己改引脚、改极性、改闪烁节奏第 2 阶段会让芯片「说话」USART能在串口助手里打印自己的名字和变量值第 3 阶段会用 GPIO 输入GPIO按键按下时串口打一行字松手再打一行第 4 阶段理解中断和时间TIMER用定时器中断做 1 秒闪灯主循环里干别的第 5 阶段会采模拟量ADC串口每秒打印一次电压值手摸一下采样点数值会变每个阶段的过关标准都写得很具体因为入门阶段最怕的就是「感觉学得差不多了」这种模糊判断。能自己从零写出来、能解释每一行为什么这么写才算过关。几个具体建议。第一别跳过第 2 阶段。串口是你后面所有调试的依赖早一点让芯片能往外说话后面所有问题的排查效率都会翻倍。第二TIMER 那一关会有点卡中断这个概念新手第一次接触都会懵卡住了不丢人把例程里中断服务函数的名字和中断向量的对应关系搞清楚这一关基本就过了。第三善用gd32e10x_it.c这个文件中断相关的代码都往这里放别硬塞进 main.c养成习惯以后你会感谢自己。最后留一个我自己的教训。我刚学的时候图快例程跑通就立刻切下一个一个都不回头结果两周之后想写个按键程序发现连 GPIO 初始化那四个参数分别是什么意思都说不全只能重新翻例程。从那以后我每跑通一个例程都强制走一遍「关掉例程自己从空文件重写一遍」的流程写不出来的地方就是没真懂的地方回去补。这个习惯看着慢实际上省下了大量回头重学的时间。入门这件事最大的门槛从来不是难度是那种「这东西看起来好复杂」的心理负担。GD32E10x 的官方例程恰恰是把这份负担切成了十几小块你只需要一次面对一小块。希望帮到你早点把第一颗灯点亮。本文还有配套的精品资源点击获取