简介OneNET平台NB-IOT接入开发文档面向使用OneNET完成NB-IoT终端接入与第三方应用开发的工程师提供从设备侧到平台侧的系统性技术指引。内容围绕SDK移植到MCU、通信模组和NB芯片的前期准备以及创建产品设备、软硬件初始化、登录平台、订阅与发现资源等接入步骤展开并覆盖第三方应用接入验证、明文与密文数据推送、设备增删查、资源读写、命令下发、离线命令、触发器及批量查询等API用法。压缩包仅含1个docx文件大小约1.73MB目录清晰便于集中查阅与随项目归档。接入实例说明MCU侧工作流程与平台侧数据收发过程协议章节解析LWM2M逻辑实体、接口、CoAP协议栈、块传输和安全传输并附常见问题适合对照实现联调与排错。目前已有1090人学习可作为NB-IoT项目接入和应用开发时的参考手册。1. 从一块永远灰着的模组说起去年帮一个做智能水表的团队排查问题模组串口 AT 回显一切正常信号值也漂亮但设备在平台上永远是灰点。翻了两个晚上的日志才发现endpoint name 里的 IMEI 少打了一位平台侧压根没完成鉴权。这类问题在 NB-IoT 项目里太常见了——协议本身不难难的是注册、对象建模、订阅发现这几步的时序任何一环对不上表现出来的症状都一样设备离线。这份《NB-IoT 接入开发文档》就是围绕这条链路展开的设备侧的 SDK 怎么移植到 MCU、通信模组或 NB 芯片三条路线上平台侧怎么建产品建设备应用侧怎么接数据推送、怎么调 API 读写资源。它面向的是手里已经有 NB 模组、但还没跑通第一个注册流程的嵌入式开发以及要对接平台数据流的应用侧开发。接下来我按自己拆这份文档的顺序把整条链路、可抄的代码和踩过的坑一次讲透。2. 端到端链路拆解设备、平台、应用三侧怎么分工2.1 一条数据要走的三段路NB-IoT 设备的数据不会直接怼到应用服务器上中间必然隔着一个平台。整条路径是终端设备经空口连到基站再由运营商核心网把数据转发到平台平台完成解析、存储和鉴权之后才通过推送或 API 把数据交给第三方应用。设备侧和应用侧根本不认识对方双方都只跟平台打交道这是理解整个接入模型的前提。三侧的职责边界很清楚动手前先对着这张表确认自己站在哪一格角色主要职责典型产出终端设备侧移植基础通信套件、建对象实例、维持注册、响应读写设备在线、资源可读可写平台侧设备鉴权、资源目录维护、数据存储、命令路由虚拟设备、数据点、触发器第三方应用侧接收推送、解析消息、调 API 下发命令业务系统里的设备台账与指令这里有个容易被忽略的前置条件设备所在网络的核心网必须对目标平台放行。不同运营商的 NB-IoT 核心网接入策略不一样有的要求设备侧走特定 APN有的需要平台侧先做白名单备案。我一般会在写第一行代码之前先拿一台样机单独验证「能不能 ping 通平台的 CoAP 端口」这一步不通后面所有调试都是在浪费时间。2.2 为什么选 LwM2M 而不是自定义协议物联网平台早期很多方案是自定义二进制协议设备侧和平台侧各写一套解析改一个字段两边都要发版。这套文档选的 LwM2M 把「设备是什么、有哪些属性、怎么读写」标准化了设备只要按规范建模平台侧不用为每个新型号写适配代码。LwM2M 的逻辑实体只有三个LwM2M Client 跑在设备上LwM2M Server 就是平台Bootstrap Server 负责下发初始配置这套接入里用得不多一般靠设备出厂烧录 endpoint 和密钥。实体之间的四个逻辑接口分别是引导、注册、设备管理与服务使能、信息上报对应到实际动作就是设备上线注册一次之后平台随时可以读它、写它、订阅它的变化。资源模型是 Object / Instance / Resource 三层。Object 表示某一类传感器Instance 表示同类传感器的第几个Resource 是具体属性。URI 长这样/3311/0/5851读作「光照控制对象、第 0 个实例、亮度资源」。用一个 JSON 把模型描述出来最直观{ obj_id: 3311, obj_name: IPSO Light Control, instances: [ { inst_id: 0, resources: [ { res_id: 5850, name: On/Off, type: bool, access: RW }, { res_id: 5851, name: Dimmer, type: int, range: 0-100, access: RW } ] } ] }obj_id建议直接用 IPSO 标准里已定义的编号比如 3311 是光照控制、3200 是数字输入、3201 是模拟输入标准编号平台侧天然认识能省掉一堆自定义映射。res_id5850 是布尔开关、5851 是 0 到 100 的整数这类资源平台会自动识别成可读可写。参数说明里那个access别随手写成 R否则应用侧下发命令时会直接被平台拦掉报错信息还很不直观。2.3 CoAP 承载与块传输的取舍LwM2M 的消息最终落在 CoAP 上CoAP 跑在 UDP 之上再往下才是 NB-IoT 的空口。选 UDP 是因为 NB 场景下设备大部分时间在 PSM 休眠TCP 的长连接保活代价太高一次心跳可能就把电量预算吃掉大半。代价是可靠性要自己做CoAP 用 CON 消息加 ACK 确认超时按指数退避重传默认 2 秒起步最多重传 4 次。设备注册报文里几个字段值得盯endpoint name 是设备在平台上的唯一标识一般直接用 IMEIlifetime 是注册有效期单位秒到期不续注册平台就会把设备标成离线binding 在 NB 场景通常只有 UDP 一种。抓包确认注册有没有真正发出去我一般这么过滤# 只抓 CoAP 默认端口看设备到底有没有把注册报文发出去 tcpdump -i any -n udp port 5683 -c 50 -vv # 设备侧如果走 DTLS端口换成 5684能同时看到握手失败的原因 tcpdump -i any -n udp port 5684 -c 20 -vv第一个命令用来判断「设备根本没发」还是「发了平台没回」这是排查离线问题的第一刀能省掉大量猜测。第二个命令针对安全传输DTLS 握手失败时设备侧往往只打印一个超时抓包才能看到是 PSK 不匹配还是证书链有问题。块传输Block1 / Block2是为大payload 准备的。NB 的单次上行包很小超过 MTU 的资源列表或批量数据点必须分块请求里带Block2选项和块号平台逐块返回。实际开发里我很少手动处理块传输SDK 会自己协商但要知道它的存在——当你在日志里看到同一个 URI 连续出现好几次 GET块号在递增那是正常的分块读取不是设备在疯狂重试。3. 设备侧落地三条 SDK 移植路线怎么选3.1 三种终端架构的横向对比文档把终端分成三类本质上是「协议栈放在哪一层」的问题。选错了架构后面每加一个传感器都要多写一层胶水代码所以这个决定要在硬件选型阶段就定下来架构SDK 位置开发者要写什么适合谁MCU 通信模组MCU协议栈移植、驱动、业务逻辑已有成熟 MCU 方案、要深度定制MCU 通信模组通信模组只写业务逻辑调 AT 指令快速出货、团队偏应用层NB 芯片 SoC芯片全栈含 RTOS 与驱动成本敏感、超低功耗第一列和第二列长得一样区别只在协议栈跑在哪颗芯片上。第二列的好处是模组厂商已经把 LwM2M 栈和 AT 封装做完了MCU 只需要发ATxxx就能建对象、报数据坏处是出了问题你只能看到 AT 返回码排查深度有限。第一列反过来控制力最强但移植工作量最大。3.2 移植到 MCU先做传输适配层协议栈本身不关心数据是从串口、SPI 还是以太网出去的所以移植的第一步永远是写一个传输适配层把收发收上来再把协议栈需要的鉴权信息喂进去。用函数指针表是最省事的做法换模组的时候只改这一张表/* 传输适配层协议栈只认这张表换模组只改实现 */ typedef struct { int32_t (*init)(void *cfg); /* 上电初始化返回 0 成功 */ int32_t (*send)(const uint8_t *buf, uint32_t len); /* 阻塞发送超时由底层兜底 */ int32_t (*recv)(uint8_t *buf, uint32_t len, uint32_t timeout_ms); int32_t (*get_imei)(char *out, uint8_t out_len); /* 鉴权用15 位数字 */ int32_t (*get_imsi)(char *out, uint8_t out_len); /* 鉴权用与 IMEI 二选一或并存 */ int32_t (*get_csq)(int8_t *rsrp); /* 信号强度排障用 */ } lwm2m_net_ops_t; int32_t lwm2m_port_register(const lwm2m_net_ops_t *ops);send和recv必须实现成阻塞语义因为 NB 模组在 PSM 唤醒后重新附着网络需要几百毫秒到几秒不等非阻塞实现很容易在附着期间丢掉第一批报文。get_imei和get_imsi两个回调返回的字符串必须和平台侧录入的完全一致大小写、位数都不能差前面那个水表项目就是栽在这里。get_csq不参与协议流程但强烈建议实现出问题时能第一时间排除「信号不好」这个最大嫌疑。适配层打通之后剩下的就是驱动和 RTOS 的对接。如果 MCU 上有现成 RTOS把recv挂在一个独立任务里其他地方只管往发送队列扔数据裸机方案则要自己维护一个状态机注意别在中断里做 CoAP 重传计时。3.3 移植到模组AT 指令封装下的边界感协议栈在模组里的时候MCU 侧看到的是一串 AT 指令。典型的上电序列大致长这样具体指令以模组手册为准AT # 握手确认串口通 ATCGSN # 读 IMEI拿去平台注册设备 ATCIMI # 读 IMSI ATCSQ # 信号质量10 基本可以认为环境有问题 ATNRB # 模组重启重新附着网络ATCSQ返回的第一个数字是 RSSINB 场景下只要不低于 10 就算能用低于 5 的时候别急着查代码先挪设备位置。ATCGSN和ATCIMI读出来的两串数字要和平台后台录的逐位核对这一步我建议直接打印到串口日志里方便肉眼比对。这种架构下最容易踩的坑是把 AT 指令当成同步调用。模组附着网络、注册到平台都是异步的OK只代表指令收到不代表业务成功。正确做法是给每条关键指令配一个超时和完成标志等到模组主动上报REG:1之类的状态再继续往下走否则会出现「代码以为上线了实际还在附着」的假在线。3.4 平台侧建产品与设备设备真正上线之前平台上必须先有一个「虚拟设备」等着它。创建产品时几个下拉框是有因果关系的接入方式选公开协议、联网方式选 NB-IoT、接入协议选 LwM2M。选错接入协议是最常见的返工原因选了别的协议栈之后设备发过来的注册报文平台根本不认但界面上又看不出任何异常。建完产品紧接着添加设备要填的字段就三个关键项设备名称自己看着起、IMEI、IMSI。是否开启自动订阅这个开关值得多说一句——开了之后设备侧创建的资源会自动同步到平台侧的虚拟设备资源列表里省掉手动维护不开的话资源列表要靠平台主动 Discover 去拉。我一般会开因为调试期资源模型经常改自动同步能少一轮对齐。3.5 设备侧五步初始化、建设备、加资源、登录、订阅发现这是整个接入里最核心的一段代码五步的顺序不能乱。初始化完成之后创建设备对象把鉴权信息和回调挂上去lwm2m_dev_t dev; memset(dev, 0, sizeof(dev)); strcpy(dev.endpoint, 86xxxxxxxxxxxxx); /* 一般就是 IMEI必须与平台录入一致 */ dev.lifetime 86400; /* 注册有效期 24 小时可按上报频率调整 */ dev.binding BINDING_UDP; /* NB 场景通常只开 UDP */ dev.cb.read on_read; /* 平台读资源时回调 */ dev.cb.write on_write; /* 平台写资源时回调 */ dev.cb.exec on_exec; /* 平台下发命令时回调 */ lwm2m_dev_create(dev);endpoint一旦确定就不能改改了等于换了一台新设备平台侧得重新建。lifetime设太短会让设备频繁续注册NB 场景下每次唤醒都要耗电86400 秒是个比较稳的起点如果设备本身是每天只上报一次的水表可以拉到 604800 秒。三个回调函数必须实现write没实现的话应用侧下发命令会直接超时而且平台侧只显示「命令已下发」看不出设备压根没处理。设备建好之后往里面塞对象实例和资源注意 SDK 里创建的资源要挂在实例下面实例挂对象下面lwm2m_obj_t *light lwm2m_obj_create(dev, 3311); /* IPSO Light Control */ lwm2m_inst_t *ins0 lwm2m_inst_create(light, 0); /* 第 0 个实例 */ lwm2m_res_create(ins0, 5850, TYPE_BOOL, ACC_RW, onoff); /* 开关可读可写 */ lwm2m_res_create(ins0, 5851, TYPE_INT, ACC_RW, dimmer);/* 亮度 0-100 */第三步登录成败全看返回码int32_t ret lwm2m_dev_login(dev); if (ret ! LWM2M_OK) { /* -1 网络未通 -2 鉴权失败 -3 lifetime 非法 -4 无可用对象 */ log_error(login failed: %d, ret); return ret; }-2鉴权失败九成是 IMEI / IMSI 对不上-4则是对象列表为空SDK 不允许登录一台没有任何资源的设备。登录成功后平台侧圆点会从灰变绿紧接着平台会下发 Observer 和 Discover 两条消息Observer 是订阅请求SDK 收到后自动维护观测记录之后资源变化会主动上报Discover 是让设备把对象和属性报一遍。这两条消息 SDK 内部处理业务代码不用管但一定要在日志里能看到它们看不到就说明注册流程其实没走完。4. 第三方应用对接握手、解密与 API 编排4.1 URL 加 Token 的握手验证应用侧接收数据的前提是先跟平台建立连接而这个「建立连接」不是长连接是一次 HTTP 回调验证。平台配置好应用地址后会带着签名参数请求你的服务你校验签名再把 echostr 原样吐回去握手才算完成。签名规则是把 Token、timestamp、nonce 三个值按字典序排好拼成一串做 SHA1。Token 是你自己在平台配置页填的随便定但别用弱口令const crypto require(crypto); const TOKEN process.env.PUSH_TOKEN; // 平台配置页里自定义的那串 token function verify(req, res) { const { msg_signature, timestamp, nonce, echostr } req.query; const raw [TOKEN, timestamp, nonce].sort().join(); // 字典序排序后拼接 const sign crypto.createHash(sha1).update(raw).digest(hex); if (sign ! msg_signature) return res.status(401).send(invalid signature); return res.send(echostr); // 必须原样返回带引号或换行都算失败 }msg_signature是平台算好的签名timestamp和nonce参与排序。这里最常见的翻车是回包内容多了个换行或者框架自动加了 JSON 包装平台侧看到回包对不上就判定验证失败但界面上只会提示一句「验证不通过」不会告诉你差在哪。我一般会在回包前打个日志把echostr的字节长度记下来比对一次就清楚了。4.2 明文与密文消息AES 解密怎么写握手通过之后设备上传的每条数据都会推过来。消息体有两个模式明文模式直接给你 JSON安全模式给你一段 Base64 密文加签名。安全模式的密钥是平台生成的 AESKey配置页上能看到也能自己指定。解密逻辑如下function decrypt(encrypted, aesKeyBase64) { // 平台给的是 43 位 base64 串补一个 还原成 32 字节密钥 const key Buffer.from(aesKeyBase64 , base64); const iv key.slice(0, 16); // 约定 IV 取密钥前 16 字节 const decipher crypto.createDecipheriv(aes-256-cbc, key, iv); decipher.setAutoPadding(true); // PKCS#7 填充 return Buffer.concat([ decipher.update(encrypted, base64), decipher.final() ]).toString(utf8); }密钥 32 字节对应 AES-256-CBCIV 直接取密钥前 16 字节这是平台侧固定的约定换别的 IV 出来的明文就是乱码。填充用 PKCS#7Node 默认就开着不用手动 Unpad。解出来的 JSON 里几个字段要认准type区分是数据上报还是设备上下线事件dev_id对应平台侧设备 IDds_id是数据流 IDat是时间戳。线上环境务必用安全模式加 HTTPS明文模式只适合本地联调。4.3 常用 API读写资源、下发命令、批量取数据点应用侧主动操作设备靠的是 HTTPS 的 REST 接口鉴权方式是请求头里带api-key。创建设备、读资源、下发命令这三类用得最多# 创建一个设备auth_info 填 IMEIobsv 打开自动订阅 curl -X POST https://api-host/devices \ -H api-key: your-apikey \ -H Content-Type: application/json \ -d {title:meter-001,auth_info:86xxxxxxxxxxxxx,obsv:true} # 读指定对象的资源obj_id/obj_inst_id 与设备侧建模保持一致 curl https://api-host/devices/device_id/resources?obj_id3311obj_inst_id0 \ -H api-key: your-apikey # 下发命令body 里的 key 是资源 ID curl -X POST https://api-host/cmds?device_iddevice_id \ -H api-key: your-apikey \ -H Content-Type: application/json \ -d {name:set_dimmer,body:{5851:80}}读资源那条命令里obj_id和obj_inst_id跟设备侧建模必须一一对应设备上报了 3311/0 而你去查 3311/1返回的是空数组而不是报错很容易误判成设备没数据。下发命令有个坑设备处于 PSM 休眠时命令会进离线队列接口照样返回成功但不代表设备已经执行要看命令状态回执或者用离线命令接口单独查。除了这三类触发器、批量查设备状态、批量查最新数据、按时间段查数据点这几组接口在运维阶段很有用。批量查设备状态一次能带几十个设备 ID比循环单查省很多次请求查数据点接口支持分页返回结构里带cursor翻页时把它带上就行。5. 常见问题排查五类高频翻车现场5.1 五条踩坑记录第一条设备一直离线圆点始终是灰的。现象是串口打印一切正常注册报文也发出去了。原因基本锁定在两处要么 endpoint name 里的 IMEI 与平台录入的不一致少位、大小写、多了空格要么平台侧设备的 IMSI 填错了。解决方式是两边各打一份出来逐位比对我习惯在设备启动时把 IMEI 和 IMSI 一起打印对着平台页面念一遍比 grep 日志快。第二条登录成功但平台侧资源列表是空的。现象是设备在线读资源却返回空。原因是设备只建了对象没建实例或者实例建了但没挂资源SDK 允许这种半成品状态通过注册。解决办法是把资源创建代码放在登录之前并且登录前加一句断言资源数量为 0 直接不发起登录。第三条平台显示在线但下发命令一直超时。现象是命令接口返回成功设备侧毫无反应。原因多半是write或exec回调没实现或者实现里把obj_id判断错了收到写请求直接走默认分支返回失败。解决办法是在回调入口先打一行日志把 URI 打出来确认平台请求的到底是/3311/0/5851还是别的路径。第四条推送地址验证通过但一条数据都收不到。现象是握手时返回 200之后静默。原因通常是推送配置里的推送时间限制和推送数据限制设得太保守平台在攒够一批才推或者安全模式下 AESKey 填成了明文但验签逻辑还在按密文解析。解决办法是先把推送频率设成实时、关闭安全模式跑通一条数据再逐步把两项能力加回来。第五条批量接口返回的数据点时间和本地对不上。现象是查出来的数据比本地时间早或者晚几个小时。原因是接口默认按 UTC 处理请求参数里没显式指定时区。解决办法是所有时间参数统一用带时区的 ISO 格式传别传裸时间戳字符串。5.2 排障顺序从串口到平台出问题的时候不要一上来就翻应用侧代码先按链路走一遍。第一刀抓包看设备报文有没有出去第二刀看平台有没有回 ACK第三刀看设备有没有处理平台下发的 Observer第四刀才轮到应用侧。前两刀用 tcpdump 就够了# 看设备有没有把注册报文发出去有没有收到响应 tcpdump -i any -n udp port 5683 -c 50 -vv # 看应用侧有没有收到平台推送如果对接方是自己的服务直接在服务上抓 tcpdump -i any -n tcp port 80 or tcp port 443 -c 30 -A第一个命令解决「设备到底动没动」的问题如果一条报文都没有问题在硬件或网络附着。第二个命令解决「平台推没推」的问题如果一段时间内完全没有请求打进来那就不用怀疑解密逻辑了先去查平台的推送配置和 URL 可达性。6. 二次开发把能跑通的 Demo 改成能交付的系统从跑通第一个注册流程到能支撑几百上千台设备的业务系统中间隔着几件事都是我在项目后期反反复复改过的。第一件事是把对象模型配置化。设备侧的资源定义如果硬编码在 C 文件里每来一个新型号就得改代码重新烧录。我的做法是抽一张资源描述表编译期生成静态数组运行期遍历建对象型号变只改表协议栈代码一行不动。表里至少要包含 obj_id、inst_id、res_id、类型、权限和回调入口六个字段缺一个后面就得打补丁。第二件事是应用侧的握手和解密做成中间件。验签、解密、消息分发这三步几乎每个推送回调都要走一遍散在业务代码里等哪天要换加密模式改起来能让人崩溃。收拢成一个装饰器或者拦截器业务侧只拿到解密后的 JSON改加密策略时只动一个文件。第三件事是补上离线命令的闭环。前面提过 PSM 休眠时命令只是进队列接口返回成功不代表执行成功。二次开发里必须有一个轮询或回调机制去查命令最终状态落一张状态表超时未执行的命令走重试或者告警。这块不做运维阶段你会收到大量「我点了没反应」的反馈而你在后台看到的全是成功。第四件事是给批量接口加限流和缓存。批量查设备状态、批量查最新数据这两类接口在仪表盘上会被高频调用直接透传到平台侧很快就会撞到调用频率限制。加一层几百毫秒的本地缓存配合一个请求合并队列能挡掉绝大部分重复请求。改造后的验证方法不用太复杂我一般准备三样东西一台故意配错 IMEI 的设备用来验证鉴权失败的报错是否可读、一个模拟平台推送的脚本用来验证解密和分发、一份离线命令的状态流转单用来确认超时重试有没有真的触发。这三样跑通基本可以交付了。从那以后我每次接新的物联网平台接入项目都会先拿一台设备把「注册、读资源、下发命令」这三件事走完再碰业务代码任何一步卡住就停下来查透绝不让它带着隐患往下走——毕竟在 NB 这种低频上报的场景里一个没跑通的注册流程可能要等到明天早上设备唤醒时才暴露。希望这些拆解和踩坑记录能帮你把第一台设备的绿点亮起来。本文还有配套的精品资源点击获取 
长河君 · 2026/10/29 22:59:38 · 阅读 1.2k NB-IoT设备接入全链路：LwM2M注册、SDK移植与离线排查
简介OneNET平台NB-IOT接入开发文档面向使用OneNET完成NB-IoT终端接入与第三方应用开发的工程师提供从设备侧到平台侧的系统性技术指引。内容围绕SDK移植到MCU、通信模组和NB芯片的前期准备以及创建产品设备、软硬件初始化、登录平台、订阅与发现资源等接入步骤展开并覆盖第三方应用接入验证、明文与密文数据推送、设备增删查、资源读写、命令下发、离线命令、触发器及批量查询等API用法。压缩包仅含1个docx文件大小约1.73MB目录清晰便于集中查阅与随项目归档。接入实例说明MCU侧工作流程与平台侧数据收发过程协议章节解析LWM2M逻辑实体、接口、CoAP协议栈、块传输和安全传输并附常见问题适合对照实现联调与排错。目前已有1090人学习可作为NB-IoT项目接入和应用开发时的参考手册。1. 从一块永远灰着的模组说起去年帮一个做智能水表的团队排查问题模组串口 AT 回显一切正常信号值也漂亮但设备在平台上永远是灰点。翻了两个晚上的日志才发现endpoint name 里的 IMEI 少打了一位平台侧压根没完成鉴权。这类问题在 NB-IoT 项目里太常见了——协议本身不难难的是注册、对象建模、订阅发现这几步的时序任何一环对不上表现出来的症状都一样设备离线。这份《NB-IoT 接入开发文档》就是围绕这条链路展开的设备侧的 SDK 怎么移植到 MCU、通信模组或 NB 芯片三条路线上平台侧怎么建产品建设备应用侧怎么接数据推送、怎么调 API 读写资源。它面向的是手里已经有 NB 模组、但还没跑通第一个注册流程的嵌入式开发以及要对接平台数据流的应用侧开发。接下来我按自己拆这份文档的顺序把整条链路、可抄的代码和踩过的坑一次讲透。2. 端到端链路拆解设备、平台、应用三侧怎么分工2.1 一条数据要走的三段路NB-IoT 设备的数据不会直接怼到应用服务器上中间必然隔着一个平台。整条路径是终端设备经空口连到基站再由运营商核心网把数据转发到平台平台完成解析、存储和鉴权之后才通过推送或 API 把数据交给第三方应用。设备侧和应用侧根本不认识对方双方都只跟平台打交道这是理解整个接入模型的前提。三侧的职责边界很清楚动手前先对着这张表确认自己站在哪一格角色主要职责典型产出终端设备侧移植基础通信套件、建对象实例、维持注册、响应读写设备在线、资源可读可写平台侧设备鉴权、资源目录维护、数据存储、命令路由虚拟设备、数据点、触发器第三方应用侧接收推送、解析消息、调 API 下发命令业务系统里的设备台账与指令这里有个容易被忽略的前置条件设备所在网络的核心网必须对目标平台放行。不同运营商的 NB-IoT 核心网接入策略不一样有的要求设备侧走特定 APN有的需要平台侧先做白名单备案。我一般会在写第一行代码之前先拿一台样机单独验证「能不能 ping 通平台的 CoAP 端口」这一步不通后面所有调试都是在浪费时间。2.2 为什么选 LwM2M 而不是自定义协议物联网平台早期很多方案是自定义二进制协议设备侧和平台侧各写一套解析改一个字段两边都要发版。这套文档选的 LwM2M 把「设备是什么、有哪些属性、怎么读写」标准化了设备只要按规范建模平台侧不用为每个新型号写适配代码。LwM2M 的逻辑实体只有三个LwM2M Client 跑在设备上LwM2M Server 就是平台Bootstrap Server 负责下发初始配置这套接入里用得不多一般靠设备出厂烧录 endpoint 和密钥。实体之间的四个逻辑接口分别是引导、注册、设备管理与服务使能、信息上报对应到实际动作就是设备上线注册一次之后平台随时可以读它、写它、订阅它的变化。资源模型是 Object / Instance / Resource 三层。Object 表示某一类传感器Instance 表示同类传感器的第几个Resource 是具体属性。URI 长这样/3311/0/5851读作「光照控制对象、第 0 个实例、亮度资源」。用一个 JSON 把模型描述出来最直观{ obj_id: 3311, obj_name: IPSO Light Control, instances: [ { inst_id: 0, resources: [ { res_id: 5850, name: On/Off, type: bool, access: RW }, { res_id: 5851, name: Dimmer, type: int, range: 0-100, access: RW } ] } ] }obj_id建议直接用 IPSO 标准里已定义的编号比如 3311 是光照控制、3200 是数字输入、3201 是模拟输入标准编号平台侧天然认识能省掉一堆自定义映射。res_id5850 是布尔开关、5851 是 0 到 100 的整数这类资源平台会自动识别成可读可写。参数说明里那个access别随手写成 R否则应用侧下发命令时会直接被平台拦掉报错信息还很不直观。2.3 CoAP 承载与块传输的取舍LwM2M 的消息最终落在 CoAP 上CoAP 跑在 UDP 之上再往下才是 NB-IoT 的空口。选 UDP 是因为 NB 场景下设备大部分时间在 PSM 休眠TCP 的长连接保活代价太高一次心跳可能就把电量预算吃掉大半。代价是可靠性要自己做CoAP 用 CON 消息加 ACK 确认超时按指数退避重传默认 2 秒起步最多重传 4 次。设备注册报文里几个字段值得盯endpoint name 是设备在平台上的唯一标识一般直接用 IMEIlifetime 是注册有效期单位秒到期不续注册平台就会把设备标成离线binding 在 NB 场景通常只有 UDP 一种。抓包确认注册有没有真正发出去我一般这么过滤# 只抓 CoAP 默认端口看设备到底有没有把注册报文发出去 tcpdump -i any -n udp port 5683 -c 50 -vv # 设备侧如果走 DTLS端口换成 5684能同时看到握手失败的原因 tcpdump -i any -n udp port 5684 -c 20 -vv第一个命令用来判断「设备根本没发」还是「发了平台没回」这是排查离线问题的第一刀能省掉大量猜测。第二个命令针对安全传输DTLS 握手失败时设备侧往往只打印一个超时抓包才能看到是 PSK 不匹配还是证书链有问题。块传输Block1 / Block2是为大payload 准备的。NB 的单次上行包很小超过 MTU 的资源列表或批量数据点必须分块请求里带Block2选项和块号平台逐块返回。实际开发里我很少手动处理块传输SDK 会自己协商但要知道它的存在——当你在日志里看到同一个 URI 连续出现好几次 GET块号在递增那是正常的分块读取不是设备在疯狂重试。3. 设备侧落地三条 SDK 移植路线怎么选3.1 三种终端架构的横向对比文档把终端分成三类本质上是「协议栈放在哪一层」的问题。选错了架构后面每加一个传感器都要多写一层胶水代码所以这个决定要在硬件选型阶段就定下来架构SDK 位置开发者要写什么适合谁MCU 通信模组MCU协议栈移植、驱动、业务逻辑已有成熟 MCU 方案、要深度定制MCU 通信模组通信模组只写业务逻辑调 AT 指令快速出货、团队偏应用层NB 芯片 SoC芯片全栈含 RTOS 与驱动成本敏感、超低功耗第一列和第二列长得一样区别只在协议栈跑在哪颗芯片上。第二列的好处是模组厂商已经把 LwM2M 栈和 AT 封装做完了MCU 只需要发ATxxx就能建对象、报数据坏处是出了问题你只能看到 AT 返回码排查深度有限。第一列反过来控制力最强但移植工作量最大。3.2 移植到 MCU先做传输适配层协议栈本身不关心数据是从串口、SPI 还是以太网出去的所以移植的第一步永远是写一个传输适配层把收发收上来再把协议栈需要的鉴权信息喂进去。用函数指针表是最省事的做法换模组的时候只改这一张表/* 传输适配层协议栈只认这张表换模组只改实现 */ typedef struct { int32_t (*init)(void *cfg); /* 上电初始化返回 0 成功 */ int32_t (*send)(const uint8_t *buf, uint32_t len); /* 阻塞发送超时由底层兜底 */ int32_t (*recv)(uint8_t *buf, uint32_t len, uint32_t timeout_ms); int32_t (*get_imei)(char *out, uint8_t out_len); /* 鉴权用15 位数字 */ int32_t (*get_imsi)(char *out, uint8_t out_len); /* 鉴权用与 IMEI 二选一或并存 */ int32_t (*get_csq)(int8_t *rsrp); /* 信号强度排障用 */ } lwm2m_net_ops_t; int32_t lwm2m_port_register(const lwm2m_net_ops_t *ops);send和recv必须实现成阻塞语义因为 NB 模组在 PSM 唤醒后重新附着网络需要几百毫秒到几秒不等非阻塞实现很容易在附着期间丢掉第一批报文。get_imei和get_imsi两个回调返回的字符串必须和平台侧录入的完全一致大小写、位数都不能差前面那个水表项目就是栽在这里。get_csq不参与协议流程但强烈建议实现出问题时能第一时间排除「信号不好」这个最大嫌疑。适配层打通之后剩下的就是驱动和 RTOS 的对接。如果 MCU 上有现成 RTOS把recv挂在一个独立任务里其他地方只管往发送队列扔数据裸机方案则要自己维护一个状态机注意别在中断里做 CoAP 重传计时。3.3 移植到模组AT 指令封装下的边界感协议栈在模组里的时候MCU 侧看到的是一串 AT 指令。典型的上电序列大致长这样具体指令以模组手册为准AT # 握手确认串口通 ATCGSN # 读 IMEI拿去平台注册设备 ATCIMI # 读 IMSI ATCSQ # 信号质量10 基本可以认为环境有问题 ATNRB # 模组重启重新附着网络ATCSQ返回的第一个数字是 RSSINB 场景下只要不低于 10 就算能用低于 5 的时候别急着查代码先挪设备位置。ATCGSN和ATCIMI读出来的两串数字要和平台后台录的逐位核对这一步我建议直接打印到串口日志里方便肉眼比对。这种架构下最容易踩的坑是把 AT 指令当成同步调用。模组附着网络、注册到平台都是异步的OK只代表指令收到不代表业务成功。正确做法是给每条关键指令配一个超时和完成标志等到模组主动上报REG:1之类的状态再继续往下走否则会出现「代码以为上线了实际还在附着」的假在线。3.4 平台侧建产品与设备设备真正上线之前平台上必须先有一个「虚拟设备」等着它。创建产品时几个下拉框是有因果关系的接入方式选公开协议、联网方式选 NB-IoT、接入协议选 LwM2M。选错接入协议是最常见的返工原因选了别的协议栈之后设备发过来的注册报文平台根本不认但界面上又看不出任何异常。建完产品紧接着添加设备要填的字段就三个关键项设备名称自己看着起、IMEI、IMSI。是否开启自动订阅这个开关值得多说一句——开了之后设备侧创建的资源会自动同步到平台侧的虚拟设备资源列表里省掉手动维护不开的话资源列表要靠平台主动 Discover 去拉。我一般会开因为调试期资源模型经常改自动同步能少一轮对齐。3.5 设备侧五步初始化、建设备、加资源、登录、订阅发现这是整个接入里最核心的一段代码五步的顺序不能乱。初始化完成之后创建设备对象把鉴权信息和回调挂上去lwm2m_dev_t dev; memset(dev, 0, sizeof(dev)); strcpy(dev.endpoint, 86xxxxxxxxxxxxx); /* 一般就是 IMEI必须与平台录入一致 */ dev.lifetime 86400; /* 注册有效期 24 小时可按上报频率调整 */ dev.binding BINDING_UDP; /* NB 场景通常只开 UDP */ dev.cb.read on_read; /* 平台读资源时回调 */ dev.cb.write on_write; /* 平台写资源时回调 */ dev.cb.exec on_exec; /* 平台下发命令时回调 */ lwm2m_dev_create(dev);endpoint一旦确定就不能改改了等于换了一台新设备平台侧得重新建。lifetime设太短会让设备频繁续注册NB 场景下每次唤醒都要耗电86400 秒是个比较稳的起点如果设备本身是每天只上报一次的水表可以拉到 604800 秒。三个回调函数必须实现write没实现的话应用侧下发命令会直接超时而且平台侧只显示「命令已下发」看不出设备压根没处理。设备建好之后往里面塞对象实例和资源注意 SDK 里创建的资源要挂在实例下面实例挂对象下面lwm2m_obj_t *light lwm2m_obj_create(dev, 3311); /* IPSO Light Control */ lwm2m_inst_t *ins0 lwm2m_inst_create(light, 0); /* 第 0 个实例 */ lwm2m_res_create(ins0, 5850, TYPE_BOOL, ACC_RW, onoff); /* 开关可读可写 */ lwm2m_res_create(ins0, 5851, TYPE_INT, ACC_RW, dimmer);/* 亮度 0-100 */第三步登录成败全看返回码int32_t ret lwm2m_dev_login(dev); if (ret ! LWM2M_OK) { /* -1 网络未通 -2 鉴权失败 -3 lifetime 非法 -4 无可用对象 */ log_error(login failed: %d, ret); return ret; }-2鉴权失败九成是 IMEI / IMSI 对不上-4则是对象列表为空SDK 不允许登录一台没有任何资源的设备。登录成功后平台侧圆点会从灰变绿紧接着平台会下发 Observer 和 Discover 两条消息Observer 是订阅请求SDK 收到后自动维护观测记录之后资源变化会主动上报Discover 是让设备把对象和属性报一遍。这两条消息 SDK 内部处理业务代码不用管但一定要在日志里能看到它们看不到就说明注册流程其实没走完。4. 第三方应用对接握手、解密与 API 编排4.1 URL 加 Token 的握手验证应用侧接收数据的前提是先跟平台建立连接而这个「建立连接」不是长连接是一次 HTTP 回调验证。平台配置好应用地址后会带着签名参数请求你的服务你校验签名再把 echostr 原样吐回去握手才算完成。签名规则是把 Token、timestamp、nonce 三个值按字典序排好拼成一串做 SHA1。Token 是你自己在平台配置页填的随便定但别用弱口令const crypto require(crypto); const TOKEN process.env.PUSH_TOKEN; // 平台配置页里自定义的那串 token function verify(req, res) { const { msg_signature, timestamp, nonce, echostr } req.query; const raw [TOKEN, timestamp, nonce].sort().join(); // 字典序排序后拼接 const sign crypto.createHash(sha1).update(raw).digest(hex); if (sign ! msg_signature) return res.status(401).send(invalid signature); return res.send(echostr); // 必须原样返回带引号或换行都算失败 }msg_signature是平台算好的签名timestamp和nonce参与排序。这里最常见的翻车是回包内容多了个换行或者框架自动加了 JSON 包装平台侧看到回包对不上就判定验证失败但界面上只会提示一句「验证不通过」不会告诉你差在哪。我一般会在回包前打个日志把echostr的字节长度记下来比对一次就清楚了。4.2 明文与密文消息AES 解密怎么写握手通过之后设备上传的每条数据都会推过来。消息体有两个模式明文模式直接给你 JSON安全模式给你一段 Base64 密文加签名。安全模式的密钥是平台生成的 AESKey配置页上能看到也能自己指定。解密逻辑如下function decrypt(encrypted, aesKeyBase64) { // 平台给的是 43 位 base64 串补一个 还原成 32 字节密钥 const key Buffer.from(aesKeyBase64 , base64); const iv key.slice(0, 16); // 约定 IV 取密钥前 16 字节 const decipher crypto.createDecipheriv(aes-256-cbc, key, iv); decipher.setAutoPadding(true); // PKCS#7 填充 return Buffer.concat([ decipher.update(encrypted, base64), decipher.final() ]).toString(utf8); }密钥 32 字节对应 AES-256-CBCIV 直接取密钥前 16 字节这是平台侧固定的约定换别的 IV 出来的明文就是乱码。填充用 PKCS#7Node 默认就开着不用手动 Unpad。解出来的 JSON 里几个字段要认准type区分是数据上报还是设备上下线事件dev_id对应平台侧设备 IDds_id是数据流 IDat是时间戳。线上环境务必用安全模式加 HTTPS明文模式只适合本地联调。4.3 常用 API读写资源、下发命令、批量取数据点应用侧主动操作设备靠的是 HTTPS 的 REST 接口鉴权方式是请求头里带api-key。创建设备、读资源、下发命令这三类用得最多# 创建一个设备auth_info 填 IMEIobsv 打开自动订阅 curl -X POST https://api-host/devices \ -H api-key: your-apikey \ -H Content-Type: application/json \ -d {title:meter-001,auth_info:86xxxxxxxxxxxxx,obsv:true} # 读指定对象的资源obj_id/obj_inst_id 与设备侧建模保持一致 curl https://api-host/devices/device_id/resources?obj_id3311obj_inst_id0 \ -H api-key: your-apikey # 下发命令body 里的 key 是资源 ID curl -X POST https://api-host/cmds?device_iddevice_id \ -H api-key: your-apikey \ -H Content-Type: application/json \ -d {name:set_dimmer,body:{5851:80}}读资源那条命令里obj_id和obj_inst_id跟设备侧建模必须一一对应设备上报了 3311/0 而你去查 3311/1返回的是空数组而不是报错很容易误判成设备没数据。下发命令有个坑设备处于 PSM 休眠时命令会进离线队列接口照样返回成功但不代表设备已经执行要看命令状态回执或者用离线命令接口单独查。除了这三类触发器、批量查设备状态、批量查最新数据、按时间段查数据点这几组接口在运维阶段很有用。批量查设备状态一次能带几十个设备 ID比循环单查省很多次请求查数据点接口支持分页返回结构里带cursor翻页时把它带上就行。5. 常见问题排查五类高频翻车现场5.1 五条踩坑记录第一条设备一直离线圆点始终是灰的。现象是串口打印一切正常注册报文也发出去了。原因基本锁定在两处要么 endpoint name 里的 IMEI 与平台录入的不一致少位、大小写、多了空格要么平台侧设备的 IMSI 填错了。解决方式是两边各打一份出来逐位比对我习惯在设备启动时把 IMEI 和 IMSI 一起打印对着平台页面念一遍比 grep 日志快。第二条登录成功但平台侧资源列表是空的。现象是设备在线读资源却返回空。原因是设备只建了对象没建实例或者实例建了但没挂资源SDK 允许这种半成品状态通过注册。解决办法是把资源创建代码放在登录之前并且登录前加一句断言资源数量为 0 直接不发起登录。第三条平台显示在线但下发命令一直超时。现象是命令接口返回成功设备侧毫无反应。原因多半是write或exec回调没实现或者实现里把obj_id判断错了收到写请求直接走默认分支返回失败。解决办法是在回调入口先打一行日志把 URI 打出来确认平台请求的到底是/3311/0/5851还是别的路径。第四条推送地址验证通过但一条数据都收不到。现象是握手时返回 200之后静默。原因通常是推送配置里的推送时间限制和推送数据限制设得太保守平台在攒够一批才推或者安全模式下 AESKey 填成了明文但验签逻辑还在按密文解析。解决办法是先把推送频率设成实时、关闭安全模式跑通一条数据再逐步把两项能力加回来。第五条批量接口返回的数据点时间和本地对不上。现象是查出来的数据比本地时间早或者晚几个小时。原因是接口默认按 UTC 处理请求参数里没显式指定时区。解决办法是所有时间参数统一用带时区的 ISO 格式传别传裸时间戳字符串。5.2 排障顺序从串口到平台出问题的时候不要一上来就翻应用侧代码先按链路走一遍。第一刀抓包看设备报文有没有出去第二刀看平台有没有回 ACK第三刀看设备有没有处理平台下发的 Observer第四刀才轮到应用侧。前两刀用 tcpdump 就够了# 看设备有没有把注册报文发出去有没有收到响应 tcpdump -i any -n udp port 5683 -c 50 -vv # 看应用侧有没有收到平台推送如果对接方是自己的服务直接在服务上抓 tcpdump -i any -n tcp port 80 or tcp port 443 -c 30 -A第一个命令解决「设备到底动没动」的问题如果一条报文都没有问题在硬件或网络附着。第二个命令解决「平台推没推」的问题如果一段时间内完全没有请求打进来那就不用怀疑解密逻辑了先去查平台的推送配置和 URL 可达性。6. 二次开发把能跑通的 Demo 改成能交付的系统从跑通第一个注册流程到能支撑几百上千台设备的业务系统中间隔着几件事都是我在项目后期反反复复改过的。第一件事是把对象模型配置化。设备侧的资源定义如果硬编码在 C 文件里每来一个新型号就得改代码重新烧录。我的做法是抽一张资源描述表编译期生成静态数组运行期遍历建对象型号变只改表协议栈代码一行不动。表里至少要包含 obj_id、inst_id、res_id、类型、权限和回调入口六个字段缺一个后面就得打补丁。第二件事是应用侧的握手和解密做成中间件。验签、解密、消息分发这三步几乎每个推送回调都要走一遍散在业务代码里等哪天要换加密模式改起来能让人崩溃。收拢成一个装饰器或者拦截器业务侧只拿到解密后的 JSON改加密策略时只动一个文件。第三件事是补上离线命令的闭环。前面提过 PSM 休眠时命令只是进队列接口返回成功不代表执行成功。二次开发里必须有一个轮询或回调机制去查命令最终状态落一张状态表超时未执行的命令走重试或者告警。这块不做运维阶段你会收到大量「我点了没反应」的反馈而你在后台看到的全是成功。第四件事是给批量接口加限流和缓存。批量查设备状态、批量查最新数据这两类接口在仪表盘上会被高频调用直接透传到平台侧很快就会撞到调用频率限制。加一层几百毫秒的本地缓存配合一个请求合并队列能挡掉绝大部分重复请求。改造后的验证方法不用太复杂我一般准备三样东西一台故意配错 IMEI 的设备用来验证鉴权失败的报错是否可读、一个模拟平台推送的脚本用来验证解密和分发、一份离线命令的状态流转单用来确认超时重试有没有真的触发。这三样跑通基本可以交付了。从那以后我每次接新的物联网平台接入项目都会先拿一台设备把「注册、读资源、下发命令」这三件事走完再碰业务代码任何一步卡住就停下来查透绝不让它带着隐患往下走——毕竟在 NB 这种低频上报的场景里一个没跑通的注册流程可能要等到明天早上设备唤醒时才暴露。希望这些拆解和踩坑记录能帮你把第一台设备的绿点亮起来。本文还有配套的精品资源点击获取