小米网关

网关局域网通讯命令一、设备发现与查询.....................2

1.网关设备发现（设备发现不加密）........................................2

2.加密机制..............................................................2

3.查询子设备id列表.....................................................2

4.子设备状态上报........................................................2

二、对设备进行读写操作.......................................................3

1.读设备...............................................................3

2.写设备...............................................................3

三、设备心跳................................................................4

1.网关心跳..............................................................4

2.子设备心跳.............................................................4

四、设备上报和控制报文格式...................................................4

五、传感器上报属性和心跳.....................................................5

a.窗磁传感器............................................................5

b.人体传感器.............................................................5

c.无线开关传感器.........................................................5

d.智能插座..............................................................6

单火开关单键.............................................................6

单火开关双键.............................................................7

无线开关单键.............................................................7

无线开关双键.............................................................7

i.温湿度传感器：.........................................................8

........................................................................8

一、设备发现与查询

1.网关设备发现（设备发现不加密）

设备发现用来在局域网中发现网关，使用组播(ip:,peer_port:4321)。

所有网关收到Whois命令都要应答、回复自己的IP信息。

PC组播方式->网关:{"cmd":"whois"}

网关单播方式->PC：

{"cmd":"iam","ip":"","port":"9898","model":"gateway",.....}

2.加密机制

采用key加密方式，默认不加密。如果用户想限制其他人对网关及其子设备的控制权限，

可以在小米智能家庭APP上对网关设置密钥（使用AES-CBC128加密，app下发随机的16

个字节长度的字符串密钥）。若没有设置密钥（即app里设置密钥为空字符串””）则其

他人均有权限可以控制网关及其子设备。

注：AES-CBC128初始向量定义为：

unsignedcharconstAES_KEY_IV[16]={0x17,0x99,0x6d,0x09,0x3d,0x28,0xdd,

0xb3,0xba,0x69,0x5a,0x2e,0x6f,0x58,0x56,0x2e};

3.查询子设备id列表

命令以单播方式发送给网关的udp9898端口，网关以单播方式回复，用来获取网关中有

哪些设备（网关返回子设备的设备id）。

PC->网关：{"cmd":"get_id_list"}

网关->PC:{"cmd":

"get_id_list_ack","sid":"1022780","token":"90abcdef","data":"["sid1","sid2

","sid3"]"}，其中的“sid”为网关did，“token”为网关生成的随机字符串，用于用

户生成写设备时的“key”。

4.子设备状态上报

以组播方式发送给(ip:,port:9898)。当子设备状态发生变化时，子设备会上报状

态。例如窗磁上报open/clo信息。用户可以拿这个状态去做联动。例如：开窗报警，开

窗关空调

网关->PC：

{"cmd":"report","model":"magnet","sid":"","short_id":4343,"data":"{"status

":"open"}"}

二、对设备进行读写操作

1.读设备

命令以单播方式发送给网关的udp9898端口。用户可以主动读取墙壁开关，插座的属

性状态，网关返回设备的全部属性信息。

{"cmd":"read","sid":"158d"}

网关以单播方式回复格式：

{"cmd":"read_ack","model":"ctrl_neutral2","sid":"158d","short_id"

:4343,"data":"{"channel_0":"on","channel_1":"off"}"}

2.写设备

命令以单播方式发送给网关的udp9898端口。当用户需要控制墙壁开关，插座等设备

时使用write命令。

{"cmd":"write","model":"ctrl_neutral1","sid":"158d","short_id":43

43,"data":"{"channel_0":"on","key":"3EB43E37C20AFF4C5872CC0D04D81314"}"}

网关以单播方式回复格式：

{"cmd":"write_ack","model":"ctrl_neutral2","sid":"158d","short_id

":4343,"data":"{"channel_0":"on","channel_1":"off"}"},该write_ack只是

代表网关收到了write命令，data里的属性状态为当前的设备最新状态，不是write之后

的最终设备状态。最终的设备状态靠report报文进行上报。

注：

其中的“key”为32个字节长度的字符串。当网关启用了加密模式时，会对该key进行

解密并校验，以验证写命令的合法性。该“key”的生成规则是：用户收到“heartbeat”里

的16个字节的“token”字符串之后，对该字符串进行AES-CBC128加密，生成16个字节

的密文后，再转换为32个字节的ASCII码字符串。

比如：用户配置16个字符长度的密钥为“01qwerty“,”token”为”90abcdef”,加

密后密文是：

0x3E,0xB4,0x3E,0x37,0xC2,0x0A,0xFF,0x4C,0x58,0x72,0xCC,0x0D,0x04,0xD8,0x13,0x14

。那么，”key”为：”3EB43E37C20AFF4C5872CC0D04D81314”。

三、设备心跳

1.网关心跳

网关心跳以组播方式发送给(ip:,port:9898)。网关每10秒钟发送一次心跳报文，

用来告诉PC网关正常工作。

{"cmd":"heartbeat","model":"gateway","sid":"1022780","short_id":0,"token":"90ab

cdef","data":"{"ip":""}"},其中的“token”为网关生成的随机字符串，用于用户生

成写设备时的“key”。

2.子设备心跳

子设备心跳以组播方式发送给(ip:,port:9898)，格式：

{"cmd":"heartbeat","model":"magnet","sid":"158d000065a271","short_id":25719

,"data":"{"status":"open"}"}。

子设备通过心跳告诉PC：子设备正常工作（心跳上报频率，一般睡眠设备是一个

钟头一次，插电设备是每10分钟一次）。子设备心跳中可能包含子设备的状态。注意这个

状态值得处理要看具体的使用场景。

例如：开窗关空调场景时

可以使用这个心跳（有可能正常的report状态报文丢失，心跳报文可以补救）。

例如：关窗开空调场景

这个就不能使用心跳。有可能人走了，走时把空调关了。

心跳报文又让空调打开会浪费电。

总之,心跳报文的使用根据场景需要用户自己决定是否用心跳做触发。

添加子设备，删除子设备，修改子设备的名字等操作目前不提供，如果开发者需要可以提供。

四、设备上报和控制报文格式

Json报文格式：

{

"cmd":"write",

体传感器

人体传感器探测到人会立即上报一次report信息。在一直有人的情况下为了省电人体传感

器最快一分钟发送一次report。

属性说明

battery0-100电池电量

statusmotion探测到有人

属性上报：

{"cmd":"report","model":"motion","sid":"112316","short_id":4343,"token":"4","da

ta":"{"status":"motion"}"}

心跳上报(~60分钟每次):

{"cmd":"report","model":"motion","sid":"112316","short_id":4343,"token":"4","da

ta":"{"battery":"71"}"}

c.无线开关传感器

无线开关传感器每按键一次上报一个报文。400ms内按两次上报的报文是双击

属性说明

statusclick/double_click(单击/双击)

battery0-100电池电量

属性上报：

{"cmd":"report","model":"switch","sid":"112316","short_id":4343,"token":"5","da

ta":"{"status":"click"}"}

{"cmd":"report","model":"switch","sid":"112316","short_id":4343,"token":"6","da

ta":"{"status":"double_click"}"}

心跳上报(~60分钟每次):

{"cmd":"report","model":"motion","sid":"112316","short_id":4343,"token":"4","da

ta":"{"battery":"65"}"}

d.智能插座

属性说明

statuson/off(开/关)

load_voltage负载电压，单位是毫伏mV

load_power负载功率，单位是瓦W

power_consumed负载消耗电量,单位是千瓦时kWh

属性上报：

{"cmd":"report","model":"plug","sid":"112316","short_id":4343,"token":"7","data

":"{"status":"on"}"}

心跳上报(~10分钟每次)：

{"cmd":"heartbeat","model":"plug","sid":"112316","short_id":4343,"token":"7","d

ata":"{"load_voltage":"234300"}","load_power":"","power_consumed

":""}"}

{"cmd":"write","model":"plug","sid":"112316","short_id":4343,"token":"8","data"

:"{"status":"on"}"}

单火开关单键

属性说明

channel_0on/off(开/关)

属性上报：

{"cmd":"report","model":"

ctrl_neutral1","sid":"112316","short_id":4343,"token":"7","data":"{"

channel_0":"on"}"}

{"cmd":"report","model":"

ctrl_neutral1","sid":"112316","short_id":4343,"token":"7","data":"{"

channel_0":"click"}"}

单火开关单键控制(写命令):

{"cmd":"write","model":"

ctrl_neutral1","sid":"112316","short_id":4343,"token":"8","data":"{"

channel_0":"on"}"}

{"cmd":"write","model":"

ctrl_neutral1","sid":"112316","short_id":4343,"token":"8","data":"{"

channel_0":"off"}"}

单火开关双键

属性说明

channel_0on/off(开/关)

channel_1on/off(开/关)

属性上报：

{"cmd":"report","model":"

ctrl_neutral2","sid":"112316","short_id":4343,"token":"7","data":"{"

channel_0":"on"}"}

{"cmd":"report","model":"ctrl_neutral2","sid":"112316","short_id":4343,"token":

"7","data":"{"channel_1":"on"}"}

单火开关双键控制(写命令):

{"cmd":"write","model":"

ctrl_neutral2","sid":"112316","short_id":4343,"token":"8","data":"{"channel_0

":"on"}"}

{"cmd":"write","model":"

ctrl_neutral2","sid":"112316","short_id":4343,"token":"8","data":"{"channel_1

":"off"}"}

无线开关单键

属性说明

channel_0click/double_click单击/双击

属性上报：

{"cmd":"report","model":"86sw1","sid":"112316","short_id":4343,"token":"7","dat

a":"{"channel_0":"click"}"}

无线开关双键

属性说明

channel_0click左键单击

double_click左键双击

channel_1click右键单击

double_click右键双击

dual_channelboth_click左右键同时按

属性上报：

{"cmd":"report","model":"86sw2","sid":"112316","short_id":4343,"token":"7","dat

a":"{"channel_0":"click"}"}

i.温湿度传感器：

温湿度传感器如果温度变化达到度或者湿度变化达到6%上报一个报文。

属性说明

temperature温度

humidity湿度

属性上报：

{"cmd":"report","model":"nsor_ht","sid":"112316","short_id":4343,"token":"5",

"data":"{"temperature":”2333”}"}

{"cmd":"report","model":"nsor_ht","sid":"112316","short_id":4343,"token":"6",

"data":"{"humidity":”6678”}"}

以上例子对应的温度为,湿度为%

属性说明

statuson/off(开/关)

level亮度

color_temperatureColorTemperatureMired

xCurrentX

yCurrentY

saturationCurrentSaturation

hueCurrentHue

状态部分

开关状态上报：

{"cmd":"report","model":"rgbw_light","sid":"

158d0000f2ac34","short_id":"8390","token":"7","data":"{"status":"on"}"}

亮度上报：

{"cmd":"report","model":"rgbw_light","sid":"

158d0000f2ac34","short_id":"8390","token":"7","data":"{"level":"126"}"}

颜色上报

{"cmd":"report","model":"rgbw_light","sid":"158d0000f2ac34","short_id":"26033",

"token":"2","data":"{"hue":"170","saturation":"254",

"color_temperature":"65279","x":"10","y":"10"}"}