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 的顺序

例程文件夹往往有十几个甚至二十几个，一股脑全打开只会更迷茫。入门阶段真正需要先跑的其实就四个，顺序也别乱，后一个会用到前一个的成果。

为什么是这么排的：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 练手，它是空架子，只保证工程能编译能下载，适合用来验证工具链是不是通的。

点进任意一个例程文件夹，里面的文件构成大同小异，认识这几个就够用了：

新手的注意力应该 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);

四个参数逐个说清楚：

gpio_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 采到的电压，用按键控制采样频率——一个迷你采集器就成了。

按照学习顺序，我给它排成一张表：

每个阶段的过关标准都写得很具体，因为入门阶段最怕的就是「感觉学得差不多了」这种模糊判断。能自己从零写出来、能解释每一行为什么这么写，才算过关。

几个具体建议。第一，别跳过第 2 阶段。串口是你后面所有调试的依赖，早一点让芯片能往外说话，后面所有问题的排查效率都会翻倍。第二，TIMER 那一关会有点卡，中断这个概念新手第一次接触都会懵，卡住了不丢人，把例程里中断服务函数的名字和中断向量的对应关系搞清楚，这一关基本就过了。第三，善用gd32e10x_it.c这个文件，中断相关的代码都往这里放，别硬塞进 main.c，养成习惯以后你会感谢自己。

最后留一个我自己的教训。我刚学的时候图快，例程跑通就立刻切下一个，一个都不回头，结果两周之后想写个按键程序，发现连 GPIO 初始化那四个参数分别是什么意思都说不全，只能重新翻例程。从那以后我每跑通一个例程，都强制走一遍「关掉例程，自己从空文件重写一遍」的流程，写不出来的地方就是没真懂的地方，回去补。这个习惯看着慢，实际上省下了大量回头重学的时间。

入门这件事，最大的门槛从来不是难度，是那种「这东西看起来好复杂」的心理负担。GD32E10x 的官方例程恰恰是把这份负担切成了十几小块，你只需要一次面对一小块。希望帮到你，早点把第一颗灯点亮。

本文还有配套的精品资源，点击获取