设备接入 IoTDA设备接入 IoTDA

文档首页> 设备接入 IoTDA> 用户指南> 消息通信> 命令下发> MQTT设备命令/属性/消息下发
更新时间:2021/07/08 GMT+08:00
分享

MQTT设备命令/属性/消息下发

物联网平台支持MQTT协议设备进行命令下发,属性设置,属性查询以及消息下发等操作。其中消息下发包括立即下发和缓存下发两种机制。

MQTT设备命令下发/属性设置/属性查询

命令下发,属性设置,属性查询业务流程相同,应用下发命令之后, 应用在请求中同步等待设备的命令执行结果。 本文仅以下发命令为例,属性设置和属性查询分别参考修改设备属性查询设备属性接口。

  1. 应用调用下发设备命令接口,下发请求到物联网平台,命令下发消息样例如下:
    POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/commands
    Content-Type: application/json
    X-Auth-Token: ********
    
    {
      "service_id" : "WaterMeter",
      "command_name" : "ON_OFF",
      "paras" : {
        "value" : "ON"
      }
    }
  2. 物联网平台根据协议规范下发命令给设备。
    MQTT设备必须先订阅平台命令下发下行接口对应的Topic才能收到平台下发的命令,消息样例如下:
    Topic: $oc/devices/{device_id}/sys/commands/request_id={request_id} 
    数据格式:  
    {
      "object_device_id": "{object_device_id}",
      "command_name": "ON_OFF",
      "service_id": "WaterMeter",
      "paras": {
        "value": "ON"
      }
    }
  3. 设备执行命令后通过平台命令下发上行接口返回命令执行结果,消息样例如下:
    Topic:$oc/devices/{device_id}/sys/commands/response/request_id={request_id}
    数据格式:  
    {
        "result_code": 0,
        "response_name": "COMMAND_RESPONSE",
        "paras": {
            "result": "success"
        }
    }
  4. 应用侧收到发送HTTP下发命令的同步响应结果。消息样例如下:
    Status Code: 200 OK
    Content-Type: application/json
    
    {
      "command_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
      "response" : {
        "result_code" : 0,
        "response_name" : "COMMAND_RESPONSE",
        "paras" : {
          "result" : "success"
        }
      }
    }

MQTT设备消息下发

MQTT设备消息下发分为缓存下发和立即下发, 当设备在线时会立即下发, 当设备不在线时会先把消息缓存起来,等设备上线后下发。

  • MQTT协议设备消息缓存下发

    本文介绍MQTT协议缓存消息下发流程。

    1. 应用调用下发设备消息接口,下发请求到物联网平台,下发消息样例如下:
      POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
      Content-Type: application/json
      X-Auth-Token: ********
      
      {
        "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364",  
        "name": "messageName",  
        "message": "HelloWorld",   
        "topic": "messageDown"
      }
    2. 物联网平台向应用返回201 Created,消息状态为PENDING。
    3. 物联网平台根据设备消息状态变更通知接口推送消息结果给应用,消息样例如下:
      Topic: $oc/devices/{device_id}/sys/messages/down  
      数据格式:
      {  
          "resource": "device.message.status",  
          "event": "update",  
          "notify_data": {   
            "message_id": "string",   
            "name": "string",    
            "device_id": "string",    
            "status": "PENDING",   
            "timestamp": "string"  
           }
       }
    4. 设备上线。
    5. 设备订阅消息下发的topic,用于接收消息,订阅的topic见步骤6
    6. 物联网平台根据协议规范下发消息给设备。MQTT设备必须先订阅平台消息下发下行接口对应的Topic才能收到平台下发的消息,消息样例如下:
      Topic: $oc/devices/{device_id}/sys/messages/down  
      数据格式:
      {
          "object_device_id": "{object_device_id}",
          "name": "name",
          "id": "id",
          "content": "hello"
      }

    7. 平台将消息的最终结果推送给应用服务器,消息结构参考步骤3

  • MQTT协议设备消息立即下发

    本文介绍MQTT协议消息立即下发流程。

    1. 应用调用下发设备消息接口,下发请求到物联网平台,下发消息样例如下:
      POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
      Content-Type: application/json
      X-Auth-Token: ********
      
      {
        "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364",  
        "name": "messageName",  
        "message": "HelloWorld",   
        "topic": "messageDown"
      }
    2. 物联网平台根据协议规范下发消息给设备。MQTT协议设备必须先订阅平台消息下发下行接口对应的Topic才能收到平台下发的消息,消息样例如下:
      Topic: $oc/devices/{device_id}/sys/messages/down  
      数据格式:
      {
          "object_device_id": "{object_device_id}",
          "name": "name",
          "id": "id",
          "content": "hello"
      }
    3. 物联网平台根据设备消息状态变更通知接口推送消息结果给应用,消息样例如下:
      Topic: $oc/devices/{device_id}/sys/messages/down  
      数据格式:
      {  
          "resource": "device.message.status",  
          "event": "update",  
          "notify_data": {   
            "message_id": "string",   
            "name": "string",    
            "device_id": "string",    
            "status": "string",   
            "timestamp": "string"  
           }
       }

MQTT设备下发消息状态

消息执行状态

说明

等待(PENDING)

MQTT协议设备不在线,物联网平台会将消息进行缓存,此时任务状态为“等待”状态。

超时(TIMEOUT)

物联网平台缓存的PENDING状态的消息,如果1天之内还没有下发下去,物联网平台会将消息状态设置为"超时”。

已送达(DELIVERED)

物联网平台将消息发送给设备后,状态变为“已送达”。

失败(FAILED)

物联网平台发送消息给设备不成功,消息状态变为“失败”。

单个MQTT设备同步命令下发

平台支持通过调用下发设备命令接口和在控制台上创建命令下发任务方式创建单个MQTT协议设备的命令下发功能。本文介绍如何在控制台上创建命令下发业务。

  1. 访问设备接入服务,单击“立即使用”进入设备接入控制台。
  2. 单击“设备”,在设备列表中,单击具体的设备进入到设备的详情页面。
  3. 在“命令”页签,单击同步命令下发右侧的“命令下发”,在弹出的窗口中选择需要下发的命令并设置命令参数。

    • 设备支持的命令,需要由产品模型定义后,才能在此进行命令下发操作。
    • MQTT设备仅支持同步命令下发,LwM2M/CoAP设备的异步命令下发,请前往LWM2M/CoAP设备命令下发

当前不支持通过API接口进行历史命令下发任务的查询,支持历史消息的查询,相关API如下表所示。

API接口

功能

下发设备命令

设备的产品模型中定义了物联网平台可向设备下发的命令,应用服务器可调用此接口向指定设备下发命令,以实现对设备的同步控制。平台负责将命令以同步方式发送给设备,并将设备执行命令结果同步返回, 如果设备没有响应,平台会返回给应用服务器超时。

查询设备属性

设备的产品模型中定义了物联网平台可向设备下发的属性,应用服务器可调用此接口查询指定设备下属性。

修改设备属性

设备的产品模型中定义了物联网平台可向设备下发的属性,应用服务器可调用此接口向指定设备下属性。平台负责将属性以同步方式发送给设备,并将设备执行属性结果同步返回。

查询设备消息

物联网平台可查询指定设备下的消息,平台为每个设备默认最多保存20条消息,超过20条后, 后续的消息会替换下发最早的消息。

下发设备消息

物联网平台可向设备下发消息,应用服务器可调用此接口向指定设备下发消息,以实现对设备的控制。应用将消息下发给平台后,平台返回应用响应结果,平台再将消息发送给设备。

查询指定消息id的消息

物联网平台可查询指定消息id的消息。

批量MQTT设备同步命令下发

平台支持通过调用创建批量任务接口,对多个MQTT协议设备下发同步命令。本文介绍如何调用创建批量任务下发批量命令。

  1. 应用调用创建批量任务接口,下发请求到物联网平台,下发消息样例如下。
    POST https://{Endpoint}/v5/iot/{project_id}/batchtasks 
    Content-Type: application/json
    X-Auth-Token: ********
    {
      "app_id": "84fb64e43c5f4c6cbec339e52449bcea",
      "task_name": "task123",
      "task_type": "createCommands",
      "targets": [
        "5f2bc9b961e7670469c5ef6d_1997930",
    	"5f2bc9b961e7670469c5ef6d_1997931"
      ],
      "document": {
        "service_id": "water",
        "command_name": "ON_OFF",
        "paras": {
          "value": "ON"
        }
      }
    }
    • app_id:资源空间ID
    • task_name:任务名(自定义)
    • task_type:createCommands
    • targets:设备ID数组
    • document:命令相关参数,参考设备同步命令
  2. 物联网平台向应用返回“201 Created”
  3. 设备订阅下行topic接收命令,并通过上行topic向平台响应命令结果, 参考平台命令下发
  4. 通过调用查询批量任务接口查询批量命令下发任务执行情况。
分享:

    相关文档

    相关产品