酷宅IOT平台zigbee补充协议12.docx

1、酷宅IOT平台zigbee补充协议12酷宅IOT平台_zigbee补充协议版本：1.2Changelog:时间修改内容备注2019-06-041、当网关不在线，子设备被别的网关添加以后，网关上报子设备离线，会收到删除子设备的消息；2、补充新的zigbee设备uiid2018-6-21支持握手上报最新子设备列表；支持批量管理设备（注册、删除、上/下线）2018-6-11初稿1 概述1.1 通用说明本协议是在长连接原有协议基础上，新增针对zigbee网关业务的相关指令。zigbee子设备的id格式：mac:port子设备申请到的deviceid：与普通wifi设备id格式一致 服务器业务逻辑修改中

2、（长连接和REST api），凡是涉及到devices和factorydevices表的修改，都要同步到缓存；2 长连接服务接口说明：长连接服务器提供一个公用接口地址，通过接收不同的指令执行不同的业务功能。连接方式：websocket连接接口地址：wss:/domain-name:port/api/ws指令格式：请求与响应都采用标准JSON（RFC 7159）格式2.1 握手指令（zigbee网关注册）说明： 对于网关来说握手跟普通设备一样，只是app端收到网关上线的指令以后，要刷新一下设备列表；请求参数：跟普通设备一样，省略响应参数：跟普通设备一样，省略注意：网关设备上线后，app收到sys

3、msg消息，应该立即刷新一下设备列表，这样可以尽快同步到子设备的在线状态；2.2 批量上报子设备指令说明：网关上线以后，分批上报子设备信息，包括在线状态； 当出现丢包或者系统异常，服务器端也可以通过该指令，要网关重新全部上报或者重新上报指定批次的信息；请求参数：ID名称类型允许NULL说明1actionStringNreportSubDevice2apikeyStringN用户的apikey3deviceidStringN网关的deviceid4userAgentStringN设备端上报填：device服务端下发填：server5d_seqlongY设备端专用：设备端上报6paramsPARA

4、MSN7sequenceStringYserver下发给设备时间戳精确到毫秒设备端上报时：PARAMS定义ID名称类型允许NULL说明1stateIntN是否完成上报操作；0：上报中1：上报完成（最后一批上报的时候，设置成1，表示这是最后一批）1subDevicesSubDeviceY子设备数组SubDevice定义：ID名称类型允许NULL说明1subDevIdStringNzigbee内部id，zigbee子设备的格式为：mac:port2uiidStringY子设备的uiid3deviceidStringY子设备的deviceid，格式跟普通wifi设备一样。上报的时候，如果是新的子设备

5、，可以不传这个字段。返回的命令里，这个字段必填4onlinebooleanY上报子设备的在线状态true: 在线（默认）false:不在线响应参数：ID名称类型允许NULL说明1errorN0 ok(操作成功)400 Bad Request（参数错误）401认证不通过403 Forbidden（无权限）414子设备超过限制500 Internal Server Error（服务器内部错误）2apikeyintN用户的apikey3d_seqlongY设备端上传，服务端原样返回4sequenceStringY时间戳，精确到秒由app下发给设备，设备端原样返回5deviceidStringN网关的

6、deviceid6subDevicesSubDeviceY子设备数组服务端的响应才有这个字段主要用来返回子设备的deviceidSubDevice定义：ID名称类型允许NULL说明1subDevIdStringNzigbee内部id，zigbee子设备的格式为：mac:port2deviceidStringN子设备的deviceid，格式跟普通wifi设备一样。服务端返回分配deviceid给网关服务器业务逻辑：如果是新增加的子设备，参考2.3 子设备管理指令来处理；如果上报完成，服务器要模拟一个网关上线的指令给app，让app再次刷新设备列表；注意：如果某个子设备，设置为下线的时候，发现de

7、viceid被别的账号添加了，那么就要给网关下发一个删除子设备的指令；（因为有可能是子设备被别的网关添加了）2.3 子设备管理指令说明：zigbee网关通过该指令，可以批量注册、删除子设备，还可以批量上报子设备在线状态。服务器端可以通过该指令下发给网关，通知网关某个子设备被删除了（被添加到其他网关）请求参数：ID名称类型允许NULL说明1actionStringNsubDevice2apikeyStringN用户的apikey3deviceidStringN网关的deviceid4userAgentStringNApp调用填：app设备端上报填：device服务端下发填：server5d_se

8、qlongY设备端专用：设备端上报6paramsPARAMSN7sequenceStringapp下发给设备时间戳精确到毫秒 PARAMS定义ID名称类型允许NULL说明1cmdsCMDN操作类型:0 注册新子设备1 删除子设备2 子设备上线3 子设备下线CMD定义ID名称类型允许NULL说明1typeIntN操作类型:0 注册新子设备1 删除子设备2 子设备上线3 子设备下线2subDevIdStringN子设备idzigbee格式：mac:port3uiidStringY子设备的uiid，由网关上报;4deviceidStringY删除子设备，上报上、下线状态都要传子设备的deviceid

9、响应参数：ID名称类型允许NULL说明1errorsErrorN针对批量的每一个命令都有一个操作结果，按照请求中的cmd顺序一一对应2apikeyintN用户的apikey3d_seqlongY设备端上传，服务端原样返回4sequenceStringY时间戳，精确到秒由app下发给设备，设备端原样返回5deviceidStringN网关的deviceidError说明：ID名称类型允许NULL说明1errorIntN0 ok(操作成功)400 Bad Request（参数错误）401认证不通过403 Forbidden（无权限）414 子设备超过限制500 Internal Server Er

10、ror（服务器内部错误）2deviceidStringY这个是子设备的deviceid服务器业务逻辑：所有请求，都要检查请求参数是否合法、有效、设备是否存在等；下面根据操作类型分别说明：0 注册新子设备a. 用请求里的deviceid去devices.params.parentid统计当前已经添加了多少个子设备，如果超过500个就返回 414；b. 根据subDevId去FactoryDevices表查询partnerDevice.ezVedioSerial字段，看是否已经存在记录；如果已经有记录，就可以重用deviceid，否则生成新的deviceid并插入到factorydevices表；

11、c. 根据factorydevices的deviceid，新增一条记录到Devices表（参考rest api的添加设备接口逻辑）d. 在Devices表除了要记录普通设备相同的数据以外，还要增加这两个字段params.parentid （父id，也就是zigbee网关的deviceid）params.subDevId (zigbee子设备本身的id，格式为mac:port)e. 根据subDevId查找网关设备的params.subDevices中是否有这个子设备，有就更新deviceid字段，否则新增数组对象；f. 返回操作成功的响应g. 转发请求给app，让app及时更新界面;1 删除子

12、设备 如果是app上报的删除操作，需要判断网关是否在线，网关不在线不能删除；a. 用请求里的params.deviceid到Devices表删除记录即可，FactoryDevices的记录保留；b. 查找网关设备的params.subDevices中是否有这个子设备，有也要删除并更新到数据库；c. 返回操作成功的代码；d. 如果是服务端发起的删除操作，检查app是否在线，如果在线，把消息转发给app，便于app刷新界面； 2/3子设备上、下线a. 修改devices表的online状态；b. 检查app是否在线，如果在线，参考普通设备的上、下线消息格式，返送给app;c. 还要检查该子设备是否

13、分享给别人，分享的app如果在线也要发送消息（跟普通设备一样）d. 如果设置为下线的时候，发现deviceid被别的账号添加了，那么就要给网关下发一个删除子设备的指令；（因为有可能是子设备被别的网关添加了） 2.4 更新/上报状态指令说明：设备端状态发生变化、设备端上报历史数据、APP修改设备状态，应该发送该指令到服务器。注意：对于服务器来说子设备相当于一个普通设备，如果是网关发送的update指令，deviceid要填写子设备的deviceid请求参数：（只列出这次有变化的地方）ID名称类型允许NULL说明xdeviceidStringN注意：控制子设备的时候，这里填的是子设备的device

14、id 新增app发下指令给网关，让网关进入/退出添加子设备模式的方法，如下：params:addSubDevState:on/off on:表示让网关进入添加子设备模式off:表示让网关退出添加子设备模式 响应参数：与原来的保持一致服务器业务逻辑修改：1、子设备可以当做普通设备去操作；2、协议处理在判断是否有控制权限的时候要增加一个逻辑，如下：如果根据连接信息查询出来的deviceid=当前请求的deviceid或者等于父设备的deviceid，那么都是合法的；3、在返回相应给设备端的时候，如果发现是子设备的控制指令（device.params.parentid！=null）,那么在respo

15、nse里的uid要用父id。2.5 设备上线/离线指令说明：服务端检测到设备上线或者下线以后，会向app发送通知指令。服务端业务逻辑修改：设备端下线的时候，根据ui判断是不是zigbee等类型的网关设备，如果是，那么不但要把网关的在线状态改成false，同时还要把他下面的子设备的online改成false;注意，如果子设备分享给别人了，并且被分享人的app在线，那么要发一个子设备下线的消息给app;2.6 分享相关指令说明：分享相关的3个指令（分享、修改分享、删除分享）需要增加一个业务分支：1、这3个指令首先要判断设备ui，如果是zigbee等网关设备，那么就要同时要把子设备一起分享、修改、删

16、除给对方。比如：网关deviceid: 1000001子设备deviceid: 1000002, 1000003A用户把网关设备1000001分享给B用户， 那么除了网关的shareUsers下新增了B用户的信息以外，还要在子设备1000002, 1000003的shareUsers下新增了B用户的信息。子设备的权限与网关的权限保持一致；主人如果需要针对某一个子设备给对方设置不一样的权限，可以在app里选中子设备单独进行修改，就像普通的设备一样操作。3 Rest Api接口总体说明：本章是在原有接口上，针对zigbee设备做的修改，所以这里只列出有变化的地方，其他都按照原有接口定义来。3.1

17、设备列表查询接口说明：设备端提供http接口，返回device列表数据给app。URL: http:/cn(区域)-api.coolkit.cc/api/user/device请求方法： get请求参数：与普通设备一样，这里省略响应参数：ID名称类型允许NULL说明1errorStringN返回的异常信息,成功不返回errorSince:2.1.10如果version=3,则必须返回02devicesObjectN返回设备信息ObjectID名称类型允许NULL说明1parentidStringN父设备的Id，这里指的是zigbee网关的id其他参数与原有设计保持不变.3.2 删除设备说明：删

18、除设备。URL: http:/cn(区域)-api.coolkit.cc/user/device/:deviceid请求方法： delete修改说明：删除接口需要判断设备的ui，如果是zigbee等网关类的设备，那么除了删除记录本身以外，还要删除他下面的子设备；如果是zigbee子设备，那么除了删除子设备以外，还要去父设备devices.params.subdevices中把这个id删掉。删除逻辑：1、删除网关设备根据网关的devices.params.subdevices数组，取数组对象里面的deviceid，去devices表查找，找到了就删除子设备（还要更新缓存）。最后删除网关设备；2、

19、删除子设备：调用内部的“api转长连接网关”接口，提供子设备的deviceid即可，将网关返回的状态码，响应给app4 Zigbee设备uiid关系表设备类型设备类型代码uiid1通道2通道3通道4通道5通道ZCL_HA_DEVICEID_ON_OFF_SWITCH 0x00001000200030004000ZCL_HA_DEVICEID_LEVEL_CONTROL_SWITCH 0x00011001200130014001ZCL_HA_DEVICEID_ON_OFF_OUTPUT0x00021002200230024002ZCL_HA_DEVICEID_LEVEL_CONTROLLABLE

20、_OUTPUT 0x00031003200330034003ZCL_HA_DEVICEID_SCENE_SELECTOR 0x00041004ZCL_HA_DEVICEID_CONFIGURATION_TOOL 0x00051005ZCL_HA_DEVICEID_REMOTE_CONTROL 0x00061006ZCL_HA_DEVICEID_COMBINED_INTERFACE 0x00071007ZCL_HA_DEVICEID_RANGE_EXTENDER0x00081008ZCL_HA_DEVICEID_MAINS_POWER_OUTLET0x00091009200930094009ZC

21、L_HA_DEVICEID_DOOR_LOCK0x000A1010ZCL_HA_DEVICEID_DOOR_LOCK_CONTROLLER0x000B1011ZCL_HA_DEVICEID_SIMPLE_SENSOR 0x000C1012ZCL_HA_DEVICEID_CONSUMPTION_AWARENESS_DEVICE 0x000D1013ZCL_HA_DEVICEID_HOME_GATEWAY 0x00501080ZCL_HA_DEVICEID_SMART_PLUG0x00511081ZCL_HA_DEVICEID_WHITE_GOODS 0x00521082ZCL_HA_DEVICE

22、ID_METER_INTERFACE 0x00531083 / This is a reserved value which could be used for test purposesZCL_HA_DEVICEID_TEST_DEVICE 0x00FF1255 / Lighting Device IDs ZCL_HA_DEVICEID_ON_OFF_LIGHT0x01001256225632564256ZCL_HA_DEVICEID_DIMMABLE_LIGHT0x01011257225732574257ZCL_HA_DEVICEID_COLORED_DIMMABLE_LIGHT0x010

23、21258ZCL_HA_DEVICEID_ON_OFF_LIGHT_SWITCH0x01031259225932594259ZCL_HA_DEVICEID_DIMMER_SWITCH0x01041260226032604260ZCL_HA_DEVICEID_COLOR_DIMMER_SWITCH 0x01051261ZCL_HA_DEVICEID_LIGHT_SENSOR 0x01061262ZCL_HA_DEVICEID_OCCUPANCY_SENSOR 0x01071263 / Closures Device IDs ZCL_HA_DEVICEID_SHADE 0x02001512ZCL_

24、HA_DEVICEID_SHADE_CONTROLLER 0x02011513ZCL_HA_DEVICEID_WINDOW_COVERING_DEVICE 0x02021514ZCL_HA_DEVICEID_WINDOW_COVERING_CONTROLLER 0x02031515 / HVAC Device IDs ZCL_HA_DEVICEID_HEATING_COOLING_UNIT 0x03001768ZCL_HA_DEVICEID_THERMOSTAT 0x03011769ZCL_HA_DEVICEID_TEMPERATURE_SENSOR 0x03021770ZCL_HA_DEVI

25、CEID_PUMP 0x03031771ZCL_HA_DEVICEID_PUMP_CONTROLLER 0x03041772ZCL_HA_DEVICEID_PRESSURE_SENSOR 0x03051773ZCL_HA_DEVICEID_FLOW_SENSOR 0x03061774ZCL_HA_DEVICEID_MINI_SPLIT_AC 0x03071775 / Intruder Alarm Systems (IAS) Device IDs ZCL_HA_DEVICEID_IAS_CONTROL_INDICATING_EQUIPMENT 0x04002024ZCL_HA_DEVICEID_IAS_ANCILLARY_CONTROL_EQUIPMENT 0x04012025ZCL_HA_DEVICEID_IAS_ZONE 0x040220263026402650266026ZCL_HA_DEVICEID_IAS_WARNING_DEVICE 0x04032027