Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
涂鸦开发者平台
search
根据文档目录筛选
涂鸦开发者平台智慧行业行业设备接入智慧消防设备接入

智慧消防设备接入

更新时间：2023-02-27 03:13:50下载pdf

本文介绍了涂鸦智慧行业智慧消防设备接入协议和具体方案，帮助智慧消防品牌方快速接⼊涂鸦 IoT 开发平台。

方案架构

  • 方案网络拓扑如下图所示：

    智慧消防设备接入

  • 方案指令流程如下图所示：

    智慧消防设备接入

准备工作

请确保您已经 注册涂鸦开发者账号。

云开发项目

云开发项目是 IoT 平台资源（设备、API 权限、数据资产等）的集合，不同云开发项目之间的资源相互隔离。本小节简略地介绍了云开发项目，详细的项目创建和管理步骤，请参考 管理项目。

创建云项目是为了获取 AccessId（client_id）和授权密钥 AccessKey（secret），设备控制依赖于 Access ID、AccessKey，调用涂鸦 OpenAPI 及订阅设备事件需要使用，请妥善保管。

  1. 进入 云开发项目列表。

    智慧消防设备接入

  2. 点击进入您创建的项目，获取项目密钥 Access ID 和 Access Secret。

    智慧消防设备接入

  3. 关联设备。

    智慧消防设备接入

创建产品

您创建的产品拥有全局唯一的标识符 PID （Product ID）。产品包含了实际场景中部署的智能设备的所有属性数据，包括产品开发中最核心最基础的功能属性。

本步骤主要完成产品功能定义，并获取 PID。详细步骤，请参考 创建产品。

创建具体的品类接入时由涂鸦指定，可询问您的涂鸦客户经理。

消息监听

涂鸦 IoT 平台使用消息机制，实现通知第三方平台查询指定条件项目列表。因此，您需要在第三方平台先订阅涂鸦消息，具体可参考 消息队列。

Java SDK

点击前往 涂鸦 Java SDK GitHub 仓库，获取 Token 和通用的调用接口。您只需更改 URL 和参数即可。

接口规范

环境说明

  • 中国区：https://openapi.tuyacn.com
  • 美洲区：https://openapi.tuyaus.com
  • 欧洲区：https://openapi.tuyaeu.com

请根据自身所在区域调用相应接口。

请求方式

支持的请求方式如下：

  • GET
  • PUT
  • POST
  • DELETE

需要注意的是，当请求方式为 POST 时，Content-Type 需使用 application/json。

请求头设置

任意接口都需要在 header 中，加入如下参数：

参数名 类型 参数位置 说明 必填
client_id String header client_id 是
lang String header 语言，默认为 en 否
sign String header 采用指定签名算法计算出的签名，涉及 Token 相关接口和业务相关接口 是
sign_method String header 签名的摘要算法，HMAC-SHA256 是
t Long header 13 位标准时间戳 是

签名方式

涂鸦根据不同应用场景，当前提供两套签名算法：

  • Token 相关接口（v1.0/token&v1.0/token/{refresh_token}）：

    sign = HMAC-SHA256(client_id + t, secret).toUpperCase()

  • 非 Token 相关的业务接口：

    sign = HMAC-SHA256(client_id + access_token + t, secret).toUpperCase()
    • client_id 为上文中 Access ID。
    • secret 为上文中的 Access Secret
    • access_token 请参考下文 授权接口 章节。

返回结果

  • 业务正常返回：

    {
	"success": true,
	"result": {
		//object
	}
}

  • 业务错误返回：

    {
	"success": false,
	"code": 1010,
	"msg": "token 非法"
}

全局错误码

Code Msg
500 系统异常
1000 数据不存在
1001 非法的 secret
1002 access_token 不能为空
1003 非法的 grant_type
1004 非法签名
1005 非法的 client_id
1010 Token 失效
1011 Token 非法
1012 非法的 status 状态
1013 非法请求时间
1100 入参为空
1101 参数取值范围非法
1102 参数为 null

功能列表

设备功能 说明
请求授权 获取涂鸦的授权，和涂鸦进行交互
三方设备绑定 三方设备通过绑定接口注册成为涂鸦的设备，从而可以在涂鸦控制此设备，及查看设备状态和其它相关信息
三方设备解绑 三方设备从涂鸦删除
三方设备更新 更新云端的三方设备信息
三方设备上线 发送三方设备上线消息给涂鸦
三方设备下线 发送三方设备下线消息给涂鸦
三方设备报警 发送三方设备报警消息给涂鸦

授权接口

获取令牌

调用设备对接接口前，需先获取 access_token，然后使用 acess_token 访问业务接口。调用方根据提供的 client_id 和 secret 签名，调用 /v1.0/token 接口到服务端换取 access_token。调用业务接口时，sign 的计算请参考 业务接口调用签名算法。

  • sign 签名计算方法

    获取 Token 的签名生成规则如下：

    sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()

    对于一个请求 URL，获取到的 Token 有效期是 5 分钟。Token 管理的更多详情，请参考 签名机制。

  • 接口地址

    GET /v1.0/token

  • header 参数

    参数名 类型 参数类型 说明 必填
    client_id String header client_id 是
    sign String header 通过 上文签名算法 计算出的签名 是
    nonce String header API 调用者生成的 UUID，结合时间戳防重复 否
    stringToSign String header 签名字符串 是
    sign_method String header 签名类型，默认为 HMAC-SHA256 是
    t Long header 13 位标准时间戳 是

  • 请求参数

    参数名 类型 参数类型 说明 必填
    grant_type Integer URL 授权类型
    • 1：简易模式
    • 2：授权码模式
    		是

  • stringToSign 签名字符串

    String stringToSign=
HTTPMethod + "\n" +
Content-SHA256 + "\n" +
Headers + "\n" +
Url

  • 请求示例

    GET /v1.0/token?grant_type=1

  • Java SDK 示例

    TuyaClient tuyaClient = new TuyaClient(accessId, accessKey, RegionEnum.CN);
String url = ServerEnum.CN_ONLINE.getUrl() + "/v1.0/token";
HashMap<String, String> hashMap = new HashMap<String, String>();
hashMap.put("grant_type", "1");
tuyaClient.commonHttpRequest(url, HttpMethod.GET, hashMap, null);

  • 返回信息

    参数名 类型 说明
    code Integer 响应码，更多详情请参考 错误码 章节
    success Boolean 是否成功
    • true：成功
    • false：失败
    msg String 请求失败的信息，成功为空
    result Object 用户设备信息

  • result 说明

    参数名 类型 说明
    access_token String 访问令牌
    expire_time Integer 过期时间，单位为秒
    refresh_token String 用以刷新 access_token

  • 返回示例

    • 业务正确返回：

      {
"success": true,
"t": 1575699977724,
"result": {
	"uid": "ay1573712013719u5***",
	"access_token": "6a5629b9285703a1f05f667757dd6***",
	"expire_time": 7200,
	"refresh_token": "adbc6363ef181dcc244769e4237d9***"
}
}

    • 业务错误返回：

      {
	"success": false,
	"code": 100323,
	"msg": "token 非法"
}

刷新令牌

access_token 有效期是 2 小时，过期后需调用 Token 刷新接口获取新的 access_token，并使用新的 access_token 访问业务接口。

  • sign 签名计算方法

    获取 Token 的签名生成规则如下：

    sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()

    对于一个请求 URL，获取到的 Token 有效期是 5 分钟。Token 管理的更多详情，请参考 签名机制。

  • stringToSign 签名字符串

    String stringToSign=
HTTPMethod + "\n" +
Content-SHA256 + "\n" +
Headers + "\n" +
Url

  • 接口地址

    GET /v1.0/token/{refresh_token}

  • header 参数

    参数名 类型 参数类型 说明 必填
    client_id String header client_id 是
    sign String header 通过 上文签名算法 计算出的签名 是
    nonce String header API 调用者生成的 UUID，结合时间戳防重复 否
    stringToSign String header 签名字符串 是
    sign_method String header 签名类型，默认为 HMAC-SHA256 是
    t Long header 13 位标准时间戳 是

  • 请求参数

    参数名 类型 参数类型 说明 必填
    refresh_token String URI /v1.0/token 的返回信息 是

  • 请求示例

    GET /v1.0/token/35e0dd4b0f9dfb87c320414a4c190***

  • Java SDK 示例

    String url = ServerEnum.CN_ONLINE.getUrl() + "/v1.0/token/"+ token;
TuyaClient tuyaClient = new TuyaClient(accessId, accessKey, RegionEnum.CN);
tuyaClient.commonHttpRequest(url, HttpMethod.GET, null, null);

  • 返回信息

    参数名 类型 说明
    code Integer 响应码，更多详情请参考 错误码 章节
    success Boolean 是否成功
    • true：成功
    • false：失败
    msg String 请求失败的信息，成功为空
    result Object 用户设备信息

  • result 说明

    参数名 类型 说明
    access_token String 访问令牌
    expire_time Integer 过期时间，单位为秒
    refresh_token String 用以刷新 access_token

  • 返回示例

    {
"success": true,
"t": 1575701937231,
"result": {
	"uid": "ay1573712013719u5***",
	"access_token": "4bbdc25b6f360b8e31125ed1e3653***",
	"expire_time": 7200,
	"refresh_token": "c81225be7122aef134094061e03c5***"
}
}

设备接入

三方设备绑定

设备在第三方云配网成功后，调用此接口向涂鸦注册设备信息。

  • 产品信息录入：调用此接口前，请确保该设备的产品信息已在涂鸦 IoT 开发平台完成录入，并且已经生成 PID（产品 ID）。详情请参考 创建产品。
  • 自动创建涂鸦用户 ID：注册设备时，需指定在涂鸦的用户名。涂鸦将自动创建三方用户对应的涂鸦用户 ID，并将设备绑定到对应的涂鸦用户 ID 下。
  • 绑定设备：当设备在第三方云配网成功后，第三方云调用此接口向涂鸦注册设备信息。该接口负责直连三方云的设备及网关设备的注册。

绑定成功后，在涂鸦体系的 App 可以控制此设备，及查看设备状态等相关信息。

接口地址

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/bind

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 三方设备唯一 ID。建议采用设备端可读取的唯一标识作为 3rd_cloud_device_id，例如设备的 SN 号、Mac 地址、IMEI 号等。 是
tuya_product_id String BODY 涂鸦的产品 ID。 是
app_schema String BODY 涂鸦应用标识 否
tuya_username String BODY 涂鸦的用户名。用来对应第三方用户唯一标识。 否
properties Object BODY 涂鸦设备属性 否
ext_properties List BODY 拓展信息，依照具体业务方而定 是

  • properties 属性：

    参数名 类型 参数类型 说明 必填
    name String BODY 设备名称 否
    lon Double BODY 经度 否
    lat Double BODY 纬度 否
    ip String BODY IP 否

  • ext_properties 参数：

    参数名 类型 参数类型 说明 必填
    code String BODY 标识符 是
    value String BODY 数值 是

    ext_properties 字段如下：

    [{"code":"cid","value":"123123***"},
{"code":"vendorCode","value":"nite"},
{"code":"deviceIp","value": "192.168.*.*"},
{"code":"macAddress","value": "mac 地址"},
{"code":"commType","value":"HTTP"},
{"code":"lat","value": "30.20***"},
{"code":"lon","value": "120.21***"},
{"code":"installLocation","value":"安装位置"},
{"code":"outProjectId","value":"三方设备所在的小区 ID"},
{"code":"deviceDesc","value":"设备描述"},
{"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\"}"},
{"code":"deviceName","value":"三方的设备名称"},
{"code":"isGateway","value":true}
]

三方厂商的设备名称需要放在 ext 字段里，对应的 key 为deviceName，并非请求参数里的 name 字段。 纬度的 key 为 lat，经度的 key 为 lon。

  • app_schema：表示渠道标识符。获取方法请参考 创建云应用 章节。

  • tuya_username：字段传厂商 code。

  • tuya_product_id：表示设备在涂鸦的 PID。获取方法参考 创建云产品 章节。

  • isGateway：表示是否为网关设备，默认传 false。如果是用传装置绑定，该值传 true，此时，extendData 字段需要传入 {\"userTransUnitNum\":\"000.000.000.000.000.155\"}, ,userTransUnitNum 表示用传装置的编号。

    如果设备是用传装置，3rd_cloud_device_id 字段生成规则为 厂商 code_用传装置编号，并使用 md5 转换。

字段说明如下：

ext_properties 的 code 描述 是否必填
cid 三方设备 ID，同 3rd_cloud_device_id。建议采用设备端可读取的唯一标识作为 cid，例如设备的 SN 号、Mac 地址、IMEI 号等。 是
vendorCode 三方供应商的英文拼写 code 是
outProjectId 三方设备所在的小区 ID 是
deviceIp 设备 IP，例如 192.168.1.1 否
macAddress 设备 Mac 地址 否
commType 通信类型，例如 HTTP、MQTT、485 电信号等 否
lat 纬度 是
lon 经度 是
installLocation 安装位置，该字段需要有可读性 是
deviceName 三方设备名称，该字段需要有可读性 是
deviceDesc 设备描述，例如 无线压力变送器，该字段需要有可读性 是
extendData JSON 字符串等设备扩展信息 否
isGateway 是否是用传装置，布尔值。如果是用传装置，传 true，否则可以不传。 否

请求示例

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/bind
{
    "app_schema":"tencentiot",
    "tuya_username": "0123456***",
    "tuya_product_id": "nr1k9ptidpov***",
    "ext_properties":[{"code":"deviceName","value":"具体设备名称"},{"code":"installLocation","value":"杭州市西湖区蒋墩路华策***"}]

}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

result 说明

参数名 类型 说明
tuya_device_id String 涂鸦设备 ID
tuya_user_id String 涂鸦用户 ID

请求示例

{
    "success": true,
    "t": 1561456817168,
    "result": {
      "tuya_device_id":"",
      "tuya_user_id":""
    }
}

三方设备批量绑定

设备在第三方云配网成功后，调用此接口向涂鸦批量注册设备信息。

  • 产品信息录入：调用此接口前，请确保该设备的产品信息已在涂鸦 IoT 开发平台完成录入，并且已经生成 PID（产品 ID）。详情请参考 创建产品。
  • 自动创建涂鸦用户 ID：注册设备时，需指定在涂鸦的用户名。涂鸦将自动创建三方用户对应的涂鸦用户 ID，并将设备绑定到对应的涂鸦用户 ID 下。
  • 绑定设备：当设备在第三方云配网成功后，第三方云调用此接口向涂鸦批量注册设备信息。该接口负责直连三方云的设备及网关设备的批量注册。

绑定成功后，在涂鸦体系的 App 可以控制此设备，及查看设备状态等相关信息

接口地址

POST /v1.0/3rdcloud/devices/actions/bind

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
tuya_product_id String BODY 涂鸦的产品 ID。 是
app_schema String BODY 涂鸦应用标识 否
tuya_username String BODY 涂鸦的用户名。用来对应第三方用户唯一标识。 否
devices List BODY 涂鸦设备属性，单次调用设备数量上限为 20。 是

  • devices 属性：

    参数名 类型 说明 必填
    id String 三方设备唯一 ID，建议采用设备端可读取的唯一标识作为 CID，例如设备的 SN 号、MAC 地址、IMEI 号等 是
    lon String 设备位置经度 否
    lat String 设备位置纬度 否
    name String 设备名称 否
    ip String 设备 IP 否
    ext String 设备扩展信息，详见下表 是

  • ext 属性：

    参数名 类型 参数类型 说明 必填
    code String BODY 标识符 是
    value String BODY 数值 是

    ext_properties 字段如下：

    [{"code":"cid","value":"123123***"},
{"code":"vendorCode","value":"nite"},
{"code":"deviceIp","value": "192.168.1.*"},
{"code":"macAddress","value": "mac 地址"},
{"code":"commType","value":"HTTP"},
{"code":"lat","value": "30.2***"},
{"code":"lon","value": "120.21***"},
{"code":"installLocation","value":"安装位置"},
{"code":"outProjectId","value":"三方设备所在的小区 ID"},
{"code":"deviceDesc","value":"设备描述"},
{"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\"}"},
{"code":"deviceName","value":"三方的设备名称"},
{"code":"isGateway","value":true}
]

三方厂商的设备名称需要放在 ext 字段里，对应的 key 为deviceName，并非请求参数里的 name 字段。 纬度的 key 为 lat，经度的 key 为 lon。

  • app_schema：表示渠道标识符。获取方法请参考 创建云应用 章节。

  • tuya_username：字段传厂商 code。请与您的涂鸦客户经理确认该字段的具体取值。

  • tuya_product_id：表示设备在涂鸦的 PID。获取方法参考 创建云产品 章节。

  • isGateway：表示是否为网关设备，默认传 false。如果是用传装置绑定，该值传 true，此时，extendData 字段需要传入 {\"userTransUnitNum\":\"000.000.000.000.000.155\"}, ,userTransUnitNum 表示用传装置的编号。

    如果设备是用传装置，3rd_cloud_device_id 字段生成规则为 厂商 code_用传装置编号，并使用 md5 转换。

字段说明如下：

ext_properties 的 code 描述 是否必填
cid 三方设备 ID，同 3rd_cloud_device_id。建议采用设备端可读取的唯一标识作为 cid，例如设备的 SN 号、Mac 地址、IMEI 号等。 是
vendorCode 三方供应商的英文拼写 code 是
outProjectId 三方设备所在的小区 ID 是
deviceIp 设备 IP，例如 192.168.1.1 否
macAddress 设备 Mac 地址 否
commType 通信类型，例如 HTTP、MQTT、485 电信号等 否
lat 纬度 是
lon 经度 是
installLocation 安装位置，该字段需要有可读性 是
deviceName 三方设备名称，该字段需要有可读性 是
deviceDesc 设备描述，例如 无线压力变送器，该字段需要有可读性 是
extendData JSON 字符串等设备扩展信息 否
isGateway 是否是用传装置，布尔值。如果是用传装置，传 true，否则可以不传。 否

请求示例

POST /v1.0/3rdcloud/devices/actions/bind
{
    "tuya_product_id": "wazil4rsq7cl***",
    "devices": [
        {
            "id": "qinfengte***",
            "ext": "[{\"code\": \"cid\",\"value\": \"**********\"},{\"code\": \"vendorCode\",\"value\": \"****\"},{\"code\": \"deviceIp\",\"value\": \"1*********3\"},{\"code\": \"macAddress\",\"value\": \"mac 地址\"},{\"code\": \"commType\",\"value\": \"HTTP\"},{\"code\": \"lat\",\"value\": \"30.2084\"},{\"code\": \"lon\",\"value\": \"120.21201\"},{\"code\": \"installLocation\", \"value\": \"安装位置\"},{\"code\": \"outProjectId\",\"value\": \"a***********3\"},{\"code\": \"deviceDesc\",\"value\": \"测试设备\"},{\"code\": \"extendData\",\"value\": \"\"},{\"code\": \"deviceName\",\"value\": \"测试设备\"}]"
        }
    ]
}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

result 说明

参数名 类型 说明
failed_bind_result List 绑定失败设备列表
success_bind_result List 绑定成功设备列表

  • success_bind_result 说明

    参数名 类型 说明
    3rd_device_id String 三方设备 ID
    tuya_device_id String 涂鸦设备 ID

  • failed_bind_result 说明

    参数名 类型 说明
    3rd_device_id String 三方设备 ID
    failed_reason String 失败原因

请求示例

{
    "result": {
        "failed_bind_result": [],
        "success_bind_result": [
            {
                "3rd_device_id": "",
                "tuya_device_id": ""
            }
        ]
    },
    "success": true,
    "t": 1635845117***
}

三方子设备绑定

子设备在第三方云配网成功后，调用此接口向涂鸦注册子设备信息。

  • 产品信息录入：调用此接口前，请确保该设备的产品信息已在涂鸦 IoT 开发平台完成录入，并且已经生成 PID（产品 ID）。详情请参考 创建产品。
  • 自动创建涂鸦用户 ID：注册设备时，需指定在涂鸦的用户名。涂鸦将自动创建三方用户对应的涂鸦用户 ID，并将设备绑定到对应的涂鸦用户 ID 下。
  • 绑定子设备：当子设备在第三方云配网成功后，第三方云调用此接口向涂鸦注册子设备信息。

绑定成功后，在涂鸦体系的 App 可以控制此设备，及查看设备状态等相关信息。

接口地址

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/sub/bind

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 第三方云子设备 ID 是
tuya_product_id String BODY 涂鸦的产品 ID。 是
app_schema String BODY 涂鸦应用标识 否
tuya_username String BODY 涂鸦的用户名。用来对应第三方用户唯一标识。 否
properties Object BODY 涂鸦设备属性 否
ext_properties List BODY 拓展信息，依照具体业务方而定 否

  • properties 属性：

    参数名 类型 参数类型 说明 必填
    name String BODY 子设备名称 否
    lon Double BODY 经度 否
    lat Double BODY 纬度 否
    ip String BODY IP 否
    gatewayId String BODY 同用传装置的 3rd_cloud_device_id 是

  • ext_properties 属性：

    参数名 类型 参数类型 说明 必填
    code String BODY 标识符 是
    value String BODY 数值 是

    ext_properties 字段如下：

    [{"code":"cid","value":"123123***"},
{"code":"vendorCode","value":"nite"},
{"code":"deviceIp","value": "192.168.*.*"},
{"code":"macAddress","value": "mac 地址"},
{"code":"commType","value":"HTTP"},
{"code":"lat","value": "30.2***"},
{"code":"lon","value": "120.21***"},
{"code":"installLocation","value":"安装位置"},
{"code":"outProjectId","value":"三方设备所在的小区 ID"},
{"code":"deviceDesc","value":"设备描述"},
{"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\",\"fireControlUnitNum\":\"000.000\",\"deviceUnitNum\":\"000.001.001.000\"}"},
{"code":"deviceName","value":"三方的设备名称"}
]

三方厂商的设备名称需要放在 ext 字段里，对应的 key 为deviceName，并非请求参数里的 name 字段。 纬度的 key 为 lat，经度的 key 为 lon。

  • app_schema：表示渠道标识符。获取方法请参考 创建云应用 章节。

  • tuya_username：字段传厂商 code。

  • tuya_product_id：表示设备在涂鸦的 PID。获取方法参考 创建云产品 章节。

  • 3rd_cloud_device_id：表示三方设备的 ID。字段生成规则为 vendorCode_用传装置编号_主机编号_器件编号，并进行 md5 转换。

  • extendData 需要传

    	{
	"userTransUnitNum": "000.000.000.000.000.155", //用传装置编号
	"fireControlUnitNum": "000.000", //主机编号
	"deviceUnitNum": "000.001.001.000" //子设备编号
}

字段说明如下：

ext_properties 的 code 描述 是否必填
cid 三方设备 ID，同 3rd_cloud_device_id。建议采用设备端可读取的唯一标识作为 cid，例如设备的 SN 号、Mac 地址、IMEI 号等。 是
vendorCode 三方供应商的英文拼写 code。可传固定值 neat。 是
outProjectId 三方设备所在的小区 ID。可传三方厂商的单位 ID。 是
deviceIp 设备 IP，例如 192.168.1.1 否
macAddress 设备 Mac 地址 否
commType 通信类型，例如 HTTP、MQTT、485 电信号等 否
lat 纬度 是
lon 经度 是
installLocation 安装位置，该字段需要有可读性 是
deviceName 三方设备名称，该字段需要有可读性 是
deviceDesc 设备描述，例如 无线压力变送器，该字段需要有可读性 是
extendData JSON 字符串等设备扩展信息 否

请求示例

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/sub/bind
{
    "app_schema":"tencentiot",
    "tuya_username": "012345***",
    "tuya_product_id": "nr1k9ptidpov***",
    "ext_properties":[
       {"code":"deviceName","value":"具体设备名称"},
       {"code":"installLocation","value":"杭州市西湖区蒋墩路华策中心***"}
    ]
}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

result 说明

参数名 类型 说明
tuya_device_id String 涂鸦设备 ID
tuya_user_id String 涂鸦用户 ID

请求示例

{
    "success": true,
    "t": 1561456817***,
    "result": {
      "tuya_device_id":"",
      "tuya_user_id":""
    }
}

三方子设备批量绑定

子设备在第三方云配网成功后，调用此接口向涂鸦批量注册子设备信息。

  • 产品信息录入：调用此接口前，请确保该设备的产品信息已在涂鸦 IoT 开发平台完成录入，并且已经生成 PID（产品 ID）。详情请参考 创建产品。
  • 自动创建涂鸦用户 ID：注册设备时，需指定在涂鸦的用户名。涂鸦将自动创建三方用户对应的涂鸦用户 ID，并将设备绑定到对应的涂鸦用户 ID 下。
  • 绑定子设备：当子设备在第三方云配网成功后，第三方云调用此接口向涂鸦批量注册子设备信息。

绑定成功后，在涂鸦体系的 App 可以控制此设备，及查看设备状态等相关信息。

接口地址

POST /v1.0/3rdcloud/sub-devices/actions/bind

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
tuya_product_id String BODY 涂鸦的产品 ID。 是
app_schema String BODY 涂鸦应用标识 否
tuya_username String BODY 涂鸦的用户名。用来对应第三方用户唯一标识。 否
devices List BODY 涂鸦设备属性，单次调用设备数量上限为 20 是

  • properties 属性：

    参数名 类型 参数类型 说明 必填
    name String BODY 子设备名称 否
    lon Double BODY 经度 否
    lat Double BODY 纬度 否
    ip String BODY IP 否
    gatewayId String BODY 同用传装置的 3rd_cloud_device_id 是
    ext String BODY 设备扩展信息，详见下表 是

  • ext 参数：

    参数名 类型 参数类型 说明 必填
    code String BODY 标识符 是
    value String BODY 数值 是

    ext_properties 字段如下：

    [{"code":"cid","value":"123123***"},
{"code":"vendorCode","value":"nite"},
{"code":"deviceIp","value": "192.168.*.*"},
{"code":"macAddress","value": "mac 地址"},
{"code":"commType","value":"HTTP"},
{"code":"lat","value": "30.2***"},
{"code":"lon","value": "120.21***"},
{"code":"installLocation","value":"安装位置"},
{"code":"outProjectId","value":"三方设备所在的小区 ID"},
{"code":"deviceDesc","value":"设备描述"},
{"code":"extendData","value":"{\"userTransUnitNum\":\"000.000.000.000.000.155\",\"fireControlUnitNum\":\"000.000\",\"deviceUnitNum\":\"000.001.001.000\"}"},
{"code":"deviceName","value":"三方的设备名称"}
]

三方厂商的设备名称需要放在 ext 字段里，对应的 key 为deviceName，并非请求参数里的 name 字段。 纬度的 key 为 lat，经度的 key 为 lon。

  • app_schema：表示渠道标识符。获取方法请参考 创建云应用 章节。

  • tuya_username：字段传厂商 code。

  • tuya_product_id：表示设备在涂鸦的 PID。获取方法参考 创建云产品 章节。

  • 3rd_cloud_device_id：表示三方设备的 ID。字段生成规则为 vendorCode_用传装置编号_主机编号_器件编号，并进行 md5 转换。

  • extendData 需要传

    	{
	"userTransUnitNum": "000.000.000.000.000.155", //用传装置编号
	"fireControlUnitNum": "000.000", //主机编号
	"deviceUnitNum": "000.001.001.000" //子设备编号
}

字段说明如下：

ext_properties 的 code 描述 是否必填
cid 三方设备 ID，同 3rd_cloud_device_id。建议采用设备端可读取的唯一标识作为 cid，例如设备的 SN 号、Mac 地址、IMEI 号等。 是
vendorCode 三方供应商的英文拼写 code。可传固定值 neat。 是
outProjectId 三方设备所在的小区 ID。可传三方厂商的单位 ID。 是
deviceIp 设备 IP，例如 192.168.1.1 否
macAddress 设备 Mac 地址 否
commType 通信类型，例如 HTTP、MQTT、485 电信号等 否
lat 纬度 是
lon 经度 是
installLocation 安装位置，该字段需要有可读性 是
deviceName 三方设备名称，该字段需要有可读性 是
deviceDesc 设备描述，例如 无线压力变送器，该字段需要有可读性 是
extendData JSON 字符串等设备扩展信息 否

请求示例

POST /v1.0/3rdcloud/sub-devices/actions/bind
{
    "tuya_product_id": "123***",
    "devices": [
        {
            "id": "1223***",
            "gatewayId": "123***",
            "lon": "",
            "lat": "",
            "name": "",
            "ip": "",
            "ext":"[{\"code\": \"cid\",\"value\": \"123***\"},{\"code\": \"vendorCode\",                    \"value\": \"123***\"},{\"code\": \"deviceIp\",\"value\": \"\"},{\"code\": \"macAddress\",\"value\": \"mac 地址\"},{\"code\": \"commType\",\"value\": \"HTTP\"},{\"code\": \"lat\",\"value\": \"30.2084\"},{\"code\": \"lon\",\"value\": \"120.21201\"},{\"code\": \"installLocation\",\"value\": \"\"},{ \"code\":\"outProjectId\",\"value\": \"a123***\"},{\"code\": \"deviceDesc\",\"value\": \"测试子设备\"},{\"code\": \"extendData\",\"value\": \"\\\"userTransUnitNum\\\":\\\"000.000.000.000.000.001\\\",\\\"fireControlUnitNum\\\":\\\"000.000\\\",\\\"deviceUnitNum\\\":\\\"000.001.001.000\\\"}\"},{\"code\": \"deviceName\",\"value\": \"测试三方子设备\"}]"
        }
    ]
}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

result 说明

参数名 类型 说明
failed_bind_result List 绑定失败设备列表
success_bind_result List 绑定成功设备列表

  • success_bind_result 说明

    参数名 类型 说明
    3rd_device_id String 三方设备 ID
    tuya_device_id String 涂鸦设备 ID

  • failed_bind_result 说明

    参数名 类型 说明
    3rd_device_id String 三方设备 ID
    failed_reason String 失败原因

请求示例

{
    "success": true,
    "t": 156145681***,
    "result": {
      "failed_bind_result":[],
      "success_bind_result":[
      	"3rd_device_id":"123***",
        "tuya_device_id":"123***"
      ]
    }
}

三方设备更新信息

第三方设备完成注册之后，可按需更新设备信息。

接口地址

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 第三方云设备 ID 是
tuya_product_id String BODY 涂鸦的产品 ID。 是
properties Object BODY 涂鸦设备属性 否
ext_properties List BODY 拓展设备属性 否

  • properties 参数：

    参数名 类型 参数类型 说明 必填
    name String BODY 设备名称 否
    lon Double BODY 经度 否
    lat Double BODY 纬度 否
    ip String BODY IP 否

  • ext_properties 参数：

    参数名 类型 参数类型 说明 必填
    code String BODY 标识符 是
    value String BODY 数值 是
    name String BODY 名称 否

    ext_properties 字段如下：

    [{"code":"vendorCode","value":"neat","name":"三方供应商 code(英文拼写)"},
{"code":"deviceName","value":"三方的设备名称","name":"三方的设备名称"},
{"code":"deviceIp","value": "192.168.1.1","设备 ID"},
{"code":"deviceDesc","value":"设备描述","name":"设备描述"},
{"code":"macAddress","value": "mac 地址","name":"mac 地址"},
{"code":"commType","value":"HTTP","name":"通信类型（http、mqtt、485 电信号）"},
{"code":"installLocation","value":"安装位置","name":"安装位置"},
{"code":"lat","value": "30.2084","name":"纬度"},
{"code":"lon","value": "120.21201","name":"经度"},
{"code":"extendData","value":"扩展信息，没有可以不传递","name":"扩展信息"}
]

三方厂商的设备名称需要放在 ext 字段里，对应的 key 为deviceName，并非请求参数里的 name 字段。 纬度的 key 为 lat，经度的 key 为 lon。

  • app_schema：表示渠道标识符。获取方法请参考 创建云应用 章节。
  • tuya_username：字段固定值 neat。
  • tuya_product_id：表示设备在涂鸦的 PID。获取方法参考 创建云产品 章节。

字段说明如下：

ext_properties 的 code 描述 是否必填
vendorCode 三方供应商的英文拼写 code。可传固定值 neat。 是
deviceIp 设备 IP，例如 192.168.1.1 否
macAddress 设备 Mac 地址 否
commType 通信类型，例如 HTTP、MQTT、485 电信号等 否
lat 纬度 是
lon 经度 是
installLocation 安装位置，该字段需要有可读性 是
deviceName 三方设备名称，该字段需要有可读性 是
deviceDesc 设备描述，例如 无线压力变送器，该字段需要有可读性 是
extendData JSON 字符串等设备扩展信息 否

请求示例

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200
{
    "properties":{
        "name":"测试设备",
        "lon":39.904***,
        "lat":116.407***,
        "ip":"124.156.99.***"
    },
    "ext_properties":[
        {
            "code":"vendorCode",
            "value":"neat",
            "name":"三方供应商 code"
        },
        {
            "code":"installLocation",
            "value":"杭州市西湖区蒋墩路华策中***",
            "name":"地址"
        }
    ]
}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Boolean 返回结果

返回示例

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

三方设备解绑

此接口可以将三方设备从涂鸦解绑，使用场景为：

  • 设备被重置时。
  • 设备被从涂鸦 App 或第三方云 App 删除时。

接口地址

DELETE /v1.0/3rdcloud/devices/{third_party_device_id}/unbind

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 第三方云设备 ID 是

请求示例

DELETE /v1.0/3rdcloud/devices/27511006b4e62d4bd200/unbind

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

请求示例

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

三方设备上线

第三方云需根据设备联网情况，同步设备上线消息。涂鸦 App 据此更新设备在线状态。

接口地址

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/online

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 第三方云设备 ID 是

请求示例

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200/online

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

响应示例

{
    "success": true,
    "t": 156145681***,
    "result": true
}

三方设备离线

第三方云需根据设备联网情况，同步设备离线消息。涂鸦 App 据此更新设备离线状态。

接口地址

PUT /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/offline

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 第三方云设备 ID 是

请求示例

PUT /v1.0/3rdcloud/devices/27511006b4e62d4bd200/offline

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

请求示例

{
    "success": true,
    "t": 156145681***,
    "result": true
}

三方设备事件上报

第三方云设备有事件发生时，调用此接口通知涂鸦。

接口地址

POST /v1.0/3rdcloud/devices/{3rd_cloud_device_id}/status

header 参数

参数名 类型 参数类型 说明 必填
access_token String header 访问令牌，获取 Token 相关接口 是
client_id String header client_id 是
sign String header 参考 业务接口调用签名算法 是
sign_method String header 签名类型，默认为 HMAC-SHA256 是
t Long header 13 位标准时间戳 是
Content-Type String header 默认为 application/json 是

请求参数

参数名 类型 参数类型 说明 必填
3rd_cloud_device_id String URI 第三方云设备 ID 是
timestamp Long BODY 第三方云设备状态变更发生时间，精确到秒 是
status List BODY 设备状态数据 是

  • status 说明

    参数名 类型 说明
    code String 设备功能 code
    value String 设备功能的值

  • status 内容

    code value 功能 数据类型 说明
    alarm_trace_id “唯一事件 ID(productId+雪花算法)” 报警事件 ID String 用于更新设备报警后的事件处理结果（alarm_result_content）
    alarm_event_content “内容描述（烟雾浓度超过阈值）等” 报警内容描述 String 报警内容说明
    fire_alarm_type 消防设备报警类型 报警类型 Enum {“range”:[“fire_alarm”,“device_fault”,“device_alarm”,“others”]}.火警报警、设备故障（电量过低），设备报警。
    alarm_trace_time 13 位毫秒时间戳 事件发生时间 String 事件发生时间，毫秒
    alarm_result_content “已处理/设备故障” 事件结果 String 事件处理结果描述（由三方平台定义具体内容，文档只是举例）
    alarm_value 数值类型 事件值 float 报警时的数值（注意：所有值需要乘以 10,000 后并转换为整数传递过来。例：36.5 传递到涂鸦为：365000，37.55 传递到涂鸦为：375500，乘以 10,000 后四舍五入。）范围：-1,000,000,000 - 1,000,000,000
    alarm_unit 单位描述 事件单位 String 报警的单位（和事件值相关联，比如是摄氏度）
    alarm_process_time 13 位毫秒时间戳 报警的处理时间 String 报警的处理时间，毫秒
  • 同个报警的多个不同事件可以发送 list 类型数据。
  • 对于事件处理结果上报时，需要保证和报警事件上报时的 alarm_trace_id 一致，并且同时上传 报警事件 和 报警处理 时的其他字段。避免只传递对应的处理结果。

请求示例

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/status
{
    "timestamp":1592920221,
    "status": [
        {
            "code": "alarm_trace_id",
            "value": "productId+雪花算法"
        },
        {
            "code": "alarm_event_content",
            "value": "温度到达阈值"
        },
        {
            "code": "fire_alarm_type",
            "value": "fire_warning"
        },
        {
        	"code": "alarm_trace_time",
            "value": "1592722282***"
        },
        {
        	"code": "alarm_result_content",
            "value": "已处理"
        },
        {
        	"code": "alarm_value",
            "value": 50
        },
        {
        	"code": "alarm_unit",
            "value": "摄氏度"
        },
        {
          "code": "alarm_process_time",
          "value": "1592722282***"
        }
    ]
}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

响应示例

{
    "success": true,
    "t": 1561456817***,
    "result": true
}

检测数据 dpcode 定义（status 内容）

code value 功能 数据类型 说明
monitor_data 检测项 code 监测项代码 String 检测项 code，三方厂商定义，最好英文单词或短语，要求简单易读
monitor_name 检测项名称 检测项名称 String 检测项中文名称
monitor_value 检测数据值 检测值 Int 范围-10,000 至 100,000，小数点后不可超过 4 位
monitor_unit 检测项数据单位 检测单位 String 检测项数值的单位名称
monitor_time_data 13 位毫秒时间戳 检测时间数据 String 检测项数据产生的时间
  • 同一设备多条数据上报可发送 list 类型数据。
  • 数据上报不可与报警 dpcode 混发，至少保证 list 的同一个元素只包含二者其一。

请求示例

POST /v1.0/3rdcloud/devices/27511006b4e62d4bd200/status
{
    "timestamp":1592920221,
    "status": [
        {
            "code": "monitor_data",
            "value": "voltage"
        },
        {
            "code": "monitor_name",
            "value": "电压"
        },
        {
            "code": "monitor_value",
            "value": "220"
        },
        {
        	"code": "monitor_unit",
            "value": "V"
        },
        {
          "code": "monitor_time_data",
          "value": "1592722282***"
        }
    ]
}

返回信息

参数名 类型 说明
code Integer 响应码，更多详情请参考 错误码 章节
success Boolean 是否成功
  • true：成功
  • false：失败
msg String 请求失败的信息，成功为空
result Object 返回结果

响应示例

{
    "success": true,
    "t": 156145681***,
    "result": true
}
上一篇BA 楼宇自控系统接入
下一篇智能环境监测接入
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们Tuya ExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English