物联网NB-IoT之电信物联网开放平台对接流程浅析

电信物联网开放平台对接流程如下图所示：

1、创建 APP 应用

登录中国电信物联网开放平台对接测试环境SP Portal（https://180.101.147.135:8843），初次登录需要修改初始密码。

选择【应用管理】->【应用】点击右上角“+创建应用”。

典型的 NB-IoT 应用的参数设置可参考如下设置：

所属行业：

公用事业(NB-IoT)

关联API包：

基础API包和公用事业(NB-IoT) API包

平台能力：

规则引擎

数据存储时间：

当超过了数据存储时间以后，应用将不能再获取到已上报的数据。

短信服务器：

使用户可以通过短信服务器实现与工程师的紧密联络。服务器可以选择平台已经支持的服务器之一，也可以选择第三方服务器。

邮件服务器：

使用户可以通过邮件服务器实现与工程师的紧密联络。服务器可以选择平台已经支持的服务器之一，也可以选择第三方服务器。

CA证书：

第三方应用通过HTTPS对接中国电信物联网开放平台时服务器下发的证书，用于身份识别和电子信息加密，实现双向认证。证书文件限制为不超过1M的PEM格式文件。当第三方应用通过HTTP对接中国电信物联网开放平台时，不需要上传CA证书。

2、设置 NB-IoT 参数

点击已经创建好的应用，并对NB-IoT参数进行设置。

目前平台支持设置如下三种模式：

PSM模式：

power saving mode，省电模式。对下行业务时延无要求，对于下行业务消息，可等待设备发送上行数据进入连接态后再发送，可进一步节省终端功耗。如智能水表。

DRX模式：

discontinuous reception，不连续接收模式。对下行业务时延要求高，可认为设备一直在线，消息能够立即下发。如路灯。

eDRX模式：

Extended idle mode DRX，扩展不连续接收模式。DRX的扩展模式，对下行业务时延有较高要求，可根据系统配置立即下发消息或者缓存消息。如智能穿戴设备。

当省电模式设置为PSM模式时，ACTIVE TIMER可以不设置，无影响；当省电模式设置为eDRX模式时，eDRX周期的设置需要与网络侧的一致，请联系中国电信物联网开放平台支持人员获取参数配置数据。

这里参数的设置要与网络侧保持一致，参数的设置只是配置到中国电信物联网开放平台中，不会配置到网络或者设备。

3、定义设备模型

Profile 定义设备模型有两种方式：

方式一：从 Portal 在线制作 Profile 文件

方式二：参考《中国电信物联网开放平台_设备能力描述文件profile开发指南》离线制作 Profile

设备模型是指中国电信物联网开放平台支持注册新的设备模型，并支持对设备模型进行管理。设备模型包括:产品、设备模板和服务模板。

产品由设备模板、制造厂商、型号、协议等构成的具体实例，SP Portal 支持用户根据需求自定义产品（移动oneNET遵循一套标准，相比电信平台更简单但灵活相稍差）。设备模板通过设备服务定义设备基本特性和能力。设备模板由多个服务模板组成。SP Portal 支持用户使用预置设备模板，也支持用户根据需求自定义设备模板。服务模板定义设备能力，包括属性、命令、事件等。SP Portal 支持用户使用预置服务模板，也支持用户根据需求自定义服务模板。

3.1、定义产品设备模型

设备模型定义了一个类型的设备具备哪些服务能力，每个服务有哪些属性（即上报的数据有哪些字段），有哪些命令以及命令的参数。每个厂家在接入 NB-IoT 之前必须先定义自己的产品的设备模型。

下面通过一个例子介绍一下如何定义产品设备模型：

例如:

某产品设备的制造信息如下：

厂商ID：ChinaTelecom
厂商名字：ChinaTelecom
设备类型：SmartDevice
设备型号：NBIoTDevice
该设备具有三个服务能力：

分别为亮度（Brightness）、温度（Temperature）、电力（Electricity）。

其中，亮度（Brightness）服务拥有一个亮度属性及设置该属性值的命令方法；

温度（Temperature）服务具有一个温度（temperature）属性及一个设置温度的方法命令；

电力（Electricity）具有四个属性，分别为：电压（votage），电力当前值（current），频率（frequency）及功率因数（powerfactor）。

下面通过在 SP portal 设置该设备能力到平台：

3.2、新增服务模板

使用浏览器登录SP Portal；单击左侧，打开“设备管理”页面；单击“模型”下拉选项，单击“服务模板”，打开“服务模板”页面；单击界面右上角“+新增服务模板按钮”。例如，增加温度（Temperature）服务。

3.3、新增服务属性

以温度服务为例，该服务具有一个属性即温度（temperature），现新增该属性。点击刚新增的温度服务。

单击“属性”，单击“新增属性”，弹出“新增属性”页面。根据实际情况设置下列参数。

名称：属性名称，且系统唯一。
属性类型：包括int、long、decimal、string、DateTime、jsonObject。
最小、最大、步长、单位：当属性类型为int、long和decimal时，才会出现。
长度：当选择属性类型为string、jsonObject或DateTime时，才会出现。
访问模式：属性能够访问的模式。
是否必选：属性是否必选。

3.4、新增服务命令

以温度服务为例，该服务具有一个命令即一个设置温度的命令（SET_TEMPERATURE）现新增该服务命令。点击刚刚新增的温度服务，单击“命令”，单击“新增命令”，弹出“新增命令”页面。

3.5、新增设备模板

使用浏览器登陆SP Portal；单击左侧，打开“设备管理”页面；单击“模型”下拉选项，选择“关于模型”，打开“关于模型”页面；单击“自定义设备模板”，打开“设备模板”页面。单击右上角“新增设备模板”，弹出“新增设备模板”页面。根据实际情况设置下列参数：

设备模板：设备模板名称，且系统唯一，这里填写SmartDevice。
描述（可选）：设备模板描述内容。

3.6、新增自定义产品

使用浏览器登录SP Portal；单击左侧，打开“设备管理”页面；单击“模型”下拉选项，选择“关于模型”，打开“关于模型”页面；单击“自定义产品”，打开“产品”页面。单击右上角“新增设备”按钮，弹出“添加设备产品”页面。根据实际情况设置下列参数：

设备类型：产品所属的设备类型。作为例子，这里填写3.6节设备模板名称。
型号：产品所属的型号。
厂商ID：产品所属的厂商ID。
厂商：产品所属的厂商名称。
协议：产品所属的协议类型。NB-IoT目前仅有CoAP和LWM2M两种协议，请正确选择接入协议。
单击“点击上传文件”上传产品图像。
（可选）描述：产品描述内容。

单击，完成自定义设备产品创建。

创建完设备后，设备产品模型中的服务项还是空的，需要将温度（Temperature）、电力（Electricity）两个已创建好的服务添加。

另外还需要添加预置服务亮度（Brightness）。

单击已创建好的设备产品, 单击服务列表中的“添加服务”，打开“添加服务类型”页面，选定需要加入的服务能力。单击即可完成。

向产品中添加服务：

3.7、编写 profile 文件

针对方式二使用《中国电信物联网开放平台_设备能力描述文件profile开发指南》离线制作 Profile 文件后再导入到中国电信物联网开放平台的场景。

模型 profile 文件包的组成:

profile 文件夹中，包含devicetype-capability、devicetype-display两个JSON文件；

其中devicetype-capability描述了设备的manufacturerId(制造商ID)、manufacturerName(制造商名称)、model(设备型号)、protocolType(协议类型)、deviceType(设备类型)、serviceTypeCapabilities(服务能力)。

service 文件夹主要描述profile文件夹的devicetype-capability文件中serviceTypeCapabilities字段提到的各项服务能力，并对每一项能力进行描述:

3.8、上传 profile 文件

上传 profile 文件功能菜单的路径为：

设备管理>模型>导入模型

4、开发编解码插件并安装

4.1、开发编解码插件

设备模型是设备的抽象模型，把设备的功能抽象为服务，对编解码库插件而言，其定义了 decode 接口的输出，encode 接口的输入格式。编解码插件开发可参考《中国电信物联网开放平台V100R001C30编解码库开发与升级指南》文档。

4.1.1、编解码插件质检

编解码插件的质检是检测编解码是否能够正常使用的关键步骤，请参照编解码插件检查工具说明，来进行操作。

工具下载地址：http://www.tianyiiot.com/attchment/174/中国电信物联网开放平台编解码插件检测工具.zip

4.2、对插件包进行离线签名

当编解码插件开发完后，在安装到平台之前，需要先对插件包进行签名。此时需要下载离线签名工具并进行签名操作。操作步骤如下：

单击左侧图标，打开管理页面。
单击左侧导航栏“工具”，在右侧区域单击“下载”，下载离线签名工具。
在下载路径找到压缩包“signtool.zip”，右键菜单中选择“Extract to signtool\”解压缩至文件夹“signtool”。
进入signtool文件夹，运行“signtool.exe”。操作界面如下所示。

4.2、生成数字签名公私钥对

根据实际情况选择签名算法。
目前提供两种签名算法：
ECDSA_256K1+SHA256
RSA2048+SHA256
设置“私钥加密口令”。
口令复杂度说明：
口令长度至少为6个字符
口令必须包含如下至少两种字符的组合：
至少一个小写字母
至少一个大写字母
至少一个数字
至少一个特殊字符：`~!@#$%^&*()-_=+|[{}];:’",<.>/？和空格
单击“生成公私密钥”，在弹出的窗口中选择需要保存的目录，单击“确定”。
可在保存的目录下查看生成的公私密钥文件。
公钥文件：public.pem
私钥文件：private.pem
2 对软件包进行数字签名。
离线签名工具只能对.zip格式的压缩包进行数字签名。
在“软件包数字签名”区域，单击“导入私钥文件”，选择步骤5.3中生成的私钥文件，单击“打开”。
在弹出的对话框中，输入步骤2中设置的口令，单击“确定”。
在“需要数字签名的软件包”区域，选择需要进行数字签名的软件包。单击“打开”。
单击“进行数字签名”。
签名成功后，在原软件包所在目录生成名为“XXX_signed.XXX”的带签名的软件包。
软件包签名验证
在“软件包签名验证”区域，单击“导入公钥文件”，选择步骤5.3中生成的公钥文件，单击“打开”。
在“需要验签的软件包”区域，选择步骤6中生成的名为“XXX_signed.XXX”的带签名的软件包。单击“打开”。
单击“进行软件包验签”。
验证成功则弹出“验证签名成功！”提示框。
验证失败则弹出“验签异常！”提示框。
4.3、上传公钥及签名后的插件包

编解码插件化能够动态的新增编解码库，这样新增设备接入时，只需要把对应的编解码库动态导入到平台，就能够兼容新增的设备。

请将公钥以及签名后的插件包发送给中国电信物联网开放平台支持人员，由中国电信完成公钥和签名后的插件包的上传配置。

5、设备接入平台

5.1、登录应用

应用访问中国电信物联网开放平台时必须首先进行登陆，登陆成功后获取访问令牌（accessToken）。这一步消息中的appId和secret就是在“创建APP应用”步骤里获取的信息。

消息示例：

Method：POST
request：(非JSON格式)
https://server:port/iocm/app/sec/v1.1.0/login
Content-Type:application/x-www-form-urlencoded
Body:

appId=******&secret=******

response：
Status Code: 200 OK
Content-Type: application/json
Body:
{
“accessToken”: “",
“tokenType”: "”,
“expiresIn”: “",
“refreshToken”: "”,
“scope”: “*******”
}
5.2、订阅

为了能接受设备上报的数据，NA需要向中国电信物联网开放平台订阅通知消息。

订阅设备数据上报通知：

POST https://server:port/iocm/app/sub/v1.1.0/subscribe
Header：
app_key: ******
Authorization:Bearer ******
Content-Type:application/json
Body:
{
“notifyType”: “deviceDataChanged”,
“callbackurl”: “https://183.4.11.104:9999/”
}
5.3、注册设备

5.3.1、有应用服务器设备注册

所有设备必须先在北向进行注册，才允许连接到平台。

通过注册设备，平台会为每个设备分配一个唯一的标识deviceId，后续应用操作这个设备时都通过deviceId来指定设备。另外，还返回psk参数（如果用户未指定psk参数，平台会随机分配一个参数），南向设备绑定时，如果设备与平台之间走DTLS加密通道，则须用到该参数，请保存。在SP portal上也可以通过deviceId来找到设备。

Method：POST
request：
https://server:port/iocm/app/reg/v1.1.0/devices
Header：
app_key: "
Authorization:Bearer ******
Content-Type:application/json
Body:
{
“verifyCode”:“447769804451095”,
“nodeId”:“447769804451095”,
“psk”: “12345678”,
“timeout”:0
}
response：
Status Code: 201 CREATED
Content-Type: application/json
Body:
{
“deviceId”: "",
“verifyCode”: "******",
“psk”: “12345678”,
“timeout”: 0
}
5.3.2、无应用服务器设备注册

无应用服务器情况下，厂商可以用设备模拟器来进行设备的模拟注册。方便厂商进行联调开发。

工具下载地址：http://www.tianyiiot.com/attchment/173/中国电信物联网开放平台北向API调试工具-_GUI_APPDemo-master.zip

IP：180.101.147.89，端口：8743

设备注册工具登录：

填写设备Node ID等信息，并进行注册，其中Node ID为设备唯一编码ID，Verify Code与Node ID相同；Time Out参数填写，请根据设备传输情况填入（如果即时传输，请填“0”），设备注册：

注册成功后可以看到设备：

5.4、设置设备信息

这一步是为了把设备的厂商、型号、设备类型等信息设置到平台，平台在处理过程中需要这些信息：

Method：PUT
request：
https://server:port/iocm/app/dm/v1.1.0/devices/{deviceId}
Header：
app_key: ******
Authorization:Bearer ******
Content-Type:application/json
Body:
{
“manufacturerId”: “",
" manufacturerName ": "”,
“deviceType”: “",
“protocolType”: " CoAP",
“model”: "”
}
response：
Status Code: 200 OK
5.5、设备接入

接入端口与协议

目前中国电信物联网开放平台支持加密与非加密两种接入设备接入方式，其中加密业务数据交互端口是5684端口。5684端口走DTLS+CoAP协议通道接入，非加密端口为5683，接入协议为CoAP。

NB-IOT设备端使用加密端口接入时提供必要的数据凭证，并支持标准DTLS协议。

设备在登录平台前，需将设备对接平台的端口设置为5684（即走DTLS加密通道）。
建议将设备出厂前的PSK秘钥预置到中国电信物联网开放平台中，PSK秘钥的数据类型为String型，长度范围为8-32位。调用5.3注册设备接口，即可将设备PSK设置到平台。
使用用非加密端口接入时，只需要使用原生的CoAP协议进行传输，同时将对接平台设置为5683即可。
注册接口
无论是加密方式还是非加密方式，设备都只需使用标准OMA接口进行注册，CoAP url里带的参数可能有: ep = {Endpoint Client Name}<={Lifetime}&sms={MSISDN}&lwm2m={version}&b={binding mode}&{ObjectLinks},为兼容旧协议，除ep外其余均为可选。
5.6、设备上线

完成这一步时，设备已经可以接入到平台。配置好网络，开启设备，观察设备是否成功接入到平台。

登陆SP Portal的设备管理页面，查看设备列表，字段ID即为在第三步里注册设备时生成的deviceId，status字段表示设备的在线状态，如果状态是在线（online）表示设备已经成功的接入到平台，接着就可以接收设备的数据。

6、示例

6.1、注册:微信公众号搜索“天翼物联产业联盟”，关注后申请注册，第二天就能获得两封邮件

6.1.1、【中国电信物联网开放平台（对接测试）】开户密码通知

6.1.2、 服务邮件:

    测试平台地址
    开发者门户地址   
    测试平台应用对接地址(企业应用接入地址)
    测试平台设备对接地址(终端设备接入地址)

6.2、进入下载专区下载全部资料

6.3、准备工作

6.3.1、安装 jdk1.8

6.3.2、准备一个 HTTPS 服务器及相应证书(建议使用阿里的免费证书)

6.4、注册应用: 登录测试平台，注册一个应用，一定要选择“基础API包”“公用事业(NB-Iot)API包”

6.5、上传证书: 登录开发者平台，选择对接信息，点击应用列表，上传 HTTPS 的证书，格式为 PEM

6.6、上传 profile 文件:

可以通过在线编辑生成；

登录开发者平台->Profile开发->Profile导入: 选择《 中国电信物联网开放平台profile样例》中一个zip文件例子(WaterMeter_Huawei_NBIoTDevice.zip)

6.7、插件编写及上传:

6.7.1、导入《中国电信物联网开放平台设备编解码插件源码及样例》中的源码，打包jar，注意看源码中的com.thrid.party.codec.demo这几个文件，这是数据上传下载的核心所在

6.7.2、登录开发者平台->插件管理->编解码插件管理,上传插件，直接用例程就好，调试通过了后面再根据业务修改。

6.8、设备管理

6.8.1、设备模板：名称与选择的 profile 文件一致 如你选择的 WaterMeter_Huawei_NBIoTDevice.zip，解压它，打开profile文件夹，打开里面的json文件，找到"serviceId": “WaterMeterBasic”，服务名及id都填WaterMeterBasic

6.8.2、服务模板：内容和属性与profile文件 一致，命令先定义一个"SET_DEVICE_LEVEL"（随便选的一个下发命令，以后自己改）,事件选择"deviceDataChanged"（数据上传需要）

6.9、使用 中国电信物联网开放平台北向API调试工具-_GUI_APPDemo-master

6.9.1、注册设备：两个下拉框，分别选择
NB-IOT Device Manager
Register Direct Device

6.9.2、修改设备: Modify Device Info

6.9.3、设备上线: 《平台接入流程描述》有指导手册，在SSCOM中通过一系列AT指令操作

6.9.4、检查激活状态 Query Device Status 输入 device id ，点击按钮"check status"，返回 “evice Status: ONLINE.
”成功

6.10、数据上报

6.10.1、在平台订阅服务，可以使用 API调试工具-_GUI_APPDemo，两个下拉框，分别选择NB-IOT Subscribe Manager
Notify Type选择 “deviceDataChanged” callback URL 填回调的htts地址

6.10.2、设备上报数据的前八位是AA720000，其它随意，形式类似AA720000AAAAAAAAAAAAAAAAAAAAAAAAAA

6.11、命令下发

6.11.1、在平台订阅服务，可以使用 API调试工具-_GUI_APPDemo，Notify Type选择 “commandRsp” callback URL 填回调的htts地址

6.11.2、下发命令的json

  {"expireTime":"0","callbackUrl":"https://回调地址","deviceId":"111-111-11-11","command":{"method":"SET_DEVICE_LEVEL","paras":{"value":"自定义"},"serviceId":"服务ID"}}