刚拿到客户工单的时候，我以为是又遇到了“自建ChirpStack不兼容STM32WL”的玄学问题。设备是STM32WL55JC，LoRaWAN MW 2.5.0 / MAC 1.0.4，工作在AU915频段，在TTN上验了两周一点事没有；搬到客户自建的ChirpStack上，节点入网后过几分钟就开始“装死”——串口里RTOS任务还在跑，网关却再也收不到任何上行帧。抓了一圈日志，发现冻结前最后一条收到的下行MAC命令，无一例外都是LinkADRReq。
这篇文章把整个排查链路完整写出来：从现象复现、抓包对比、AU915信道掩码解析，到最终在MAC层代码里定位到根因，以及我采用的补丁方案。如果你是做STM32WL产品、自建LoRaWAN服务器，或者正在为“TTN正常、ChirpStack不正常”这种问题头疼，这篇应该能帮你省下不少时间。
1. 现象复现：同样的固件，为什么TTN上稳如老狗，ChirpStack上一小时不到就哑了
1.1 部署背景与设备形态
先说下现场环境。节点用的是STM32WL55JC，LoRaWAN协议栈是ST官方STM32CubeWL里的MiddleWare版本2.5.0，MAC层对应LoRaWAN 1.0.4规范，区域参数选的是AU915。业务逻辑很简单，每30秒上报一次温湿度传感器数据，端口1、无应答模式；每天上报一次GPS定位数据，端口2、确认模式。
服务器端是客户自建的ChirpStack v4，网关用的是SX1302核心板，通过标准LoRaWAN包转发协议接到ChirpStack。TTN那边是同一块硬件、同一份固件，只改了OTAA的JoinEUI/AppEUI/AppKey和网络服务器地址。
在TTN上跑了14天，数据成功率超过99%，我以为这个固件已经够稳了，然后就把它直接部署到了ChirpStack。结果第一天就被打脸。
1.2 故障特征与复现步骤
故障表现非常有规律：节点上电，OTAA入网成功，开始正常上报，大概30到60秒之后，网关就再也收不到这个节点的任何上行帧。打开ChirpStack的日志，看到最后一条和这个节点相关的记录是“下行一条MAC命令”，具体就是LinkADRReq。
为了确认不是偶发，我拿了两块开发板同时测，现象一模一样。断电重启或按复位键后，节点重新入网、重新上报，然后再过几十秒被“冻结”。反复测了十几次，每次都能复现，简直比闹钟还准。
有个细节值得注意：冻结期间串口日志仍然在打印应用层的运行信息，说明MCU没有死机，RTOS调度器还在工作，只是协议栈不再往外发LoRaWAN帧。这种“半死”状态比完全死机更难排查，因为问题出在协议栈内部，而不是硬件或供电。
1.3 初步排除方向
我把可能的原因列了一遍：
- 射频硬件问题：天线匹配、PA供电异常等。但同硬件在TTN上正常，且两块板子独立复现，硬件嫌疑不大。
- 服务器配置问题：ChirpStack的AU915通道配置、ADR策略等。这个嫌疑最大，毕竟换服务器才出问题。
- 固件版本问题：MW 2.5.0 / MAC 1.0.4在AU915区域可能有已知缺陷，需要进一步确认。
- 供电或干扰：节点供电是USB直接供的，示波器看过纹波也不大，排除。
于是我把重点放在服务器差异上，特别是ADR（Adaptive Data Rate）相关逻辑。关闭ChirpStack设备配置里的ADR功能后，问题立即消失，节点可以连续运行。这基本锁定了方向：问题出在ADR机制，具体是ADR过程中的LinkADRReq命令处理。
2. 抓包验证：ChirpStack和TTN下发的LinkADRReq到底差在哪
2.1 抓包工具方案
既然怀疑LinkADRReq，那就得看清楚服务器到底发了什么。当时我用了两个手段：
第一，在ChirpStack侧开DEBUG日志。ChirpStack v4支持通过启动参数或配置文件把日志级别调到DEBUG，这样能看到网络服务器分发下行MAC命令的详细信息，包括命令类型、参数内容。TTN v3那边我直接用控制台的网关日志和事件日志，也能拿到对应的下行记录。
第二，在STM32WL固件里加“协议栈黑匣子”打印。具体做法是在LoRaWAN MAC层的下行帧处理函数里，把解析出来的所有MAC命令原始字节通过串口打印出来。这个方法比较土，但最靠谱，因为服务器日志不一定把MAC命令的原始二进制打全，而设备端打印出来的东西是确定性的。
我当时在固件里加了这样一个调试打印：
void Debug_DumpMacCommands(uint8_t *buf, uint8_t len) { for (uint8_t i = 0; i < len; i++) { printf("[MAC] %02X ", buf[i]); } printf("\r\n"); }把这个函数挂在下行帧解析入口，每次收到下行帧就把FOpts字段里的MAC命令字节全部打出来。
2.2 两边服务器下发内容的实测对比
实测数据整理成表格，差别非常明显。
| 观察项 | ChirpStack v4 | TTN v3（同设备同位置） |
|---|---|---|
| 入网后多久收到第一条LinkADRReq | 约30~60秒 | 本次长时间观察中未主动下发 |
| DataRate字段 | DR3（SF9 / 125 kHz） | 未触发 |
| TXPower字段 | 14 dBm | 未触发 |
| ChMask / ChMaskCntl | ChMask=0x00FF，ChMaskCntl=0 | 未触发 |
| NbTrans | 1 | 未触发 |
| 是否反复重发 | 是，因为没收到有效LinkADRAns | 未触发 |
| 故障是否复现 | 必现 | 未复现 |
需要说明一点：TTN那边并不是永远不发LinkADRReq，只是在同样的测试窗口内，它的ADR引擎没有像ChirpStack这样激进。TTN的ADR通常要积累足够的SNR/RSSI统计样本后才会调整参数，而且它对通道掩码的处理方式和ChirpStack也不太一样，这点后面细说。
2.3 ChirpStack的ADR策略和TTN的差异
ChirpStack从LoRaServer时代开始，ADR策略就倾向于“快速收敛”。节点入网后，只要网络服务器统计到几帧上行数据，ADR适配器就会计算目标数据速率、发射功率、信道掩码，然后立即通过LinkADRReq下发给节点。这个逻辑本身没问题，问题在于它下发的信道掩码格式，恰好踩中了STM32WL MW 2.5.0的一个实现缺陷。
TTN那边则保守得多。TTN的ADR引擎会持续观察终端的信噪比，并且倾向于保持终端当前的通道配置，只调整数据速率和功率，不会轻易把一个通道掩码子集（比如只保留0到7号通道）发给终端。所以即使设备固件存在通道掩码解析的边界缺陷，TTN也很难触碰到这个分支。
2.4 LinkADRReq在协议里的作用
简单回顾一下LinkADRReq的机制。LinkADRReq是网络服务器发给终端的MAC命令，用来调整三类参数：数据速率（通过DataRate字段）、发射功率（通过TXPower字段）、可用信道集合和重传次数（通过ChMask、ChMaskCntl、NbTrans字段）。终端收到后必须解析并执行，然后在下一帧上行里通过LinkADRAns回报这三个字段各自的确认状态。
在EU868这类频段，通道数少，掩码处理相对简单。但在AU915这类频段，上行通道多达72个，信道掩码要分成多组映射，这就给实现带来了不少边界情况。
3. 深入AU915信道掩码：那些“看起来正常”的通道配置怎么把设备带坑里
3.1 AU915的信道布局和LinkADRReq掩码映射规则
AU915频段的上行链路分成两部分：
- 64个125 kHz带宽通道，对应通道号0到63，数据速率DR0到DR4；
- 8个500 kHz带宽通道，对应通道号64到71，数据速率DR5到DR6。
LinkADRReq里的ChMask字段是16位，但AU915有72个通道，所以协议里用ChMaskCntl字段来指定这16位到底映射到哪一组通道。大致规律如下：
- ChMaskCntl=0：ChMask的bit0到bit15对应通道0到15；
- ChMaskCntl=1：对应通道16到31；
- ChMaskCntl=2：对应通道32到47；
- ChMaskCntl=3：对应通道48到63；
- ChMaskCntl=4：对应通道64到71，但只用到低8位。
还有一个容易被忽略的点：AU915的默认启用通道，通常是通道0到7这8个125 kHz通道。也就是说，如果服务器想“维持现状”，最合理的方式是发ChMask=0x00FF、ChMaskCntl=0。这个写法本身完全符合协议规范，没有任何问题。
3.2 STM32WL MW 2.5.0 的RegionAU915代码路径
问题出在设备固件怎么解释这组参数。STM32CubeWL的LoRaWAN MiddleWare沿用了Semtech LoRaMac-node的代码结构，区域相关实现放在RegionAU915.c文件里。和LinkADRReq处理相关的函数是RegionAU915LinkAdrReq。
我加了串口日志，把函数入口参数和内部计算的启用通道数都打了出来。在接收到ChirpStack下发的ChMask=0x00FF、ChMaskCntl=0这条命令后，日志显示协议栈内部计算出来的“启用通道数”是0。
也就是说，MW 2.5.0在AU915的掩码解析逻辑中，把这个“合法且常见”的通道掩码解释成了“所有通道都被禁用”。为什么会这样，我分析是代码里比特序或通道组索引处理的问题，具体到不同编译器、不同优化选项可能还有细微差异，但结果都是一样的：区域状态里没有任何可用通道。
3.3 协议栈没有对“零启用通道”做保护
如果只是解析错误也就算了，更麻烦的是，MW 2.5.0在RegionAU915LinkAdrReq里没有对“启用通道数为0”这种边界情况做防护。按照我的阅读，它验证了一堆参数，但唯独没检查“处理后通道集合是否为空”。函数返回状态是成功，上层MAC层以为配置已经生效，实际却把所有上行通道都关了。这个组合拳打下去，设备就彻底哑了。
有人可能问，协议规范里LinkADRReq不是有Status返回吗？的确，LinkADRReq对应的LinkADRAns里有一个ChannelMaskOK位，用来告诉服务器“你给的通道掩码不合法”。但固件认为这次解析是成功的，根本没有把ChannelMaskOK置0，所以也不会触发服务器的回退逻辑。
这就像快递公司生成了运单，但把仓库地址清空了，快递员拿着单子不知道去哪取件，只能一直等着，永远也发不出去。
3.4 为什么TTN不会踩到这个bug
TTN侧不是没有ADR，而是它的ADR引擎几乎不发会导致这种误判的通道掩码。它更倾向于保持默认的8个通道打开，然后用LinkADRReq里的DataRate和TXPower字段做调整。设备固件在解析时，如果掩码本身是“全开”或者保持不变，代码路径不会走到那个把通道清零的分支。
这就解释了标题里的现象：同一个固件，在TTN上稳定，在ChirpStack上必现冻结。差异不在设备，而在服务器下发的参数组合。
4. 定位根因：状态机里没有可用通道，MlmeRequest卡死
4.1 加固日志后的观测链路
定位到“通道被清零”只是第一步，还得把冻结的完整过程串起来。我在这几个关键函数里加了状态打印：
LoRaMacMcpsRequest入口和出口；LoRaMacMlmeRequest入口和出口；RegionAU915NextChannel返回时；- 应用层RTOS任务的事件等待点。
日志显示，在收到LinkADRReq之后，应用层下一次调用LoRaMacMcpsRequest(MCPS_UNCONFIRMED, ...)发送数据时，协议栈返回了LORAMAC_STATUS_NO_CHANNEL_FOUND。这个返回码本身不是致命错误，但问题在于MW内部的RTOS封装逻辑：它期望发送完成后通过McpsConfirm回调通知应用层，现在连通道都选不出来，回调永远触发不了。
应用层代码是在osThreadFlagsWait上等待发送完成标志的，超时时间设为了30秒。发送请求失败后，等待超时，任务重新执行，但下一次发送又走同样的流程，再次卡住。于是节点看起来就是“冻结”，但MCU其实还在满世界打转。
4.2 根因链完整梳理
把整个过程串起来，就是下面这条链路：
- ChirpStack在节点入网约30秒后下发LinkADRReq，参数为ChMask=0x00FF、ChMaskCntl=0、DR3；
- STM32WL MW 2.5.0的RegionAU915解析函数把这个掩码解释为“所有通道禁用”，启用通道数变成0；
- MAC层未检查通道为空这种边界情况，返回成功，状态机认为配置已更新；
- 后续所有上行发送请求进入
RegionAU915NextChannel时找不到可用通道，返回LORAMAC_STATUS_NO_CHANNEL_FOUND； - MW的RTOS封装没有对这种失败做正确的Confirm回调，应用层永久等待发送完成标志；
- 节点无法发出上行帧，形成“上行冻结”。
4.3 为什么Mac 1.0.4版本会有这种问题
LoRaWAN 1.0.4规范本身对AU915的通道掩码定义是明确的，问题不在规范，而在实现。Semtech的LoRaMac-node在某些历史版本里，对AU915/US915这种多通道区域的LinkADRReq处理一直有边界情况。MW 2.5.0对应的是某个时间点的代码快照，这个缺陷在特定配置组合下被触发了。
这个bug之所以没有在ST内部测试中被发现，大概率是因为测试环境里的网络服务器没有用ChirpStack那种ADR参数组合。换句话说，很多“服务器兼容性问题”，本质是“服务器参数组合触发了固件边界bug”。
4.4 和LoRaWAN认证测试的关联
LoRaWAN认证测试（比如典型的产品认证测试项）主要验证设备在标准参数下的行为，通常不会覆盖“服务器下发把所有通道禁用的合法掩码”这类边界用例。所以哪怕设备过了认证，也不代表它对所有服务器侧的合法参数组合都够健壮。这个教训值得每个做LoRaWAN产品的人记住。
5. 修复方案与实测：改服务器配置只能临时救急，补丁得打在协议栈里
5.1 快速恢复方案：在ChirpStack里关闭ADR
先说最快速的应急方案。如果现场需要马上恢复业务，可以把ChirpStack里这个节点的Device Profile中ADR功能关闭，或者通过API将ADR参数设为禁用。修改后节点不需要重启，下一帧上行后服务器就不会再下发LinkADRReq了，问题立刻消失。
这个方案的代价是：整网的链路自适应能力没了，所有节点固定用入网时的数据速率，距离网关远的节点可能需要更高发射功率或更低DR来保证通信，但没法自动调整。对于十几台节点的小规模部署，勉强能用；对成百上千台节点的网络，完全不可接受。
5.2 固件补丁A：启用通道数为0时拒绝应用LinkADRReq
我选择在固件侧根治。补丁A的思路是在RegionAU915LinkAdrReq里解析完ChMask后，加一个启用通道计数检查。如果启用通道数为0，直接返回LORAMAC_STATUS_PARAMETER_INVALID，并保留原来的通道配置，同时在返回的Status里把ChannelMaskOK位置0。
关键代码示意如下：
static uint8_t RegionAU915LinkAdrReq(LinkAdrReqParams_t *params, ...) { uint8_t chMaskCntl = params->ChMaskCntl; uint16_t chMask = params->ChMask; uint16_t enabledChannels = 0; // 统计本次掩码对应的启用通道数 for (uint8_t i = 0; i < 16; i++) { if ((chMask & (1UL << i)) != 0) { enabledChannels++; } } if (enabledChannels == 0) { // 所有通道都被禁用，不能应用这个配置 return LORAMAC_STATUS_PARAMETER_INVALID; } // ... 原有的通道应用逻辑 }这样修改后，即使服务器再次下发一个会把通道清零的掩码，协议栈也会拒绝应用。LinkADRAns返回给服务器时，ChannelMaskOK为0，服务器会认为终端不认可这组通道配置，从而避免进一步下发同样的错误参数。
5.3 固件补丁B：修正ChMaskCntl映射逻辑
补丁A只能防住“零通道”这个边界，但如果服务器想合法地把通道组切换到8到15号通道，设备依然可能解析错误。所以我同时做了补丁B：对照LoRaWAN 1.0.4和RP002（Regional Parameters 2）文档，把RegionAU915里ChMaskCntl到通道组的映射关系重新核对一遍，修正比特序和数组索引。
具体做法是给区域参数表加一个只读的映射数组：
typedef struct { uint8_t chMaskCntl; uint8_t startCh; uint8_t endCh; } ChMaskMap_t; static const ChMaskMap_t au915ChMaskMap[] = { {0, 0, 15}, {1, 16, 31}, {2, 32, 47}, {3, 48, 63}, {4, 64, 71}, // 5以上为保留值，按协议规范处理 };然后在LinkADRReq解析函数里，先根据ChMaskCntl查表，得到本次掩码对应的通道范围，再逐位应用。这个补丁比补丁A更治本，它确保固件对服务器发送的合法掩码组合都能正确理解。
5.4 固件补丁C：NextChannel失败时恢复发送状态机
补丁A和B解决的是“通道被错误禁用”的根因。但在实际产品里，我建议再加一道保险：当RegionAU915NextChannel返回LORAMAC_STATUS_NO_CHANNEL_FOUND时，协议栈不应该让上层无限等待Confirm
