设备控制

更新时间:2024-06-28 06:02:20下载pdf

顾名思义,设备控制 是实现物联网设备功能的控制和状态变化的过程。云服务 API 提供了设备下发控制指令、查询设备上报状态的能力,用来感知设备运行状态的变化。

基本概念

属性

属性 是用于描述设备运行时具体信息和状态,在某些场景下也称为 DP(Data Point)。您可以通过 属性 相关接口,查询、修改设备参数状态。

例如,在面向彩灯设备的业务场景中,可以通过修改彩灯的颜色、亮度等属性达到控制彩灯展现效果的目的。

  • 系统流程:

    设备云端开发者应用属性下发流程控制设备1下发属性2下发返回3属性下发指令4下发返回5属性上报流程属性上报消息6云端验证并保存上报属性78属性上报消息9属性查询流程查看设备状态10查询属性11属性状态12设备云端开发者应用查询、修改设备参数状态流程
  • 接口列表:

    服务名称 API 说明
    下发属性 POST: /v2.0/cloud/thing/{device_id}/shadow/properties/issue 立即向设备下发属性设置指令。
    查询属性 GET: /v2.0/cloud/thing/{device_id}/shadow/properties 查询设备最近上报到云端的属性状态。
    修改属性 POST: /v2.0/cloud/thing/{device_id}/shadow/properties 修改设备上报到云端的属性状态。
    属性上报消息 bizCode: devicePropertyMessage 接收设备属性上报的通知消息。

期望属性

设备期望属性 是指对设备进行属性设置时,如果设备不在线,云端可以缓存需要设置的值,待设备上线后再来获取期望属性。

例如,低功耗设备可能周期性的被休眠或唤醒,并非长时间与云端保持连接。如果在休眠状态下,云端直接向设备下发指令,则设备将无法收到。因此,期望属性 提供了一种离线设备下发能力。它能先将设备指令存储在云端,待设备上线后主动从云端拉取存储在云端的指令。

  • 系统流程如下:

    设备云端开发者应用期望属性下发流程控制设备1设置期望属性2存储期望属性3设置成功4设备拉取指令流程唤醒设备5连接云端6设备端查询期望属性7返回属性下发指令8执行指令9查询下发状态流程查看下发状态10云端查询期望属性11期望属性状态12设备云端开发者应用期望属性设置流程
  • 接口列表如下:

    服务名称 API 说明
    设置期望属性 POST: /v2.0/cloud/thing/{device_id}/shadow/properties/desired 将属性下发指令暂存在云端,当设备唤醒时下发给设备。
    查询期望属性 GET: /v2.0/cloud/thing/{device_id}/shadow/properties/desired 查询暂存在云端的属性下发指令。

物模型

物模型 是涂鸦针对物理实体设备在云端建立的数据模型,主要用于描述产品的功能。物模型通过定义一款产品设备所应具备的功能属性、动作功能、事件来表示一个物理实体设备在云端的数据展现。

  • 通过 物模型 相关接口,您可以查询设备的功能定义元数据。
  • 物模型提供功能参数的详细定义,您可以利用这些信息完成面板动态渲染、数据分析等功能开发。

例如,一个彩灯包含颜色、亮度、开关三个属性。而颜色具有红、黄、蓝三种可选值,开关具有开和关两种可选值。通过以下物模型案例,您可以清楚地了解物模型的数据结构。

{
    "modelId":"000000er..",
    "name":"彩灯",
    "services":[
        {
            "code":"",
            "properties":[
                  {
                    "abilityId": 1,
                    "code":"switch",
                    "name":"开关",
                    "accessMode":"rw",
                    "typeSpec":{
                        "type":"bool"
                    }
                },
                {
                    "abilityId": 2,
                    "code":"color",
                    "name":"颜色",
                    "accessMode":"rw",
                    "typeSpec":{
                        "type":"enum",
                        "range":["red", "yellow", "blue"]
                    }
                }
            ]
        }
    ]
}

涂鸦提供的接口列表如下:

服务名称 API 说明
查询物模型 GET: /v2.0/cloud/thing/{device_id}/model 查询设备物模型定义。

相关能力

针对设备控制的需求,除了本文提到的接口之外,涂鸦还提供了另一套基于涂鸦标准指令集的设备控制方案,主要面向有需要针对多个厂商生产的同品类设备的控制场景。更多详情,请参考 设备控制(标准指令集)