酷宅IOT平台zigbee补充协议12.docx
- 文档编号:11652701
- 上传时间:2023-03-29
- 格式:DOCX
- 页数:22
- 大小:22.11KB
酷宅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
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 酷宅 IOT 平台 zigbee 补充协议 12
![提示](https://static.bdocx.com/images/bang_tan.gif)