7.6 OneNET 组件

学习阁2026/7/18大约 11 分钟常用组件组件OneNET通信NB-IoT

7.6 OneNET 组件

📚 本节导读

学习时长: 约 45 分钟
难度级别: ⭐⭐⭐⭐☆
前置知识: NB-IoT 基础知识、CoAP/LwM2M 协议、第 7.2 节网络协议栈

🎯 学习目标

理解 OneNET 平台的定位和架构
掌握 OneNET NB-IoT SDK 的核心数据结构（mo_onenet_ops_t）
掌握 OneNET 资源模型（Object/Instance/Resource）
掌握设备配置、数据上报、命令下发、事件通知等核心操作
了解 OneNET 发现（Discover）和观察（Observe）机制
能够基于 OneNET SDK 开发 NB-IoT 设备应用

一、概述

OneNET 是中国移动打造的开放物联网平台，提供设备接入、设备管理、数据存储、数据分析、应用使能等 IoT 服务。OneOS 通过 Molink 蜂窝模组抽象层深度集成了 OneNET NB-IoT SDK，支持基于 NB-IoT 网络的设备接入。

OneNET 组件位于 components/net/molink/，核心头文件 mo_onenet_nb.h，通过 MOLINK_USING_ONENET_NB_OPS 宏启用。

核心设计特点：

模组无关：基于 Molink 抽象层，支持多种 NB-IoT 模组（BC26、BC28、BC95、M5311 等）
LwM2M 协议：基于 OMA LwM2M 协议实现设备管理和数据交互
资源模型：Object/Instance/Resource 三级资源模型，灵活定义设备能力
异步通知：支持 URC（Unsolicited Result Code）异步消息处理
DTLS 安全：支持 DTLS 加密传输，保障数据安全
PSK 认证：支持预共享密钥（PSK）身份认证

二、OneNET 资源模型

2.1 Object/Instance/Resource 三级结构

OneNET 基于 LwM2M 协议，采用三级资源模型：

Object (对象)
  └── Instance (实例)
       └── Resource (资源)

层级	描述	示例
Object	设备功能的逻辑分组	温度传感器对象（Object ID=3303）
Instance	对象的实例化	第 0 个温度传感器实例
Resource	实例的具体属性或操作	温度值（Resource ID=5700）、单位

2.2 标准 IPSO 对象

OneNET 支持 OMA IPSO 标准对象模型：

Object ID	对象名称	典型 Resource
3303	温度传感器	5700（温度值）、5701（单位）
3304	湿度传感器	5700（湿度值）、5701（单位）
3308	光照传感器	5700（光照值）
3311	电灯控制	5850（开关状态）、5851（调光）
3313	加速度计	5702（X 轴）、5703（Y 轴）、5704（Z 轴）
3347	按钮	5500（按下状态）、5501（按下计数）

三、核心数据结构

3.1 mo_config_resp_t —— 设备配置响应

定义在 mo_onenet_nb.h 第51-66行，存储 OneNET 接入配置：

typedef struct mo_config_resp
{
    int8_t   guide_mode_enable;          /* Guide mode enable; -1:invalid */
    int8_t   ip[IPADDR_MAX_STR_LEN + 1]; /* Server ip */
    uint16_t port;                       /* Server port; [0-15535] */
    uint8_t  rsp_timeout;                /* Respond timeout; 0:invalid, range:[2-20](s) */
    int8_t   obs_autoack_enable;         /* Obs autoack mode enable; -1:invalid */
    int8_t   auth_enable;                /* Auth mode enable; -1:invalid */
    int8_t   auth_code[NBCONFIG_AUTHCODE_MAX_STR_LEN];
    /* Auth code string with Double quotation marks */
    int8_t dtls_enable;                   /* DTLS mode enable; -1:invalid */
    int8_t psk[NBCONFIG_PSK_MAX_STR_LEN]; /* PSK string with Double quotation marks */
    int8_t write_format;                  /* Write format; -1:invalid */
    int8_t buf_cfg;                       /* Downlink data cache configuration; -1:invalid */
    int8_t buf_urc_mode;                  /* Downlink data cache enabled indication;-1:invalid */
} mo_config_resp_t;

3.2 URC 事件结构体

OneNET 平台通过 URC（Unsolicited Result Code）向设备推送异步通知。每种 URC 对应一个结构体。

（1）mo_onenet_discover_t —— 发现通知（+MIPLDISCOVER）

typedef struct mo_onenet_discover
{
    uint32_t ref;    /* The descriptor of molink module instance */
    int32_t  msg_id; /* MessageID */
    int32_t  obj_id; /* ObjectID */
} mo_onenet_discover_t;

（2）mo_onenet_observe_t —— 观察通知（+MIPLOBSERVE）

typedef struct mo_onenet_observe
{
    uint32_t ref;    /* The descriptor of molink module instance */
    int32_t  msg_id; /* MessageID */
    int8_t   flag;   /* Observe enable flag */
    int32_t  obj_id; /* ObjectID */
    int32_t  ins_id; /* InstanceID; -1:request all ins */
    int32_t  res_id; /* ResourceID; -1:request all res */
} mo_onenet_observe_t;

（3）mo_onenet_read_t —— 读取请求（+MIPLREAD）

typedef struct mo_onenet_read
{
    uint32_t ref;    /* The descriptor of molink module instance */
    int32_t  msg_id; /* MessageID */
    int32_t  obj_id; /* ObjectID */
    int32_t  ins_id; /* InstanceID; -1:request all ins */
    int32_t  res_id; /* ResourceID; -1:request all res */
} mo_onenet_read_t;

（4）mo_onenet_write_t —— 写入请求（+MIPLWRITE）

typedef struct mo_onenet_write
{
    uint32_t ref;        /* The descriptor of molink module instance */
    int32_t  msg_id;     /* MessageID */
    int32_t  obj_id;     /* ObjectID */
    int32_t  ins_id;     /* InstanceID */
    int32_t  res_id;     /* ResourceID */
    int8_t   value_type; /* Value type; @see +MIPLWRITE */
    int32_t  len;        /* Value len;  @see +MIPLWRITE */
    int8_t   flag;       /* Message flag, indicate messages position of value */
    int32_t  index;      /* Index of write request messages */
} mo_onenet_write_t;

（5）mo_onenet_execute_t —— 执行请求（+MIPLEXECUTE）

typedef struct mo_onenet_execute
{
    uint32_t ref;    /* The descriptor of molink module instance */
    int32_t  msg_id; /* MessageID */
    int32_t  obj_id; /* ObjectID */
    int32_t  ins_id; /* InstanceID */
    int32_t  res_id; /* ResourceID */
    int32_t  len;    /* Execute arguements length; (optional) */
} mo_onenet_execute_t;

（6）mo_onenet_parameter_t —— 参数通知（+MIPLPARAMETER）

typedef struct mo_onenet_parameter
{
    uint32_t ref;    /* The descriptor of molink module instance */
    int32_t  msg_id; /* MessageID */
    int32_t  obj_id; /* ObjectID */
    int32_t  ins_id; /* InstanceID; -1:request all ins */
    int32_t  res_id; /* ResourceID; -1:request all res, checkout IPSO */
    int32_t  len;    /* Parameter length */
} mo_onenet_parameter_t;

（7）mo_onenet_event_t —— 事件通知（+MIPLEVENT）

typedef struct mo_onenet_event
{
    uint32_t ref;    /* The descriptor of molink module instance */
    uint8_t  evt_id; /* EventID; 0:invalid */
    int32_t  extend; /* Extend;                      (optional) -1:invalid */
    uint16_t ack_id; /* AckID;                       (optional)  0:invalid range:[1-65535] */
    uint8_t  time_stamp[NBEVENT_TIME_STAMP_MAX_STR_LEN];
    /* Time stamp;                  (optional) YYYYMMDDHHmmSS */
    int8_t cache_command_flag; /* Cache command enable Flag;   (optional) -1:invalid */
} mo_onenet_event_t;

3.3 mo_onenet_cb_t —— URC 回调函数表

typedef void (*discover_notify_cb_t)(mo_onenet_discover_t *discover_notify);
typedef void (*observe_notify_cb_t)(mo_onenet_observe_t *observe_notify);
typedef void (*read_notify_cb_t)(mo_onenet_read_t *read_notify);
typedef void (*write_notify_cb_t)(mo_onenet_write_t *write_notify, const char *value);
typedef void (*execute_notify_cb_t)(mo_onenet_execute_t *execute_notify, const char *arguments);
typedef void (*parameter_notify_cb_t)(mo_onenet_parameter_t *parameter_notify, const char *parameter);
typedef void (*event_notify_cb_t)(mo_onenet_event_t *event_notify);

typedef struct mo_onenetnb_cb
{
    discover_notify_cb_t  discover_notify_cb;
    observe_notify_cb_t   observe_notify_cb;
    read_notify_cb_t      read_notify_cb;
    write_notify_cb_t     write_notify_cb;
    execute_notify_cb_t   execute_notify_cb;
    parameter_notify_cb_t parameter_notify_cb;
    event_notify_cb_t     event_notify_cb;
} mo_onenet_cb_t;

3.4 mo_onenet_ops_t —— 操作函数表

定义在 mo_onenet_nb.h 第241-267行。源码用 ONENET_NB_FUNC_ARGS 宏 + DEFINE_ONENET_OPT_FUNC 宏统一定义函数指针。完整源码：

#define ONENET_NB_FUNC_ARGS (mo_object_t * module, int32_t timeout, void *resp, const char *format, va_list args)

typedef struct mo_onenet_ops
{
#define DEFINE_ONENET_OPT_FUNC(NAME, ARGS) os_err_t(*NAME) ARGS
    DEFINE_ONENET_OPT_FUNC(onenetnb_get_config, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_set_config, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_create, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_createex, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_delete, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_addobj, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_delobj, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_nmi, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_open, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_close, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_discoverrsp, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_observersp, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_readrsp, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_writersp, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_executersp, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_parameterrsp, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_notify, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_update, ONENET_NB_FUNC_ARGS);
    DEFINE_ONENET_OPT_FUNC(onenetnb_get_write, ONENET_NB_FUNC_ARGS);
    os_err_t (*onenetnb_cb_register)(mo_object_t *module, mo_onenet_cb_t user_callbacks);
#ifdef OS_USING_SHELL
    DEFINE_ONENET_OPT_FUNC(onenetnb_all, ONENET_NB_FUNC_ARGS);
#endif
} mo_onenet_ops_t;

关键理解（宏定义）：

ONENET_NB_FUNC_ARGS 统一定义所有函数的可变参数列表 (mo_object_t *module, int32_t timeout, void *resp, const char *format, va_list args)；
DEFINE_ONENET_OPT_FUNC(NAME, ARGS) 展开为 os_err_t(*NAME) ARGS，即定义函数指针 os_err_t (*NAME)(module, timeout, resp, format, va_list)；
cb_register 例外（固定参数 (mo_object_t *module, mo_onenet_cb_t)）；onenetnb_all 仅在 OS_USING_SHELL 下编译；
展开后等价于各 os_err_t (*onenetnb_xxx)(...) 函数指针（见 4.x 的对外 API 声明）。

四、核心 API 详解

4.1 设备注册（create / addobj / delobj）

os_err_t mo_onenetnb_create(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_createex(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_delete(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_addobj(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_delobj(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);

4.2 连接管理（open / close）

os_err_t mo_onenetnb_open(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_close(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);

4.3 数据交互（notify / update / read / write）

os_err_t mo_onenetnb_notify(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_update(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_readrsp(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_writersp(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);

4.4 配置管理（get_config / set_config）

os_err_t mo_onenetnb_get_config(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_set_config(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);

4.5 发现与观察响应

os_err_t mo_onenetnb_discoverrsp(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);
os_err_t mo_onenetnb_observersp(mo_object_t *module, int32_t timeout, void *resp, const char *format, ...);

4.6 回调注册

os_err_t mo_onenetnb_cb_register(mo_object_t *module, mo_onenet_cb_t user_callbacks);

五、OneNET 通信流程

5.1 设备接入流程

┌──────────┐          ┌──────────┐          ┌──────────┐
│  设备端   │          │  NB 模组  │          │ OneNET  │
└────┬─────┘          └────┬─────┘          └────┬─────┘
     │                      │                     │
     │  1. 模组初始化         │                     │
     │─────────────────────>│                     │
     │  2. 网络注册           │                     │
     │─────────────────────>│  3. 网络附着          │
     │                      │────────────────────>│
     │  4. 设置配置           │                     │
     │  (auth_code, psk)    │                     │
     │─────────────────────>│                     │
     │  5. 添加对象 (addobj)  │                     │
     │─────────────────────>│  6. 注册 (Register)   │
     │                      │────────────────────>│
     │  7. 打开连接 (open)    │                     │
     │─────────────────────>│  8. Bootstrap        │
     │                      │<───────────────────>│
     │  ◄══ 设备已注册，可通信 ══►                     │

5.2 数据上报流程

     │  1. notify/update    │                     │
     │─────────────────────>│  2. LwM2M Notify    │
     │                      │────────────────────>│

5.3 命令下发流程

     │                      │  1. LwM2M Write/Exec│
     │                      │<────────────────────│
     │  2. URC +MIPLWRITE   │                     │
     │<─────────────────────│                     │
     │  3. 解析并处理命令     │                     │
     │ 4. writersp/executersp│                    │
     │─────────────────────>│  5. 响应结果          │
     │                      │────────────────────>│

六、使用示例

6.1 设备初始化与配置

#include <mo_onenet_nb.h>
#include <mo_object.h>

extern mo_object_t *g_module;

void onenet_device_init(void)
{
    mo_config_resp_t config;
    int ret;

    /* 获取当前配置 */
    ret = mo_onenetnb_get_config(g_module, 10, &config, NULL);
    if (ret != 0) {
        os_kprintf("Get config failed\r\n");
        return;
    }

    /* 设置认证码 */
    memcpy(config.auth_code, "\"your_auth_code\"", strlen("\"your_auth_code\""));
    config.auth_enable = 1;

    /* 启用 DTLS */
    config.dtls_enable = 1;
    memcpy(config.psk, "\"your_psk_key\"", strlen("\"your_psk_key\""));

    ret = mo_onenetnb_set_config(g_module, 10, NULL, NULL);
    if (ret != 0) {
        os_kprintf("Set config failed\r\n");
        return;
    }

    os_kprintf("OneNET config set successfully\r\n");
}

6.2 添加对象并注册

void onenet_register_device(void)
{
    int ret;

    /* 添加温度传感器对象 (Object ID: 3303) */
    ret = mo_onenetnb_addobj(g_module, 10, NULL, "%d,%d,%d", 3303, 1, (1 << 0));
    if (ret != 0) {
        os_kprintf("Add object failed\r\n");
        return;
    }

    /* 打开 OneNET 连接（注册到平台） */
    ret = mo_onenetnb_open(g_module, 120, NULL, NULL); /* 120 秒超时 */
    if (ret != 0) {
        os_kprintf("OneNET register failed\r\n");
        return;
    }

    os_kprintf("OneNET device registered successfully!\r\n");
}

6.3 数据上报

void onenet_report_temperature(float temperature)
{
    int ret;

    /* 上报温度值 (Object:3303, Instance:0, Resource:5700) */
    ret = mo_onenetnb_notify(g_module, 10, NULL,
        "%d,%d,%d,%d,%s,%d,%d",
        3303,   /* 温度传感器对象 */
        0,      /* 第 0 个实例 */
        5700,   /* 温度值资源 */
        0,      /* 值类型 */
        "%.1f", /* 值 */
        temperature,
        0       /* 索引 */
    );

    if (ret == 0) {
        os_kprintf("Temperature reported: %.1f\r\n", temperature);
    }
}

6.4 处理平台下发命令

/* URC 回调 - 写请求处理 */
void onenet_write_callback(mo_onenet_write_t *write, const char *value)
{
    os_kprintf("Write request: obj=%d, ins=%d, res=%d, value=%s\r\n",
               write->obj_id, write->ins_id, write->res_id, value);

    if (write->obj_id == 3311 && write->res_id == 5850) {
        /* 电灯开关控制 */
        /* led_control(value); */
        mo_onenetnb_writersp(g_module, 10, NULL, "%d,%d", write->msg_id, 0);
    }
}

/* URC 回调 - 执行请求处理 */
void onenet_execute_callback(mo_onenet_execute_t *exec, const char *arguments)
{
    os_kprintf("Execute request: obj=%d, ins=%d, res=%d\r\n",
               exec->obj_id, exec->ins_id, exec->res_id);
    /* 执行相应操作... */
    mo_onenetnb_executersp(g_module, 10, NULL, "%d,%d", exec->msg_id, 0);
}

/* 注册 URC 回调 */
void onenet_register_callbacks(void)
{
    mo_onenet_cb_t callbacks = {0};
    callbacks.write_notify_cb    = onenet_write_callback;
    callbacks.execute_notify_cb  = onenet_execute_callback;
    mo_onenetnb_cb_register(g_module, callbacks);
}

6.5 完整设备任务

void onenet_device_task(void *arg)
{
    onenet_device_init();
    onenet_register_device();
    onenet_register_callbacks();

    while (1) {
        float temp = read_temperature();
        float humidity = read_humidity();

        /* 上报温度 */
        onenet_report_temperature(temp);

        /* 上报湿度 (Object:3304, Instance:0, Resource:5700) */
        mo_onenetnb_notify(g_module, 10, NULL,
            "%d,%d,%d,%d,%s,%d,%d", 3304, 0, 5700, 0, "%.1f", humidity, 0);

        os_task_tsleep(30000);  /* 每 30 秒上报一次 */
    }
}

七、Kconfig 配置

OneNET 组件通过 Molink 的 Kconfig 配置（components/net/molink/api/Kconfig）：

配置项	类型	默认值	说明
`MOLINK_USING_ONENET_NB_OPS`	bool	n	启用 OneNET NB-IoT 操作（总开关；`select MOLINK_USING_IP` + `OS_USING_MESSAGEQUEUE` 等）
`MOLINK_USING_ONENET_NB_OPS_AUTO_REG`	bool	n	启用模组上电自动注册到 OneNET
模组选择	bool	—	选择使用的 NB-IoT 模组（如 `MOLINK_USING_BC26`/`MOLINK_USING_M5311`），模组需实现 `mo_onenet_ops_t` 对应操作

关键理解：
OS_USING_ONENET / ONENET_USING_DTLS / ONENET_USING_PSK 这些宏不存在。启用 OneNET 用 MOLINK_USING_ONENET_NB_OPS（mo_onenet_nb.h 整个头文件由 #ifdef MOLINK_USING_ONENET_NB_OPS 包裹）；
DTLS 与 PSK 不是编译宏，而是运行时通过 mo_config_resp_t 配置：dtls_enable=1 启用 DTLS、auth_code（认证码）/psk（PSK 密钥）字段设置后下发（见 6.1 示例）；
使用前还需开启 NET_USING_MOLINK 及所选模组（如 MOLINK_USING_BC26）。

八、支持的 NB-IoT 模组

品牌	型号	频段
移远 (Quectel)	BC20	B1/B3/B5/B8/B20/B28
移远 (Quectel)	BC26	B1/B3/B5/B8/B20/B28
移远 (Quectel)	BC28	B1/B3/B5/B8/B20/B28
移远 (Quectel)	BC95	B3/B5/B8
中移物联	M5310A	B3/B5/B8
中移物联	M5311	B3/B5/B8
广和通	N21	B1/B3/B5/B8/B20/B28
广和通	N58	B1/B3/B5/B8/B20/B28

九、关键宏定义

宏	值	说明
`NBCONFIG_AUTHCODE_MAX_LEN`	16	认证码最大长度
`NBCONFIG_PSK_MAX_LEN`	16	PSK 密钥最大长度
`NBEVENT_TIME_STAMP_MAX_LEN`	14	事件时间戳最大长度
`NBCONFIG_AUTHCODE_MAX_STR_LEN`	19	认证码字符串最大长度（含双引号）
`NBCONFIG_PSK_MAX_STR_LEN`	19	PSK 字符串最大长度（含双引号）
`NBEVENT_TIME_STAMP_MAX_STR_LEN`	15	事件时间戳字符串最大长度（含空终止符）

📝 本节小结

核心要点回顾

定位：OneNET 是中国移动开放物联网平台，OneOS 通过 Molink 抽象层集成 OneNET NB-IoT SDK（components/net/molink/api/include/mo_onenet_nb.h），核心头文件由 #ifdef MOLINK_USING_ONENET_NB_OPS 包裹。
资源模型：基于 LwM2M，Object/Instance/Resource 三级；标准 IPSO 对象（3303 温度/3304 湿度/3311 电灯/3313 加速度计等）。
数据结构：mo_config_resp_t（设备接入配置：guide_mode/ip/port/rsp_timeout/auth_code/psk/dtls_enable/write_format 等）、module_mgr_resp_t（get_write 响应）、7 个 URC 结构体（discover/observe/read/write/execute/parameter/event）。
操作函数表：mo_onenet_ops_t 用 DEFINE_ONENET_OPT_FUNC(NAME, ONENET_NB_FUNC_ARGS) 宏统一定义 19+1 个函数指针（get/set_config、create/delete、addobj/delobj、open/close、discoverrsp/observersp、readrsp/writersp/executersp/parameterrsp、notify/update、get_write、cb_register、all）。
回调注册：mo_onenet_cb_t 7 个回调（discover/observe/read/write/execute/parameter/event_notify_cb）统一处理 URC 异步通知。
接入流程：模组初始化 → 网络注册/附着 → mo_onenetnb_set_config（auth_code/psk）→ mo_onenetnb_addobj → mo_onenetnb_open（注册到平台）→ notify/update 上报。
Kconfig：总开关 MOLINK_USING_ONENET_NB_OPS（不是 OS_USING_ONENET）；DTLS/PSK 是运行时配置（dtls_enable/auth_code/psk），非编译宏。
模组支持：BC20/BC26/BC28/BC95（移远）、M5310A/M5311（中移物联）、N21/N58（广和通）等 NB-IoT 模组。

关键易错点速查

易错点	正确做法
用 `OS_USING_ONENET` / `ONENET_USING_DTLS` / `ONENET_USING_PSK` 配置	不存在 → 用 `MOLINK_USING_ONENET_NB_OPS`（总开关）；DTLS/PSK 走运行时 `mo_config_resp_t`
在源码结构体中加中文注释	违反"逐字一致"规范 → 保留源码英文注释，中文解释写正文
忘开 `MOLINK_USING_ONENET_NB_OPS`	头文件被 `#ifdef` 整体裁剪 → 先开该宏及所选模组（如 `MOLINK_USING_BC26`）
直接用 `mo_onenetnb_xxx` 但没开启对应用例	需 `mo_object_get_default`/`g_module` 拿到模组对象 → 先确认模组对象存在
`set_config` 前不填 `auth_code`/`psk`	认证失败无法连接 → 从 OneNET 平台申请并正确填写（带双引号字符串）
`dtls_enable=1` 但未配置 `psk`	DTLS 握手失败 → 启用 DTLS 时须同时提供有效 PSK
`mo_onenetnb_notify` 的 format 参数错误	notify 用 `"%d,%d,%d,%d,%s,%d,%d"`（obj/ins/res/type/format/值/index）→ 严格按格式传参
忘注册 `mo_onenetnb_cb_register`	URC 回调不触发 → 注册后平台下发命令才能被处理
命令下发回调里不响应	平台等待 `writersp`/`executersp` → 处理完调用 `mo_onenetnb_writersp`/`executersp` 回执
混淆 discover/observe 与 read/write	discover=发现资源、observe=观察、read=读、write=写 → 按 URC 类型选择对应回调与响应接口

下一步

本节已完整覆盖 OneNET NB-IoT 接入。接下来可回到 7.2 网络协议栈巩固 Socket/MQTT 等传输层知识；下一章"综合实战"（如"8.1 温湿度采集与 MQTT 上云"）将把传感器采集与云平台上报组合成一个完整项目实践。