酷宅IOT平台zigbee补充协议12.docx
《酷宅IOT平台zigbee补充协议12.docx》由会员分享，可在线阅读，更多相关《酷宅IOT平台zigbee补充协议12.docx（22页珍藏版）》请在冰豆网上搜索。
酷宅IOT平台zigbee补充协议12
酷宅IOT平台_zigbee补充协议
版本：
1.2
Changelog:
时间
修改内容
备注
2019-06-04
1、当网关不在线，子设备被别的网关添加以后，网关上报子设备离线，会收到删除子设备的消息；
2、补充新的zigbee设备uiid
2018-6-21
支持握手上报最新子设备列表；
支持批量管理设备（注册、删除、上/下线）
2018-6-11
初稿
1概述
1.1通用说明
本协议是在长连接原有协议基础上，新增针对zigbee网关业务的相关指令。
zigbee子设备的id格式：
mac:
port
子设备申请到的deviceid：
与普通wifi设备id格式一致
服务器业务逻辑修改中（长连接和RESTapi），凡是涉及到devices和factorydevices表的修改，都要同步到缓存；
2长连接服务接口
说明：
长连接服务器提供一个公用接口地址，通过接收不同的指令执行不同的业务功能。
连接方式：
websocket连接
接口地址：
wss:
//domain-name:
port/api/ws
指令格式：
请求与响应都采用标准JSON（RFC7159）格式
2.1握手指令（zigbee网关注册）
说明：
对于网关来说握手跟普通设备一样，只是app端收到网关上线的指令以后，要刷新一下设备列表；
请求参数：
跟普通设备一样，省略
响应参数：
跟普通设备一样，省略
注意：
网关设备上线后，app收到sysmsg消息，应该立即刷新一下设备列表，这样可以尽快同步到子设备的在线状态；
2.2批量上报子设备指令
说明：
网关上线以后，分批上报子设备信息，包括在线状态；
当出现丢包或者系统异常，服务器端也可以通过该指令，要网关重新全部上报或者重新上报指定批次的信息；
请求参数：
ID
名称
类型
允许NULL
说明
1
action
String
N
reportSubDevice
2
apikey
String
N
用户的apikey
3
deviceid
String
N
网关的deviceid
4
userAgent
String
N
设备端上报填：
device
服务端下发填：
server
5
d_seq
long
Y
设备端专用：
设备端上报
6
params
PARAMS
N
7
sequence
String
Y
server下发给设备
时间戳精确到毫秒
设备端上报时：
PARAMS定义
ID
名称
类型
允许NULL
说明
1
state
Int
N
是否完成上报操作；
0：
上报中
1：
上报完成（最后一批上报的时候，设置成1，表示这是最后一批）
1
subDevices
[SubDevice]
Y
子设备数组
SubDevice定义：
ID
名称
类型
允许NULL
说明
1
subDevId
String
N
zigbee内部id，
zigbee子设备的格式为：
mac:
port
2
uiid
String
Y
子设备的uiid
3
deviceid
String
Y
子设备的deviceid，格式跟普通wifi设备一样。
上报的时候，如果是新的子设备，可以不传这个字段。
返回的命令里，这个字段必填
4
online
boolean
Y
上报子设备的在线状态
true:
在线（默认）
false:
不在线
响应参数：
ID
名称
类型
允许NULL
说明
1
error
N
0ok（操作成功）
400BadRequest（参数错误）
401认证不通过
403Forbidden（无权限）
414子设备超过限制
500InternalServerError（服务器内部错误）
2
apikey
int
N
用户的apikey
3
d_seq
long
Y
设备端上传，服务端原样返回
4
sequence
String
Y
时间戳，精确到秒
由app下发给设备，设备端原样返回
5
deviceid
String
N
网关的deviceid
6
subDevices
[SubDevice]
Y
子设备数组
服务端的响应才有这个字段
主要用来返回子设备的deviceid
SubDevice定义：
ID
名称
类型
允许NULL
说明
1
subDevId
String
N
zigbee内部id，
zigbee子设备的格式为：
mac:
port
2
deviceid
String
N
子设备的deviceid，格式跟普通wifi设备一样。
服务端返回分配deviceid给网关
服务器业务逻辑：
如果是新增加的子设备，参考2.3子设备管理指令来处理；
如果上报完成，服务器要模拟一个网关上线的指令给app，让app再次刷新设备列表；
注意：
如果某个子设备，设置为下线的时候，发现deviceid被别的账号添加了，那么就要给网关下发一个删除子设备的指令；（因为有可能是子设备被别的网关添加了）
2.3子设备管理指令
说明：
zigbee网关通过该指令，可以批量注册、删除子设备，还可以批量上报子设备在线状态。
服务器端可以通过该指令下发给网关，通知网关某个子设备被删除了（被添加到其他网关）
请求参数：
ID
名称
类型
允许NULL
说明
1
action
String
N
subDevice
2
apikey
String
N
用户的apikey
3
deviceid
String
N
网关的deviceid
4
userAgent
String
N
App调用填：
app
设备端上报填：
device
服务端下发填：
server
5
d_seq
long
Y
设备端专用：
设备端上报
6
params
PARAMS
N
7
sequence
String
app下发给设备
时间戳精确到毫秒
PARAMS定义
ID
名称
类型
允许NULL
说明
1
cmds
[CMD]
N
操作类型:
0注册新子设备
1删除子设备
2子设备上线
3子设备下线
CMD定义
ID
名称
类型
允许NULL
说明
1
type
Int
N
操作类型:
0注册新子设备
1删除子设备
2子设备上线
3子设备下线
2
subDevId
String
N
子设备id
zigbee格式：
mac:
port
3
uiid
String
Y
子设备的uiid，由网关上报;
4
deviceid
String
Y
删除子设备，上报上、下线状态都要传子设备的deviceid
响应参数：
ID
名称
类型
允许NULL
说明
1
errors
[Error]
N
针对批量的每一个命令都有一个操作结果，按照请求中的cmd顺序一一对应
2
apikey
int
N
用户的apikey
3
d_seq
long
Y
设备端上传，服务端原样返回
4
sequence
String
Y
时间戳，精确到秒
由app下发给设备，设备端原样返回
5
deviceid
String
N
网关的deviceid
Error说明：
ID
名称
类型
允许NULL
说明
1
error
Int
N
0ok（操作成功）
400BadRequest（参数错误）
401认证不通过
403Forbidden（无权限）
414子设备超过限制
500InternalServerError（服务器内部错误）
2
deviceid
String
Y
这个是子设备的deviceid
服务器业务逻辑：
所有请求，都要检查请求参数是否合法、有效、设备是否存在等；
下面根据操作类型分别说明：
0注册新子设备
a.用请求里的deviceid去devices.params.parentid统计当前已经添加了多少个子设备，如果超过500个就返回414；
b.根据subDevId去FactoryDevices表查询partnerDevice.ezVedioSerial字段，看是否已经存在记录；如果已经有记录，就可以重用deviceid，否则生成新的deviceid并插入到factorydevices表；
c.根据factorydevices的deviceid，新增一条记录到Devices表（参考restapi的添加设备接口逻辑）
d.在Devices表除了要记录普通设备相同的数据以外，还要增加这两个字段
params.parentid（父id，也就是zigbee网关的deviceid）
params.subDevId（zigbee子设备本身的id，格式为mac:
port）
e.根据subDevId查找网关设备的params.subDevices中是否有这个子设备，有就更新deviceid字段，否则新增数组对象；
f.返回操作成功的响应
g.转发请求给app，让app及时更新界面;
1删除子设备
如果是app上报的删除操作，需要判断网关是否在线，网关不在线不能删除；
a.用请求里的params.deviceid到Devices表删除记录即可，FactoryDevices的记录保留；
b.查找网关设备的params.subDevices中是否有这个子设备，有也要删除并更新到数据库；
c.返回操作成功的代码；
d.如果是服务端发起的删除操作，检查app是否在线，如果在线，把消息转发给app，便于app刷新界面；
2/3子设备上、下线
a.修改devices表的online状态；
b.检查app是否在线，如果在线，参考普通设备的上、下线消息格式，返送给app;
c.还要检查该子设备是否分享给别人，分享的app如果在线也要发送消息（跟普通设备一样）
d.如果设置为下线的时候，发现deviceid被别的账号添加了，那么就要给网关下发一个删除子设备的指令；（因为有可能是子设备被别的网关添加了）
2.4更新/上报状态指令
说明：
设备端状态发生变化、设备端上报历史数据、APP修改设备状态，应该发送该指令到服务器。
注意：
对于服务器来说子设备相当于一个普通设备，如果是网关发送的update指令，deviceid要填写子设备的deviceid
请求参数：
（只列出这次有变化的地方）
ID
名称
类型
允许NULL
说明
x
deviceid
String
N
注意：
控制子设备的时候，这里填的是子设备的deviceid
新增app发下指令给网关，让网关进入/退出添加子设备模式的方法，如下：
"params":
{
"addSubDevState":
"on/off"
}
on:
表示让网关进入添加子设备模式
off:
表示让网关退出添加子设备模式
响应参数：
与原来的保持一致
服务器业务逻辑修改：
1、子设备可以当做普通设备去操作；
2、协议处理在判断是否有控制权限的时候要增加一个逻辑，如下：
如果根据连接信息查询出来的deviceid==当前请求的deviceid或者等于父设备的deviceid，那么都是合法的；
3、在返回相应给设备端的时候，如果发现是子设备的控制指令（device.params.parentid！
=null）,那么在response里的uid要用父id。
2.5设备上线/离线指令
说明：
服务端检测到设备上线或者下线以后，会向app发送通知指令。
服务端业务逻辑修改：
设备端下线的时候，根据ui判断是不是zigbee等类型的网关设备，如果是，那么不但要把网关的在线状态改成false，同时还要把他下面的子设备的online改成false;
注意，如果子设备分享给别人了，并且被分享人的app在线，那么要发一个子设备下线的消息给app;
2.6分享相关指令
说明：
分享相关的3个指令（分享、修改分享、删除分享）需要增加一个业务分支：
1、这3个指令首先要判断设备ui，如果是zigbee等网关设备，那么就要同时要把子设备一起分享、修改、删除给对方。
比如：
网关deviceid:
1000001
子设备deviceid:
1000002,1000003
A用户把网关设备1000001分享给B用户，那么除了网关的shareUsers下新增了B用户的信息以外，还要在子设备1000002,1000003的shareUsers下新增了B用户的信息。
子设备的权限与网关的权限保持一致；
主人如果需要针对某一个子设备给对方设置不一样的权限，可以在app里选中子设备单独进行修改，就像普通的设备一样操作。
3RestApi接口
总体说明：
本章是在原有接口上，针对zigbee设备做的修改，所以这里只列出有变化的地方，其他都按照原有接口定义来。
3.1设备列表查询接口
说明：
设备端提供http接口，返回device列表数据给app。
URL:
http:
//cn（区域）-api.coolkit.cc/api/user/device
请求方法：
get
请求参数：
与普通设备一样，这里省略
响应参数：
ID
名称
类型
允许NULL
说明
1
error
String
N
返回的异常信息,成功不返回error
Since:
2.1.10
如果version=3,则必须返回0
2
devices
[Object]
N
返回设备信息
Object
ID
名称
类型
允许NULL
说明
1
parentid
String
N
父设备的Id，这里指的是zigbee网关的id
其他参数与原有设计保持不变...
3.2删除设备
说明：
删除设备。
URL:
http:
//cn（区域）-api.coolkit.cc/user/device/:
deviceid
请求方法：
delete
修改说明：
删除接口需要判断设备的ui，如果是zigbee等网关类的设备，那么除了删除记录本身以外，还要删除他下面的子设备；
如果是zigbee子设备，那么除了删除子设备以外，还要去父设备devices.params.subdevices中把这个id删掉。
删除逻辑：
1、删除网关设备
根据网关的devices.params.subdevices数组，取数组对象里面的deviceid，去devices表查找，找到了就删除子设备（还要更新缓存）。
最后删除网关设备；
2、删除子设备：
调用内部的“api转长连接网关”接口，提供子设备的deviceid即可，将网关返回的状态码，响应给app
4Zigbee设备uiid关系表
设备类型
设备类型代码
uiid
1通道
2通道
3通道
4通道
5通道
ZCL_HA_DEVICEID_ON_OFF_SWITCH
0x0000
1000
2000
3000
4000
ZCL_HA_DEVICEID_LEVEL_CONTROL_SWITCH
0x0001
1001
2001
3001
4001
ZCL_HA_DEVICEID_ON_OFF_OUTPUT
0x0002
1002
2002
3002
4002
ZCL_HA_DEVICEID_LEVEL_CONTROLLABLE_OUTPUT
0x0003
1003
2003
3003
4003
ZCL_HA_DEVICEID_SCENE_SELECTOR
0x0004
1004
ZCL_HA_DEVICEID_CONFIGURATION_TOOL
0x0005
1005
ZCL_HA_DEVICEID_REMOTE_CONTROL
0x0006
1006
ZCL_HA_DEVICEID_COMBINED_INTERFACE
0x0007
1007
ZCL_HA_DEVICEID_RANGE_EXTENDER
0x0008
1008
ZCL_HA_DEVICEID_MAINS_POWER_OUTLET
0x0009
1009
2009
3009
4009
ZCL_HA_DEVICEID_DOOR_LOCK
0x000A
1010
ZCL_HA_DEVICEID_DOOR_LOCK_CONTROLLER
0x000B
1011
ZCL_HA_DEVICEID_SIMPLE_SENSOR
0x000C
1012
ZCL_HA_DEVICEID_CONSUMPTION_AWARENESS_DEVICE
0x000D
1013
ZCL_HA_DEVICEID_HOME_GATEWAY
0x0050
1080
ZCL_HA_DEVICEID_SMART_PLUG
0x0051
1081
ZCL_HA_DEVICEID_WHITE_GOODS
0x0052
1082
ZCL_HA_DEVICEID_METER_INTERFACE
0x0053
1083
//Thisisareservedvaluewhichcouldbeusedfortestpurposes
ZCL_HA_DEVICEID_TEST_DEVICE
0x00FF
1255
//LightingDeviceIDs
ZCL_HA_DEVICEID_ON_OFF_LIGHT
0x0100
1256
2256
3256
4256
ZCL_HA_DEVICEID_DIMMABLE_LIGHT
0x0101
1257
2257
3257
4257
ZCL_HA_DEVICEID_COLORED_DIMMABLE_LIGHT
0x0102
1258
ZCL_HA_DEVICEID_ON_OFF_LIGHT_SWITCH
0x0103
1259
2259
3259
4259
ZCL_HA_DEVICEID_DIMMER_SWITCH
0x0104
1260
2260
3260
4260
ZCL_HA_DEVICEID_COLOR_DIMMER_SWITCH
0x0105
1261
ZCL_HA_DEVICEID_LIGHT_SENSOR
0x0106
1262
ZCL_HA_DEVICEID_OCCUPANCY_SENSOR
0x0107
1263
//ClosuresDeviceIDs
ZCL_HA_DEVICEID_SHADE
0x0200
1512
ZCL_HA_DEVICEID_SHADE_CONTROLLER
0x0201
1513
ZCL_HA_DEVICEID_WINDOW_COVERING_DEVICE
0x0202
1514
ZCL_HA_DEVICEID_WINDOW_COVERING_CONTROLLER
0x0203
1515
//HVACDeviceIDs
ZCL_HA_DEVICEID_HEATING_COOLING_UNIT
0x0300
1768
ZCL_HA_DEVICEID_THERMOSTAT
0x0301
1769
ZCL_HA_DEVICEID_TEMPERATURE_SENSOR
0x0302
1770
ZCL_HA_DEVICEID_PUMP
0x0303
1771
ZCL_HA_DEVICEID_PUMP_CONTROLLER
0x0304
1772
ZCL_HA_DEVICEID_PRESSURE_SENSOR
0x0305
1773
ZCL_HA_DEVICEID_FLOW_SENSOR
0x0306
1774
ZCL_HA_DEVICEID_MINI_SPLIT_AC
0x0307
1775
//IntruderAlarmSystems（IAS）DeviceIDs
ZCL_HA_DEVICEID_IAS_CONTROL_INDICATING_EQUIPMENT
0x0400
2024
ZCL_HA_DEVICEID_IAS_ANCILLARY_CONTROL_EQUIPMENT
0x0401
2025
ZCL_HA_DEVICEID_IAS_ZONE
0x0402
2026
3026
4026
5026
6026
ZCL_HA_DEVICEID_IAS_WARNING_DEVICE
0x0403
2027
升级会员 