Lierda NB861&MB261&MB961 OneNET应用指导

yutao

　　1  引言

　　本文档描述Lierda NB861/MB961/MB261模组与OneNET平台对接流程，对接时采用LwM2M协议。本文旨在帮助客户在AT COMMAND的方式下快速的完成Lierda NB861/MB961/MB261模组与OneNET平台的对接工作。

　　在完成本手册进行OneNET平台对接之前，需要先完成芯片(模组)初始化入网流程，模组注网成功后，方可进行OneNET平台业务对接流程。

　　1.1  LwM2M协议介绍

　　LwM2M是一套适用于物联网的协议，全称是Lightweight Machine-To-Machine，由OMA(Open Mobile Alliance)提出并定义。协议的主要实体包括LwM2M Server，LwM2M Client和LwM2M Bootstrap Server。LwM2M Server作为服务器，部署在服务提供商处；LwM2M Client作为客户端，部署在各个LwM2M设备上；此外根据需要还可以部署LwM2M Bootstrap Server，对客户端进行引导。LwM2M的基本架构如下图所示。

图1.1 LwM2M协议框架

　　在这些实体之间，协议定义了4个接口，来实现各自的功能。

　　●引导接口(Bootstrap)
　　LwM2M引导服务器向LwM2M客户端提供注册到LwM2M服务器的必要信息。

　　●客户端注册接口(Client Registration)
　　使LwM2M客户端与LwM2M服务器互联，并告知LwM2M客户端的相关信息。

　　●设备管理与服务实现接口(Device Management and Service Enablement)
　　LwM2M服务器向LwM2M客户端发送指令，LwM2M客户端对指令做出回应并将回应消息发送给LwM2M服务器。

　　●信息上报接口(Information Reporting)
　　该接口允许LwM2M服务器向LwM2M客户端订阅资源信息，LwM2M客户端接收订阅后按照约定的模式向服务端报告自己的资源变化情况。

　　LwM2M协议基于REST架构，协议的消息传递通过基于UDP的CoAP协议达成，消息的加密由DTLS负责。此外，LwM2M定义了以资源(Resource)为基本单位的模型，每个资源表示LwM2M客户端中的一项可用信息，资源都存在于对象实例中(Object Instance)，即对象(Object)的实例化。协议允许使用者根据实际需要自定义对象来描述自己的产品，更详细的LwM2M协议描述请访问https://www.omaspecworks.org。

　　1.2  文档目的

　　Lierda NB861/MB961/MB261模组OneNET LwM2M应用笔记描述了如何使用OneNET平台，如何采用Lierda NB861/MB961/MB261模组实现用户设备与OneNET平台的连接，实现从OneNET平台上对设备实施监控。本文对OneNET模块的使用提供了详细的AT交互流程，帮助客户的开发人员尽快完成相关的应用开发。

　　1.3  对接总体流程

　　Lierda NB861/MB961/MB261模组与OneNET平台对接包括两个方面的准备工作：
　　1、OneNET平台侧--产品创建与设备注册流程。
　　2、Lierda NB861/MB961/MB261模组侧–初始化驻网与设备创建/登录流程。

图1.2 OneNET与模组的对接流程

　　2  环境搭建

　　平台侧需要完成产品创建和设备注册流程，用于在平台上创建产品，并声明产品下挂载的设备；该步骤需要在模组侧设备登录操作之前完成。

　　中移物联网在全国多个省市均部署有OneNET平台，本文档以重庆OneNET平台为主平台进行相关的对接和测试工作。

　　重庆OneNET平台的门户网站为：https://open.iot.10086.cn/。

　　2.1  用户注册

　　访问https://open.iot.10086.cn，点击右上角注册，用手机号进行注册。

图2.1 OneNET物联网开放平台

图2.2 用户注册

　　注册成功后，点击登陆，可进入如下页面，在右上角点击开发者中心(新版开发者中改为控制台)，进入控制台，选择红圈所示的NB-IoT物联网套件点击进入，至此完成注册。

图2.3 开发者中心

图2.4 NB-IoT物联网套件

　　2.2  产品创建

　　开始时产品列表为空，右侧有添加产品按钮，用户可根据自己的产品类型来创建自己的产品。

图2.5 添加产品

图2.6 填写产品特性

　　输入产品名称等各项内容，选择联网方式：NB-IoT，设备协议为LWM2M。添加完成后，如果暂时不添加设备，刚创建的产品会出现在公开协议产品下：

图2.7 产品开发

　　如果不选择立刻添加设备，点击产品，进入产品概况：

图2.8 产品概况

　　除产品名称外，还有产品ID、用户ID和Master-APIKey。产品ID标识刚刚创建的产品，用户ID标识用户，Master-APIKey用于需要鉴权或身份鉴定等场合，例如OneNET HTTP API，参考“OneNET RESTFul API说明.docx”。点击左侧的设备列表，进入下图所示界面，可以点击添加设备，为该产品添加设备。

图2.9 添加设备

图2.10 填写设备参数

　　IMEI要求是15位数字的真实IMEI号（非法IMEI号无法输入），IMSI是不能超过15位的数字，这两个数值唯一标识这个设备。Auth_code为鉴权用，PSK为DTLS加密使用（选填）。添加成功后，设备即能在设备列表中看到。如果需要一次性导入多个设备，可以选择批量导入，点击后可以下载模板，将IMEI、IMSI、Auth_code填入Excel表格，批量添加设备。

　　注：添加的设备的IMEI号必须与设备的IMEI号对应，使用AT+CGSN=1可以查询设备的IMEI号。

图2.11 设备列表

　　至此OneNET平台部分的工作完成。

　　3  模组侧操作流程及数据收发说明

　　本章节介绍了模组与OneNET对接涉及到的关键AT命令交互流程，从而了解AP端与Lierda NB861/MB961/MB261模组以及Lierda NB861/MB961/MB261模组与OneNET平台端的总体交互过程，然后给出了具体的AT命令示例说明模组端的操作流程。

　　3.1  OneNET对接AT COMMAND总体流程

　　3.2  设备对象选择

　　目前OneNET不支持显示自定义的object id，用户想要在OneNET上展示自己的设备，可以从IPSO和OMA模型规范中选一个object与自己产品相似或相近的使用。例如温度传感器，需要设置或读取温度传感器的测量范围、温度数值等，可以使用object id：3303，resource id：5601，5602，5700，这样设备上线后，从OneNET平台上能够显示设备的具体资源名称。如果使用的是自定义的object id，OneNET资源栏里只能显示opaque类型。如有必要也可以向www.omaspecworks.org申请注册自己的object id。

       具体的Object编码规范可以参照IPSO规范或者OMA模型规范，具体文档请从如下地址获取：http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html。

　　3.3  设备上线及资源订阅

　　本文中的设备为非加密设备，这里通过AT命令的方式，操作设备上线。Cis OneNET模块会读取设备的SIM卡中的IMSI号，和设备flash中存储的IMEI号，这两个号码必须与2.2节中创建的设备相匹配。

　　设备上线的步骤如下：

　　1、Lierda NB861/MB961/MB261模组上电，确定驻网成功后，从串口输入。

　　ATQ0

　　确保主动上报消息能从串口输出。

　　2. 创建设备实例

　　AT+MIPLCREATE

　　具体的配置含义详见《中国移动蜂窝物联网终端基础通信套件技术规范》，给出的这条指令配置的连接地址是OneNET的非bootstrap server地址183.230.40.40。

　　成功后串口会输出

　　+MIPLCREATE:0

　　OK

　　失败返回+CIS ERROR:XXX

　　详细参考AT Manual.docx。

　　3. 添加对象实例object id:3200

　　AT+MIPLADDOBJ=0,3200,1,”1”,1,0

　　创建1个实例，1个属性。

　　4. 设备注册

　　AT+MIPLOPEN=0,86400

　　设备的lifetime时间为86400秒。

　　成功返回

　　OK

　　失败返回

　　+CIS ERROR: XXX

　　注册成功可见设备列表中对应设备为在线状态，平台对资源订阅成功后，点击详情即可在设备资源列表界面中看到设备的资源列表。

图3.1 设备详情

　　5. 资源订阅

　　设备上线后，OneNET会向设备发送observe指令，请求观察设备的对象3200，通常资源id为-1，即观察对象的所有资源。例如：

　　+MIPLOBSERVE: 0, 129665,1,3200,0,-1

　　接着OneNET会向设备发送discover指令，目的是询问对象有哪些资源。例如：

　　+MIPLDISCOVER:0,64130,3200

　　此时设备应立刻回复对象拥有的资源id：

　　AT+MIPLDISCOVERRSP=0,64130,1,4,”5750”。

图3.2 设备资源列表

　　及时回复了discover指令后，点击在线设备的设备资源列表，就能看到如上图所示的对象名称，把鼠标放到Digital Input上会弹出对象id：3200。点击左侧的“>”按钮，可以看到如下图所示页面，将鼠标放到属性名Application Type上会弹出资源id：5750。根据IPSO定义的对象3200，资源5750是string类型，为可读可写资源，所以操作读写均为蓝色，可以点击。至此设备完成上线过程。

图3.3 属性列表

　　注：目前NB861、MB961、MB261对于Onenet平台发送的observe指令已进行内置的自动回复，不需要通过AT指令再进行回复。若用户不需要自动回复observe指令的功能，可通过指令AT+MIPLCONFIG=3,0进行设置。设置完成后，在平台端发送observe指令时，需要回复AT+MIPLOBSERVERSP=0,129665,1(示例)，才能继续接收到平台下发的discover指令。

　　3.4  设备主动上报数据

　　因为设备上线时平台已经启动了对设备的观察observe，那么当设备对象的资源值发生变化，就应该向平台告知，例如Application Type值改变，设备应发送AT命令通知平台。

　　例如：AT+MIPLNOTIFY=0,20819,3200,0,5750,1,4,"WWYY",0,0

　　注意，该指令的msgid必须与收到的observe指令msgid的一致。

　　3.5  平台侧操作设备

　　从平台上点击读取属性5750，OneNET会向设备发送read指令。

　　例如：+MIPLREAD:0,40111,3200,0,5750

　　目前OneNET的指令有20秒的超时，在20秒之内没有回复即提示超时，设备应发送读指令的响应。

　　例如：AT+MIPLREADRSP=0,40111,1,3200,0,5750,1,2,"WY",0,0

　　平台收到响应后会在页面上显示出来。

图3.4 读属性

　　注：模组接入移动OneNET平台后，不会自动更新平台侧的lifetime，需要通过AT指令AT+MIPLUPDATE手动更新平台侧lifetime，建议用户每次发送心跳包之前先进行update。AT指令示例：AT+MIPLUPDATE=0,86400,0

　　4  AT指令示例流程

　　本章节给出的示例流程中所添加的object id为3200，resource id为5750，其主要目的是演示一下整体的操作流程，包括读、写、执行等所有操作。

　　4.1  上电检查流程

　　AT                               //判断模组是否上电开机成功
　　AT+CPIN?                  //查询是否读到卡
　　AT+CEREG?               //判断PS域附着状态，第二个参数为1或5表示附着正常
　　AT+CGPADDR           //查询核心网是否已分配IP

　　4.2  与OneNET平台交互流程

　　AT+MIPLCREATE                                                   //创建一个LwM2M客户端实例
　　+MIPLCREATE:0
　　OK

　　AT+MIPLADDOBJ=0,3200,1,"1",1,0                      //添加Object, Instance及Resource
　　OK

　　AT+MIPLOPEN=0,86400                                      //客户端注册OneNET平台
　　OK
　　+MIPLEVENT:0,1
　　+MIPLEVENT:0,2
　　+MIPLEVENT:0,4
　　+MIPLEVENT:0,6
　　+MIPLOBSERVE:0,20819,1,3200,0,-1
　　+MIPLDISCOVER:0,20820,3200

　　AT+MIPLDISCOVERRSP=0,20820,1,4,"5750"       //回复Discover请求
　　OK

　　4.3  OneNET平台数据收发流程

　　AT+MIPLNOTIFY=0,20819,3200,0,5750,1,6,"lierda",0,0                    //数据主动上报
　　OK

　　+MIPLREAD:0,31091,3200,0,5750                              
　　AT+MIPLREADRSP=0,31091,1,3200,0,5750,1,6,"lierda",0,0             //读操作回复
　　OK

　　+MIPLWRITE:0,23415,3200,0,5750,2,4,57575959,0,0                      //写操作回复
　　AT+MIPLWRITERSP=0,23415,2
　　OK

　　+MIPLEXECUTE:0,46755,3300,0,5605,4,"1234"                              //执行操作回复
　　AT+MIPLEXECUTERSP=0,46755,2
　　OK

　　4.4  设备注销流程

　　AT+MIPLCLOSE=0                                        //客户注销OneNET平台
　　OK
　　+MIPLEVENT:0,15

　　AT+MIPLDELOBJ=0,3200                             //删除Object
　　OK

　　AT+MIPLDELETE=0                                      //删除LwM2M实例
　　OK

　　5  错误码

　　5.1  引言

　　本章介绍NB861&MB961&MB261模组的相关错误码。

　　以下表格中列出的错误代码符合3GPP规范，可参考3GPP TS 27.007 V13.5.0, sub-clause 9.2了解所有可能的<err>错误码。

　　错误代码0-255在3GPP TS 27.007中保留和定义，可能会在未来版本中使用。

　　用户可通过AT+CMEE=<n>指令开启或禁用错误码（n=0为禁用，n=1为开启）。

　　5.2  一般错误码（27.007）

表5-1 一般错误码（27.007）

　　5.3  一般错误代码（27.005）

表5-2 一般错误代码（27.005）

　　6  相关文档
   
　　以下相关文档提供了文档的名称，版本请以最新发布的为准。