IOT技术架构
# 1 系统架构图
# 2. 协议设计
# 2.1 IOT 平台与设备通信协议
# 2.1.1 握手协议
握手协议是首先通过通过 curve25519 完成共享密钥交换，并且通过 ED25519 提前生成的公私钥对来验证双方通信身份的有效性以及数据完整性，完成握手后通信双方约定出一种对称加密算法，以及一个对称加密密钥。
# 2.1.1.1 初始化
- 请求 (Device -> Cloud)
{ "iq": { "id": "411", "type": "query", "method": "urn:xiot:initialize", "content": { "version": "1.0", "authentication": "device-id" } } }1
2
3
4
5
6
7
8
9
10
11
authentication，指定认证方式为根据单个设备认证，还根据设备类型认证：
| authentication | 说明 |
|---|---|
| device-id | 根据单个设备认证 |
| device-type | 根据设备类型认证 |
- 应答 (Cloud -> Device)
{ "iq": { "id": "411", "type": "result", "method": "urn:xiot:initialize" } }1
2
3
4
5
6
7
8
# 2.1.1.2 开始验证
- 请求 (Device -> Cloud)
{
"id": "412",
"type": "query",
"method": "urn:xiot:verify-start",
"content": {
"public-key": "<A>"
}
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
- 应答 (Cloud -> Device)
{
"iq": {
"id": "412",
"type": "result",
"method": "urn:xiot:verify-start",
"content": {
"public-key": "<B>",
"signature": "<encryptedSignature>"
}
}
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
# 2.1.1.3 结束验证
- 请求 (Device -> Cloud)
{
"iq": {
"id": "413",
"type": "query",
"method": "urn:xiot:verify-finish",
"content": {
"device-id": "<encryptedDeviceId>",
"device-type": "<encryptedDeviceType>",
"signature": "<encryptedSignature>",
"codec": 0
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
其中: codec 指定对称加密方法：
| codec | 说明 |
|---|---|
| 0 | 不加密 |
| 1 | chacha20+poly1305 |
| 2 | aes+hkdf+sha1 |
- 应答 (Cloud -> Device)
{
"iq": {
"id": "413",
"type": "result",
"method": "urn:xiot:verify-finish"
}
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 2.1.2 设备控制
# 2.1.2.1 读属性
- 请求 (Cloud -> Device)
{
"iq": {
"id": "421",
"type": "query",
"method": "urn:xiot:get-properties",
"content": {
"properties": [
"abc.1.1",
"abc.1.2",
"abc.1.3"
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
- 应答 (Device -> Cloud)
{
"iq": {
"id": "421",
"type": "result",
"method": "urn:xiot:get-properties",
"content": {
"properties": [
{
"pid": "abc.1.1",
"value": 26
},
{
"pid": "abc.1.2",
"status": -1
},
{
"pid": "abc.1.3",
"status": -3
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 2.1.2.2 写属性
- 请求 (Cloud -> Device)
{
"iq": {
"id": "422",
"type": "query",
"method": "urn:xiot:set-properties",
"content": {
"properties": [
{
"pid": "abc.2.3",
"value": 37
},
{
"pid": "abc.2.4",
"value": 3600
},
{
"pid": "abc.2.5",
"value": 10.7
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- 应答 (Device -> Cloud)
{
"iq": {
"id": "422",
"type": "result",
"method": "urn:xiot:set-properties",
"content": {
"properties": [
{
"pid": "1.2.3",
"status": 0
},
{
"pid": "1.2.4",
"status": -2,
"description": "设备不在线"
},
{
"pid": "1.2.5",
"status": -4,
"description": "属性不可写"
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 2.1.2.3 执行方法
- 请求 (Cloud -> Device)
{
"iq": {
"id": "423",
"type": "query",
"method": "urn:xiot:invoke-actions",
"content": {
"actions": [
{
"aid": "aaa.1.9",
"in": [37, 3600]
},
{
"aid": "bbb.1.10",
"in": [37, 3600]
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
- 成功应答（Device -> Cloud）
{
"iq": {
"id": "423",
"type": "result",
"method": "urn:xiot:invoke-action",
"content": {
"actions": [
{
"aid": "abc.1.9",
"status": -434,
"descripion": "中文出错信息"
},
{
"aid": "abc.1.10",
"out": [3600],
"status": 0
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
- 失败应答（Device -> Cloud）
{
"iq": {
"id": "423",
"type": "result",
"method": "urn:xiot:invoke-action",
"content": {
"actions": [
{
"aid": "abc.1.9",
"status": -3,
"description": "action not found"
},
{
"aid": "abc.1.10",
"status": -3,
"description": "action not found"
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 2.1.2.4读取所有子设备
- 请求 (Cloud -> Device)
{
"iq": {
"id": "5009",
"type": "query",
"method": "urn:xiot:get-children",
"content": {
"did": "ppp"
}
}
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
- 应答 (Device -> Cloud)
{
"iq": {
"id": "5009",
"type": "result",
"method": "urn:xiot:get-children",
"content": {
"children": [
{
"did": "aaa",
"summary": {
"type": "urn:homekit-spec:device:outlet:00000a01:abc:aaa:1",
"online": true,
"parentId": "ppp",
"protocol": "zigbee"
}
},
{
"did": "bbb",
"summary": {
"type": "urn:homekit-spec:device:motion-sensor:00000a11:abc:bbb:2",
"online": true,
"parentId": "aaa",
"protocol": "zigbee"
}
}
]
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 2.1.3 设备消息
# 2.1.3.1 子设备已添加
通知(Device -> Cloud)
{
"message": {
"id": "1",
"topic": "urn:xiot:device",
"type": "children-added",
"payload": {
"did": "xxx",
"children": [
{
"did": "08:00:27:87:53:C5@25",
"summary": {
"type": "urn:homekit-spec:device:bridge:00000002:yingtuo:hhh:1",
"online": false,
"protocol": "zigbee",
"parentId": "xxx"
}
},
{
"did": "08:00:27:87:53:xx@26",
"summary": {
"type": "urn:homekit-spec:device:bridge:00000002:yingtuo:hhh:1",
"online": false,
"protocol": "btmesh",
"parentId": "xxx"
}
}
],
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 2.1.3.2 子设备已删除
通知(Device -> Cloud)
{
"message": {
"id": "1",
"topic": "urn:xiot:device",
"type": "children-removed",
"payload": {
"did": "xxx",
"children": [
"08:00:27:87:53:C5@25",
"08:00:27:87:53:xx@26"
],
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 2.1.3.3 属性已改变
通知(Device -> Cloud)
{
"message": {
"id": "1",
"topic": "urn:xiot:device",
"type": "properties-changed",
"payload": {
"properties": [
{
"pid": "47a5521d-4d28-4ad1-8126-03bd2910bcdc.1.1",
"value": 17
},
{
"pid": "47a5521d-4d28-4ad1-8126-03bd2910bcdc.1.2",
"value": 12.7
},
{
"pid": "47a5521d-4d28-4ad1-8126-03bd2910bcdc.1.3",
"value": "hello"
}
],
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 2.1.3.4 事件已发生
通知(Device -> Cloud)
{
"message": {
"id": "1",
"topic": "urn:xiot:device",
"type": "event-occurred",
"payload": {
"event": {
"eid": "eee.1.1",
"oid": "xxx",
"arguments": [
{
"piid": 1,
"values": ["hello"]
},
{
"piid": 2,
"values": [1]
},
{
"piid": 3,
"values": [100,200,300]
}
]
},
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 2.1.3.5 设备摘要已改变
通知(Device -> Cloud)
- 主要是上下线状态变化
- 其次是 deviceType 变化、parentId 变化等，这些变化都是由于设备上线变化引起的，所以放一起。
{
"message": {
"id": "1",
"topic": "urn:xiot:device",
"type": "summary-changed",
"payload": {
"did": "xxx",
"summary": {
"type": "urn:homekit-spec:device:lightbulb:00000005:a:zzz:1",
"online": true,
"protocol": "zigbee",
"parentId": "aaa"
},
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 2.1.3.6 设备绑定
通知( Cloud -> Device)
当设备被上层业务添加到 owner 时，推送给设备的消息
{
"message": {
"id": "1",
"topic": "urn:xiot:ownership",
"type": "ownership-taken",
"payload": {
"CloudpId": "xxxx",
"ownerId": "xxxx",
"did": "xxx",
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
# 2.1.3.7 设备解除绑定
通知( Cloud -> Device)
当设备被上层业务删除某个 owner 时，推送给设备的消息
{
"message": {
"id": "1",
"topic": "urn:xiot:ownership",
"type": "ownership-disclaimed",
"payload": {
"CloudpId": "xxxx",
"ownerId": "xxxx",
"did": "xxx",
"timestamp": 1640164172915
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
# 2.2 IOT 平台与业务方通信协议
IOT 平台收到设备上报的数据后，会将原始的协议经过转换，并最终推送给到业务方
IOT 平台需要将设备状态数据推送给到业务方，目前主要⽀持 http，kafka，rocketmq 三种方式，这些对接方式需要在业务应用注册时候需要指定好，这些对接数据会持久化到 app_info 数据表。
| 事件发送⽅式 | EventReceiver | 备注 |
|---|---|---|
| http | { "configuration": { "url": "http://127.0.0.1:80/event/receiver" }, "type": "http" } | 授权认证 |
| kafka | { "configuration": { "bootstrapServers": "10.26.21.71:9092", "topic": "smart-home-message" }, "type": "kafka" } | 授权认证 |
| rocketmq | { "configuration": { "bootstrapServers": "10.26.21.71:9092", "topic": "smart-home-message", "accessKey": "LTAIbpwPiX00", "secretKey": "bCArXw1KXa0r" }, "type": "rocketmq" } | 授权认证 |
业务主要收到的数据类型有：
| 事件类型 | 事件类型名称 |
|---|---|
| OwnerDeviceAdded | 设备添加事件 |
| OwnerDeviceRemoved | 设备移除事件 |
| OwnerPropertiesChanged | 设备属性变更事件 |
| OwnerEventOccurred | 设备事件触发事件 |
| OwnerDeviceSummaryChanged | 设备摘要变更事件 |
# 2.2.1 OwnerDeviceAdded
产生原因：
- 网关绑定归属者
- 网关绑定归属者后又添加子设备
数据格式：
{
"id": "155094-10.228.141.22-62-1637810287224-899#0",
"type": "device-added",
"payload": {
"appId": "sqn-test",
"ownerId": "sqn-test",
"did": "1628@0",
"summary": {
"online": false,
"type": "urn:knowin-spec:device:gateway:00000001:know:insight:1"
},
"timestamp": 1640164172915
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
# 2.2.2 OwnerDeviceRemoved
产生原因：
- 网关解绑了归属者
- 网关删除了子设备
- 设备进行了重置，设备访问 token 发生了变化
数据格式：
{
"id": "155094-10.228.141.22-58-1637811054524-901#0",
"type": "device-removed",
"payload": {
"appId": "sqn-test",
"ownerId": "sqn-test",
"did": "1628@0",
"timestamp": 1640164172915
}
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# 2.2.3 DeviceSummaryChanged
产生原因：
- 设备的在离线发生了变化
- 设备对物模型的类型发生了变化
数据格式：
{
"id":"19e2cf0d-c334-4a4a-9b54-256f6871298c#0",
"type":"device-summary-changed",
"payload":{
"appId":"sqn-test",
"ownerId":"sqn-test",
"did":"1628@0",
"summary":{
"online":true,
"type":"urn:knowin-spec:device:gateway:00000001:know:insight:1",
"parentId": "xxxxxx",
"members": ["aaa", "bbb"]
},
"timestamp": 1640164172915
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 2.2.4 DevicePropertiesChanged
产生原因：
- 设备属性状态数据发生了变化
数据格式：
{
"id": "b#1628#1#s#1",
"type": "device-properties-changed",
"payload": {
"appId": "xxxx",
"ownerId": "xxxx",
"properties": [{
"pid": "1628@0.2.1",
"value": 0
},
{
"pid": "1628@0.2.2",
"value": 0
},
{
"pid": "1628@0.2.3",
"value": 0
},
{
"pid": "1628@0.2.4",
"value": ""
},
{
"pid": "1628@0.2.5",
"value": 0
}
],
"timestamp": 1640164172915
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# 2.2.5 OwnerEventOccurred
产生原因：
- 设备产生了物模型事件
数据格式：
{
"id": "b#1628#1#s#1",
"type": "device-event-occurred",
"payload": {
"appId": "xxxx",
"ownerId": "xxxx",
"event": {
"eid": "1628@0.1.1",
"arguments": [{
"piid": 1,
"values": [
1
]
}],
"oid": "12345667888"
},
"timestamp": 1640164172915
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 2.3 业务平台对接 IOT 平台 API
# 2.3.1 基本概念
# 2.3.1.1 设备
设备指的是具体的物理设备，⽐如灯、开关、插座、空调等。
# 2.3.1.2 owner
owner 就是设备拥有者，设备的拥有者可以是⼀个具体的⼈，也可以是⼀个抽象的组织。
# 2.3.1.3从属关系
⼀个 owner 可以拥有多个设备，⼀个设备可以有多个 owner。
# 2.3.2 IoT 简介
# 2.3.2.1 调⽤
IoT 调⽤关系如下：
# 2.3.2.2 应⽤
IoT 平台⽀持多个 IoT 应⽤，每个应⽤可以：
# 2.3.3 服务
# 2.3.3.1 主要功能
# 2.3.3.1.1 控制
调⽤服务接⼝，可以对设备进⾏控制操作。
# 2.3.3.1.2 事件
事件会主动发送给应⽤在开发者控制台填写的订阅地址。
# 2.3.3.2 鉴权
所有应⽤向 IoT 服务发起的请求，都需要携带⼀个 token，IoT 服务⽤此 token 鉴权。
鉴权⽅式由应⽤指定，有两种鉴权⽅式：
# 2.3.3.2.1 JWT 鉴权
⽤⼀个固定的 serectKey 对 token 加解密，token ⾥包含 ownerId，格式如下：
{
"id": "{ownerId}"
}
1
2
3
2
3
# 2.3.3.2.2 HTTP 鉴权
应⽤提供⼀个 url 地址，IoT 服务向次 url 发起请求鉴权，请求如下：
GET /xxxxxxx HTTP/1.1
authorization: Bearer {TOKEN}
1
2
2
鉴权成功，应答如下：
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 28
{
"code":"SUCCESS",
"data":{
"id":"{ownerId}"
}
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
鉴权失败，应答如下：
HTTP/1.1 401 UNAUTHORIZED
1
# 2.3.4 事件分发
IoT 服务提供设备的事件分发功能，⽬前⽀持：
通过 HTTP POST 请求发送事件给应⽤（接收消息的服务由应⽤提供）
通过 kafka topic 发送事件给应⽤（接收消息的服务由应⽤提供）
# 2.4 如何使⽤
# 2.4.1 使⽤流程
应⽤需要在 IoT 平台注册，填写必要的信息（鉴权⽅式和接收事件的⽅式），如：
# 2.4.2 调⽤ iot 平台 Api 的 header 约定
在 IoT 开发平台注册应⽤后，会得到⼀个应⽤ ID，调⽤任何 IoT 服务都需要携带⼀个它，如：
App-Id: {appId}
1
所有 HTTP/HTTPS 接⼝必须携带⼀个 owner token，此 token 解开后能拿到⼀个 ownerId，如：
authorization：Bearer {token}
1
如果接⼝返回 401，说明 token 错误，⽐如 token 过期等。
HTTP/1.1 401 UNAUTHORIZED
1
如果接⼝返回 200，说明操作完成，返回的数据格式如下：
{
"code":"SUCCESS",
"data":{
}
}
1
2
3
4
5
6
2
3
4
5
6
如果 code 为"SUCCESS"，说明操作成功，data ⾥包含为期望的数据。
如果 code 不为"SUCCESS"，说明操作失败，不携带 data，将携带⼀个 message，详细描述失败原因，如：
{
"code":"ERROR",
"message":"did invalid!"
}
1
2
3
4
2
3
4
# 2.4.3 名词定义
请参考⽂档：《物模型》，在本⽂档⾥⽤到⼏个缩写：
# 2.4.3.1 did
deviceId，即设备 ID，简称 did
# 2.4.3.2 iid
instance id，分为 siid，piid，aiid, eiid
# 2.4.3.3 siid
service instance id
# 2.4.3.4 piid
property instance id
# 2.4.3.5 aiid
action instance id
# 2.4.3.6 eiid
event instance id
# 2.4.3.7 pid
propety id，由 did + service iid + property iid 组成，即:
pid = {did}.{siid}.{piid}
# 2.4.3.8 aid
action ID，由 did + service iid + action iid 组成，即：
aid = {did}.{siid}.{aiid}
# 2.4.3.9 token
token 分两种：
# 2.4.3.10 owner token
拥有者 token，访问所有的 API 必须使⽤的 token。
# 2.4.3.11 device token
设备 token，添加设备时使⽤。
# 2.5 服务接⼝
# 2.5.1 设备列表
# 2.5.1.1 读取设备列表
# 2.5.1.1.1 请求
GET /controller/v1/devices?did={aaa,bbb,ccc}
1
# 2.5.1.1.2 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"aaa",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000a001:gkct:nc:1",
"online":true,
"parentId":"1234@33",
"cloudId":"1521075"
}
},
{
"did":"bbb",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000a001:gkct:nc:1",
"online":true,
"parentId":"1234@33",
"cloudId":"1521075"
}
},
{
"did":"ccc",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000a001:gkct:nc:1",
"online":true,
"parentId":"1234@33",
"cloudId":"1521075"
}
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# 2.5.1.2 读取所有设备
# 2.5.1.2.1 请求
GET /controller/v1/devices
1
# 2.5.1.2.1 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"001@99",
"status":0,
"summary":{
"type":"urn:k-spec:device:switch:0000A002:a:b:1",
"online":true,
"cloudId":"",
"parentId":"1234@33",
"protocol": "zigbee"
}
},
{
"did":"001@888",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000A001:a:b:1",
"online":true,
"cloudId":"",
"parentId":"1234@33"
}
},
{
"did":"xxx@666",
"status":0,
"summary":{
"type":"urn:k-spec:group:light:0000A001:a:b:1",
"cloudId":"xiaomi",
"online":true,
"parentId":"1234@33"
}
},
{
"did":"aaaa@666",
"status":0,
"summary":{
"type":"urn:k-spec:device:gateway:0000A003:a:b:1",
"online":true,
"cloudId":"1521075",
"protocol": "zigbee"
}
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# 2.5.1.3 读取设备下所有子设备
# 2.5.1.3.1 请求
GET /controller/v1/devices?parentId=1234@33
1
# 2.5.1.3.2 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"001@99",
"status":0,
"summary":{
"type":"urn:k-spec:device:switch:0000A002:a:b:1",
"online":true,
"cloudId":"",
"parentId":"1234@33"
}
},
{
"did":"001@888",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000A001:a:b:1",
"online":true,
"cloudId":"",
"parentId":"1234@33"
}
},
{
"did":"xxx@666",
"status":0,
"summary":{
"type":"urn:k-spec:group:light:0000A001:a:b:1",
"cloudId":"xiaomi",
"online":true,
"parentId":"1234@33",
"protocol": "zigbee"
}
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# 2.5.1.4 读取第三⽅设备
# 2.5.1.4.1 不同步
不同步的意思是仅从缓存中读取，速度快，但可能数据不准确。
# 2.5.1.4.2 请求
GET /controller/v1/devices?cloudId=xxx //第三⽅平台ID
1
# 2.5.1.4.3应答
{
"code":"SUCCESS",
"data":{
"status":0,
"devices":[
{
"did":"f26789188a00dbb5c42c23bc599fcd9d",
"summary":{
"type":"urn:miot-spec-v2:device:switch:0000a002:a:b:1",
"online":true,
"cloudId":"1521075"
}
}
]
}
}
{
"code":"SUCCESS",
"data":{
"status":-601,
"description":"cloud not authorized"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 2.5.1.4.4 同步
同步的意思是会去第三⽅平台读取⼀次，有⼀定耗时，但数据准确
# 2.5.1.4.5 请求
GET /controller/v1/devices?cloudId=1521075&sync=true //只能为true，不携带此参数，视为sync=false
1
# 2.5.1.4.6 应答
{
"code":"SUCCESS",
"data":{
"status":0,
"devices":[
{
"did":"f26789188a00dbb5c42c23bc599fcd9d",
"summary":{
"type":"urn:miot-spec-v2:device:switch:0000A002:a:b:1",
"online":true,
"cloudId":"1521075"
}
}
]
}
}
{
"code":"SUCCESS",
"data":{
"status":-601,
"description":"cloud not authorized"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 2.5.1.5 添加设备
# 2.5.1.5.1 请求
POST /controller/v1/devices
{
"devices":[
{
"did":"001@888",
"token":"xxxxxxx"
},
{
"did":"aaa@666",
"cloudId":"xxxxxxx"
},
{
"did":"aaa@777",
"token":"xxxxxxx"
}
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
其中
did 是设备 id
token 是从设备上读取到的 token
如果添加⾃有设备，只需要传输 token 字段。
如果添加第三⽅设备，只需要传输 cloudId 字段。
只能添加 root 设备，即不支持子设备的添加，子设备添加通过其他方式，删除同。
# 2.5.1.5.2 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"001@888",
"status":0
},
{
"did":"aaaa@666",
"status":-28,
"description":"invaid did"
},
{
"did":"aaaa@777",
"status":-500,
"description":"device is not a root device!"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 2.5.1.6 删除设备
# 2.5.1.6.1 请求
DELETE /controller/v1/devices?did=abc,aaa,ccc
1
# 2.5.1.6.2 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"001@888",
"status":0
},
{
"did":"aaaa@666",
"status":-28,
"description":"did not found"
},
{
"did":"aaaa@777",
"status":-500,
"description":"device is not a root device!"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 2.5.1.7 探测设备
类似读设备列表，但是不做鉴权，业务可以探测任何设备
1
# 2.5.1.7.1 请求
GET /controller/v1/probe/devices?did={aaa,bbb,ccc}
1
# 2.5.1.7.2 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"aaa",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000a001:gkct:nc:1",
"online":true,
"parentId":"1234@33"
}
},
{
"did":"bbb",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000a001:gkct:nc:1",
"online":true,
"parentId":"1234@33"
}
},
{
"did":"ccc",
"status":0,
"summary":{
"type":"urn:k-spec:device:light:0000a001:gkct:nc:1",
"online":true,
"parentId":"1234@33"
}
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# 2.5.2 设备控制
# 2.5.2.1 读设备影⼦
# 2.5.2.1.1 请求
GET /controller/v1/shadows?did=aaa,bbb,ccc
1
# 2.5.2.1.2 应答
{
"code":"SUCCESS",
"data":{
"devices":[
{
"did":"aaa",
"status":0,
"shadow":[
{
"siid":2,
"piid":2,
"status":0,
"value":19
},
{
"siid":2,
"piid":3,
"status":-425,
"decription":"xxxx"
}
]
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 2.5.2.2 读属性
# 2.5.2.2.1 请求
GET /controller/v1/properties?pid=aaaa.1.1,bbb.2.2,ccc.3.3
1
# 2.5.2.2.2 应答
{
"code": "SUCCESS", // 需要和公司通用的规范保持一致~！
"data": {
"properties":[
{
"pid":"aaaa.1.1",
"status":0,
"value":19
},
{
"pid":"aaaa.1.2",
"status":0,
"value":"ABB"
},
{
"pid":"aaaa.2.1",
"status":-1,
"description":"service nout found"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"msg": "error", // 需要和公司通用的规范保持一致~！
"description": "xxxxxx"
}
1
2
3
4
2
3
4
# 2.5.2.3 写属性
# 2.5.2.3.1 请求
PUT /controller/v1/properties
{
"offlineMode":false,//设备离线后可以走离线模式，云端缓存，设备上线执行
"properties":[
{
"pid":"aaaa.1.1",
"value":17
},
{
"pid":"aaaa.1.2",
"value":199.3
}
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
# 2.5.2.3.2 应答
{
"code":"SUCCESS",
"data":{
"properties":[
{
"pid":"aaaa.1.1",
"status":0
},
{
"pid":"aaaa.1.2",
"status":-2,
"description":"invalid value"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 2.5.2.4 执⾏⽅法
# 2.5.2.4.1 请求
PUT /controller/v1/actions
{
"offlineMode":false,//设备离线后可以走离线模式，云端缓存，设备上线执行
"actions":[
{
"aid":"aaaa.2.1",
"in":[
{
"piid":1,
"values":[
17,
19,
21
]
},
{
"piid":2,
"values":[
"abc"
]
}
]
}
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 2.5.2.4.2 应答
{
"code":"SUCCESS",
"data":{
"actions":[
{
"aid":"aaaa.2.1",
"status":0,
"out":[
{
"piid":3,
"values":[
"a",
"b",
"c",
"d",
"e"
]
}
]
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
上次更新: 2024/07/10, 15:53:57