Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
云服务 API 参考（归档）
search
根据文档目录筛选
arrDownIoT Core服务
arrDown行业通用 API
arrDown全屋智能 API
arrDown垂直品类硬件 API
arrDown智能门锁开放能力
arrDown万能红外开放能力
arrDown实时音视频
arrDown视频云存储
arrDown短语音合成服务
arrDown物联网卡
arrDown智能发卡器开放能力
arrDown网关开放能力
arrDown扫地机器人开放能力
arrDown行业三方设备能力
arrDown公区通用能力
行业三方设备通用能力说明
arrDown公区设备信息
arrDown公区设备指令
arrDown公区设备权限
arrDown公区设备功能点
arrDown门禁开放能力
arrDown梯控开放能力
arrDown车行开放能力
arrDown摄像头开放能力
arrDown消防开放能力
arrDown周界开放能力
arrDown智能断路器开放能力
arrDown智能水表开放能力
arrDown室内外融合定位器开放能力
arrDown通用基础 API
arrDown行业服务 API
云服务 API 参考（归档）垂直品类硬件 API行业三方设备能力公区通用能力行业三方设备通用能力说明

行业三方设备通用能力说明

更新时间：2023-06-15 05:22:16

本文介绍行业三方设备通用能力的使用说明。

网络拓扑

行业三方设备通用能力说明

  1. 设备通过直连或边缘网关的方式，和 涂鸦 IoT 开发平台 进行交互。
  2. 开发者云通过 HTTPS 方式，调用涂鸦提供的 API 接口。更多信息，请参考 API 接入指南。
  3. 涂鸦通过 Pulsar 主动推送各种事件数据给开发者云。更多信息，请参考 Pulsar 接入指南。
  4. 各自品类设备接入流程，详见品类接入说明文档。例如，门禁，车行 和 梯控。

名词解释

名词 说明
行业三方设备 包括但不限于门禁、摄像头、梯控、车行、消防、周界、楼控、水表、断路器等。
指令下发 开发者调用涂鸦开放的 API 接口，下发指令给设备。
设备消息事件 设备端触发事件后，设备上报至涂鸦 IoT 开发平台。涂鸦 IoT 开发平台通过 Pulsar 消息通知开发者。
ISV 独立软件开发商，即接入涂鸦 IoT 开发平台的开发商。
devId 等同 deviceId，涂鸦设备 ID。
productKey 等同 productId，涂鸦设备产品 ID。
productType 涂鸦设备品类 Code。
sn 号 设备指令全局唯一标志，设备指令上下文会话唯一标志。

API 说明

行业三方设备信息

API 名称 接口地址
获取设备详情 GET:/v1.0/expand/devices/{device_id}
获取设备列表 GET:/v1.0/expand/devices

行业三方设备指令

可通过此接口主动查询下发给设备的指令结果，也可通过设备 指令执行结果事件，获取指令执行结果。

API 名称 接口地址
指令记录查询 GET:/v1.0/expand/cmds/{sn}

行业三方设备权限

此接口均为⾮必选，如设备具备可视对讲能⼒，则需对接创建涂鸦⽤户、新增⽤户权限和删除⽤户权限这三个接⼝。例如，⻔禁设备具备可视对讲能⼒，开发者需创建涂鸦⽤户，获取到涂鸦⽤户 ID，然后授权涂鸦⽤户 ID 给对应的⻔禁设备，才能使⽤云可视对讲能⼒。

API 名称 接口地址
创建涂鸦用户 POST: /v1.0/apps/{schema}/user
新增用户设备权限 POST:/v1.0/expand/spaces/{device_id}/persons/{person_id}
删除用户的设备权限 DELETE:/v1.0/expand/spaces/{device_id}/persons/{person_id}

行业三方设备功能点

不同厂商和品类的设备⽀持的功能点存在差异，可以通过下列接⼝查询设备⽀持的功能点。

API 名称 接口地址
获取设备功能点 GET:/v1.0/expand/devices/{device_id}/functions
获取设备功能池 GET:/v1.0/expand/devices/{device_id}/function-pool
修改设备功能点 PUT:/v1.0/expand/devices/{device_id}/functions

行业三方设备事件格式

设备配网事件

功能描述

创建涂鸦开发者账号后，涂鸦施⼯⼈员去现场进⾏设备配⽹。配⽹结果将通过消息的⽅式通知开发者。如果设备信息发⽣变动，也将通过此事件通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 Code，bindUser。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
ts Long 时间 13 位时间戳。 是
uuid String 设备激活 UUID。 是
bizData Object 业务数据。 是

bizData 参数说明

参数名 类型 说明 必填
devId String 涂鸦设备 ID。 是
uid String 开发者 ID。 是
parentDevId String 设备网关 ID。 是
ownerId String 家庭组 ID。 是
uuid String 设备激活 UUID。 是
deviceName String 设备名称。 是
productType String 设备品类 Code。 是
cid String 设备 CID。 是
projectId String 设备所属项目 ID。 是

数据示例

{
    "bizCode": "bindUser",
    "bizData": {
        "devId": "6c0f9f75942945886b****",
        "uid": "bay1617693984346****",
        "parentDevId": "6c8508b09c431549fa****",
        "ownerId": "3406****",
        "uuid": "45106581bdee****",
        "deviceName": "涂鸦行业三方设备",
        "productType": "wf_znmj",
        "cid": "abc123****",
        "projectId": "abc123****"
    },
    "devId": "6c0f9f75942945886b****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637292810795,
    "uuid": "45106581bdee****"
}

指令执行结果事件

功能描述

下发指令的执行结果，通过消息的方式通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 Code，cmdIssueResult。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
ts Long 时间 13 位时间戳。 是
bizData Object 业务数据。 是

bizData 参数说明

参数名 类型 说明 必填
sn String 指令记录 ID。 是
processStatus Integer 指令执行状态。
1：指令发送中。
2：指令已发送。
3：指令执行成功。
4：指令执行失败。		 是
message String 指令执行描述，如果指令执行失败，则返回失败原因。 否
happenTime Long 指令执行时间，13 位时间戳。 是
dataFlag Integer 1：标志同步数据指令。
2：标志控制类指令。		 否
bizId String 业务 ID。 否
cmdBizType String 指令业务类型。 否
data String 业务处理返回数据。 否

数据示例

{
    "bizCode": "cmdIssueResult",
    "bizData": {
        "processStatus": 3,
        "data": "{}",
        "dataFlag": 2,
        "sn": 146153748529231****,
        "message": "success",
        "deviceId": "6ce23ee0de009667c0****",
        "happenTime": 1637292665335
    },
    "devId": "6ce23ee0de009667c0****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637292665405
}

设备上线事件

功能描述

设备发生上线事件，通过消息的方式通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 Code，取值为 online。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
ts Long 时间 13 位时间戳。 是
uuid String 设备 UUID。 是
bizData Object 业务数据。 是

bizData 参数说明

参数名 类型 说明 必填
uid String 用户 ID。 是
time Long 上线时间 13 位时间戳。 是

数据示例

{
    "bizCode": "online",
    "bizData": {
        "uid": "bay161769398434****",
        "time": 1637216002196
    },
    "devId": "6c0b7b2ac7b6c1eb5e****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637216002224,
    "uuid": "4991ffc40430****"
}

设备离线事件

功能描述

设备发生离线事件，通过消息的方式通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 Code，取值为 offline。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
ts Long 时间 13 位时间戳。 是
uuid String 设备 UUID。 是
bizData Object 业务数据。 是

bizData 参数说明

参数名 类型 说明 必填
uid String 用户 ID。 是
time Long 离线时间 13 位时间戳。 是

数据示例

{
    "bizCode": "offline",
    "bizData": {
        "uid": "bay1617693984346****",
        "time": 1637215931403
    },
    "devId": "6ce23ee0de009667c0****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637215931555,
    "uuid": "a3c7ecc1ada4****"
}

设备解绑事件上报

功能描述

设备解绑后，发送解绑事件通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 Code，取值为 delete。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
ts Long 时间，13 位时间戳。 是
uuid String 设备 UUID。 是
bizData Object 业务数据。 是

bizData 参数说明

参数名 类型 说明 必填
devId String 设备 ID。 是
uid String 用户 ID。 是
ownerId String 家庭组 ID。 是

数据示例

{
    "bizCode": "delete",
    "bizData": {
        "devId": "6c0f9f75942945886b****",
        "uid": "bay1617693984346****",
        "ownerId": "3406****"
    },
    "devId": "6c0f9f75942945886b****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637303082416,
    "uuid": "45106581bdee****"
}

设备消息事件上报

功能描述

设备事件上报并通知开发者。对于不同品类设备，具体事件消息参考各品类的接入说明文档。

参数说明

参数名 类型 说明 必填
dataId String 数据唯一标志。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
status List 设备消息对象。 是

status 参数说明

参数名 类型 说明 必填
code String 设备事件 Code。 是
t Long 时间戳。 是
value String 事件内容。 是

数据示例

{
  "dataId": "AAXRV4BrtW9BRB9A2JYW****",
  "devId": "6cac703763f7653deb8****",
  "productKey": "iyktmr3hd2qp****",
  "status": [
    {
      "126": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}",
      "code": "event_pass",
      "t": 1637548630455,
      "value": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}"
    }
  ]
}

行业三方设备事件格式（1.0 版本）

设备事件消息兼容 1.0 版本格式。如需开通 1.0 版本格式，请联系涂鸦工作人员。更多信息，请参考 Pulsar 接入参考。

1.0 版本接入流程说明

接收消息代码示例

String url = "";
String accessId = "";
String accessKey = "";
MqConsumer mqConsumer = MqConsumer.build()
    .serviceUrl(url)
    .accessId(accessId)
    .accessKey(accessKey)
    .maxRedeliverCount(3)
    .messageListener(new MqConsumer.IMessageListener() {
     @Override
     public void onMessageArrived(Message message) throws Exception {
        String content = new String(message.getData());
     }
    });
mqConsumer.start();

content 即为 Pulsar 客户端接收到的消息内容。

content 参数说明

参数名 类型 说明 必填
encryptPayload String 已加密的数据内容。 是
encryptType String 数据加密类型，默认 aes_ecb。 是
sign String 签名。 是
t Long 13 位时间戳。 是
v Long 数据版本号，默认 1.0。 是

content 数据示例

{
  "encryptPayload": "Cl6rUppuwmjUJZRZNdwJdfs2NpGyqYSyVlXjgdiLLbeb6/UvWSZa972jFl+6q3Q8QyNZnOluC9VQeUh7BosdD7p/NcJYLYDknFPqpTD1R7sIg0HZgag3W+YCQtL8b+SKE5UwDEWg0toy1mCmTg5qyrYad+uGWLY98yrT9et/ePj/7FP9g9zGOHAmnytrcCS7a/4j5bARkROHiDzYnQt1lA==",
  "encryptType": "aes_ecb",
  "sign": "3f2b0dbe19119806f8f7f884653dca5d",
  "t": 1611221228800,
  "v": "1.0"
}

解密后数据示例

数据的签名校验及解密流程，请参考 数据签名。

对 encryptPayload 解密后的结果示例：

{
  "data": "{\"deviceId\":\"6c280fdff93c18e45ben6i\",\"status\":1,\"happenTime\":1611221228433}",
  "bizCode": "edge_device",
  "eventType": "dev_online_status"
}

1.0 版本消息均只定义了 encryptPayload 解密后的数据格式。

设备配网事件

功能描述

创建涂鸦开发者账号后，涂鸦施⼯⼈员会去现场进⾏设备配⽹。设备的配⽹结果，通过消息的⽅式通知开发者。如果设备信息发生变动，也会通过此事件通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认 edge_device。 是
eventType String 事件类型，默认 activate_device。 是
deviceId String 涂鸦设备 ID。 是
cid String 设备硬件唯⼀ ID，例如设备的 SN 号、MAC 地址 、IMEI 号等。 是
gatewayId Integer 涂鸦设备网关 ID。 否
projectId String 项目 ID，设备配网时由开发者自定义。 是
uid String 开发者 ID。 是
deviceName String 设备名称。 是
deviceIp Long 设备 IP 地址。 是
macAddress String 设备 MAC 地址。 否
supplierCode String 供应商 code。 是
productType String 产品品类。 是
productId String 产品 ID。 是
installLocation String 安装地址。 否
extendData String 扩展数据，json 格式。 否
activeStatus Integer 设备激活状态。0 代表未激活，1 代表已激活。 是
onlineStatus Integer 设备在线状态。0 代表离线，1 代表在线。 是
createTime Long 设备创建时间。 是

数据示例

{
  "bizCode": "edge_device",
  "eventType": "activate_device",
  "data": "{\"cid\": \"120759236001223****\",\"deviceId\":
  \"002dj00118fe34d9****\",\"deviceName\": \"⼩区东⼊⼝⻔禁\",\"deviceIp\":
  \"192.168.16.111\",\"macAddress\": \"00-55-52-24-01-65\",\"productType\":
  \"wf_znmj\",\"productId\": \"0vbrvxonnjsxi****\",\"supplierCode\":
  \"tuya\",\"installLocation\": \"⼩区东⼊⼝\",\"extendData\":
  \"\",\"activeStatus\": 1,\"onlineStatus\": 1,\"createTime\": 1591693362843}"
}

指令执行结果事件

功能描述

下发指令的执行结果，通过消息的方式通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认 edge_device。 是
eventType String 事件类型，默认 cmd_issue_result。 是
deviceId String 涂鸦设备 ID。 是
sn String 指令记录 ID。 是
processStatus Integer 指令执行状态。
1：指令发送中。
2：指令已发送。
3：指令执行成功。
4：指令执行失败。
5：指令状态未知。		 是
message String 指令执行描述。如果指令执行失败，则返回失败原因。 否
happenTime Long 指令执行时间，13 位时间戳。 是

数据示例

{
  "bizCode": "edge_device",
  "eventType": "cmd_issue_result",
  "data": "{\"sn\": \"1212581947449081856\",\"deviceId\": \"002dj00118fe34d9**** \",\"processStatus\":2,\"message\":\"指令已发送\",\"happenTime\":1591693362843}"
}

设备上线/离线事件

功能描述

设备发生上线或离线事件，通过消息的方式通知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认 edge_device。 是
eventType String 事件类型，默认 dev_online_status。 是
deviceId String 涂鸦设备 ID。 是
status Integer 设备状态。0 代表离线，1 代表在线。 是
happenTime Long 设备上线或离线时间，13 位时间戳。 是

数据示例

{
  "bizCode": "edge_device",
  "eventType": "dev_online_status",
  "data": "{\"deviceId\": \"002dj00118fe34d9****\",\"status\": 1,\"happenTime\": 1591693362843}"
}

设备解绑事件上报

功能描述
​
设备解绑后发送解绑事件告知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认 edge_device。 是
eventType String 事件类型，默认 edge_report_data。 是
mode String 事件模式，设备解绑：device-unbind。 是
deviceId String 涂鸦设备 ID。 是

数据示例

{
  "data": "{\"mode\":\"device-unbind\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\"}",
  "bizCode": "edge_device",
  "eventType": "edge_report_data"
}

网关解绑事件上报

功能描述

​网关解绑后，发送解绑事件告知开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认 edge_device。 是
eventType String 事件类型，默认 edge_report_data。 是
mode String 事件模式，网关解绑：gateway-unbind。 是
deviceId String 涂鸦设备 ID。 是

数据示例

{
  "data": "{\"mode\":\"gateway-unbind\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\"}",
  "bizCode": "edge_device",
  "eventType": "edge_report_data"
}
上一篇公区通用能力
下一篇公区设备信息
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English