北向设备能力调用最佳实践

更新时间：2023-07-06 06:05:04下载pdf

本文介绍如何调用设备北向能力控制设备。

您现在正在阅览的，是一篇不完全公开的文档，这表示该文档内容的适用性有一定的限制，文档或目录所描述的内容适用于旧版本 SDK、API、工具、平台等。
如果您需要更准确的技术文档，请访问涂鸦 IoT 开发平台，然后自行搜索。

概述

设备北向对外暴露的接口，统一称为设备能力（Device Capabilities）。应用开发者可基于能力，与设备实现信息交互，包含设备控制和设备消息监听。

根据不同来源，能力分为以下两类：

能力类型	来源	定义
标准能力 Standard Capabilities	涂鸦官方定义	标准能力是指经过涂鸦标准化映射包装，可实现跨产品、品类进行统一控制的能力。比如，开关可以作为一个标准能力，所有带有开关这个能力的设备都能使用同一套参数进行统一控制，客户无需考虑各个产品之间的硬件差异。
原始能力 Original Capabilities	设备底层定义	设备模型上未经转换的硬件产品定义，比如：彩灯 `R` 的值（DP 或属性）、摄像机初始化（动作）和设备掉电告警（事件）。注意：通过原始能力控制设备，您需要先了解硬件产品模型定义（如：DP 模型或物模型），才能正确下发设备指令或进行消息解析。

操作流程

步骤 1. 创建云项目

云项目创建的详细流程，请参考项目管理。

如果您已有云项目，可跳过此步骤。

进入涂鸦 IoT 开发平台云开发，点击创建云项目。
填写项目基础信息。
选择基础云服务，开通并授权。
快速创建资产和用户。

步骤 2. 添加设备

项目添加设备。根据你的设备类型，将设备关联到项目下。具体详情，可参考关联设备。
TuyaLink 设备绑定。针对带有 Bind Code 的 TuyaLink 设备，您可以在云开发直接绑定到资产下。具体绑定的方法如下：

（1）单击一个云项目进入详情页，选择资产 > 资产下设备 > 添加设备 > 其他。

（2）输入设备 Bind Code，点击绑定设备，即可快速将此设备绑定到资产下。

步骤 3. 开通设备能力云服务

订阅

目前，此服务还没有对外公开。如需订阅，可访问设备北向能力。
授权

单击一个云项目进入详情页，选择 服务 API > 新增 API 授权。找到设备北向能力这个云服务，授权给项目。

步骤 4. 使用 API 调试设备

打开 API Explorer。单击设备北向能力操作栏里的去调试，可以打开 API Explorer，开始 API 调试。
查询设备拥有的能力。

tags 可选 standard（标准能力）和 original（原始能力）。具体详情，可参考查询设备能力列表。

设备能力列表解析。

/v1.0/iot-03/devices/{device_id}/capabilities-definition
{
"result": {
    "capabilities": [
    {
        "capability_code": "switch_led",
        "methods": [
        "get",
        "post",
        "event"
        ],
        "name": "灯开关",
        "request": {
        "description": "",
        "name": "开关",
        "type": "boolean"
        },
        "response": {
        "description": "",
        "name": "开关",
        "type": "boolean"
        },
        "tags": [
        "standard"
        ]
    },
    {
        "capability_code": "bright_value",
        "methods": [
        "get",
        "post",
        "event"
        ],
        "name": "亮度值",
        "request": {
        "description": "",
        "max": 1000,
        "min": 10,
        "name": "亮度值",
        "scale": 0,
        "step": 1,
        "type": "integer"
        },
        "response": {
        "description": "",
        "max": 1000,
        "min": 10,
        "name": "亮度值",
        "scale": 0,
        "step": 1,
        "type": "integer"
        },
        "tags": [
        "standard"
        ]
    },
    ],
    "device_id": "vdevo159661074251043"
},
"success": true,
"t": 1644561248369
}

通过分析返回的设备列表定义，提取以下几个重要的字段：

capability_code：能力代码，在访问能力时将要用到。如上例中的 switch_led。
methods：访问能力的方式。
- get：可使用 GET 方法调用 API。
- post：可使用 POST 方法调用 API。
- event：可使用 Pulsar 消息订阅的方式访问。
request：访问能力时需要输入的参数解释。如上例中，switch_led 的入参要求是 Boolean类型，则访问能力时你应该填写 true 或 false。
response：访问能力的返回结果解释。

执行设备指定能力。

通过对能力列表的分析，我们得知此设备有一个 capability_code 为 switch_led 的能力，能力请求参数为 Boolean 类型。

于是，我们可以在 API Explorer 中填入对应的参数，即可执行此能力。
查询设备指定能力.

与执行设备能力类似，只是将访问方法由 POST 变为 GET。

步骤 5. Pulsar 设备消息订阅

关于消息订阅接入流程，可参考快速入门。

开启消息订阅。

选择 云开发 > 消息订阅。选择一个云项目，开启消息订阅。
设备消息监听。

具体详情，可参考基于 Pulsar 获取消息推送。