简介：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 把数据交给第三方应用。设备侧和应用侧根本不认识对方，双方都只跟平台打交道，这是理解整个接入模型的前提。

三侧的职责边界很清楚，动手前先对着这张表确认自己站在哪一格：

这里有个容易被忽略的前置条件：设备所在网络的核心网必须对目标平台放行。不同运营商的 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 是设备在平台上的唯一标识，一般直接用 IMEI；lifetime 是注册有效期，单位秒，到期不续注册平台就会把设备标成离线；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 三种终端架构的横向对比

文档把终端分成三类，本质上是「协议栈放在哪一层」的问题。选错了架构，后面每加一个传感器都要多写一层胶水代码，所以这个决定要在硬件选型阶段就定下来：

第一列和第二列长得一样，区别只在协议栈跑在哪颗芯片上。第二列的好处是模组厂商已经把 LwM2M 栈和 AT 封装做完了，MCU 只需要发AT+xxx就能建对象、报数据；坏处是出了问题你只能看到 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 # 握手，确认串口通 AT+CGSN # 读 IMEI，拿去平台注册设备 AT+CIMI # 读 IMSI AT+CSQ # 信号质量，<10 基本可以认为环境有问题 AT+NRB # 模组重启，重新附着网络

AT+CSQ返回的第一个数字是 RSSI，NB 场景下只要不低于 10 就算能用，低于 5 的时候别急着查代码，先挪设备位置。AT+CGSN和AT+CIMI读出来的两串数字要和平台后台录的逐位核对，这一步我建议直接打印到串口日志里，方便肉眼比对。

这种架构下最容易踩的坑是把 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-CBC，IV 直接取密钥前 16 字节，这是平台侧固定的约定，换别的 IV 出来的明文就是乱码。填充用 PKCS#7，Node 默认就开着，不用手动 Unpad。解出来的 JSON 里几个字段要认准：type区分是数据上报还是设备上下线事件，dev_id对应平台侧设备 ID，ds_id是数据流 ID，at是时间戳。线上环境务必用安全模式加 HTTPS，明文模式只适合本地联调。

4.3 常用 API：读写资源、下发命令、批量取数据点

应用侧主动操作设备靠的是 HTTPS 的 REST 接口，鉴权方式是请求头里带api-key。创建设备、读资源、下发命令这三类用得最多：

# 创建一个设备，auth_info 填 IMEI，obsv 打开自动订阅 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_id=3311&obj_inst_id=0" \ -H "api-key: <your-apikey>" # 下发命令，body 里的 key 是资源 ID curl -X POST "https://<api-host>/cmds?device_id=<device_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 这种低频上报的场景里，一个没跑通的注册流程，可能要等到明天早上设备唤醒时才暴露。希望这些拆解和踩坑记录，能帮你把第一台设备的绿点亮起来。

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