电信物联网开放平台nb iot业务对接指导书

本文档针对NB-IoT业务，从准备工作、自定义设备模型、编插件开发、应用接入NB-IoT在开发者Portal线上开发的编插件，在后，在开发者Portal线上开发的编插件，支持对命令IoT平台提供了半透传编插件模板用于警示紧急的情形，若不避免，将会导致人员或严重的人身。 “注意”不涉及人身用于突出重要/“说明”不是安全警示信息，不涉及人身、设备及环境由中国电信公司提出并归口起草单位：中国电信物联网开放前 目 申 创建APP应 NB-IoT参数设 Profile介 开发 编插件介 开发者Portal插件开 离线开发编插 开发编插 编插件质 订 有应用服务器设备........................................................................................................................................无应用服务器设备........................................................................................................................................ NA订阅固件升级状态和结 北向NA订阅接 北向NA订阅通 设备...................................................................................................................................... PSK的预 PSK的更 12功 开放测 在设备侧，智能设备采用了NB-IOT，它和中国电信物联网开放平台之间通CoAP协议通讯。CoAPpayloadserverhttp/httpsAPI来控制设备，平json格式数据。NB-IOTNB-IoT设备、NB-IOT网络、中国电信物联网开放平台、垂直行业NB-IOT设备：CoAP协议接入，NB-IOT网络NB-IoTNB-IoT终端建立用户面承载，传下行业务数据。中国电信物联网开放平台：实现对各种NB-IoT设备数据的统一管理，同时向第应垂直行业应用：实现对NB设备的业务管理，包括业务、业务控制和呈现等，由第基于中国电信物联网开放平台开放接口进行开发。客户或电信政企经理登录“天翼物联” 2.1.2申客户或者电信政企经理登录“天翼物联”（ APP登录中国电信物联网开放平台对接测试环境SPPortal（初次登录需要修改初始。NB-IoT应用的参数设置可参考如下设置：APIAPI包和公用事业(NB-IoT)API包17天（以默认值为例。服务器：与规则引擎配合使用，可以在指定条件下通过服务器给指定人员。服务器可以选择经支持的服务器之一，也可以选择第服务器。定人员。服务器可以选择经支持的服务器之一，也可以选择第服务器。CA：用于消息推送场景，需要上传应用服务器的CA。如果订阅的回调地址是HTTPs地址，就需要上传。文件限制为不超过1M的PEM格式文件；中国电信物联网开放平台预制了7个CA机构颁发的，如果对接的第 书在这7个之中，则不需要上传到平台，否则需要在IoT中进行上传。7个 别为CAbaltimore、digicert、entrust、geotrust、globalsign、thawte、verisign。说明当第应用通过HTTP对接中国电信物联网开放，不需要上传CA，但APPIDNB-IoTNB-IoTNB-IoTAPN对应的模式保持一致。平台根据设置的PSM模式：当命令为缓存下发时，平台将收到的下发命令缓存，等设备上报数据时，按顺序将缓存令全部下发；当命令为立即下发时，平台将收到的PSM态，设备将不能收到下发命令，设备处DRX模式：当命令为缓存下发时，平台将收到的下发命令缓存，按顺序将缓存令全部下发；当命令为立即下发时，平台将收到的下发命令立即下发，设序将缓存令全部下发；当命令为立即下发时，平台将收到的下发命令立即下发，说明eDRX模式时，eDRX周期的设置需要与网络侧的一致，请联系中国ProfileProfile文件是用来描述一款设备是什么、能做什么以及如何控制该设备的文Profile文件。Profile文件的内容主要包括两部分，一部分是设备的基础属性信息，如ID开发者Portal支持开发Profile；对开发完成的Profile也支持导出和导入请使用章节2.1获取到的账号和登录开发者Portal。如果初始已经修改，请用Portal请参考开发者Portal使用指导完成Profile开发。开发者Portal使用指导地址： 登录开发者portal->Profile开发->Profile开发->自定义产品->创建全新产品->填写ID、厂商名称、协议类型，点击确定（如下图所示）发令，命令必须有字段，如下图所示：profileprofileIoT平台上使用。导出方法如下 编插件介BIoTCoPCP消息的数据BIoT通常较高，所以应用层数据一般采用十六进制格式。应用层数据电信物联网开jsonjson编插件。一款设备对应一个编插件。开发编插件有两种方式方式一：开发者Portal插件开发。此方式实现了化的开发，开发复杂度低；json格式消息需要计算后再转换的场景。开发者Portal插件开修改后的登录。Portal请参考开发者Portal使用指导完成Profile开发。开发者Portal使用指导地址： 20如设备上报数据码流为00000 传插件可以实现将666768（rawData）透传。Profile（profileprofile）->点击确定profile点击新增消息按钮，定义一条数据上报消息（消称可自定义具体操作和详细开发过程请直接参考开发者Portal支持完成的插件，后的编插件已经完成签名离线开发编插开发编插4个接口，同时附带了样例代码。编插件质工具地址：http:/ 1SPPortal步骤2离线签名工具单击左侧导航栏“工具”，在右侧区域单击“”，离线签名工具步骤3在路径找到压缩包“signtool.zip”，右键菜单中选择“Extracttosigntool\”解压缩4signtool文件夹，运行“signtool.exe5 6 6离线签名工具只能对.zip5.5中生成的私钥在弹出的框中，输入步骤5.2中设置的口令，单击“确定” 75.5中生成的公钥6中生成的名为“XXX_signed.XXX”的 为了防止应用接入中国电信物联网开放平台，应用首先需要进行登陆验证，登陆成功后获取令牌（accessoken。登录验证时使用章节2.2创建APPappIdsecret进行鉴权。APIAPIJavaSDKAPIJavaSDK说明文档》章节“4.1.1Token8.2附件的如果多次获取令牌，则之前的令牌失效,最后一次获取的令牌才有效。并发获取令

callbackurl上。APIAPI参考》的“订阅平台业务数JavaSDKAPIJavaSDK说明文档》章节“4.3.5应用订阅，样例代码请参考章节8.2附件的所有设备需要先在北向进行，才允许连接到平台。通过设备，平台会为每个devieIddeicedpsk参数（pk，S加密通道，则须用到该参数，请保SPportaldeviceId设备的API描述请参考《中国电信物联网开放平台API参考》的“直连设JavaSDKAPIJavaSDK说明文档》章节“4.2.1直连设备样例代码请参考章节8.2附件的verifyCode和nodeId需要填写为设备唯一标识；高通设备的唯一标识为urn:imei:xxxx，xxxx为IMEI号，海思设备的唯一标识为IMEI号，其他种类的设备唯一标识请联系模组厂商确认；IMEI6.1设备接入一节。timeout建0。无应用服务器情况下，厂商可以用开发者portal的应用模拟器来进行设备的。方登录开发者portal->我的设备->设备->选择需要设备的Profile（即选择一款设使用开发者portal设备时，已完成了设备和修改设备信息两个步骤应用服务器需要调用平台的修改设备信息接口，根据Profile文件对已的设备信（厂商、型号、设备类型等）进行修改，以实现设备和Profile文件的关联APIAPI参考》的“修改设备JavaSDKAPIJavaSDK说明文档》章节“4.2.48.2附件的NB-IoTmanufacturerId、manufacturerName、deviceType、model、protocolType5profile中定义的值保持一AT查询IMEI，IMEI即为设备标识，应用设备的，不能与其他设备重复，且只能设置一次。IMEI识，应用调用API设备时，如果设备使用的是海思设置网APN，APN与设备的休眠、保活等模式有关，需要与CoAP5683即可。APN如下图所示：登陆开发者Portal，在我的设备列表页面，查看设备状态，字段设备ID即为设备（Bound”登录开发者portal，选择模拟器->NB设备模拟器->绑定设备，在弹出的框中输IMEI 插步骤1设步骤2编APP{"requestId":null,"deviceId":"b8b92cc7-2622-4f27-a24b-041ab26f0b80", {"data":{"brightness":50}, {"serviceId":"Electricity",{ {"serviceId":"Temperature","serviceType":"Temperature","data":{"temperature":25},"eventTime":" }]}servicesBrightness,ElectricityTemperature服务数据就是经过编json格式的数据，字段和产品设备模型定义的一致。APP编APP编 插步骤3步骤4decodeAPIJavaSDKAPIJavaSDK说明文档》章节“4.4.18.2附件的portal->我的设备->点击对应的设备->历史命令页面，查看命令下发的情ACK（2.04Changed）命令应答（decodedeviceRspmid来标识命令和命令执行结果。在命令下发时，encodemid（int类1开始递增mid的值加到命令码流里（416进制码流，不够4位需要面补0，下发给设备。设备执行完命令后，再将mid与命令结果一起报decodemidint4.3离线开发说明ACK（2.04Changed）命立即下发：平台立即发送收到令，如果设备不或者设备没收到指令则下发失expireTime（简称TTL，表示最大缓存时间expireTimeexpireTime48小时。说明步骤1 应用服务器调用北向接口立即下发命令，参数expireTime传0表示立即下发，样Method:Method:POSTapp_key:{appID}{"deviceId":"********","command":{"method":"********","paras":{"paraName2":"paraValue2"}"callbackUrl":"}步骤2 平台收到命令后，调用插件编码，将命令下发给对应插件的encode函数，encode{{}步骤 平台将编码后令向设备下发步骤 平台向应用返回200OK响应，更新命令状态为SENT，表示命令已经下发步骤5 NB模组收到命令时，回CoAP协议的ACK消息（注：ACK消息对设备应用不可步骤 平台收到ACK后，认为命令送达设备。向NA推送送达通知。消息样例{{"deviceId":"6213fa11-68d6-4457-aa98-871a25c152c1","result":"resultCode":"DELIVERED", etail":null}}步骤 UE执行完命令，如果需要上报命令执行结果，则上报执行结步骤 平台调用插件，输出样例：其中mid参数表示命令标识，应该和步骤9 平台根据mid查找命令，并给NA上报命令响应通知，如果没有mid，那么平台不去匹配命令来更新命令成功或失败的状态，推送给NA的commandID为null。插件收到命令执行结果后，decode函数解析完成上报令应答json样例：{{"body":{}步骤1 NA下发命令时，expireTime传大于0的值表示缓存下发，平台把命令写入缓存队列，返回200OK。步骤2 平台会根据设备省电模式决定何时下发缓存命令：对PSM模式设备，平台等待设步骤3 时（即收到NB模组发送的ACK报文）开始下发后一个缓存命令。步骤4 平台对缓存命令的最大缓存时间有限制，由参数expireTime指定。当命令在平台缓存的时间超过expireTime时，命令将从缓存队列移除，不再进行发送处理。步骤 缓存命令的其他处理过程和立即命令相同LWM2Mfirmwareupdate对象。winRAR等压缩工具将固件包版本文件打包成ZIP4.3.314.3.3生成的public.pemSPPortal，选择应用管理，点击进入对应的应用下，在升2345NANA提供了订阅固件升级状态和升级结果的接口，NA订阅后，在平台对设备做NA推送固件升级状态变更和升级结果的消息。NANADMNA。携域信"app_key:"Authorization:Bearer******"NA"Authorization:Bearer******"{}}StatusCode:200NA中国电信物联网开放平台在A订阅触发时，会使用A订阅的回调接口向A推送订阅的消息平台的设备功能可以提供对设备属性的读写功能为了方便用户调用设备的LWM2M能力，平台将LWM2M对象实例映射为设备的ServiceID（设备服务 LwM2MLwM2M0LwM2MLwM2M0LwM2MAccessLwM2MAccess00ConnectivityConnectivity00ConnectivityConnectivity0FirmwareFirmware0为了使用LWM2M的设备，首先需要在设备profile里添加上表所示的LWM2M相profileprofileLWM2Mprofile样例进行删减，只保留将修改后的profile上传到平台后，设备，在SPportal的设备管理页面选择设备，点击“设备”页签，可以看到LWM2M的服务的字段：19truepmin和pmax来设置订阅上报的周期范围。LWM2M对象实例，不支持订阅单个字段。比如要订阅device对象，在设备页签点击“属性配置找到device服务，设如果设备，就可以收到Observe/3/0的消息，然后开始上报device对象的数据。待设备上报后，就可以在设备看到设备上报的数据：如果要取消订阅某个对象，可以在设备设置该对象对应的服务的CollectionFlag字