LoRaWAN协议栈实现

LoRaWAN 协议栈实现 · 教程导读：一本链路预算账

一个装在农田井盖下的水位传感器，要在 4.2 公里外把 12 字节的数据送到网关，用一节 2400mAh 的电池撑过五年——这件事能不能成，不取决于代码写得多优雅，而取决于一本账：发射端付出多少功率，路途上损耗多少分贝，接收端还剩多少灵敏度余量，电池里还剩多少毫安时。这套教程的写法只有一条主线：用链路预算去审视 LoRaWAN 协议栈的每一层实现。SF 为什么有七档、接收窗口为什么开那么短、Join 为什么要等 5 秒、ADR 为什么一次只降一档——这些看似孤立的标准条文，在链路预算这本账上全部能对上号。

三个真实的翻车现场

讲清这本账的价值，先看三个工程现场的翻车案例。

案例一：满功率换不来一公里。 一个园区抄表项目照抄了别家的配置：SF7、14dBm 发射功率。表计装在金属井盖下，信号出井就衰减了 20dB，网关在 800 米外收不到。团队本能地继续加发射功率，发现 EU868 上限就是 14dBm，再加功率这条路走不通。翻账本才知道：SF7 在 125kHz 带宽下接收灵敏度约 -123dBm，穿透井盖后链路预算只剩不到 5dB 余量，而无线信道的阴影衰落动辄 10dB 以上——这个余量打这样的信道，等于雨天不带伞。把 SF 换到 SF10，灵敏度改善 12dB，问题立刻消失，代价是空中时间变长 32 倍、单包能耗上升。你看，账本上的每一个数字都在牵动别的数字。

案例二：电池寿命缩水到八个月。 一个温控标签项目原型阶段一切正常，量产三个月后续航集体腰斩。排查发现：固件里把"上行后开接收窗口"实现成了"上行后常开接收直到收到 ACK"，RX 持续电流 11mA，而 Class A 规范定义的 RX1 只有 5 个符号时长的前导窗口。这不是算法错误，是时间账没算：接收窗口每多开一秒，就多烧 11 毫安秒，一天上行 24 次，一年就是 3400 毫安时——半节电池就这么没了。

案例三：一分钱省出十倍运维。 一个城市级燃气表项目为了省网关，把站间距从 2 公里拉到 4 公里。链路账面上"刚好够"（余量 3dB），投产第一年，雨季来临时表计在线率从 99% 跌到 87%。雨衰、树叶生长、季节性衰落把那 3dB 余量吃光了。最后补建了三分之一的基站。链路预算不是及格线，是风险线——余量给多少，取决于你能容忍多大的掉线率。

这三个案例的共同教训：LoRaWAN 协议栈的每一项实现决策，本质都是一次预算分配。射频层分配频谱与功率，MAC 层分配时隙与字节，安全层分配计算周期，架构层分配内存与电流，部署层分配网关密度与信道容量。谁算得清这本账，谁就能在标准条文与现实约束之间做出正确取舍；谁不算账，谁就在靠运气做工程。

图 0-1 全册知识地图：链路预算如何贯穿九层账本

这张图是全册的行军路线。第 1 章先立起账本框架（dB、余量、空中时间、电流预算四大记账科目）；第 2、3 章下探物理层与 MAC 层，看灵敏度和时隙怎么从调制参数里算出来；第 4 章把安全开销计入账本；第 5 章盘点软件架构层的内存与电流账；第 6 章讲 ADR 这个"自动记账调参器"如何动态平衡各科目；第 7 章把视角抬到网络侧，看网关与网络服务器怎么管理一张更大的账；第 8 章教你场测与容量规划，把账本对准真实世界；第 9 章看向中继与卫星，看预算约束被推到极限时协议如何重构。

本教程不覆盖什么

先划清边界，免得你在错误的期待里翻页。不覆盖的：LoRa 联盟标准文档的逐条翻译——我们只讲每条规则背后那笔账，条文的完整原文请查 RP001 与各区域参数规范；不覆盖具体芯片的完整数据手册参数（本文出现的寄存器与电气参数以 Semtech SX1276 与 STM32L0 系列为代表，换芯片请翻对应手册）；不覆盖 LoRaWAN 以外的 LPWAN 制式（NB-IoT、Sigfox）的内部实现，只在第 1 章的选型对比里过一次招；不覆盖网络服务器的分布式部署与云原生运维——那是后端工程师的疆域，我们只讲到"网络服务器在账本上管什么"为止；不覆盖硬件射频电路设计（天线匹配、PCB 布局），协议栈视角下天线只是路径损耗公式里的一个增益项。

需要什么基础

代码：看得懂 C 语言——指针、结构体、状态机 switch-case、中断服务函数。协议栈实现的主语言就是 C，本书代码片段全部可以按伪 C 读。数学：高中对数 + 电路欧姆定律。链路预算的全部数学是 dB 的加减法和"功率×时间=电量"的乘除法，不需要通信原理的积分。经验：玩过任意一块开发板（Arduino 也行），烧录过程序，用过串口打印。不需要预先懂射频——第 2 章会把扩频调制讲到刚好够用的深度；不需要预先懂密码学——第 4 章从"AES 是个换字节的黑盒"讲起。

术语约定

全书统一几处叫法，避免和标准文档打架时找不到北：上行/下行指终端发往网关、网关发往终端的方向；**终端（End Device）**指传感器节点本身，模组、节点、设备在本书里同义；**网关（Gateway）**只做物理层转发、不做 MAC 解析，这一点和 Zigbee 协调器有本质区别，第 7 章细讲；**DR（Data Rate）**是数据速率档位的统称，一个 DR 编号绑定一组 SF 与带宽；**空中时间（ToA，Time on Air）**指一帧信号占用信道的物理时长，是贯穿全册的核心记账单位；**余量（Margin）**指链路预算减去路径损耗后剩下的 dB 数，本书一律指"中值余量"，衰落余量单列。dBm 是绝对功率（以 1 毫瓦为零点），dB 是相对差值，两者能加减的前提是分清楚谁是锚点——这个区别第 1 章会用三道算例钉死。

你会怎么学

每章由一个问答型支柱页开篇：先亮出本章要回答的两三个真问题，再交代这些问题为什么值得问，然后一张分工表告诉你每节负责哪一问。每一节聚焦一到三个知识点，多数从一笔具体的账算起——先手工算一遍建立直觉，再对照协议栈源码看工程上怎么落地，中间穿插可复现的案例（背景、操作、结果、解读、变式五环齐全）和排错实录。代码片段以可读的小段为主：状态机骨架、定时器算式、密钥派生伪码、链路预算表格。你可以拿任何一款 LoRa 开发板跟着算，没有硬件也能用书里的数值做纸上演练。

读完后你能做什么

• 拿到任何一个部署场景（距离、地形、报文长度、上报频率、目标续航），手工算出大致可行的 SF/功率组合，并说出余量给多少才稳；
• 读懂 LoRaMac-node 这类开源协议栈的目录结构与关键路径，知道把接收窗口时长、ADR 步长这类参数改在哪儿、改成什么值有什么代价；
• 对一次现场掉线，能按"物理层→MAC 层→网络层"的顺序翻账排查，而不是盲目重启网关；
• 在选型会上用量化的账目论证网关密度、频段选择、Class A/B/C 的取舍，而不是引用别人的经验值；
• 看懂 Relay、LR-FHSS 这些新规范在改什么账——它们都是在原有预算科目里开辟新科目，理解了账本框架，新规范只需要读一遍。

最后交代一句写作立场：本书对标准的态度是"每条规则先问它在保护哪笔预算"。有些规则（比如占空比 1%）在你的部署里可能是负担，理解它保护的对象之后，怎么取舍就是你的工程判断，而不是对条文的盲从。带着账本读协议，是我所知最快的路径。