中国电信物联网开放平台NBIoT业务对接指导书Word格式文档下载.docx
《中国电信物联网开放平台NBIoT业务对接指导书Word格式文档下载.docx》由会员分享，可在线阅读，更多相关《中国电信物联网开放平台NBIoT业务对接指导书Word格式文档下载.docx（46页珍藏版）》请在冰豆网上搜索。
通过无线网络连接到中国电信物联网开放平台，采用CoAP协议接入。
将设备读数，告警等信息上报到平台，如水表、燃气表等。
NB-IOT控制器：
实现对NB-IoT终端的移动性管理与会话管理；
为NB-IoT终端建立用户面承载，传递上下行业务数据。
中国电信物联网开放平台：
实现对各种NB-IoT设备数据的统一管理，同时向第三方应用系统开放接口，让各种应用能快速构建自己的物联网业务。
垂直行业应用：
实现对NB设备的业务管理，包括业务发放、业务控制和呈现等，由第三方基于中国电信物联网开放平台开放接口进行开发。
1.3业务测试接入流程
为客户接入测试便捷化，制定了如下的测试接入流程：
2准备工作
2.1获取测试环境账号
客户或电信政企经理登录“天翼物联产业联盟”微信公众号填写开放平台测试账号申请。
图2-1查找微信公众号并进入
图2-2点击联盟服务选择实验服务申请
图2-3完成表格填写并提交
图2-4账号申请通过后，收到账号和初始密码
----结束
2.2创建APP应用
登录中国电信物联网开放平台对接测试环境SPPortal（https:
//180.101.147.135:
8843）。
初次登录需要修改初始密码。
图2-1SPPortal
选择【应用管理】->
【应用】点击右上角“+创建应用”。
典型的NB-IoT应用的参数设置可参考如下设置：
所属行业：
公用事业（NB-IoT）
关联API包：
基础API包和公用事业（NB-IoT）API包
平台能力：
规则引擎
数据存储时间：
7。
当超过了数据存储时间以后，应用将不能再获取到已上报的数据。
短信服务器：
使用户可以通过短信服务器实现与工程师的紧密联络。
服务器可以选择平台已经支持的服务器之一，也可以选择第三方服务器。
邮件服务器：
使用户可以通过邮件服务器实现与工程师的紧密联络。
CA证书：
第三方应用通过HTTPS对接中国电信物联网开放平台时服务器下发的证书，用于身份识别和电子信息加密，实现双向认证。
证书文件限制为不超过1M的PEM格式文件。
当第三方应用通过HTTP对接中国电信物联网开放平台时，不需要上传CA证书。
图2-2创建应用
创建APP成功后，得到应用ID和应用密钥，请保存。
2.3NB-IoT参数设置
点击已经创建好的应用，并对NB-IoT参数进行设置。
图2-1已创建应用
图2-2NB-IoT设置
目前平台支持设置如下三种模式：
PSM模式：
powersavingmode，省电模式。
对下行业务时延无要求，对于下行业务消息，可等待设备发送上行数据进入连接态后再发送，可进一步节省终端功耗。
如智能水表。
DRX模式：
discontinuousreception，不连续接收模式。
对下行业务时延要求高，可认为设备一直在线，消息能够立即下发。
如路灯。
eDRX模式：
ExtendedidlemodeDRX，扩展不连续接收模式。
DRX的扩展模式，对下行业务时延有较高要求，可根据系统配置立即下发消息或者缓存消息。
如智能穿戴设备。
当省电模式设置为PSM模式时，ACTIVETIMER可以不设置，无影响；
当省电模式设置为eDRX模式时，eDRX周期的设置需要与网络侧的一致，请联系中国电信物联网开放平台支持人员获取参数配置数据。
这里参数的设置要与网络侧保持一致，参数的设置只是配置到中国电信物联网开放平台中，不会配置到网络或者设备。
3定义设备模型
Profile定义设备模型有两种方式：
方式一：
从Portal在线制作Profile文件，请参考章节3.1~3.7
方式二：
参考《中国电信物联网开放平台_设备能力描述文件profile开发指南》离线制作Profile，然后再参考章节3.8上传离线Profile文件
3.1设备模型介绍
设备模型是指中国电信物联网开放平台支持注册新的设备模型，并支持对设备模型进行管理。
设备模型包括:
产品、设备模板和服务模板。
产品由设备模板、制造厂商、型号、协议等构成的具体实例。
SPPortal支持用户根据需求自定义产品。
设备模板通过设备服务定义设备基本特性和能力。
设备模板由多个服务模板组成。
SPPortal支持用户使用预置设备模板，也支持用户根据需求自定义设备模板。
服务模板定义设备能力，包括属性、命令、事件等。
SPPortal支持用户使用预置服务模板，也支持用户根据需求自定义服务模板。
图3-1产品、设备模板和服务模板关系图:
3.2定义产品的设备模型
设备模型定义了一个类型的设备具备哪些服务能力，每个服务有哪些属性（即上报的数据有哪些字段），有哪些命令以及命令的参数。
每个厂家在接入NB-IoT之前必须先定义自己的产品的设备模型。
下面通过一个例子介绍一下如何定义产品设备模型。
例如:
某产品设备的制造信息如下：
●厂商ID：
ChinaTelecom
●厂商名字：
●设备类型：
SmartDevice
●设备型号：
NBIoTDevice
该设备具有三个服务能力：
分别为亮度（Brightness）、温度（Temperature）、电力（Electricity）。
其中，亮度（Brightness）服务拥有一个亮度属性及设置该属性值的命令方法；
温度（Temperature）服务具有一个温度（temperature）属性及一个设置温度的方法命令；
电力（Electricity）具有四个属性，分别为：
电压（votage），电力当前值（current），频率（frequency）及功率因数（powerfactor）。
下面通过在SPportal设置该设备能力到平台。
图3-1产品设备示例图
3.3新增服务模板
使用浏览器登录SPPortal；
单击左侧
，打开“设备管理”页面；
单击“模型”下拉选项，单击“服务模板”，打开“服务模板”页面；
单击界面右上角“+新增服务模板按钮”。
例如，增加温度（Temperature）服务。
图3-1新增服务模板
单击确定后即可，温度服务模板创建完毕。
服务电力（Electricity）创建过程类似，不再赘述。
服务亮度（Brightness）已经预置，不用再创建。
3.4新增服务属性
以温度服务为例，该服务具有一个属性即温度（temperature），现新增该属性。
点击刚新增的温度服务。
图3-1Temperature服务
单击“属性”，单击“新增属性”，弹出“新增属性”页面。
根据实际情况设置下列参数。
∙名称：
属性名称，且系统唯一。
∙属性类型：
包括int、long、decimal、string、DateTime、jsonObject。
∙最小、最大、步长、单位：
当属性类型为int、long和decimal时，才会出现。
∙长度：
当选择属性类型为string、jsonObject或DateTime时，才会出现。
∙访问模式：
属性能够访问的模式。
∙是否必选：
属性是否必选。
图3-2新增服务属性
点击
，即可完成对温度属性的设置。
其他服务属性值设置类似，不再赘述。
3.5新增服务命令
以温度服务为例，该服务具有一个命令即一个设置温度的命令（SET_TEMPERATURE）现新增该服务命令。
点击刚刚新增的温度服务，单击“命令”，单击“新增命令”，弹出“新增命令”页面。
图3-1新增服务命令
单击确定即可在命令栏看到新增的命令。
3.6新增设备模板
使用浏览器登陆SPPortal；
单击“模型”下拉选项，选择“关于模型”，打开“关于模型”页面；
单击“自定义设备模板”，打开“设备模板”页面。
单击右上角“新增设备模板”，弹出“新增设备模板”页面。
根据实际情况设置下列参数：
∙设备模板：
设备模板名称，且系统唯一，这里填写SmartDevice。
∙描述（可选）：
设备模板描述内容。
图3-1新增设备模板
3.7新增自定义产品
单击“自定义产品”，打开“产品”页面。
单击右上角“新增设备”按钮，弹出“添加设备产品”页面。
∙设备类型：
产品所属的设备类型。
作为例子，这里填写3.6节设备模板名称。
∙型号：
产品所属的型号。
∙厂商ID：
产品所属的厂商ID。
∙厂商：
产品所属的厂商名称。
∙协议：
产品所属的协议类型。
NB-IoT目前仅有CoAP和LWM2M两种协议，请正确选择接入协议。
∙单击“点击上传文件”上传产品图像。
∙（可选）描述：
产品描述内容。
图3-1添加设备产品
单击
，完成自定义设备产品创建。
创建完设备后，设备产品模型中的服务项还是空的，需要将温度（Temperature）、电力（Electricity）两个已创建好的服务添加。
另外还需要添加预置服务亮度（Brightness）。
单击已创建好的设备产品,单击服务列表中的“添加服务”，打开“添加服务类型”页面，选定需要加入的服务能力。
即可完成。
图3-2向产品中添加服务
3.8编写profile文件
此章节针对方式二使用《中国电信物联网开放平台_设备能力描述文件profile开发指南》离线制作Profile文件后再导入到中国电信物联网开放平台的场景。
模型profile文件包的组成
图3-1一级目录结构
profile文件夹中，包含devicetype-capability、devicetype-display两个JSON文件；
其中devicetype-capability描述了设备的manufacturerId（制造商ID）、manufacturerName（制造商名称）、model（设备型号）、protocolType（协议类型）、deviceType（设备类型）、serviceTypeCapabilities（服务能力）。
图3-2profile文件示例
service文件夹主要描述profile文件夹的devicetype-capability文件中serviceTypeCapabilities字段提到的各项服务能力，并对每一项能力进行描述
图3-3service文件夹结构示例
3.9上传profile文件
上传profile文件功能菜单的路径为：
设备管理>
模型>
导入模型
图3-1将离线制作的Profile文件导入
图3-2导入成功
4开发编解码插件并安装
4.1开发编解码插件
设备模型是设备的抽象模型，把设备的功能抽象为服务，对编解码库插件而言，其定义了decode接口的输出，encode接口的输入格式。
编解码插件开发可参考《中国电信物联网开放平台V100R001C30编解码库开发与升级指南》文档。
4.2编解码插件质检
编解码插件的质检是检测编解码是否能够正常使用的关键步骤，请参照编解码插件检查工具说明，来进行操作。
工具下载地址：
4.3对插件包进行离线签名
当编解码插件开发完后，在安装到平台之前，需要先对插件包进行签名。
此时需要下载离线签名工具并进行签名操作。
操作步骤如下：
步骤1使用浏览器登录SPPortal。
步骤2下载离线签名工具。
1.单击左侧
图标，打开管理页面。
2.单击左侧导航栏“工具”，在右侧区域单击“下载”，下载离线签名工具。
步骤3在下载路径找到压缩包“signtool.zip”，右键菜单中选择“Extracttosigntool\”解压缩至文件夹“signtool”。
步骤4进入signtool文件夹，运行“signtool.exe”。
操作界面如下所示。
图4-1离线签名工具
步骤5生成数字签名公私钥对。
3.根据实际情况选择签名算法。
目前提供两种签名算法：
−ECDSA_256K1+SHA256
−RSA2048+SHA256
4.设置“私钥加密口令”。
口令复杂度说明：
−口令长度至少为6个字符
−口令必须包含如下至少两种字符的组合：
⏹至少一个小写字母
⏹至少一个大写字母
⏹至少一个数字
⏹至少一个特殊字符：
`~!
@#$%^&
*（）-_=+\|[{}];
:
'
"
<
.>
/？
和空格
5.单击“生成公私密钥”，在弹出的窗口中选择需要保存的目录，单击“确定”。
可在保存的目录下查看生成的公私密钥文件。
−公钥文件：
public.pem
−私钥文件：
private.pem
步骤6对软件包进行数字签名。
离线签名工具只能对.zip格式的压缩包进行数字签名。
6.在“软件包数字签名”区域，单击“导入私钥文件”，选择步骤5.3中生成的私钥文件，单击“打开”。
7.在弹出的对话框中，输入步骤5.2中设置的口令，单击“确定”。
8.在“需要数字签名的软件包”区域，选择需要进行数字签名的软件包。
单击“打开”。
9.单击“进行数字签名”。
签名成功后，在原软件包所在目录生成名为“XXX_signed.XXX”的带签名的软件包。
步骤7软件包签名验证。
10.在“软件包签名验证”区域，单击“导入公钥文件”，选择步骤5.3中生成的公钥文件，单击“打开”。
11.在“需要验签的软件包”区域，选择步骤6中生成的名为“XXX_signed.XXX”的带签名的软件包。
12.单击“进行软件包验签”。
−验证成功则弹出“验证签名成功！
”提示框。
−验证失败则弹出“验签异常！
4.4上传公钥及签名后的插件包
编解码插件化能够动态的新增编解码库，这样新增设备接入时，只需要把对应的编解码库动态导入到平台，就能够兼容新增的设备。
请将公钥以及签名后的插件包发送给中国电信物联网开放平台支持人员，由中国电信完成公钥和签名后的插件包的上传配置。
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：
StatusCode:
200OK
application/json
{
"
accessToken"
*******"
tokenType"
expiresIn"
refreshToken"
scope"
}
注意：
如果多次获取令牌，则之前的令牌失效,最后一次获取的令牌才有效。
请勿并发获取令牌。
这一步获取token后，接下来所有接口必须在https消息头里携带以下字段。
图5-1携带字段
字段
app_key
填写appId
Authorization
填写BeareraccessToken（注意中间有空格）
5.2订阅
为了能接受设备上报的数据，NA需要向中国电信物联网开放平台订阅通知消息。
订阅设备数据上报通知：
POSThttps:
port/iocm/app/sub/v1.1.0/subscribe
Header：
app_key:
******
Authorization:
Bearer******
application/json
notifyType"
deviceDataChanged"
callbackurl"
//183.4.11.104:
9999/"
订阅成功后，设备上报数据时，中国电信物联网开放平台会将数据推送到callbackurl上。
5.3注册设备
5.3.1有应用服务器设备注册
所有设备必须先在北向进行注册，才允许连接到平台。
通过注册设备，平台会为每个设备分配一个唯一的标识deviceId，后续应用操作这个设备时都通过deviceId来指定设备。
另外，还返回psk参数（如果用户未指定psk参数，平台会随机分配一个参数），南向设备绑定时，如果设备与平台之间走DTLS加密通道，则须用到该参数，请保存。
在SPportal上也可以通过deviceId来找到设备。
port/iocm/app/reg/v1.1.0/devices
******"
verifyCode"
447769804451095"
nodeId"
psk"
12345678"
timeout"
201CREATED
deviceId"
0
verifyCode和nodeId需要填写为设备唯一标识，请联系模组厂商确认唯一标识；
nodeId需与章节5.5.2中的endpointname一致。
timeout建议填写为0。
5.3.2无应用服务器设备注册
无应用服务器情况下，厂商可以用设备模拟器来进行设备的模拟注册。
方便厂商进行联调开发。
IP：
180.101.147.89，端口：
8743
图5-1设备注册工具登录
图5-2填写平台IP、端口、应用ID、应用密码后，进行登录
图5-3登录后界面
填写设备NodeID等信息，并进行注册，其中NodeID为设备唯一编码ID，VerifyCode与NodeID相同；
TimeOut参数填写，请根据设备传输情况填入（如果即时传输，请填“0”）
图5-4设备注册
注册完成后，请修改设备的其他信息，这些信息根据profile文件中填写的内容，进行填写，需要保持一致
图5-5修改设备信息
图5-6修改成功后
图5-7设备注册后，在平台可看到设备情况
5.4设置设备信息
这一步是为了把设备的厂商、型号、设备类型等信息设置到平台，平台在处理过程中需要这些信息。
PUT
port/iocm/app/dm/v1.1.0/devices/{deviceId}
manufacturerId"
****"
manufacturerName"
deviceType"
protocolType"
CoAP"
model"
上述例子中的5个字段都必须进行设置。
5.5设备接入
5.5.1接入端口与协议
目前中国电信物联网开放平台支持加密与非加密两种接入设备接入方式，其中加密业务数据交互端口是5684端口。
5684端口走DTLS+CoAP协议通道接入，非加密端口为5683，接入协议为CoAP。
NB-IOT设备端使用加密端口接入时提供必要的数据凭证，并支持标准DTLS协议。
∙设备在登录平台前，需将设备对接平台的端口设置为5684（即走DTLS加密通道）。
∙建议将设备出厂前的PSK秘钥预置到中国电信物联网开放平台中，PSK秘钥的数据类型为String型，长度范围为8-32位。
调用5.3注册设备接口，即可将设备PSK设置到平台。
使用用非加密端口接入时，只需要使用原生的CoAP协议进行传输，同时将对接平台设置为5683即可。
5.5.2注册接口
无论是加密方式还是非加密方式，设备都只需使用标准OMA接口进行注册，CoAPurl里带的参数可能有:
ep={EndpointClientName}&
lt={Lifetime}&
sms={MSISDN}&
lwm2m={version}&
b={b
升级会员 