STM32 PN532 HSU串口驱动实战：帧解析、寻卡读写与避坑

简介：面向STM32嵌入式开发者与NFC功能学习者，这是一套将PN532模块接入STM32的串口驱动工程，重点解决UART通信配置、PN532命令帧收发以及NFC卡片读写等问题。包内共211个文件，以43个.h头文件、41个.c源文件和32个.s启动/汇编文件为主体，配合Keil工程文件、hex与axf输出、map映射及少量说明文档，压缩包约3.7MB，结构覆盖底层外设、协议解析与应用示例。驱动围绕STM32的UART初始化、波特率与帧格式设置、Host Initialization握手、命令帧构建与校验、读写卡流程及超时/CRC错误处理展开，并给出中断接收优化思路，便于在STM32F103C8T6等平台上快速验证。已有1805人学习下载，适合需要从串口通信打通到NFC应用层的读者参考与二次开发。

1. 用串口跟 PN532 说话：为什么先解帧再谈驱动

多数人第一次接 PN532 都是在串口屏上盯着乱码发呆：模块明明上了电，TX/RX 也对调过了，STM32 发出去的字节却像扔进了黑洞，偶尔回几个00 FF就没了下文。问题往往不在串口配置，而在于 PN532 的 HSU（高速串行）接口并不是「发什么回什么」的透明管道——它有一套带长度字段和双重校验的帧协议，任何一帧对不上就整帧丢弃，连错误码都不给你。

这份 stm32-PN532 串口驱动资源解决的问题很具体：把 PN532 的 HSU 帧格式、命令编解码、寻卡与读写流程，在 STM32 的 USART 上做成一套可复用的驱动层，让上层只关心「发命令、拿结果」，而不用每次对着十六进制流数字节。适合正在做门禁、考勤、标签读写的嵌入式开发者，也适合手上已经有模块、卡在「能收到 ACK 但读不到卡」这一步的人。

2. HSU 帧结构拆解：从 00 00 FF 到 DCS 的自洽校验

2.1 一帧数据里每个字节在干什么

PN532 的 HSU 帧是变长的，但骨架非常固定。一帧从主机发往模块的正常数据帧长这样：

以最常见的获取固件版本命令为例，完整一帧是：

00 00 FF 02 FE D4 02 2A 00

验算一遍：LEN = 0x02表示后面跟着 TFI 加 1 字节命令字，共 2 字节；LCS = 0xFE，0x02 + 0xFE = 0x100，取低 8 位为 0，成立；DCS由0xD4 + 0x02 = 0xD6取反加一得到0x2A，成立。模块回应的帧把 TFI 换成0xD5，DATA 里第一个字节是命令字加 1（0x02对应0x03），后面跟版本信息。

真正容易翻车的是 ACK 帧。PN532 对每条命令都会先回一个固定 6 字节的确认帧：

00 00 FF 00 FF 00

注意这里的LEN = 0x00、LCS = 0xFF，如果按「LEN + LCS = 0」的规则去卡，0x00 + 0xFF = 0xFF，根本对不上。ACK 帧是协议里的硬编码特例，必须单独识别，否则你的校验函数会把每一条正常响应之前的确认帧全部判为非法，然后一直等下去。这个坑我在下面第 4 章还会展开。

2.2 STM32 侧接收状态机怎么设计

串口是字节流，帧是离散的，中间必须有一层状态机把字节流切成帧。最省事的做法是用 HAL 的HAL_UART_Receive阻塞收固定长度，但那要求你提前知道长度，而 PN532 的响应长度随命令变化，阻塞收必然错位。常见做法是逐字节中断喂状态机，或者在 DMA 环形缓冲上跑状态机，两者逻辑一致，区别只在于字节从哪来。

状态机的关键不是把所有字段都建一个状态，而是抓住三个判定点：前导码是否命中、长度与 LCS 是否自洽、DCS 是否自洽。只要这三关过了，中间的数据段基本不会错。

typedef enum { RX_HUNT, /* 搜索 00 00 FF 前导码 */ RX_LEN, /* 收 LEN */ RX_LCS, /* 收 LCS 并校验 */ RX_BODY, /* 收 TFI + DATA */ RX_DCS, /* 收 DCS 并校验 */ } pn532_rx_state_t; typedef struct { pn532_rx_state_t st; uint8_t zero_cnt; /* 连续收到的 0x00 个数 */ uint8_t len; uint8_t idx; uint8_t buf[64]; /* TFI + DATA，够放寻卡响应 */ uint8_t frame_ready; /* 1 = 收到完整合法帧 */ uint8_t ack_flag; /* 1 = 收到 ACK */ uint32_t last_tick; /* 用于超时复位 */ } pn532_rx_t; void pn532_rx_feed(pn532_rx_t *r, uint8_t b) { switch (r->st) { case RX_HUNT: if (b == 0x00) { r->zero_cnt++; } else if (b == 0xFF && r->zero_cnt >= 2) { r->st = RX_LEN; /* 命中 00 00 FF */ r->zero_cnt = 0; } else { r->zero_cnt = 0; /* 噪声字节，重新找 */ } break; case RX_LEN: r->len = b; r->st = RX_LCS; break; case RX_LCS: if ((uint8_t)(r->len + b) != 0x00) { /* 长度校验失败，但 LEN=0 的 ACK 是特例 */ if (r->len == 0x00 && b == 0xFF) { r->st = RX_DCS; /* 交给 RX_DCS 收最后那个 0x00 */ } else { r->st = RX_HUNT; } break; } r->idx = 0; r->st = (r->len == 0) ? RX_DCS : RX_BODY; break; case RX_BODY: r->buf[r->idx++] = b; if (r->idx >= r->len) r->st = RX_DCS; break; case RX_DCS: if (r->len == 0) { /* ACK 帧的收尾字节 */ if (b == 0x00) r->ack_flag = 1; } else { uint8_t sum = 0; for (uint8_t i = 0; i < r->len; i++) sum += r->buf[i]; if ((uint8_t)(sum + b) == 0x00) r->frame_ready = 1; } r->st = RX_HUNT; r->zero_cnt = 0; break; } }

这段代码的逻辑说明几点。RX_HUNT里用zero_cnt计数连续零字节，是为了容忍串口上电瞬间的噪声——如果只匹配单个0x00就期待后面跟0xFF，噪声很容易把状态机带偏，然后整帧丢失。RX_LCS分支做了双重判断：正常帧走补码校验，LEN=0且LCS=0xFF的 ACK 帧走特例通道，直接跳到收尾状态。RX_DCS里对正常帧重新累加 TFI 加 DATA 的值，与收到的 DCS 相加应为 0，这一步是整个驱动里唯一的完整性保障，不能为了省几个周期去掉。

参数上，buf开 64 字节是按最长响应估的：InListPassiveTarget在单目标模式下响应约 12~20 字节，InDataExchange读 16 字节块的数据响应约 26 字节，留一倍余量足够。如果你的应用要读 Felica 或做多目标轮询，改成 128 更稳。

2.3 组帧、发帧与最小可用代码

发送侧比接收简单，因为长度是你自己算的。但有一个边界必须处理干净：len的语义是「TFI + DATA 的字节数」，而调用者手里通常只有 DATA（命令字加参数），两者差 1，这个 off-by-one 是新手最常见的错。

/* data 只包含命令字和参数，不含 TFI；len 为 data 的字节数 */ uint8_t pn532_build(uint8_t *out, uint8_t tfi, const uint8_t *data, uint8_t len) { uint8_t n = 0, sum = 0; uint8_t body_len = len + 1; /* TFI + DATA */ out[n++] = 0x00; out[n++] = 0x00; out[n++] = 0xFF; out[n++] = body_len; out[n++] = (uint8_t)(~body_len + 1); /* LCS */ out[n++] = tfi; sum = tfi; for (uint8_t i = 0; i < len; i++) { out[n++] = data[i]; sum += data[i]; } out[n++] = (uint8_t)(~sum + 1); /* DCS */ out[n++] = 0x00; /* POSTAMBLE */ return n; /* 返回总字节数 */ }

调用时注意tfi固定传0xD4，主机永远是这个方向值。返回值是总长度，直接丢给HAL_UART_Transmit就行。

如果手上暂时没有硬件，或者怀疑是上位机算法写错了，用几行 Python 把帧拼出来对一遍是最快的排查手段，省得在板子上反复烧录：

def pn532_frame(cmd: bytes) -> bytes: body = bytes([0xD4]) + cmd ln = len(body) lcs = (-ln) & 0xFF dcs = (-sum(body)) & 0xFF return bytes([0x00, 0x00, 0xFF, ln, lcs]) + body + bytes([dcs, 0x00]) # 获取固件版本 print(pn532_frame(bytes([0x02])).hex(' ')) # 输出: 00 00 ff 02 fe d4 02 2a 00

这个脚本的价值在于它把校验逻辑用另一种语言独立实现了一遍。当 C 侧和 Python 侧对同一命令生成的帧不一致时，问题一定出在组帧函数，不用再怀疑串口线。

3. 命令链路跑通：从固件版本到寻卡 UID 的完整闭环

3.1 上电握手、SAMConfiguration 与 ACK 判定

驱动第一次跑起来，不要急着寻卡，先老老实实拿到固件版本。GetFirmwareVersion是唯一一条不需要任何前置配置的命令，能返回就说明物理链路、波特率、帧格式三样全对了。这一步过不了，后面所有调试都是空转。

上电时序上有两个动作要做。第一，模块刚上电时可能处于掉电或休眠状态，主机会先发一个唤醒帧：

/* 唤醒帧：55 55 00 00 00，不是标准数据帧格式 */ static const uint8_t wakeup_seq[5] = {0x55, 0x55, 0x00, 0x00, 0x00}; HAL_UART_Transmit(&huart2, (uint8_t *)wakeup_seq, 5, 100); HAL_Delay(10); /* 给模块留出启动时间 */

第二，等模块稳定后（数据手册里写的是启动时间在几十毫秒量级，我一般直接给 100ms 余量），再发版本查询。

发完命令，接收侧会先收到 ACK，再收到响应。很多驱动在这里写错，把 ACK 当成响应解析，结果TFI读出来是 0，后面全是垃圾。正确的顺序是：收 ACK 置位，收正式帧后清 ACK 标志。

拿到版本号之后立刻做SAMConfiguration，模式选正常模式，并决定是否使用 IRQ 引脚：

/* D4 14 01 14 01：Mode=正常模式, Timeout=0x14(20*50ms), UseIRQ=1 */ uint8_t cmd[] = {0x14, 0x01, 0x14, 0x01}; uint8_t frame[16]; uint8_t n = pn532_build(frame, 0xD4, cmd, sizeof(cmd)); pn532_send_wait_ack(frame, n, 100);

这一步不做，后面的InListPassiveTarget会返回0x13之类的错误码，也就是「配置不对」——但错误码本身不会告诉你是哪项配置不对，所以顺序不能省。

3.2 InListPassiveTarget 寻卡与 UID 解析

寻卡是这条链路里最核心的一条命令。InListPassiveTarget的命令字是0x4A，两个参数：最大目标数和波特率类型。刷卡场景一般写01 00，即只找一张、106kbps Type A。

/* D4 4A 01 00 */ uint8_t cmd[] = {0x4A, 0x01, 0x00}; uint8_t frame[16]; uint8_t n = pn532_build(frame, 0xD4, cmd, sizeof(cmd)); pn532_send_wait_ack(frame, n, 100); if (pn532_wait_frame(500) == 0) { /* r.buf = D5 4B NbTg Tg SENS_RES(2) SEL_RES NFCIDLen NFCID... */ uint8_t nfcid_len = r.buf[6]; uint8_t *uid = &r.buf[7]; uint8_t uid_len = nfcid_len; }

解析这段响应时，索引一定要对清楚。buf[0]是0xD5，buf[1]是0x4B（命令字 0x4A + 1），buf[2]是目标个数，buf[3]是目标编号，buf[4..5]是 SENS_RES，buf[6]是 SEL_RES，buf[7]才是 NFCID 长度，buf[8]起才是 UID。差一个字节，读出来的 UID 就会整体偏移，表现为「卡能寻到但比对总是不通过」。

如果寻不到卡，buf[2]会是0x00，模块返回的是一帧合法响应而不是错误，这一点和超时要区分开：超时说明链路有问题，NbTg=0说明链路正常但天线没感应到卡。

3.3 InDataExchange 读写 MIFARE 块

能拿到 UID 之后，读写卡就统一走InDataExchange（0x40）。这条命令的 DATA 部分是「透传」的——你把 ISO14443-3 的指令原样塞进去，模块负责转发。MIFARE Classic 的认证和读写都通过它走。

以读第 4 块为例，先认证再读：

/* 认证：D4 40 01 60 <block> <keyA 6B> <UID 4B> */ uint8_t auth[] = {0x40, 0x01, 0x60, 0x04, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, /* 默认 KeyA */ 0x00, 0x00, 0x00, 0x00}; /* 换成实际 UID */ uint8_t frame[32]; uint8_t n = pn532_build(frame, 0xD4, auth, sizeof(auth)); pn532_send_wait_ack(frame, n, 100); /* 响应中 buf[2] 为 0x00 表示认证成功 */

认证明文里的 UID 必须是上一步从InListPassiveTarget拿到的真实值，不能写死成00 00 00 00，这是另一个高频翻车点——写死之后认证必然返回0x01（超时）或0x14（认证失败），而错误码里不会提 UID 的事。

认证成功后读块：

/* 读块：D4 40 01 30 <block> */ uint8_t rd[] = {0x40, 0x01, 0x30, 0x04}; uint8_t n2 = pn532_build(frame, 0xD4, rd, sizeof(rd)); pn532_send_wait_ack(frame, n2, 100); /* 成功响应：D5 41 00 <status> <16 字节数据> */

写块用0xA0，后面跟 16 字节数据。写操作要特别注意超时设长一点，MIFARE 写块的耗时比读块长，超时给 100ms 在一些低成本卡上会偶发失败，我一般给到 300ms。

4. 避坑与排查：ACK 丢失、寻卡为空、数据错位的三类现场

4.1 通信层：ACK 校验和接口模式的两个雷

现象一：发完命令完全没反应，示波器上 TX 有波形、RX 一片安静。

原因通常是模块根本没工作在 HSU 模式。PN532 支持 I2C、SPI、HSU 三种主机接口，出厂默认不一定是串口，板载的拨码开关或者配置电阻决定了上电后走哪条路。多数模块用两个拨码位或者 0 欧电阻来选择，HSU 一般对应SEL0=0、SEL1=0的位置，但不同板子的丝印定义不一致，必须以模块背面印的表格为准。

解决办法是断电后用万用表量拨码位到地的通断，对照丝印确认，再上电。改完拨码必须重新上电，热切换不生效。

现象二：能收到00 00 FF 00 FF 00但永远等不到正式响应。

这说明 ACK 收到了，命令其实已经下发成功，问题出在后续帧的接收状态机。最常见的原因是第 2 章提到的 ACK 特例没有被单独处理：LEN=0时LCS是0xFF，走通用补码校验必然失败，状态机复位，正式响应来了也被当成噪声丢掉。

解决办法是把 ACK 识别做成硬编码分支，或用 6 字节滑动窗口直接比对固定序列。同时确认RX_HUNT状态在前导码匹配失败时能正确回退，不能在收到一个0x00之后就死等0xFF。

现象三：偶发收到半帧、数据从中间开始错位。

原因一般是串口上没有做流控，加上模块在上电瞬间的引脚电平不确定，RX 线上会灌进一段噪声，把状态机带偏之后，后续若干帧的边界全乱。

解决办法是在驱动初始化时先清空接收缓冲、重置状态机，然后发一次唤醒帧，让双方从确定的边界开始。另外把HAL_UART_Receive_IT的重启放在错误回调里，防止一次溢出后彻底收不到数据。

4.2 应用层：寻卡与读写的高频问题

现象四：InListPassiveTarget返回 OK，但NbTg = 0，反复寻不到卡。

链路完全正常，问题在天线侧或卡型侧。先排除最简单的：卡是不是 Type A（门禁卡里 125kHz 的 ID 卡和 PN532 玩不了，它只做 13.56MHz）；再查天线是否插紧，很多模块的天线是排针连接，松动之后读距会掉到 1cm 以内。

如果硬件没问题，多半是射频配置保守。可以先用RFConfiguration（0x32）把MxRtyATR之类的重试次数调大，把寻卡超时从默认值放宽。仍然不行就检查天线附近有没有金属或者大电流走线，13.56MHz 对金属非常敏感，贴着电池或者铝合金外壳时读距会断崖式下降。

现象五：认证返回0x14，或者认证成功但读出来的 16 字节全是FF。

0x14是认证失败，第一嫌疑是 KeyA/KeyB 不对，第二嫌疑是 UID 传错。全FF则说明块本身是空的或者写入时没写进去，不是读的问题。

解决办法是先确认卡的扇区密钥，很多出厂卡不是FF FF FF FF FF FF，尤其是二次发行的卡；然后逐字节打印InListPassiveTarget返回的 UID，把它原样填进认证命令。读写之前先做一次认证，认证状态在切换块时会失效，跨扇区读必须重新认证。

5. 参数与时序压榨：波特率切换、超时分档与低功耗唤醒

5.1 波特率切换的顺序与失败回退

115200 在寻卡场景够用，一次交互的字节量只有几十个，但如果要做连续轮询、每秒查十几次卡，把波特率提上去能明显减少阻塞时间。PN532 支持从 9600 到 1288000 的若干档，命令字是0x10，参数是速率编码。

切换的顺序有讲究，顺序错了会直接失联：

/* 第一步：用旧波特率下发切换命令 D4 10 <rate> */ uint8_t cmd[] = {0x10, 0x07}; /* 切到 921600 */ uint8_t frame[16]; uint8_t n = pn532_build(frame, 0xD4, cmd, sizeof(cmd)); HAL_UART_Transmit(&huart2, frame, n, 100); /* 第二步：等模块回 ACK，此时仍在旧波特率上 */ if (pn532_wait_ack(100) == 0) { /* 第三步：先改 MCU 侧波特率，再等模块的新速率响应 */ huart2.Init.BaudRate = 921600; HAL_UART_Init(&huart2); /* 可选：发一次 GetFirmwareVersion 验证新链路 */ }

关键是第二步和第三步之间的顺序：必须先收到 ACK 再切 MCU 波特率。如果先切 MCU，模块还来不及回 ACK，那条 ACK 就丢了，你无法判断切换是否成功。切换完成后重新发一次版本查询做确认，是比较稳妥的收尾动作。

失败回退也要写：如果切完之后版本查询超时，把 MCU 波特率改回 115200 再试一次——部分固件在切换失败时会自动回落到原速率，此时你还停在新速率上，双方就彻底失联了。

5.2 超时分档与重试策略

整条链路上有三处时间消耗，各处的超时应该分开设，而不是统一一个 500ms 了事。

第一处是发完命令等 ACK，模块内部处理很快，100ms 足够，超时基本意味着物理链路断了。第二处是等正式响应，寻卡这条命令受天线环境、卡片进入时机影响，波动最大，给 500ms 甚至 1s 都合理。第三处是InDataExchange的读写，写块的耗时最长，给 300ms 起步。

重试策略上，我一般只对「超时」重试，不对「错误码」重试。超时说明没收到响应，重发给一次机会成本很低；而收到错误码说明模块已经处理过了并且明确告诉你失败原因，重试大概率还是同样结果，不如把错误码抛给上层。重试次数控制在 2 次以内，再多就变成掩盖硬件问题了。

5.3 低功耗唤醒与 IRQ 引脚

电池供电的产品必须考虑休眠。PN532 本身可以进入低功耗检测模式，靠射频场里的卡片把它唤醒，MCU 侧就能长时间睡下去。进入休眠用PowerDown（0x16），参数0x00是可被唤醒的正常掉电模式。

唤醒靠的仍然是那个55 55 00 00 00序列。这里有个细节：模块在掉电状态下不响应标准帧，只认这个特殊唤醒帧，所以休眠之后第一步永远是发它，而不是直接发命令。

IRQ 引脚则是另一条省电路径。把模块的 IRQ 接到 MCU 的外部中断，寻卡命令发出去之后 MCU 立刻进低功耗，卡片进入场区时模块拉低 IRQ，MCU 被唤醒再收数据。这样比轮询省电得多，代价是要在SAMConfiguration里把对应的使能位打开，并且注意 IRQ 的极性和上拉配置。如果 IRQ 一直不动作，先怀疑使能位没开，再怀疑引脚接错了——这两个原因占了绝大多数。

6. 进阶验证：DMA 加空闲中断做零丢包接收，附压力测试方法

逐字节中断在 115200 下没问题，但切到 921600 之后中断频率上一个量级，加上驱动里还有别的外设要处理，丢字节的概率就上来了。表现很有迷惑性：大多数帧正常，偶尔失败一次，重试就好了，于是你以为是自己重试逻辑写得对，其实是接收层在丢数据。

稳妥的做法是 DMA 环形缓冲加空闲中断。DMA 负责把字节搬进缓冲，空闲中断负责告诉你「这一批收完了」，状态机在回调里成批消费，CPU 占用降下来，丢包也基本消失。

#define RX_BUF_SIZE 256 static uint8_t dma_buf[RX_BUF_SIZE]; static uint8_t ring[RX_BUF_SIZE]; /* 环形缓冲 */ static uint16_t head, tail; static uint16_t last_pos; /* DMA 上次搬运位置 */ /* 空闲中断回调：把 DMA 新增的字节搬进环形缓冲 */ void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t size) { uint16_t pos = RX_BUF_SIZE - __HAL_DMA_GET_COUNTER(huart->hdmarx); uint16_t last = last_pos; while (last != pos) { ring[head] = dma_buf[last]; head = (head + 1) % RX_BUF_SIZE; last = (last + 1) % RX_BUF_SIZE; } last_pos = pos; /* 游标已经绕回，重新校准 DMA，避免半缓冲判断出错 */ if (pos == 0) { __HAL_DMA_DISABLE(huart->hdmarx); __HAL_DMA_SET_COUNTER(huart->hdmarx, RX_BUF_SIZE); __HAL_DMA_ENABLE(huart->hdmarx); } pn532_rx_poll(); /* 从 ring 里取字节喂状态机 */ }

这段代码里最值得说的是 DMA 游标绕回的处理。HAL_UARTEx_RxEventCallback拿到的size在某些 HAL 版本里是本次传输的字节数，而不是绝对位置，直接用last_pos + size会算错。用__HAL_DMA_GET_COUNTER反算绝对位置更可靠，但一旦计数器绕回 0，就必须重新校准，否则环形缓冲会因长度判断失误而丢失一整圈数据。这类问题平时测不出来，只有连续跑几十分钟才暴露。

验证方法比代码更重要，因为「偶尔丢一帧」这种问题靠肉眼盯串口打印是发现不了的。我的做法是加两个计数器：一个是「发出的命令数」，一个是「收到的合法帧数」，两者在稳定的「一问一答」流程里应该严格相等。然后写一个循环，连续跑 2000 次GetFirmwareVersion，把两个计数打印出来。

如果计数相等，说明接收层没问题；如果有差额，把差额和总次数做比，差值稳定在某个数字上，往往是缓冲大小或者游标处理不当；差值是随机的，往往是波特率偏高导致的溢出。再配合一个「校验失败次数」计数器，就能区分是丢字节还是帧被误判，定位速度快很多。

我在一个模拟项目上吃过亏：单次寻卡测试一百遍全过，上产线跑连续刷卡时每隔十几分钟就漏读一次，查了三天才定位到 DMA 游标绕回时的缓冲覆盖。从那以后，任何串口协议驱动我都会先跑一遍两千次的一问一答压力测试，再看业务逻辑，这个习惯省下的时间比写驱动本身还多。希望帮到你。

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