Skip to content

通信协议

Jump to bottom
ZipZhang edited this page Apr 23, 2021 · 6 revisions

此文档对应zDC1固件v1.0.0及以上版本. 此文档还在更新中

通信格式

MQTT主题

使用MQTT服务器时,

zDC1接收数据监听的topic为device/zdc1/MAC/set,

zDC1发送出的数据的topic为device/zdc1/MAC/state

zDC1定时反馈功率等信息topic为device/zdc1/MAC/sensor

(MAC为小写mac地址字符串,如1234567890ab)

使用UDP时,zDC1接收数据监听的端口为10182,发送数据的端口为10181,发送的目标IP为255.255.255.255,即局域网内全网广播.

通信通过Json格式进行通信,无论是否使用MQTT服务器,通信协议内容相同.

如:

{
    "name":"zDC1_90ab",
    "mac":"1234567890ab"
}

当手机app/其他服务器(后面简称为app)通过MQTT或UDP给zDC1设备(后面简称为zDC1或设备)后,zDC1会返回相似的命令.

控制

{
	"name":"zDC1_90ab",			//当前设备名称,设备依靠此判断此条命令是否应该执行后面的命令
	"mac":"1234567890ab",		//当前设备mac地址,设备依靠此判断此条命令是否应该执行后面的命令
	"ssid":"当前连接ssid",		  //查询当前连接的wifi名称
	"version":"版本信息",		 //当前固件版本
	"setting":
	{
		"name":"zDC1",			//设置zDC1的新名称,最长32个字节
		"wifi_ssid":"你的wifi ssid",	//设置连接的wifi ssid
		"wifi_password":"wifi 密码",	//设置连接的wifi 密码
		"mqtt_uri":"www.mqtt.com",	//设置mqtt服务器
		"mqtt_port":1883,		//设置mqtt服务器端口
		"mqtt_user":"z",		//设置mqtt服务器登录用户名
		"mqtt_password":"123456"	//设置mqtt服务器登录密码
	},
	"plug_0":				//0-3表示分别表示总开关,1-3插口, 后面的0-3省略
	{
    	"name":"插口1",				//当前插口当前名称
    	"on":1,					//当前插口开关
    	"setting":
    	{
            "name":"新名称",		 	//设置当前插口名称
            "task_0":				//设置当前插口定时任务,总共0-4 5组,1-4省略 
            {					//注意 设置task时,task中所有字段都必须存在而且数据有效
            	"hour":12			//设置定时任务时间为12:59
                "minute":59			//同上
                "repeat":10			//重复,bit0-bit6分别表示周一-周日,全部为0时表示一次
                "action":1			//动作,0表示关闭插口 1表示开启插口
                "on":1				//当前任务是否有效 0表示无效,1表示有效
            }
    	}
	}
	
}
  • 以上命令中,"mac"字段为必须有,当有多个zDC1设备时,设备会依靠此字段来判断此条命令是否应该由自己执行.
  • mac字段为最根本的识别符,所以无论app发送给设备还是设备发送给app,mac字段都不能省略且不能为null或其他无意义的内容.
  • 如果仅仅为了查询某个字段的结果可以将字段冒号后的参数写为null(不带引号,在json中表示空),此时设备不会做任何修改,只会返回当前值
  • 请注意以上字段冒号后面携带的参数,有些如1,无引号,表示类型为数字,有些为"名称"表示类型字符.如果类型与要求不同,则与参数写为null效果相同,即为查询.
  • 当执行命令和其他功能无关时,其他功能的字段可以省略.
  • 设备返回app命令的字符串长度不能超过1023,所以如果发现返回的命令长度可能超过1023,请将命令拆解为多条分别发送.否则可能会引起设备重启的问题.
  • 定时任务重复值说明:bit0-bit6分别表示周一-周日,
    • 当全部为0时,即值为0,表示仅一次有效,定时任务执行后,任务会自动变为无效
    • 当全部为1时,即值为127(二进制1111111->十进制127),表每天都有效
    • 当其他情况时,bit0-bit6中哪一位为1,表示每周当天定时任务有效,如值为41时(十进制41->二进制0101001),则bit0 3 5为1,则每周一周四周六定时任务有效.

功率反馈

zDC1定时反馈功率电压电流等信息,每秒返回一次.

mqtt 的 topic为device/zdc1/MAC/sensor

{
	"mac":"1234567890ab",	 //唯一标识符
	"power":"4.2",			 //当前功率,单位W
	"voltage":"220"，		//当前电压,单位V
	"current":"0.14"		 //当前电流,单位A
}

设备配对

{"cmd":"device report"},此命令为当app设备列表中无此设备时,发送此命令,设备会返回名称,设备类型编号,mac地址及设备类型名称,

如

{
    "name":"zDC1_1234",		//当前设备名称
    "type":2,			//设备类型编号,2表示zDC1排插
    "type_name":"zDC1",		//设备类型名称
	"mac":"1234567890ab"	//当前设备的mac地址
}

app接收到此命令后,会将此设备加入到列表中.

ota在线升级

v0.2版本开始,支持ota在线升级.

查询当前版本:

{
"mac" : "1234567890ab",
"version":null
}

zDC1返回数据:

{
    "mac" : "1234567890ab",
    "version":"v0.2"
}

v0.2即为当前版本,app可与服务器判断当前最新版本.若当前版本与最新版本不同,则可以发送一下ota升级命令进行升级.

ota升级:

{
	"mac" : "1234567890ab",
    "setting":
    {
    	"ota1":"http://www.uri.com/user1.1024.new.2.bin",
    	"ota2":"http://www.uri.com/user2.1024.new.2.bin"
    }
}

dc1主控ota原理为2个固件交替使用(当前为固件1升级后自动切换为固件2,当前为固件2,升级后自动切换为固件1).所以当不确定当前固件为哪个固件时,必须保证ota1 ota2字段都存在且固件下载地址正确!

其中, "http://www.uri.com/user1.1024.new.2.bin" 或 "http://www.uri.com/user2.1024.new.2.bin" 为固件下载地址.需要保证用浏览器打开此链接,可以直接下载bin文件即可,且端口必须为80端口.

注意:

链接中不可含有@符号.

链接不可为重定向地址

zDC1返回数据:

{
	"mac" : "1234567890ab",
    "setting":
    {
    	"ota1":"http://www.uri.com/user1.1024.new.2.bin",
    	"ota2":"http://www.uri.com/user2.1024.new.2.bin"
    }
}

升级完成后,zDC1通过UDP返回数据,并自动重启:

{
	"mac":"1234567890ab",
	"ota_progress":100
}

举例

app发给设备或设备返回的数据中,字段的顺序没有影响.

控制mac地址为"1234567890ab"的zDC1设备打开总开关和插口2,关闭插口1.

app发送zDC1命令(注意总开关、插口1-3编号为plug_0-3):

{
	"mac":"1234567890ab",
	"plug_0":
	{
		"on":1
	},
	"plug_1":
	{
		"on":0
	}
	"plug_2":
	{
		"on":1
	}
}

zDC1返回数据:

{
	"mac":"1234567890ab",
	"plug_0":
	{
		"on":1
	},
	"plug_1":
	{
		"on":0
	}
	"plug_2":
	{
		"on":1
	}
}
设置mac地址为"1234567890ab"的zDC1设备名称为"zdc1"

app发送

{
	"mac":"1234567890ab",
	"setting":
	{
		"name":"zdc1"
	}
}

zDC1返回:

{
	"mac":"1234567890ab",
	"name":"zdc1",
	"setting":
	{
		"name":"zdc1"
	}
}
查询mac地址为"1234567890ab"的zDC1设备的mqtt服务器

app发送:

{
	"mac":"1234567890ab",
	"setting":
	{
		"mqtt_uri":null
	}
}

zDC1返回:

{
	"mac":"1234567890ab",
	"name":"zdc1",
	"setting":
	{
		"mqtt_uri":"www.mqtt.com"
	}
}

homeassistant 相关协议

homeassistant同样为读取以上json格式数据来同步/控制状态.

Clone this wiki locally