1. 从一块最小系统和 GPS 模块说起:代码开发工具能省掉哪些手写初始化
拿到一块 STM32F103ZET6 最小系统和一块串口输出的 GPS 模块,接上线,串口助手里立刻滚出一屏 $GPGGA,... 报文,不少人到这一步就认为例程跑通了。真正的活其实在后面:让 MCU 自己收、自己拆字段、自己吐出经纬度和时间。这类链路的初始化如果全靠手写,时钟、引脚复用、DMA 通道、中断优先级里任何一项没对齐,后面的调试就全白费,所以我更愿意先用代码开发工具把底层骨架生成出来,把时间花在协议和解析上。
这篇按 STM32CubeMX 的实际操作顺序走一遍:UART 怎么配、DMA 怎么挂、NMEA 报文怎么拆、上板之后哪里最容易翻车。适合已经点亮过 LED、但被串口接收和协议解析卡住的人,也适合手上有现成板子想直接照着配的。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具里的 UART+DMA 配置:时钟、引脚与接收链路一次配通
2.1 先把模块手册上的串口参数抄下来
GPS 模块上电之后是单向往外吐报文的,MCU 只管收,不需要发指令去问。所以第一件事不是打开 CubeMX,而是翻模块手册第一页,把三个参数确认下来:波特率、数据格式、电平。
波特率多数模块出厂是 9600,也有设成 38400 或 115200 的,不同批次可能不一样,这个数字后面要原样填进 CubeMX,填错就是满屏乱码。数据格式基本固定在 8 位数据、无校验、1 位停止位,NMEA 报文本身是纯 ASCII,用不到 9 位或者校验位。电平是 3.3V TTL,模块的 TX 接 MCU 的 RX,模块的 RX 接 MCU 的 TX,两边 GND 必须共起来——只接信号线不接地,是后面各种「玄学收不到」的头号来源。
只做接收的话,其实模块 RX 那根线可以不接,但我的习惯是把它也接出来,因为调试阶段经常需要把解析结果从 MCU 的 TX 打回串口助手,和模块原始报文并排对比,省一个 USB 转串口。
2.2 时钟树决定串口能不能出正确的波特率
STM32F103ZET6 的 USART1 挂在 APB2 总线上,USART2 和 USART3 挂在 APB1 上,两条总线的时钟频率不一样,这直接决定串口分频能不能除得尽。常见配置是把 SYSCLK 拉到 72MHz,APB2 不分频保持 72MHz,APB1 二分频到 36MHz。
波特率是拿总线时钟分频出来的,分频系数除不尽就有误差,误差小的时候表现为偶发校验失败,误差大的时候就是整屏乱码,而且这个问题在 CubeMX 的界面上完全看不出来,只能靠算或者靠实测反推。所以配时钟的时候别随手拖,先想清楚串口挂在哪条总线上。
| 配置页 | 配置项 | 取值 | 说明 |
|---|---|---|---|
| RCC | HSE | Crystal/Ceramic Resonator | 板上有 8MHz 晶振就选它,比内部 RC 稳 |
| Clock Configuration | SYSCLK | 72 MHz | F103 系列的常见上限 |
| Clock Configuration | APB1 Prescaler | /2 | 36 MHz,USART2/3 挂这里 |
| Clock Configuration | APB2 Prescaler | /1 | 72 MHz,USART1 挂这里 |
| Connectivity > USART1 | Mode | Asynchronous | 单向接收不用硬件流控 |
| Connectivity > USART1 | Baud Rate | 9600 | 必须与模块手册一致 |
| Connectivity > USART1 | Word Length | 8 Bits | NMEA 是 ASCII |
| Connectivity > USART1 | Parity | None | 同上 |
| Connectivity > USART1 | Stop Bits | 1 | 同上 |
引脚在 CubeMX 里选了 Asynchronous 模式之后会自动分配,USART1 默认落到 PA9(TX)和 PA10(RX),如果板子上这两个脚被别的外设占了,就在引脚图上改到重映射脚位,改完记得回头看一眼串口配置页有没有变红。
2.3 DMA 那条链路:谁搬数据、谁判帧尾
GPS 是持续不断往外吐的,如果每个字节都进一次中断,CPU 大部分时间都在做搬运工。用 DMA 接住数据流,CPU 只在「一帧收完」的时候被打断一次,这才是合理的分工。
在 CubeMX 的 DMA Settings 页点 Add,选 USART1_RX,方向会自动填成 Peripheral To Memory,数据宽度两边都是 Byte,模式选 Circular。Circular 这个选项很关键:Normal 模式下 DMA 搬完指定长度就停了,必须靠代码手动重开,只要漏一次,后面就再也收不到数据,而现场表现就是「上电头几秒正常,之后完全没反应」,特别容易误判成模块坏了。
NVIC 页里把 USART1 global interrupt 勾上,优先级给个中等值就行,不用抢在系统滴答前面。配置完点生成代码,CubeMX 会把 DMA 初始化、串口初始化、中断使能按顺序排进 main.c。
c复制/* CubeMX 生成的 USART1 初始化骨架,保留关键几行 */
huart1.Instance = USART1;
huart1.Init.BaudRate = 9600; /* 与模块手册一致 */
huart1.Init.WordLength = UART_WORDLENGTH_8B;
huart1.Init.StopBits = UART_STOPBITS_1;
huart1.Init.Parity = UART_PARITY_NONE;
huart1.Init.Mode = UART_MODE_TX_RX;
huart1.Init.HwFlowCtl = UART_HWCONTROL_NONE;
huart1.Init.OverSampling = UART_OVERSAMPLING_16;
if (HAL_UART_Init(&huart1) != HAL_OK)
{
Error_Handler();
}
这段代码是生成出来的,正常情况下不用手写,但每一行对应界面上哪个勾选项得心里有数,出错时才知道回哪儿改。常见的错误做法是在 main 里补一句 huart1.Init.BaudRate = 115200; 就以为改了波特率——初始化函数已经跑完了,改结构体成员不会重新配置硬件,必须改完再调一次 HAL_UART_Init,或者干脆回 CubeMX 改完重新生成。
2.4 启动接收的那一行,位置比内容重要
DMA 配好只是把管子接上了,真正让数据流起来的是启动接收这一句。它必须放在 while(1) 之前、所有外设初始化之后,放进去就只执行一次,之后靠回调自己续命。
c复制#define GPS_BUF_SIZE 256
uint8_t gps_dma_buf[GPS_BUF_SIZE];
/* 启动 DMA + 空闲中断接收,长度是本次接收的上限,不是收满才回调 */
if (HAL_UARTEx_ReceiveToIdle_DMA(&huart1, gps_dma_buf, GPS_BUF_SIZE) != HAL_OK)
{
Error_Handler();
}
/* 关掉半传输中断,避免缓冲区填一半时就触发一次回调 */
__HAL_DMA_DISABLE_IT(&hdma_usart1_rx, DMA_IT_HT);
HAL_UARTEx_ReceiveToIdle_DMA 里的 Size 参数容易被理解错:它不是「收满 256 字节才回调」,而是本次接收允许的最大长度,实际触发条件是总线空闲。NMEA 一帧通常几十个字节,256 是个留了余量的安全值。
半传输中断默认是开的,缓冲区写到一半也会进一次回调,如果解析逻辑只认整帧,这一下就会拿到半截数据。关掉它是最省事的处理,代价是失去了「前半段缓冲区可用」的流水线机会,但对 GPS 这种低速率数据源完全无所谓。
2.5 生成工程后先检查三处再看现象
第一处是 main.c 里的调用顺序,MX_DMA_Init 必须在 MX_USART1_UART_Init 之前。CubeMX 生成的顺序一般是对的,但只要手动挪过代码块就可能被打乱,DMA 时钟没开就去配串口,现象是一个字节都收不到,而且编译零告警。
第二处是 DMA 句柄和串口句柄的关联,huart1.hdmaRx 应该指向 hdma_usart1_rx,CubeMX 会自动填好,但如果你在代码里手动改过 DMA 配置,这层关联有可能断掉。断掉的表现是串口能发不能收。
第三处是编译完先别急着写解析,做一遍透传:把 DMA 收到的字节原样从 TX 发回去,用串口助手看是否和模块直连时看到的报文一模一样。链路通了再动解析,出了问题是解析的锅还是接收的锅,一目了然。这一步花五分钟,能省掉后面两个小时的互相怀疑。
3. NMEA 报文拆解:解析器该按什么顺序写
3.1 一条语句的五段结构
随便抓一行报文:$GPGGA,114530.00,3958.1234,N,11619.5678,E,1,08,0.92,45.2,M,-8.5,M,,*6A。拆开看是五段。
$ 是起始符,解析器认它来对齐帧头。GPGGA 是语句地址,前两位 GP 是 Talker 标识,换北斗模块可能变成 BD 或 GN,后三位 GGA 是语句类型,这个才是决定后面字段含义的部分。中间一大串是逗号分隔的数据字段。* 后面两位十六进制是校验和,覆盖 $ 和 * 之间的全部字符。最后是 CR LF 收尾。
这里最需要记住的一点是:空字段是合法的。未定位时经纬度字段干脆是空的,两个逗号直接挨在一起,这不是报文损坏,是模块在明确告诉你「这项现在没有值」。后面用字符串切分函数的时候,这个特性会把不处理它的人坑得很惨。
3.2 GGA 和 RMC 两条就够用了
模块一次会吐好几种语句,全解析既没必要也浪费 CPU。定位场景里 GGA 和 RMC 覆盖了绝大部分需求:位置、时间、定位质量、卫星数、速度、日期。
| 字段序号 | GGA 含义 | RMC 含义 |
|---|---|---|
| 1 | UTC 时间 hhmmss.ss | UTC 时间 hhmmss.ss |
| 2 | 纬度 ddmm.mmmm | 定位状态 A 有效 / V 无效 |
| 3 | 纬度半球 N/S | 纬度 ddmm.mmmm |
| 4 | 经度 dddmm.mmmm | 纬度半球 N/S |
| 5 | 经度半球 E/W | 经度 dddmm.mmmm |
| 6 | 定位质量 0 无效 1 单点 2 差分 | 经度半球 E/W |
| 7 | 使用卫星数 | 地面速度,单位节 |
| 8 | HDOP 水平精度因子 | 航向,单位度 |
| 9 | 海拔高度,单位米 | UTC 日期 ddmmyy |
两张表放在一起看会发现字段序号完全对不上,这是最容易出错的地方——照着 GGA 的序号去读 RMC 的速度字段,读出来的会是经度。所以解析函数里必须先按语句地址分发,再拿字段。
纬度经度是「度分」格式而不是十进制度,3958.1234 表示 39 度 58.1234 分,换算要拆成整数部分和分钟部分:度数取整数除法,分钟部分除以 60 再加回去。这一步不换算直接当十进制度用,位置会偏出去几十公里,而且在室内测试时因为坐标本身就是乱的,还不一定看得出来。
3.3 校验和:不验不是不能跑,是跑起来心里没底
校验和的算法很简单,$ 之后、* 之前的所有字符做异或,结果用两位十六进制表示。这个过程值得写成一个独立函数,因为它是丢弃脏数据的第一道闸。
c复制/* 校验 $ 与 * 之间的字符异或,返回 0 表示通过 */
static int nmea_checksum_ok(const char *line)
{
const char *p = line;
uint8_t sum = 0;
if (*p != '$')
{
return -1;
}
for (p++; (*p != '\0') && (*p != '*'); p++)
{
sum ^= (uint8_t)(*p);
}
if (*p != '*')
{
return -1; /* 没有校验和字段,视为不完整帧 */
}
return (strtoul(p + 1, NULL, 16) == sum) ? 0 : -1;
}
strtoul 用十六进制解析时会自动在 CR 或 LF 处停下,所以不用额外把行尾截掉。返回非 0 的整行直接丢,不要抱着「先解析看看能不能用」的心态放过——校验不过说明这帧在传输中已经失真,字段内容不可信,拿去算坐标只会得到更隐蔽的错误。
3.4 切字段别直接上 strtok
这是我在这个链路上踩得最深的一个坑。strtok 会把连续的分隔符当成一个处理,而 NMEA 里的空字段恰恰就是「两个逗号挨着」。一旦中间有一个空字段被吞掉,它后面所有字段的位置都会整体前移一位,这时候你按序号取纬度,拿到的是半球标识,程序不崩,数据全错。
正确的做法是手动扫描,每个逗号都切一刀,空字段保留成一个长度为零的字符串。
c复制/* 按逗号切分,空字段保留,返回切出来的字段个数 */
static int nmea_split(char *line, char *fields[], int max_fields)
{
int n = 0;
char *p = line;
if (*p == '$')
{
p++; /* 跳过起始符 */
}
while ((n < max_fields) && (*p != '\0') && (*p != '*'))
{
fields[n++] = p; /* 当前字段起点 */
char *comma = strchr(p, ',');
if (comma == NULL)
{
break; /* 最后一个字段 */
}
*comma = '\0'; /* 就地截断 */
p = comma + 1;
}
return n;
}
* 处就停止扫描,校验和不会混进字段数组。空字段切出来的结果是一个指向 \0 的指针,用之前判断 fields[i][0] == '\0' 即可,不需要额外的标志位。这个函数就地修改原缓冲区,所以传进来的必须是一份可以破坏的副本,直接拿 DMA 缓冲区往里传,会把还没解析的后续帧一起写坏。
4. 代码开发工具生成工程之后:空闲中断 + 解析层的落点
4.1 帧边界从哪来
DMA 负责搬字节,但它不知道一帧在哪里结束。NMEA 用 CR LF 收尾,理论上可以在缓冲区里找 \n,但更省事也更稳的办法是让硬件告诉你:总线静默超过一个字符时间,空闲中断就会触发,此时 DMA 已经停下,回调里的 Size 参数就是这一帧实际收到的字节数。
这正好对上 GPS 报文不定长的特点,短的一帧五六十字节,长的一帧八九十字节,都不需要提前约定。代价是帧与帧之间必须真的有空隙,好在小速率串口上这几乎总是成立的。
c复制/* 空闲中断回调:只做拷贝和重启接收,不做任何解析 */
void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t Size)
{
if (huart->Instance == USART1)
{
ringbuf_put(&gps_rb, gps_dma_buf, Size); /* 拷进环形缓冲 */
HAL_UARTEx_ReceiveToIdle_DMA(&huart1, gps_dma_buf, GPS_BUF_SIZE);
}
}
回调里绝对不能做解析。9600 波特率下一个字节约 1ms,256 字节的缓冲区最快一秒多就会被下一次接收覆盖,如果中途跑了一次带浮点运算和打印的解析,重入和覆盖就都来了。回调要短到只有几条赋值,把活留给主循环。
4.2 环形缓冲把收和解析解耦
环形缓冲的作用是给接收侧和解析侧各留一段跑道,两边不用等对方。接收侧只管往 head 位置写,解析侧只管从 tail 位置读,两边都只在指针上做原子的加减,不需要关中断。
容量按最坏情况估:串口一秒最多吐多少字节,乘以解析一次的最长耗时,再留三倍余量。GPS 模块 9600 波特率下每秒大概 960 字节,一帧解析加打印控制在 5ms 以内,一千字节的缓冲就绰绰有余。
有一个细节容易忽略:ringbuf_put 收到的 Size 是这一帧的字节数,但缓冲区里可能还躺着上一帧没被取走的尾部,如果环形缓冲容量不够,新帧会把旧帧的尾巴盖掉,解析时看到的就是半截报文接半截报文。把容量放大、并在取行函数里明确「找不到换行符就丢弃当前行」,是两道保险。
4.3 解析层放主循环,按行取、按地址分发
主循环里不断尝试从环形缓冲取出一整行,校验通过再分发到具体语句的解析分支。
c复制char line[NMEA_LINE_MAX];
char *f[20];
while (ringbuf_getline(&gps_rb, line, sizeof(line)) == 0)
{
if (nmea_checksum_ok(line) != 0)
{
gps_stat.checksum_err++;
continue; /* 校验不过整帧丢弃 */
}
int n = nmea_split(line, f, 20);
if (n < 10)
{
continue; /* 字段数不足,说明帧被截断 */
}
if (strcmp(f[0], "GPGGA") == 0)
{
gps_fix.quality = atoi(f[6]);
if (gps_fix.quality == 0)
{
continue; /* 未定位,后面的经纬度没有意义 */
}
gps_fix.lat = nmea_ddmm_to_deg(atof(f[2]), f[3][0]);
gps_fix.lon = nmea_ddmm_to_deg(atof(f[4]), f[5][0]);
gps_fix.sats = atoi(f[7]);
}
else if (strcmp(f[0], "GPRMC") == 0)
{
if (f[2][0] == 'A') /* A 有效,V 无效 */
{
gps_fix.speed_knots = atof(f[7]);
}
}
}
两处判断值得单独说。n < 10 这道门槛是拦截断帧的,正常 GGA 有十几个字段,少于十个基本可以断定这帧没接完。quality == 0 的判断必须放在坐标换算之前,很多现场报告的「经纬度一直是 0」其实是模块还没锁星,解析器把空的纬度字段当 0 处理,然后一路传下去,看起来像是解析写错了,实际是没定位。
4.4 度分转换与半球符号
经纬度的换算本身只有几行,但符号处理错了会让位置镜像到地球另一边,而这种错误在静态测试里很难发现,因为设备不动,你只会觉得「怎么和地图对不上」。
c复制/* ddmm.mmmm + 半球字符 -> 十进制度,南纬西经取负 */
static double nmea_ddmm_to_deg(double ddmm, char hemi)
{
int deg = (int)(ddmm / 100.0);
double min = ddmm - deg * 100.0;
double v = deg + min / 60.0;
return (hemi == 'S' || hemi == 'W') ? -v : v;
}
ddmm 除以 100 取整得到度,余下的小数部分就是分钟。半球字符只有 N/S/E/W 四种,用字符直接比,不要用 ASCII 差值做偏移,那样可读性差而且容易写错。
4.5 怎么确认解析对了
三个对照一起做,基本不会错。第一是把原始行打印出来,和串口助手直连模块时看到的报文比对,确认经过 DMA 和环形缓冲之后一个字节没少。第二是把 nmea_split 切出来的字段个数打印出来,正常 GGA 稳定在十几个,如果一直是 10 或者波动很大,说明帧被截断了。第三是挑一条报文手工算一遍校验和,和程序打印的结果对一次,确认算法本身没写反。
位置对不对,可以拿静止状态下的经纬度去地图上比,和实际位置差几十米是正常的漂移,差一个数量级就是换算错了。时间字段比本地时间早 8 小时是正常的,报文里是 UTC,不是解析出错。
5. 常见问题排查:能收到报文却定位不了,多半卡在这五处
5.1 接收侧:一个字节都没有、只收到第一帧、满屏乱码
现象一:上电之后一个字节都收不到,串口助手也没有任何输出。
原因通常有三个层次。最外层是接线,模块 TX 没接到 MCU RX,或者两根线没共地,信号没有参考电平。中间层是初始化顺序,MX_DMA_Init 排到了串口初始化后面,DMA 时钟没开就配通道,编译无告警但硬件不工作。最内层是启动接收那一行没被执行,比如误放进了某个条件分支或者被前面的阻塞代码挡住了。
解决顺序是从外往里:先只接模块 TX、MCU RX 和 GND 三根线,用 USB 转串口直连模块确认它确实在吐报文;再翻 main.c 看 MX_DMA_Init 的位置;最后在启动接收那句后面打个断点或者点个灯,确认真的执行到了。
现象二:上电头几秒能收到,之后彻底没反应,复位又好了。
基本可以断定是 DMA 配置成了 Normal 模式,搬完设定长度就停,而回调里又没有重新启动接收。这个问题特别有欺骗性,因为一开始数据是好的,很容易让人往模块耗电、天线干扰那些方向猜。回 CubeMX 把 DMA 模式改成 Circular,并且在 HAL_UARTEx_RxEventCallback 末尾无条件重新调用一次接收函数,两个动作做齐。
现象三:满屏乱码,偶尔能蹦出半条像样的报文。
波特率对不上是第一嫌疑,模块手册写 9600 而代码里填了 115200,或者反过来。第二嫌疑是时钟树配错,串口挂在 APB1 上但按 APB2 的频率算分频。第三嫌疑是电平不匹配,5V 模块直连 3.3V 引脚,波形削顶之后边沿判断全乱。
前两个回 CubeMX 对着改,第三个要加电平转换或者确认模块本身支持 3.3V。还有一种情况是乱码只在特定位置出现,比如每次接线一动就变,那多半是地线接触不良,这类问题靠看代码永远找不到,得拿手去碰线。
5.2 解析侧:字段整体错位、定位一直是无效值
现象四:坐标读出来完全不对,但报文本身看着正常。
第一反应往往是换算公式写错了,实际上更常见的是切分环节把空字段吞掉了。用 strtok 处理 ,, 这种连续分隔符时,空的纬度字段被直接跳过,后面的半球字符、经度、定位质量全部前移一位,于是「纬度」变成了「北纬标识」,「经度」变成了「东经标识」,程序不崩,数值荒唐。
解决就是换成手动扫描的切分函数,每个逗号都切一刀,空字段保留为空字符串。改完之后把字段个数打印出来对一遍,正常 GGA 的字段数是稳定的,一旦开始波动就说明还有帧没接完整。
现象五:卫星数在涨,坐标却一直是 0 或者一直不变。
先看 GGA 的第 6 个字段,定位质量是 0 就代表模块自己都认为当前没有有效定位,这时候经纬度字段本来就是空的,被 atof 转成 0 完全是预期行为。冷启动阶段模块要下载星历,室内靠窗也要等几分钟,这不是代码问题。
如果质量字段已经是 1 而坐标还是不动,那就往解析分支里查:是不是 strcmp(f[0], "GPGGA") 里的字符串写成了 GPRMC,或者模块实际输出的是 GNGGA 而不是 GPGGA。多系统模块的 Talker 标识会变,硬编码 GP 前缀是很容易翻车的一处,稳妥的写法是比较后三位 GGA,前两位放开。
6. 把 GPS 收成可复用模块:上板验证顺序与两个固化习惯
链路调通之后不要急着往下叠业务,先按一套固定顺序把这条链路验一遍,后面任何改动都能拿这套流程回查。
| 步骤 | 做法 | 通过标准 |
|---|---|---|
| 1 链路 | 只接模块 TX、GND,串口助手直连 | 稳定滚出 $ 开头的行 |
| 2 接收 | MCU 打印收到的原始字节 | 与串口助手看到的内容逐字节一致 |
| 3 帧长 | 打印每次回调的 Size | 每帧几十字节且长度有波动 |
| 4 校验 | 统计校验失败的帧数 | 稳定后应接近 0,上电初期允许少量 |
| 5 解析 | 打印经纬度、时间、卫星数 | 与已知位置一致,南北纬符号正确 |
| 6 挂机 | 连续跑 30 分钟 | 不丢帧、不重启、缓冲不溢出 |
这里面第 3 步最容易被跳过,但它能一次性暴露帧截断和缓冲区覆盖两类问题。Size 如果长期恒定在某一个值,说明多半是 DMA 长度到了而不是空闲中断触发,那时候你收到的其实是「被切齐」的数据,看似能用,实则不可靠。
两个我后来固化下来的习惯。第一个是把解析结果收进一个结构体,主循环只更新结构体,其他模块只在需要的时候读快照,不在解析函数里直接调打印或者发无线——打印是阻塞的,一阻塞缓冲就开始堆,堆满就丢帧,这个因果关系在调试阶段特别隐蔽。第二个是每次改完 CubeMX 重新生成代码之前,把所有手写逻辑挪到独立的 .c 文件里,main.c 里只留调用。生成代码会覆盖 main.c 的用户代码区之外的内容,血泪经验是曾经把整个解析函数写在 while(1) 前面,重新生成之后没了,对着编译报错愣了半小时才反应过来。
再往上走一步,可以把 GPS 模块包装成一个只暴露三个接口的小组件:初始化、取最新定位快照、注册定位更新回调。内部怎么用 DMA、怎么切环形缓冲,外面完全不用知道,换一块不同波特率的模块,只改初始化参数就行。做嵌入式做久了会发现,真正省时间的不是把功能写出来,而是把「下次改的时候不用重读一遍代码」这件事提前做好。
从那以后我每次动串口接收这部分,都会先把透传跑通、把 Size 打印出来看一眼,再写解析。希望帮到你。
