ChirpStack LoRaWAN 编解码：JS 函数实战与避坑指南

1. 为什么要在 ChirpStack 里写 JS 编解码函数

如果你接触过 LoRaWAN 网络，大概率听说过 ChirpStack 这个开源的网络服务器。设备通过网关把数据传上来，ChirpStack 负责解包、鉴权、路由，最后把应用层数据推给你的业务系统。但这里有个问题：终端设备上报的 payload 通常是一串紧凑的二进制字节，业务系统根本看不懂。比如一个温湿度传感器上报01 02 1A 3B，你得知道第一个字节是通道号，后面两个字节是温度，最后一个是湿度，还得做定点数转换。这些活儿如果全丢给业务系统做，每个接入方都得重复实现一遍，维护起来非常痛苦。

ChirpStack 的解决思路是在网络服务器内部提供一个JavaScript 编解码函数的挂载点。设备配置里可以分别指定解码函数（decode）和编码函数（encode），前者负责把上行二进制转成 JSON，后者负责把下行 JSON 转成二进制。这样一来，业务系统拿到的就是结构化的数据，下行指令也能用人类可读的 JSON 表达。这个机制从 ChirpStack v3 一直延续到 v4，虽然 v4 在架构上做了不少调整，但 JS 编解码的核心逻辑基本没变。

这篇文章主要面向刚上手 ChirpStack、需要自己写编解码脚本的开发者。我会从实际项目出发，把 decode/encode 函数的输入输出约定、常见数据类型的处理方式、调试手段、以及几个容易踩的坑讲清楚。文中涉及的设备类型和业务场景都做了脱敏处理，但代码逻辑是通用的，你可以直接套用到自己的项目里。

注意：ChirpStack v3 和 v4 在设备配置界面上有差异，v4 把编解码函数放在了 Device Profile 里，而不是单个 Device 上。如果你用的是 v4，记得去 Device Profile 的 "Codec" 标签页配置，否则单个设备上找不到入口。

2. 编解码函数的输入输出约定与运行环境

2.1 decode 函数的入参结构

ChirpStack 调用 decode 函数时，会传入一个对象，里面包含几个关键字段。最常用的是bytes，它是一个字节数组，每个元素是 0 到 255 之间的整数。注意，不是 Buffer，也不是十六进制字符串，就是普通的 JS 数组。很多从其他平台迁移过来的开发者习惯性地用Buffer.from(bytes)去转，在 ChirpStack 的 JS 运行时里不一定能直接用，因为它的沙箱环境可能没有完整的 Node.js API。

除了bytes，入参里还有fPort，表示 LoRaWAN 的端口号。这个字段非常有用，因为同一个设备可能在不同端口上发送不同格式的数据。比如 fPort=1 是周期上报，fPort=2 是告警上报，fPort=3 是心跳。你可以在 decode 函数里根据 fPort 做分支处理，避免把所有解析逻辑混在一起。

还有一个recvTime字段，是接收时间戳。这个字段在需要做时间补偿或者判断数据时效性时会用到，但大多数场景下用不上。另外 v4 里可能会传入deviceInfo之类的上下文，但不同版本有差异，建议不要过度依赖，核心逻辑还是围绕 bytes 和 fPort 来写。

function decode(fPort, bytes) { // fPort 是端口号，bytes 是字节数组 // 返回一个对象，ChirpStack 会把它作为 decoded 数据推给应用 return { data: { // 你的解析结果 } }; }

上面这个结构是 v3 的常见写法。v4 里 decode 函数的签名可能略有不同，有的版本是decode(fPort, bytes, variables)，多了一个 variables 参数用于传入设备级变量。但核心思路一致：拿到字节，解析，返回对象。

2.2 encode 函数的入参结构

encode 函数处理的是下行。ChirpStack 会把应用层传来的 JSON 对象传给你，你需要把它转成字节数组返回。入参通常是一个对象，里面包含data字段，也就是你在应用层构造的 JSON。返回值必须是一个字节数组，每个元素 0 到 255。

function encode(fPort, data) { // data 是应用层传来的 JSON 对象 // 返回字节数组 var bytes = []; // 填充 bytes return bytes; }

这里有个容易忽略的点：encode 函数的返回值必须是纯数组，不能是 Buffer，也不能是 Uint8Array。ChirpStack 内部会遍历这个数组，把每个元素当作一个字节写入 LoRaWAN 帧。如果你返回了 Buffer，某些版本会报错，某些版本会静默失败，表现就是下行数据发不出去，但日志里又看不到明显异常。

2.3 JS 运行时的能力边界

ChirpStack 的 JS 编解码函数运行在一个沙箱环境里，不是完整的 Node.js。这意味着你不能require模块，不能用fs、net这些内置库，也不能发起网络请求。可用的就是 ECMAScript 的基础语法，加上一些 Math、Date、JSON 之类的全局对象。

这个限制其实是好事。编解码函数本来就应该是纯函数，输入确定，输出确定，不依赖外部状态。如果你发现自己的编解码逻辑需要查数据库或者调接口，那说明架构设计有问题，应该把这类逻辑放到应用层去做，而不是塞进编解码函数里。

提示：不同版本的 ChirpStack 底层用的 JS 引擎可能不同，有的用 Otto，有的用 Goja。这两个引擎对 ES6+ 的支持程度有差异。保险起见，编解码函数里尽量用 ES5 语法，避免箭头函数、let/const、模板字符串这些特性，否则可能在某些版本上跑不起来。

3. 常见传感器数据类型的解析套路

3.1 整数与定点数的处理

传感器数据里最常见的就是整数和定点数。整数好办，按字节拼接就行。比如两个字节表示一个 16 位无符号整数，高位在前：

var value = (bytes[0] << 8) | bytes[1];

如果是小端序，就反过来：

var value = (bytes[1] << 8) | bytes[0];

定点数稍微麻烦一点。很多传感器为了省字节，会把浮点数乘以一个系数后转成整数上报。比如温度精确到 0.1 度，实际值 23.5 度会上报成 235。解析的时候除以 10 就行：

var temp = ((bytes[0] << 8) | bytes[1]) / 10.0;

但这里有个坑：如果传感器上报的是有符号数，直接按无符号解析会得到错误的正值。比如 -5 度，乘以 10 是 -50，用 16 位补码表示是 0xFFCE。如果你按无符号解析，得到的是 65486，除以 10 就是 6548.6 度，明显不对。这时候需要做符号扩展：

var raw = (bytes[0] << 8) | bytes[1]; if (raw & 0x8000) { raw = raw - 0x10000; } var temp = raw / 10.0;

这个符号扩展的逻辑我见过太多人写错。有的是忘了判断最高位，有的是减错了值。记住：16 位有符号数的范围是 -32768 到 32767，如果最高位是 1，说明是负数，减去 65536 就得到正确的负值。

3.2 位域与标志位的拆解

有些设备为了极致压缩数据，会把多个状态塞进一个字节的不同位里。比如一个字节的 bit0 表示开关状态，bit1-bit3 表示档位，bit4 表示告警，bit5-bit7 保留。这种就需要用位运算来拆：

var status = bytes[0]; var powerOn = status & 0x01; var gear = (status >> 1) & 0x07; var alarm = (status >> 4) & 0x01;

位运算的优先级容易搞混，建议每个表达式都加括号。另外，移位操作在 JS 里是 32 位的，对于超过 32 位的数据要特别小心。不过 LoRaWAN 的 payload 通常很短，很少超过 32 位，这个问题不常见。

还有一种情况是多个字节拼成一个长整数，比如 4 个字节表示一个计数器。这时候用乘法和加法比移位更安全，因为移位在超过 31 位时会出问题：

var counter = bytes[0] * 16777216 + bytes[1] * 65536 + bytes[2] * 256 + bytes[3];

这样写虽然啰嗦，但不会有溢出问题。16777216 是 2 的 24 次方，65536 是 2 的 16 次方，256 是 2 的 8 次方。按权重展开，逻辑清晰。

3.3 字节序的判断与统一

字节序是编解码里最容易出错的地方。大端序（Big-Endian）是高位在前，小端序（Little-Endian）是低位在前。不同厂商的设备可能用不同的字节序，甚至同一个设备的不同字段用不同的字节序。

我的经验是：拿到一个新设备，先别急着写解析代码，先找厂商要协议文档，确认每个字段的字节序。如果文档没写，就找几个已知数值的报文来反推。比如设备上报温度 25.0 度，你抓到的报文里有两个字节是 0x00 0xFA，那 0x00FA 就是 250，说明是大端序。如果是 0xFA 0x00，那就是小端序。

在代码里，我习惯把字节序转换封装成辅助函数，这样主逻辑里就不用反复写移位：

function readUInt16BE(bytes, offset) { return (bytes[offset] << 8) | bytes[offset + 1]; } function readUInt16LE(bytes, offset) { return (bytes[offset + 1] << 8) | bytes[offset]; }

这样主逻辑里直接调readUInt16BE(bytes, 0)就行，可读性也好很多。如果设备协议里混合了大小端，这种封装能帮你少犯很多错。

4. 从零写一个完整的编解码脚本

4.1 需求拆解与协议映射

假设我们有一个虚构的环境监测设备，协议定义如下：上行 fPort=1，payload 共 6 个字节。第 1 字节是设备状态位，bit0 表示电源，bit1 表示传感器故障。第 2-3 字节是大端序有符号整数，表示温度，单位 0.1 度。第 4-5 字节是大端序无符号整数，表示湿度，单位 0.1%。第 6 字节是电池电压，单位 0.1V，无符号。

下行 fPort=2，payload 共 2 个字节。第 1 字节是命令字，0x01 表示重启，0x02 表示校准。第 2 字节是参数，重启命令时忽略，校准命令时表示校准值。

这个协议不算复杂，但涵盖了状态位、有符号数、无符号数、多字节拼接、下行编码等常见场景。我们一步步来实现。

4.2 decode 函数的完整实现

先写 decode。按照协议，我们需要从 bytes 里提取各个字段，然后组装成 JSON 返回。

function decode(fPort, bytes) { if (fPort !== 1) { return { data: { error: "unsupported fPort" } }; } if (bytes.length < 6) { return { data: { error: "payload too short" } }; } var status = bytes[0]; var powerOn = (status & 0x01) === 1; var sensorFault = ((status >> 1) & 0x01) === 1; var tempRaw = (bytes[1] << 8) | bytes[2]; if (tempRaw & 0x8000) { tempRaw = tempRaw - 0x10000; } var temperature = tempRaw / 10.0; var humidityRaw = (bytes[3] << 8) | bytes[4]; var humidity = humidityRaw / 10.0; var battery = bytes[5] / 10.0; return { data: { powerOn: powerOn, sensorFault: sensorFault, temperature: temperature, humidity: humidity, battery: battery } }; }

这段代码有几个细节值得说。第一，我加了 fPort 和长度校验，这是防御性编程。实际项目中，设备可能因为固件 bug 发错端口，或者 payload 被截断，如果不校验，解析出来的就是垃圾数据，还会污染业务系统。第二，状态位解析用了=== 1而不是直接赋值，这样返回的是布尔值，业务系统用起来更直观。第三，温度做了符号扩展，湿度没有，因为湿度按协议是无符号的。

4.3 encode 函数的完整实现

下行编码相对简单，但也要注意参数校验和字节序。

function encode(fPort, data) { if (fPort !== 2) { return []; } var cmd = data.command; var param = data.param || 0; var bytes = []; if (cmd === "reboot") { bytes.push(0x01); bytes.push(0x00); } else if (cmd === "calibrate") { bytes.push(0x02); bytes.push(param & 0xFF); } else { return []; } return bytes; }

这里我用了字符串命令而不是数字，因为应用层传 JSON 的时候，字符串更可读。如果应用层传的是数字，把判断条件改成数字比较就行。param & 0xFF是为了确保参数在 0 到 255 之间，防止应用层传了超出范围的值导致字节数组里出现非法元素。

注意：encode 函数返回空数组时，ChirpStack 会认为没有下行数据，不会发送任何帧。如果你希望发送一个空帧，至少返回一个字节，比如[0x00]。这个区别在实际调试时很容易搞混，明明 encode 被调用了，但设备就是收不到下行，最后发现是返回了空数组。

4.4 在 ChirpStack 里配置与验证

脚本写好后，需要配置到 ChirpStack 里。v3 的话，进入 Device 详情页，找到 "Codec" 或 "Payload Codec" 区域，把 decode 和 encode 函数分别粘贴进去。v4 的话，进入 Device Profile，找到 "Codec" 标签页，选择 "JavaScript" 类型，然后填入函数。

配置完成后，ChirpStack 通常会提供一个测试入口，你可以手动输入十六进制 payload 来验证 decode 结果。这个功能非常实用，建议每次修改脚本后都先在这里测一遍，确认无误再让真实设备上报。

如果测试时发现返回结果不对，先检查 bytes 数组的每个元素是不是你预期的值。有时候你以为设备发的是01 02 1A 3B，实际上因为网关或网络的问题，收到的可能是01 02 1A，少了一个字节。这种情况下 decode 函数里的长度校验就能帮你快速定位问题。

5. 调试技巧与常见错误排查

5.1 用日志输出定位问题

ChirpStack 的 JS 沙箱里通常支持console.log，输出会写到 ChirpStack 的日志里。这是最直接的调试手段。你可以在 decode 函数的关键位置打日志，比如：

console.log("fPort:", fPort); console.log("bytes:", JSON.stringify(bytes));

然后去 ChirpStack 的日志里看输出。不同版本的日志位置不一样，v3 可能在/var/log/chirpstack-network-server/下，v4 可能在 Docker 容器的 stdout 里。找到日志后，搜索你打的标记就能看到。

但要注意，生产环境里不要留太多日志，尤其是高频上报的设备，日志量会很恐怖。调试完成后记得把日志删掉，或者加个开关控制。

5.2 常见错误对照表

下面这张表列了我遇到过的高频问题，你可以对照排查：

这张表里的每一行都是我实际踩过的坑。尤其是字节序和符号扩展这两个，几乎每个新手都会中招。我的建议是：拿到新设备后，先别写完整脚本，先写一个最简单的 decode，只打印 bytes 数组，确认收到的数据和你预期的一致，然后再逐步加解析逻辑。这样出问题时容易定位是哪一步引入的。

5.3 版本差异带来的坑

ChirpStack v3 和 v4 在编解码函数的调用方式上有一些差异，如果不注意，从 v3 迁移到 v4 时会很痛苦。

v3 里，decode 函数的签名通常是function decode(fPort, bytes)，返回{ data: {...} }。v4 里，有的版本签名变成了function decode(fPort, bytes, variables)，返回结构也可能变成直接返回对象，不需要包一层data。这个差异没有统一的文档说明，不同小版本之间都可能不一样。

我的做法是：先在目标版本的 ChirpStack 里建一个测试设备，写一个最简单的 decode，返回一个固定值，然后看应用层收到的是什么结构。根据实际收到的结构来调整脚本，而不是照搬网上的示例。网上很多示例是 v3 的，直接拿到 v4 上用很可能不兼容。

另外，v4 把编解码函数从 Device 移到了 Device Profile，这意味着同一个 Profile 下的所有设备共用一套编解码逻辑。如果你的设备型号相同但固件版本不同，payload 格式有差异，就需要建多个 Device Profile，或者在一个脚本里根据 deviceInfo 做分支。后者更灵活，但代码会复杂一些。

6. 编解码脚本的工程化建议

6.1 把脚本当代码管理

很多人写编解码脚本就是直接在 ChirpStack 的文本框里敲，敲完保存，也不留备份。这种做法在设备少的时候没问题，但设备一多，或者需要多人协作，就会乱套。我的建议是把脚本存成独立的.js文件，用 Git 管理，每次修改都有记录。ChirpStack 的文本框只作为部署目标，不作为编辑环境。

具体做法是：在本地建一个目录，每个设备型号一个文件，比如device-a-decode.js、device-a-encode.js。修改后在本地测试，测试通过再粘贴到 ChirpStack 里。如果 ChirpStack 支持通过 API 配置编解码函数，那就更好了，可以写个脚本自动部署，避免手动粘贴出错。

6.2 写单元测试

JS 编解码函数是纯函数，非常适合写单元测试。你可以在本地用 Node.js 跑测试，构造各种边界情况的输入，验证输出是否符合预期。比如：

function testDecode() { var result = decode(1, [0x01, 0x00, 0xFA, 0x01, 0x2C, 0x0A]); console.assert(result.data.temperature === 25.0, "temperature should be 25.0"); console.assert(result.data.humidity === 30.0, "humidity should be 30.0"); console.assert(result.data.battery === 1.0, "battery should be 1.0"); }

这个测试用例里，温度原始值是 0x00FA 即 250，除以 10 是 25.0。湿度是 0x012C 即 300，除以 10 是 30.0。电池是 0x0A 即 10，除以 10 是 1.0。跑一遍测试，如果断言都通过，说明基本逻辑没问题。

边界情况也要测：payload 长度为 0、长度为 5（不足 6）、温度为负数、湿度为最大值 65535、电池为 0。这些情况在实际运行中都会遇到，提前测过，上线后就少出问题。

6.3 版本控制与回滚

编解码脚本一旦上线，就影响着所有该型号设备的数据解析。如果改错了，可能导致大量设备数据异常。所以每次修改都要有版本记录，并且保留回滚能力。

我的做法是在脚本文件头部加一个版本注释：

// version: 1.2.0 // date: 2024-01-15 // changes: 修复温度符号扩展问题

然后在 ChirpStack 里配置时，把版本号也记在设备文档里。如果新版本出问题，能快速找到上一个版本的文件回滚。如果 ChirpStack 支持多版本共存或者灰度发布，那就更好了，可以先在一小部分设备上验证新脚本，确认无误再全量推送。

6.4 性能考量

编解码函数会在每次上行和下行时被调用，虽然单次执行很快，但如果设备数量大、上报频率高，累积的 CPU 开销也不容忽视。优化方向主要是减少不必要的计算和内存分配。

比如，不要在 decode 里频繁创建临时对象和数组。能用基本类型就用基本类型，能复用变量就复用。字符串拼接也要小心，JSON.stringify在调试时用用可以，生产环境里如果日志级别不够高，就不要调用。

另外，避免在编解码函数里做复杂的循环和递归。LoRaWAN 的 payload 通常很短，解析逻辑应该是线性的、常数时间的。如果你发现自己的脚本里有嵌套循环，大概率是设计有问题，应该重新审视协议解析方式。

7. 几个真实项目里的经验教训

7.1 浮点数精度问题

JS 的浮点数运算有精度问题，0.1 + 0.2不等于0.3。在编解码里，这个问题主要体现在定点数转换上。比如温度原始值 235，除以 10 得到 23.5，这个没问题。但如果原始值是 233，除以 10 得到 23.299999999999997，直接返回给业务系统，显示出来就很难看。

解决办法是在返回前做一次四舍五入：

var temperature = Math.round(tempRaw / 10.0 * 10) / 10;

这样 23.299999999999997 会变成 23.3。虽然多了一次运算，但避免了业务系统显示异常。湿度、电压这些定点数字段也建议同样处理。

7.2 设备固件升级导致的协议变更

我遇到过一个情况：同一型号的设备，固件从 1.0 升到 2.0 后，payload 格式变了，多了一个字节的状态字段，导致后面所有字段的偏移量都变了。但设备型号没变，Device Profile 也没变，结果就是升级后的设备数据全部解析错误。

这个问题的根源在于：编解码脚本是绑定在 Device Profile 上的，而 Device Profile 是按设备型号划分的，不是按固件版本。如果厂商在固件升级时改了协议，但没有新增型号，就会出问题。

应对策略有两个：一是在 decode 函数里根据 payload 长度做分支，长度是 6 走旧协议，长度是 7 走新协议。二是推动厂商在固件升级时新增型号，或者至少通知你协议变更，以便及时更新脚本。前者更现实，但代码会复杂一些；后者更规范，但依赖厂商的配合。

7.3 下行编码的幂等性

encode 函数应该是幂等的，同样的输入永远产生同样的输出。但有些开发者会在 encode 里引入随机数或时间戳，比如给每个下行包加一个序列号。这在某些场景下有用，但会让调试变得困难，因为同样的 JSON 每次生成的字节数组不一样。

如果确实需要序列号，建议由应用层生成后通过 data 传进来，而不是在 encode 里生成。这样 encode 保持纯函数特性，应用层也能控制序列号的生成逻辑。编解码函数的职责应该尽量单一：只做格式转换，不做业务逻辑。

7.4 测试数据的积累

每次调试新设备时，我都会把原始的十六进制 payload 和解析后的 JSON 保存下来，形成一个测试数据集。这个数据集在后续修改脚本时非常有用，可以快速回归测试，确保修改没有破坏原有逻辑。

数据集可以是一个简单的 JSON 文件：

[ { "fPort": 1, "bytes": [1, 0, 250, 1, 44, 10], "expected": { "powerOn": true, "sensorFault": false, "temperature": 25.0, "humidity": 30.0, "battery": 1.0 } } ]

然后写一个脚本遍历这个数据集，对每条数据调用 decode，比对实际输出和 expected。这样每次改完脚本，跑一遍测试就能知道有没有引入回归问题。数据集越大，覆盖的场景越多，信心就越足。

8. 从编解码延伸出去的几个实用思路

8.1 用编解码函数做数据过滤

decode 函数除了做格式转换，还可以做简单的数据过滤。比如设备偶尔会上报异常值，温度 200 度、湿度 150%，这些明显超出物理范围的数据，可以在 decode 里直接标记为无效，而不是推给业务系统。

if (temperature < -40 || temperature > 125) { return { data: { error: "temperature out of range", raw: tempRaw } }; }

这样业务系统收到的就是明确的错误标记，而不是一个看起来正常但实际错误的值。过滤规则要根据具体传感器的量程来定，不要拍脑袋。

8.2 多端口协议的统一处理

如果一个设备在多个端口上发送不同格式的数据，decode 函数里可以用 switch 来分发：

function decode(fPort, bytes) { switch (fPort) { case 1: return decodePeriodic(bytes); case 2: return decodeAlarm(bytes); case 3: return decodeHeartbeat(bytes); default: return { data: { error: "unknown fPort" } }; } }

这样每个端口的解析逻辑独立成函数，主函数只做分发，可读性和可维护性都好很多。每个子函数可以单独测试，修改一个端口的逻辑不会影响其他端口。

8.3 编解码脚本的复用

不同设备型号的编解码脚本往往有很多相似之处，比如都有温度、湿度、电池这些字段。可以把公共的解析逻辑抽出来，做成辅助函数库，然后在各个设备的脚本里复制粘贴。虽然 ChirpStack 不支持模块导入，但你可以把辅助函数直接写在每个脚本的开头，或者维护一个模板文件，生成新脚本时从模板复制。

我自己的做法是维护一个helpers.js，里面放常用的字节读取、符号扩展、定点数转换函数。每次写新脚本时，把 helpers 的内容复制到脚本开头，然后写具体的解析逻辑。虽然有点笨，但在 ChirpStack 的限制下，这是最稳妥的方式。

8.4 监控编解码失败率

编解码函数出错时，ChirpStack 通常会记录错误日志，但不会自动告警。如果你的设备数量多，建议在应用层做一个监控：统计每个设备的上行数据里有多少是解析失败的。如果某个设备的失败率突然升高，可能是设备固件出了问题，或者编解码脚本有 bug。

实现方式很简单：在 decode 返回的对象里加一个_codecError字段，应用层收到后统计这个字段的出现频率。或者更直接一点，在 decode 里捕获异常，返回一个固定的错误结构，应用层根据这个结构做告警。

function decode(fPort, bytes) { try { // 解析逻辑 return { data: { ... } }; } catch (e) { return { data: { _codecError: e.message, _raw: bytes } }; } }

这样即使解析逻辑抛异常，也不会导致整个上行处理失败，应用层还能拿到原始数据做进一步分析。这个技巧在实际项目中非常实用，尤其是设备刚上线、协议还不稳定的时候。

8.5 编解码脚本的文档化

最后一点，也是容易被忽视的一点：给编解码脚本写文档。不要觉得脚本里有注释就够了，注释是给写代码的人看的，文档是给使用数据的人看的。业务系统的开发者需要知道每个字段的含义、单位、取值范围，这些信息应该整理成文档，和脚本一起维护。

文档可以很简单，一个 Markdown 表格就行：

这样业务系统对接时就不用反复问你了。文档和脚本放在同一个目录下，用 Git 一起管理，修改脚本时同步更新文档。时间长了，这就是团队的知识资产。

我在实际项目里最大的体会是：编解码脚本虽然看起来简单，但它是设备和业务系统之间的桥梁，一旦出错影响面很大。花时间把测试、版本管理、文档这些工程化的事情做好，远比写一个能跑的脚本重要。尤其是设备数量上去之后，一个小的解析错误可能导致成千上万条数据异常，排查起来非常痛苦。提前做好防御，比事后救火划算得多。