企业官网建设流程全解析

简介：《OneNET平台NB-IOT接入开发文档》面向物联网终端开发者、嵌入式工程师及第三方应用开发人员，系统梳理NB-IoT设备接入OneNET平台并完成应用开发的技术路径。内容从SDK向MCU、NB通信模组和NB芯片移植讲起，依次说明平台创建产品与设备、终端软硬件初始化、设备及资源创建、登录、订阅与资源发现等环节；第三方应用部分覆盖接入验证、平台配置、明文与密文数据推送、加密算法，以及创建设备、读写资源、下发命令、触发器、批量查询等API用法。接入实例与LWM2M、CoAP协议章节进一步解释MCU侧流程、平台侧数据收发和协议栈、块传输、安全传输等关键细节，并附常见问题与资源下载指引。压缩包为1个docx文档，约1.73MB，结构按章节组织，便于按接入阶段查阅。已有1090人学习，适合需要落地NB-IoT项目、对照接口与协议排查问题的开发者参考。

1. 一块 NB 模组、一张物联网卡、一份六十多页的 PDF

不少人第一次做 OneNET 平台 NB-IoT 接入开发文档落地，状态都差不多：模组焊上板子，AT 口通了，卡也识别到了，平台上的设备图标却一直是灰的。这份文档的价值就在这里——它把“终端侧 SDK 该放在哪一层、平台侧产品和设备怎么建、北向应用怎么接数据和命令”三件事压在同一份材料里，而不是拆成三份各说各话的手册。它面向的是已经能点亮 NB 模组、但还不清楚 LwM2M 资源模型怎么摆的嵌入式开发者，以及需要调通北向 API 和推送接口的应用侧同学。首版标注在 2018 年 5 月，属于 NB-IoT 大规模铺网早期的技术基线，里面的 AT 流程和资源对象定义至今仍是排查问题的参照系。

2. 三条 SDK 移植路径：MCU、模组与芯片的层次差异和选型判据

NB-IoT 设备和云平台之间不是“连上网就能发数据”这么简单。OneNET 走的是 LwM2M 协议，终端必须先跑起一个 LwM2M 引擎，把设备抽象成 Object/Instance/Resource 三层资源树，再用 CoAP 把注册、上报、通知这些动作映射到 UDP 报文上。这份引擎加协议栈，文档里统一叫基础通信套件 SDK。SDK 放在哪一层，直接决定了后面谁写应用、谁写 AT 指令、移植工作量有多大。

2.1 三种架构下 SDK 的落点

文档把终端拆成三类，本质是按 SDK 的物理位置划分：

第一类里，模组退化成一个串口转射频的管道，SDK 完整跑在 MCU 上，LwM2M 引擎、CoAP 编解码、DTLS（如需）全压进 MCU 的 Flash 和 RAM。第二类把这一坨整体搬进模组，MCU 只发 AT 指令操作资源，比如新建对象、写资源值、读下发命令。第三类干脆没有 MCU，芯片本身就是主控。

2.2 选型判据：从 Flash、迭代速度、量产成本倒推

选哪条路不是看哪个先进，是看三个约束谁先顶到墙。我一般按这个顺序问：

先问 Flash 和 RAM 余量。完整的 LwM2M 引擎加 CoAP 栈，编译出来通常是几十 KB 量级，加上 DTLS 还要再涨一截。如果 MCU 只剩 32KB Flash，第一条路直接排除，别硬啃。

再问迭代速度。走模组 AT 指令的方案，固件升级只需要换模组或换 AT 脚本，应用侧改动小；走 MCU 自带 SDK 的方案，每次协议栈调参都要重新烧 MCU 固件，调试周期明显更长。产品还在验证阶段、协议参数要反复试的时候，第二条路更省事。

最后问 BOM 和体积。SoC 方案省掉一颗 MCU，量产成本最低，但前期投入最大，芯片内的 SDK 移植通常由芯片原厂或方案商完成，普通团队拿到的已经是带 SDK 的固件，能改的只有应用层。文档附录里列了两张表，一张是已完成 SDK 移植的 NB 模组型号清单，一张是已完成移植的 NB 芯片型号清单，选型前先翻这两张表对一遍型号，比自己从零移植省几个月。

提示：清单只说明“这家已经移植过”，不代表你拿到的固件版本就带这些接口。下单前把模组固件版本号和 SDK 版本号一起确认，版本对不上是最常见的翻车点。

2.3 移植前要落实的抽象接口

不管走哪条路，SDK 都要和你的硬件、你的应用之间定一组接口。文档里的做法是抽象出读、写、执行三类回调，由移植者实现，SDK 在收到平台下发的 Observe、Write、Execute 消息时回调进来。骨架大致是这样：

/* 抽象接口层：由移植者按自己的硬件实现，SDK 只认函数指针 */ typedef struct { /* 平台写资源时回调：把 buf 里的值落到你的传感器/执行器上 */ int (*write)(uint16_t obj_id, uint16_t ins_id, uint16_t res_id, const uint8_t *buf, uint32_t len); /* 平台读资源时回调：把你的当前值填进 buf，*len 回填实际长度 */ int (*read)(uint16_t obj_id, uint16_t ins_id, uint16_t res_id, uint8_t *buf, uint32_t *len); /* 平台下发 Execute 时回调：执行一次性动作，比如重启、校准 */ int (*exec)(uint16_t obj_id, uint16_t ins_id, uint16_t res_id); } lwm2m_ops_t;

三个回调的入参都是三元组obj_id / ins_id / res_id，因为同一个资源 ID 在不同对象、不同实例下含义不同，不能只靠 res_id 分发。write的len由平台侧决定，布尔量是 1 字节、整型按 CoAP 的紧凑编码可能是 1 到 4 字节，解析时别写死长度。read的*len必须回填真实写入的字节数，填 0 会被平台当成空值，资源列表里那一项就是空白。

资源注册部分通常写成静态表，由 SDK 在登录前遍历注册：

/* IPSO Light Control：Object 3311，实例 0，两个可读写资源 */ static lwm2m_res_t light_res[] = { {5850, LWM2M_TYPE_BOOL, LWM2M_OP_RW, &g_onoff}, /* On/Off */ {5851, LWM2M_TYPE_INT, LWM2M_OP_RW, &g_dimmer}, /* Dimmer 0-100 */ };

LWM2M_OP_RW这个操作位要和应用的真实能力对齐：传感器只上报就标R，执行器只接收就标W，标错了平台侧的下发命令会被 SDK 直接拒掉，现象是“命令发了没反应”，但设备其实在线。这是排查阶段最容易走弯路的一类问题。

3. 五步接入：从建产品到 Observer 订阅生效

终端能上线，中间隔着五个动作：平台建产品和设备、终端软硬件初始化、终端创建设备和资源、登录平台、平台下发订阅与发现。文档把它们画成一条线性流程，实际做的时候最耗时间的不是写代码，是参数填错之后不知道错在哪一步。

3.1 产品创建里的三个选项决定后面所有事

进入开发者中心创建产品，字段很多，真正致命的只有三个：

这三个选项在产品创建后基本不可逆，重建产品意味着设备、数据流、触发器全部重来。我见过为了图省事随便选一个、后面推倒重来的情况，血泪经验就是建产品这一步慢一点。

产品建完，页面会提示立即添加设备。设备名称只是平台侧的显示名，可以随便起；IMEI 和 IMSI 是鉴权字段，必须和终端真实值一致。

3.2 IMEI、IMSI 与 endpoint name 的对应关系

LwM2M 的注册请求里带一个 endpoint name，平台拿它和设备列表里的记录做匹配，匹配不上就返回注册失败。OneNET 的做法是把 IMEI 或 IMSI 作为 endpoint name 的取值来源：

这里有个容易忽略的点：平台侧填的 IMEI 和终端上报的 endpoint name 必须逐字符一致。模组 AT 指令查出来的 IMEI 有时带前导零、有时末尾补空格，直接拼进 endpoint name 就会匹配失败，现象是设备一直离线、平台日志里没有任何注册记录。我一般会在终端侧打印一次实际拼出来的字符串，逐位对照平台页面上的输入框。

3.3 资源模型：Object、Instance、Resource 三层怎么摆

登录前终端必须把资源树建好，否则平台收到注册请求后发现没有可观测的对象，设备图标会变绿但资源列表是空的。LwM2M 的资源模型是三层：

• Object：一类传感器或执行器，比如 3311 是灯光控制，3200 是数字输入
• Instance：同类设备的编号，一路灯是 0，第二路是 1
• Resource：具体属性，比如 5851 是亮度、5850 是开关

以文档里的例子，Object 3311 下挂三个实例，每个实例两个资源，结构就是3311/0/5851、3311/0/5850，依此类推。资源 ID 不是随便编的，5850 和 5851 来自 IPSO 的既有定义，平台侧认得，能直接映射成可视化控件。自定义对象一般落在 1024 以上的区间，别占用标准区间，否则平台可能按标准语义解析，值对不上。

一个实例号重复的低级错误值得单独说：同一个 Object 下两个实例都填 0，SDK 注册时会覆盖前一个，平台侧只看到一个实例，另一个的资源永远读不到。多路设备的项目里这个坑出现频率不低。

3.4 登录时序与 Observer、Discover 的自动处理

终端上电后的顺序不能乱：硬件初始化（模组上电、寄存器、工作模式）→ 软件初始化（SDK、socket 抽象、应用接口）→ 创建设备对象并配置接入地址、endpoint name、lifetime 和三个回调 → 创建 Object/Instance/Resource → 发起注册。

lifetime 是注册有效期，平台在这个周期内认为设备在线。设置时要留足余量：设得太短，网络抖动导致续注册失败，设备会在平台上频繁上下线；设得太长，设备异常掉电后平台仍显示在线，下发的命令全部石沉大海。常见做法是把 lifetime 设成业务上报周期的若干倍，并且保证终端有稳定的续注册机制。

注册成功后，平台会主动向设备下发两条消息：Observer 和 Discover。Observer 是观测请求，告诉 SDK“这个对象下的资源变化要通知我”；Discover 是发现请求，要求 SDK 回报指定 Object 下有哪些实例和资源。这两条消息由基础通信套件自动处理，应用层不用写代码响应。很多人第一次抓包看到这两条 CoAP 报文，以为是设备发出去的，其实方向是平台到设备。

Discover 的响应决定了平台侧资源列表的内容。如果终端在注册完成后才异步创建资源，Discover 早就回完了，列表里就是空的——这也是“设备在线但看不到资源”的一个典型原因。

3.5 上行数据与下行命令的完整路径

上行：应用改资源值 → SDK 检测到被观测资源变化 → 组 Notify 报文 → CoAP 发到平台 → 平台更新虚拟设备的数据点 → 若配置了推送，转发给第三方应用。

下行：第三方应用调 API 下发命令 → 平台把命令转成 Write 或 Execute 报文 → 设备 SDK 收到后回调write或exec→ 应用执行动作 → 若资源可读，平台可能再发一次 Read 回读确认。

这条链路上任何一环断掉，现象都是“命令没生效”。定位时按反方向逐段验证：先看平台侧命令状态是不是已送达，再看设备串口有没有收到 CoAP 报文，最后看回调有没有进。跳过中间步骤直接改代码，通常会白改两轮。

4. 北向应用：URL&Token 握手、推送解密与 API 调用

设备上线只是把数据送到了平台，业务系统要拿到数据、要反向控制设备，得走北向。OneNET 给北向留了两个口子：一个是平台主动推给你的数据推送，一个是你主动调的 REST API。两者鉴权方式完全不同，混用是最常见的对接失败原因。

4.1 接入验证程序要回答的两件事

在平台侧填好 URL 和 Token 点提交，平台会立刻向你的地址发起一次验证请求。你的服务要回答两件事：这个请求确实来自平台（Token 对得上），以及我愿意接收推送（原样回传挑战值）。

from flask import Flask, request import hashlib app = Flask(__name__) TOKEN = "your_token" # 与平台侧配置的 Token 保持完全一致 @app.route("/onenet/callback", methods=["GET"]) def verify(): signature = request.args.get("signature", "") timestamp = request.args.get("timestamp", "") nonce = request.args.get("nonce", "") echostr = request.args.get("echostr", "") # 常见做法：token、timestamp、nonce 排序拼接后取摘要，与 signature 比对 raw = "".join(sorted([TOKEN, timestamp, nonce])) if hashlib.sha1(raw.encode()).hexdigest() != signature: return "invalid signature", 403 return echostr # 必须原样返回，握手才算通过

这段代码的关键在最后一行：echostr不回传或者多包一层 JSON，平台都判定验证失败，界面上只显示一句笼统的“配置失败”。TOKEN里带空格、带不可见字符也会导致摘要对不上，粘贴完记得用编辑器显示一下不可见字符。签名算法按平台文档给的顺序实现，排序方式差一个字符结果就完全不同。

4.2 明文与安全模式：AESKey 从哪来、怎么解

推送消息有两种模式。明文模式下，平台把 JSON 直接 POST 过来，解析即用。安全模式下，报文体是加密的，需要在平台侧配置一个 AESKey，可以自定义也可以让平台随机生成，应用侧拿同一把 Key 解密。

选型的判断很简单：数据里有没有敏感字段、链路是不是全程 HTTPS。纯设备状态类数据用明文模式足够，调试成本低得多；涉及控制指令或者有合规要求时上安全模式。切安全模式之后最常见的翻车是 Key 拷贝时截断——AESKey 有固定长度要求，少一位多一位解密出来全是乱码，而报错信息通常只说“解析失败”。

解密后拿到的消息体里，字段大致分三类：设备标识（设备 ID、IMEI）、数据点（资源路径、值、时间戳）、消息类型（数据上报、设备上线、设备离线、命令响应）。业务侧按消息类型分流处理，别把所有消息都往同一个数据表里塞。

4.3 API 清单与两个可复用的调用片段

文档列了十几个接口，按使用频率排一下更实用：

北向 API 用 APIKey 做请求头鉴权，这个 Key 在产品或用户维度生成，权限范围要看清楚——用只读 Key 去调下发命令接口，返回的是权限错误而不是参数错误，报错文案容易误导。

import requests API_HOST = "https://{平台给出的API接入地址}" # 以控制台展示为准，不要自己拼 DEVICE_ID = "123456789" HEADERS = {"api-key": "{你的APIKey}"} # 查设备在线状态：返回体里的 online 字段是排障第一看的东西 r = requests.get(f"{API_HOST}/devices/{DEVICE_ID}", headers=HEADERS, timeout=10) print(r.status_code, r.json())

超时设 10 秒是保守值，批量接口可以放到 30 秒。返回码要分开处理：401 是 Key 问题，404 是设备 ID 不存在，200 但 body 里errno非 0 是业务层错误，三者排查方向完全不同，别笼统打一句“请求失败”。

# 下发命令：name 是命令名，data 是载荷，具体格式随资源类型变化 body = {"name": "set_dimmer", "data": "50"} r = requests.post(f"{API_HOST}/cmds?device_id={DEVICE_ID}", headers=HEADERS, json=body, timeout=10) print(r.status_code, r.json())

命令下发成功只代表平台受理了，不代表设备执行了。要确认执行结果，得看设备侧的回调日志，或者用读资源接口回读一次值。把“受理成功”当“执行成功”，是北向联调里最普遍的误判。

4.4 批量推送的两个阈值参数

平台侧配置里有两个参数容易被忽略：推送时间限制（秒）和推送数据限制（个）。不设的时候平台实时推送，设备一多，你的回调接口会被高频请求打满。设了之后，平台攒够时间或攒够条数再推一批，服务端压力立刻降下来。代价是实时性下降，做告警类业务时这两个值要压得很小，做电量统计类业务可以放宽到分钟级。

这两个参数和业务的消息类型要匹配：控制类消息走实时，统计类消息走批量。全都走同一套配置，要么接口被打爆，要么告警延迟到没意义。

5. 避坑排查：五类上线失败现象的定位顺序

文档最后一章叫常见问题，但实际排障时更需要的是“先看哪、再看哪”的顺序。下面五条是按出现频率排的，每条都给出可直接对照的现象、根因和动作。

5.1 设备一直灰色离线，平台侧没有任何注册记录

现象：模组已注网，串口能看到发送注册报文，平台设备图标始终灰色，设备详情里最后上线时间为空。

原因：注册报文根本没到平台，或者 endpoint name 与平台记录不匹配。常见细分是接入地址填错、产品协议不是 LWM2M、IMEI 与平台填写的值差一位。

解决：先在终端打印实际使用的接入地址和 endpoint name 字符串，逐字符对照平台页面；再确认产品的三个关键选项（公开协议、NB-IoT、LWM2M）；最后确认设备是否真的添加在产品下，而不是添加在别的产品里。

5.2 图标变绿但资源列表为空

现象：设备在线，点开资源列表什么都没有，或者只有一个空对象。

原因：资源创建时机晚于注册，Discover 请求回来时资源树还没建好；或者 Observer 请求发出后 SDK 没有维护观测记录。

解决：把资源创建挪到注册之前，确保register调用返回时资源表已经就绪；检查 SDK 的观测记录是否真的写入，有些移植版本需要在初始化时显式打开观测开关；重启一次设备看 Discover 响应报文里的资源数量对不对。

5.3 命令下发返回成功，设备侧毫无反应

现象：API 返回 200，平台命令状态显示已送达，设备串口没有任何 CoAP 报文，或者收到了但回调没进。

原因：资源操作位标错（只标了 R 却下发写命令）、命令下发的资源路径与终端注册的不一致、设备处于 PSM/eDRX 休眠窗口外。

解决：先用读资源接口确认路径可通，再对照终端的资源表核对操作位；NB-IoT 设备有省电模式，唤醒周期长的设备要等窗口，别把等待当成失败；离线命令功能可以兜底，但要确认平台侧已经开启。

5.4 数据推送一直验证不通过

现象：平台配置页点提交后提示失败，你的服务日志里能看到请求进来。

原因：签名算法实现与平台不一致、Token 里有不可见字符、回调地址不是公网可达的 HTTPS、网关层把 GET 请求的查询参数吃掉了。

解决：把收到的timestamp、nonce、signature原样打印出来，用文档给的算法在本地重算一遍比对；用浏览器直接访问回调地址看是否能拿到echostr；确认反向代理没有丢弃 query string。

5.5 安全模式下解密全是乱码

现象：明文模式一切正常，切到安全模式后消息体解出来是二进制垃圾。

原因：AESKey 长度不对、编码方式不一致（十六进制字符串被当成 UTF-8 用）、加解密用的模式与平台不一致、Base64 解码次数多了一层。

解决：先把 Key 的字节长度打出来核对；确认传输层是否已经做过一次编码，解密前只解一层；用平台的测试推送功能发一条固定内容的消息，本地解密后逐字节比对，别拿真实业务数据试。

注意：五条里最耗时的是 5.2 和 5.3，因为它们表现成“看起来正常”。养成联调时先抓包的习惯，报文层面能看到的比日志多得多。

6. 把“能连上”变成“能验收”的四个自检动作

联调跑到图标变绿只是及格线，真正交付前我固定会过一遍四个动作，每个动作对应一类上线后才会暴露的问题。

第一个动作是断电重启三轮。NB 设备现场部署后第一次上电往往是冷启动，模组注网、SDK 初始化、资源注册的时序和调试时热的板子不一样。三轮里只要有一轮资源列表没出来，就是创建时机的问题，别等现场返工。

第二个动作是改一次资源值再读回来。写 5851 到 60，等三秒，用读资源接口拉一次值，确认回读是 60 而不是初始值。这一步同时验证了写回调、通知上报、平台存储三条链路，比单独测每条都省事。

第三个动作是模拟一次离线。把模组天线拔掉或进飞行模式，等超过 lifetime，平台图标应该转灰；恢复后再看是否自动重注册。很多项目死在这里：设备能上线，但掉线后再也回不来，因为续注册失败没有重试逻辑。

第四个动作是压一次推送接口。把推送时间限制和推送数据限制调到很小，让平台短时间推一批，观察回调服务的响应时间和错误率。批量模式下的并发问题和单条调试完全不是一个量级。

这四个动作加起来不到半小时，但能把上线后八成的问题提前暴露。我现在的习惯是：任何一个 NB-IoT 项目，验收前一天必须把这四步强制走一遍并留下截图，谁签字谁负责——吃过一次“现场设备全离线、回滚重刷固件”的亏之后，这个流程就再没省过。这份文档的第七章讲了 LwM2M 和 CoAP 的协议栈细节，第八章列了常见问题，配合上面这套自检顺序看，能把大部分“玄学掉线”落到具体参数上。希望帮到你。

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