- 最新动态
- 产品介绍
- 价格说明
- 快速入门
- 开发指南
- 用户指南
- 最佳实践
- API参考
-
SDK参考
- SDK介绍(联通用户专用)
- 应用侧JAVA SDK API参考(联通用户专用)
- 应用侧Python SDK API参考(联通用户专用)
- 设备侧Agent Lite API参考(C)(联通用户专用)
- 设备侧Agent Lite API参考(Android)(联通用户专用)
- 设备侧Agent Lite API参考(Java)(联通用户专用)
-
常见问题
- 热门问题(联通用户专用)
-
方案咨询(联通用户专用)
- 开发中心、设备接入和设备管理的差异是什么?
- IAM子用户或子项目是否可以开通物联网平台服务?
- 物联网平台支持在华为云的哪些区域开通?
- 如何成为华为IoT生态合作伙伴?
- 物联网平台支持哪些接入方式和协议?
- 华为是否提供模组/硬件终端/应用软件等?
- 设备接入模拟器HubSimulator是否能在设备管理使用?
- 设备接入服务如何获取设备数据?
- 物联网平台的应用和设备可以无限创建吗?
- 物联网平台支持批量注册设备吗?
- 物联网平台对应用和设备有消息流控吗?
- 开发中心单个应用允许接入设备数是多少?
- 数据在物联网平台的保存时间是多久?
- 物联网平台支持的DTLS加密算法有哪些?
- 物联网平台支持二进制大小端模式切换吗?
- 什么是NB-IoT?
- 物联网平台支持的硬件架构和使用的相关组件有哪些?
-
设备集成(联通用户专用)
- 如何获取设备和应用对接地址?
- 如何下载LiteOS IDE/IoT Studio?
- 物联网平台允许一个IMEI号注册多个设备吗?
- 如何设置设备名称?
- IoT设备如何激活?
- 物联网平台如何切换设备的在线/离线状态?
- 通过网关接入的子设备,平台如何识别是哪一个设备?
- deviceId、nodeId和IMEI有什么对应关系?
- Agent Lite和Agent Tiny有什么区别?
- 使用Agent Lite接入的网关设备gwbindinfo.json文件丢失如何处理?
- 运行Agent Lite Java Demo报UnsatisfiedLinkError错误怎么处理?
- 设备如何发送文件至物联网平台?
- 开发中心模拟设备如何上报负数?
- 开发中心支持哪几种省电模式?
- 开发中心支持数据转发吗?
- 开发中心没有设备分组和批量添加设备,怎么办?
- 如何检测NB网络信号?
- NB模组附着网络失败如何处理?
- NB模组绑定设备失败怎么办?
- NB模组无法正常上报数据怎么办?
- NB设备上报数据为字符串时如何转换为二进制编码?
- NB设备接入时,出现513错误?
- 为什么执行AT+CUFN=1会返回error?
- 平台向NB-IoT设备缓存下发命令,为什么设备一直收到同一条控制命令?
- AT+CGDCONT=1, CTNB是什么?
- NB-IoT设备如何选择PSM、DRX、eDRX模式?
- 应用集成(联通用户专用)
-
订阅推送(联通用户专用)
- 调用订阅接口时,回调地址如何获取?
- 应用服务器如何收到命令状态变化的通知?
- 如何获取证书?
- 回调地址可以使用域名吗?
- 订阅后消息推送失败,例如提示503如何处理?
- 应用服务器收到数据,但是平台显示推送失败?
- 应用服务器只有内网地址,能否订阅成功?
- 调用订阅接口时,提示回调地址不合法?
- 物联网平台只支持HTTPS的回调地址吗?
- 回调地址可以修改吗?
- 推送证书失效怎么处理?
- 调用删除单个订阅接口时,subscriptionId如何获取?
- 设备数据变化通知和批量设备数据变化通知的区别是什么?
- 应用服务器如何获取物联网平台推送消息时使用的地址?
- 物联网平台订阅推送是否具有重推机制?
- 为什么设备上报一条数据后应用服务器会收到多条推送?
- 在同一个应用下,平台可以将不同设备上报的数据,推送到两个服务器吗?
- NB-IoT设备已订阅消息确认和命令响应通知,为何应用服务器收不到推送消息?
- 数据上报(联通用户专用)
- 命令下发(联通用户专用)
- 产品模型/Profile(联通用户专用)
- 编解码插件(联通用户专用)
- 软/固件升级(联通用户专用)
- 文档下载
- 通用参考
链接复制成功!
命令下发(联通用户专用)
非联通用户请查看设备接入服务。
概述
为能有效地对设备进行管理,设备的产品模型中定义了物联网平台可向设备下发的命令,应用服务器可以调用物联网平台开放的API接口向单个设备或批量设备下发命令,或者用户通过物联网平台直接向单个设备下发命令,以实现对设备的远程控制。
物联网平台有两种命令下发机制,如下表所示。
命令下发机制 |
定义 |
适用场景 |
LWM2M/CoAP协议设备 |
集成Agent Lite SDK设备/原生MQTT设备 |
---|---|---|---|---|
立即下发 |
不管设备是否在线,平台收到命令后立即下发给设备。如果设备不在线或者设备没收到指令则下发失败。支持给本应用的设备和被授予权限的其它应用的设备下发命令。 |
立即下发适合对命令实时性有要求的场景,比如路灯开关灯,燃气表开关阀。使用立即下发时,命令下发的时机需要由应用服务器来保证。 |
建议用户使用缓存下发模式,工作模式设置为PSM模式(系统默认值)。 如需使用立即下发模式(工作模式设置为DRX或eDRX模式),需要在设备上报数据后立即下发命令才能成功。 |
适用 |
缓存下发 |
物联网平台在收到命令后先缓存,等设备上线或者设备上报数据时再下发给设备,如果单个设备存在多条缓存命令,则进行排队串行下发。支持给本应用的设备和被授予权限的其它应用的设备下发命令。 |
缓存下发适合对命令实时性要求不高的场景,比如配置水表的参数。 |
适用。工作模式设置为PSM模式(系统默认值)。 |
不适用 |
业务流程
LWM2M/CoAP协议设备场景
物联网平台提供立即下发和缓存下发两种机制。应用服务器向物联网平台下发命令时,携带参数expireTime(简称TTL,表示最大缓存时间)。如果不带expireTime,则默认expireTime为48小时。

- 应用调用创建设备命令接口,下发请求到物联网平台,携带expireTime参数为0。消息样例如下:
Method: POST request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands Header: "app_key: ******" "Authorization:Bearer******" Content-Type:application/json Body: { "deviceId": "********", "command": { "serviceId": "Brightness", "method": "SET_DEVICE_LEVEL", "paras": { "value": "1", } }, "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl", "expireTime": 0, "maxRetransmit": 1 }
- 物联网平台调用编解码插件对命令请求进行编码后,会通过LWM2M协议定义的设备管理和服务实现接口的Execute操作下发命令,消息体为二进制格式。
- 物联网平台向应用返回201 Created,携带命令状态为SENT。(如果设备不在线或者设备没收到指令则下发失败,命令状态为FAIL)
- 设备收到命令后返回ACK响应。
- 若应用下发命令时携带了"callbackUrl",物联网平台通过命令状态变化通知接口推送消息给应用,携带命令状态为DELIVERED。消息样例如下:
Method: POST request: Body: { "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba3", "result": { "resultCode": "DELIVERED", "resultDetail": null } }
- 设备执行命令后通过205 Content响应返回命令执行结果。
- 若应用下发命令时携带了"callbackUrl",物联网平台会调用编解码插件对设备响应进行解码,然后通过命令状态变化通知接口推送消息给应用,携带命令状态为SUCCESSFUL。消息样例如下:
Method: POST request: Body: { "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba", "result": { "resultCode": "SUCCESSFUL", "resultDetail": null } }

- 应用调用创建设备命令接口,下发请求到物联网平台,携带expireTime参数大于0。
- 物联网平台将命令写入缓存队列,并上报201 Created,携带命令状态为PENDING。
- 设备上线或设备上报数据到平台。
- 物联网平台调用编解码插件对命令请求进行编码后,根据协议规范下发命令给设备。
- 若应用下发命令时携带了"callbackUrl",物联网平台通过命令状态变化通知接口推送消息给应用,携带命令状态为SENT。
- 后续流程请参考“命令立即下发”的步骤4到步骤7。
集成Agent Lite SDK设备/原生MQTT设备场景
对于集成Agent Lite SDK设备/原生MQTT设备,物联网平台只支持直接下发模式,设备不在线时命令下发失败。
- 应用调用设备服务调用接口,下发请求到物联网平台。消息样例如下:
Method: POST request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands Header: "app_key: ******" "Authorization:Bearer******" Content-Type:application/json Body: { "deviceId": "********", "command": { "serviceId": "Brightness", "method": "SET_DEVICE_LEVEL", "paras": { "value": "1", } }, "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl", "expireTime": 0, "maxRetransmit": 1 }
- 物联网平台根据协议规范下发命令给设备。
MQTT设备必须先订阅平台命令下发接口对应的Topic才能收到平台下发的命令,消息样例如下:
{ "msgType": "cloudReq", "serviceId": "Brightness", "mid": 2016, "cmd": "SET_DEVICE_LEVEL", "paras": { "value": "1" } }
- 物联网平台向应用返回202 Accepted,携带命令状态为SENT。
- 设备收到命令后返回ACK响应。
- 若应用下发命令时携带了"callbackUrl",物联网平台通过命令状态变化通知接口推送消息给应用,携带命令状态为DELIVERED。消息样例如下:
Method: POST request: Body: { "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba", "result": { "resultCode": "DELIVERED", "resultDetail": null } }
- 设备执行命令后通过设备命令响应通知接口返回命令执行结果,消息样例如下:
response: Status Code: 200 OK
- 若应用下发命令时携带了"callbackUrl",物联网平台会调用编解码插件对设备响应进行解码,然后通过命令状态变化通知接口推送消息给应用,携带命令状态为SUCCESSFUL。消息样例如下:
Method: POST request: Body: { "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba", "result": { "resultCode": "SUCCESSFUL", "resultDetail": null } }
单个设备命令下发
LWM2M/CoAP协议设备
两种方式创建单个NB-IoT设备的命令下发:
- 调用创建设备命令接口。
- 在控制台上创建命令下发,操作步骤如下。
- 登录物联网平台控制台,点击右上角“进入设备管理服务”。
- 在设备列表中,单击具体的设备进入到设备的详情页面。
- 在“命令”页签中,点击右上角“命令下发”,在弹出的窗口中选择需要下发的命令并设置命令参数。
说明:
- 仅NB-IoT设备支持通过控制台进行下发命令操作。
- 设备支持的命令,需要由产品模型定义后,才能在此进行命令下发操作。
- 下发命令的参数中,带“*”的参数为必选配置项,选择不同的命令,界面所呈现的参数不同。
- 在界面上,展示通过界面或“创建设备命令”接口给设备下发的历史命令列表,通过该功能可以详细查看命令下发任务的创建时间、平台发送命令的时间、送达的时间、发送的状态等信息,便于用户了解命令的命令执行状态说明。
同时,还支持通过调用相关API接口查询、修改、撤销设备命令等操作,如下表所示。
API接口 |
功能 |
---|---|
应用服务器向设备下发命令后,可调用此接口在物联网平台查询下发命令的状态及内容信息,以了解命令的执行情况。 |
|
应用服务器向设备下发命令后,如果由于命令排队、设备不在线等原因,物联网平台还未把命令下发给设备执行,此时应用服务器可调用此接口修改该命令的状态信息。当前仅支持把命令状态修改为CANCELED状态,即撤销命令的执行。 |
|
应用服务器向设备下发命令后,如果由于命令排队、设备不在线等原因,物联网平台还未把命令下发给设备执行(PENDING状态),此时应用服务器可调用此接口撤销指定设备的所有未下发的命令,对于已下发成功的命令不可撤销。 |
|
应用服务器创建了设备命令撤销任务后,可调用此接口查询设备命令撤销任务的详细信息和执行状态,以了解撤销任务的执行情况。 |
集成Agent Lite SDK设备/原生MQTT设备
通过调用设备服务调用接口,向设备下发命令。
支持通过控制台设备详情里的“命令”页签,查看给设备下发的历史命令列表,可以详细查看命令下发任务的创建时间、平台发送命令的时间、送达的时间、发送的状态等信息,便于用户了解命令的执行状态。
当前不支持通过API接口进行历史命令下发任务的查询。
批量设备命令下发
当前物联网平台仅支持对批量NB-IoT设备进行相同命令的下发。应用服务器可以调用创建批量任务接口,对批量设备下发控制指令。
批量任务下发之后,可以登录物联网平台控制台,点击右上角“进入设备管理服务”。在“批量任务”->“批量命令下发”界面查看任务执行的状态和结果,如果成功率低于100%,则可以单击具体的任务名称,进入任务详情,查看执行失败的原因。
命令执行状态说明
命令执行状态以及状态变化机制如下所示。
命令执行状态 |
说明 |
---|---|
等待(PENDING) |
|
超期(EXPIRED) |
|
取消(CANCELED) |
如果命令下发任务为“等待”状态时,用户人工取消了命令下发任务,则任务状态变更为“取消”。 |
已发送(SENT) |
|
超时(TIMEOUT) |
NB-IoT设备收到命令后,物联网平台在180秒内未收到设备反馈的收到命令响应,此时状态会变为“超时”。MQTT设备无此状态。 |
已送达(DELIVERED) |
物联网平台收到设备反馈的已收到下发命令响应后,状态变为“已送达”。 |
成功(SUCCESSFUL) |
如果设备在执行完命令后,会给物联网平台反馈命令执行成功的结果,将任务状态变更为“成功”。 |
失败(FAIL) |
|