BA 楼宇自控系统接入

更新时间：2024-06-20 02:26:00下载pdf

本文介绍了涂鸦智慧行业 BA 楼宇自控系统接入方案。

概述

涂鸦为 BA 楼宇自控系统提供了边缘⽹关接⼊的⽅案，能够帮助 BA 品牌方快速接⼊涂鸦开发者平台，方案架构如下图：
BA 楼宇自控系统接入

对接协议

三⽅ BA ⽹关⽤ MQTT 协议与涂鸦边缘⽹关进⾏通信，其中三⽅ BA ⽹关做客户端，涂鸦边缘⽹关做 broker。

开发指南

在使用此文档进行对接时，需要开发者注册涂鸦开发者账号，并且创建产品以及产品功能点，请参考创建产品。

如下为 BA 楼宇自控系统的各子系统具体设备属性信息，设备属性上报时作为参考：

BA变配电能耗系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	上报A相电压_电流_功率	phase_a	只上报（ro）	raw	/
2	上报B相电压_电流_功率	phase_b	只上报（ro）	raw	/
3	上报C相电压_电流_功率	phase_c	只上报（ro）	raw	/
4	A相温度	phase_a_temp	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
5	B相温度	phase_b_temp	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
6	C相温度	phase_c_temp	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
7	零线电流	cur_neutral	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
8	Uab线电压	uab_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
9	Ubc线电压	ubc_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
10	Uca线电压	uca_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
11	视在功率	power_apparent	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kV
12	功率因数	power_factor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
13	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
15	分合闸状态	on_off_state	可下发可上报（rw）	enum	枚举值: 开合中/closed_opened, 关闭中/closing
16	开关	switch	可下发可上报（rw）	bool	0,1
17	当前功率	power_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: W
18	当前电压	voltage_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
19	最大电流	current_max	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
20	当前电流	cur_current	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
21	当前温度	temp_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
22	欠压值	voltage_under	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
23	过压值	voltage_over	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
24	漏电预警值	leakage_warn_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mA
25	漏电故障值	leakage_fault_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mA
26	漏电电流	leakage_current	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mA
27	泄露保护	leakage_protection	只上报（ro）	enum	枚举值: 没漏保不显示漏电值/no_leak_pro_without_value, 没漏保显示漏电值/no_leak_pro_with_value, 有漏保显示漏电值/leak_pro_with_value
28	使能开关	switch_enabled	可下发可上报（rw）	bool	0,1
29	过流持续时间	over_current_duration	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: s
31	设备告警	device_alarm	只上报（ro）	string	/
39	漏电动作值	leakage_action_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
40	过温值	over_temp_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位:℃
41	过欠压动作保护时间	over_vol_protect_time	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: min
42	过欠压保护恢复时间	over_vol_recovery_time	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: min
43	日用电量数据	daily_energy	可下发可上报（rw）	raw	/
44	开关次数	switch_times	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
45	短路次数	short_times	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
46	总电量	electric_total	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW·h
47	日用电量	electric_daily	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW·h
48	月用电量	electric_month	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW·h
49	剩余电量	residual_electricity	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
50	限定功率	power_limit	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: W
51	电量预警值	electric_warm_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
52	正向总有功电量	forward_energy_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
53	无功电量	energy_reactive	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
58	开关状态	switch_state	可下发可上报（rw）	bool	0,1
59	有功电量	active_energy_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
60	高低压母联状态	bus_coupler_state	只上报（ro）	raw	/
61	高低压进线状态	incoming_line_state	只上报（ro）	raw	/
62	有功功率	power_effective	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
63	无功功率	power_reactive	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
64	频率	supply_frequency	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
65	在线状态	state	可下发可上报（rw）	enum	枚举值: 在线/online, 掉线/offline
66	电压	battery_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
67	管网压力	pressure_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: Mpa
68	运行状态	status	可下发可上报（rw）	enum	枚举值: 运行/run, 停止/stop
69	月用电量数据	month_energy	只上报（ro）	raw	/
70	油位高度	oil_level	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m
71	模式	mode	可下发可上报（rw）	enum	枚举值: 手动/manual, 自动/auto, 关闭/close
72	喷淋状态	spray_state	只上报（ro）	enum	枚举值: 开启中/opening, 关闭中/closing
73	消防开关状态	fire_switch_state	只上报（ro）	enum	枚举值: 开启中/opening, 关闭中/closing
74	电流不平衡度	cur_unbalance	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
75	线电压不平衡度	l_vol_unbalance	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
76	相电压不平衡度	p_vol_unbalance	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
77	漏电状态	leakage_state	只上报（ro）	enum	枚举值: 正常/normal, 告警/alarm
78	剩余电流	cur_residual	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
79	N相温度	phase_n_temp	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃

BA冷热源系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	状态	status	可下发可上报（rw）	enum	枚举值: 运行/run, 停止/stop
2	模式	mode	可下发可上报（rw）	enum	枚举值: 自动/auto, 手动/manual
3	总运行时间	runtime_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: min
4	压力值	pressure_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: Mpa
5	水温	water_temp	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
6	水流量	water_flow	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
7	室外温度	temp_outdoor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
8	室外湿度	humidity_outdoor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位:
9	水流状态	flow_state	只上报（ro）	enum	枚举值: 运行/run, 停止/stop
10	阀门状态	valve_state	可下发可上报（rw）	enum	枚举值: 全开/fully_open, 非全开/partially_open
11	故障告警	fault	可下发可上报（rw）	bitmap	故障值: 高温报警/high_temp, 低温报警/low_temp, 缺水/lack_water
12	水阀反馈	water_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
13	阀门检测	valve_check	可下发可上报（rw）	bool	0,1
14	旁通阀	bypass_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
15	水阀	water_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
16	电动蝶阀开关	butterfly_valve_switch	可下发可上报（rw）	bool	0,1
17	压差	pressure_dif	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
18	跳闸状态	trip_state	只上报（ro）	enum	枚举值: 正常/normal, 设备报警/device_alarm
19	瞬时流量	flow_rate_instant_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
20	总流量	flowrate_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
21	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
22	流体速度	flow_velocity	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3

BA消防系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
2	Li1状态	li_state_1	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
3	Li2状态	li_state_2	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
4	Li3状态	li_state_3	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
5	Li4状态	li_state_4	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
6	Li5状态	li_state_5	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
7	Li6状态	li_state_6	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
8	Li7状态	li_state_7	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
9	Li8状态	li_state_8	可下发可上报（rw）	enum	枚举值: 开启中/opening, 关闭中/closing
10	室内温度	temp_indoor	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
11	传感器探头	sensor_probe	只上报（ro）	enum	枚举值: 正常/normal, 设备报警/device_alarm
12	室内湿度	humidity_indoor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
13	液位深度	liquid_depth	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m
14	电池电压	battery_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
15	水浸检测状态	watersensor_state	只上报（ro）	enum	枚举值: 告警/alarm, 正常/normal
16	压力值	pressure_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: Mpa
17	供水温度	inlet_temp_1	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
18	门磁开关状态	doorcontact_state	可下发可上报（rw）	bool	0,1
19	光照度	illuminance_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
20	故障告警	fault	只上报（ro）	bitmap	枚举值：高液位报警/water_high, 故障/fault

BA空调系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	开关状态	switch_state	可下发可上报（rw）	bool	0,1
2	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
3	当前电流	cur_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
4	当前温度	temp_current	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
5	目标温度	target_temp	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
6	风速档位	fan_level	可下发可上报（rw）	enum	枚举值: 1档/level_1, 2档/level_2, 3档/level_3, 4档/level_4, 5档/level_5
7	开关	switch	可下发可上报（rw）	bool	0,1
8	模式	mode	可下发可上报（rw）	enum	枚举值: 自动/auto, 制冷/colding, 制热/hot, 空气/air, 除湿/dehumidify
9	上下摆风	switch_vertical	可下发可上报（rw）	bool	0,1
10	左右摆风	switch_horizontal	可下发可上报（rw）	bool	0,1
11	故障告警	fault	只上报（ro）	bitmap	故障值: 故障/fault, 初级滤网报警/fan_filter_low, 滤网报警/filter_alarm, 中级滤网报警/fan_filter_med, 防冻开关报警/freeze_pro_alarm, 送风机故障/blower_alarm, 回风机故障/return_fan_alarm, 失效告警/ailure_alarm
12	送风温度	supply_temp	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
13	送风湿度	humidity_supply	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
14	水阀反馈	water_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
15	状态	state	可下发可上报（rw）	enum	枚举值: 自动/auto, 手动/manual
16	初效过滤网开关	first_filter_switch	可下发可上报（rw）	bool	0,1
17	风机滤网开关	fan_filter_switch	可下发可上报（rw）	bool	0,1
18	水阀	water_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
19	加湿阀	hum_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
20	新风阀开关	freshair_valve_switch	可下发可上报（rw）	bool	0,1
21	排风阀	exhaust_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
22	瞬时流量	flow_rate_instant_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
23	总流量	flowrate_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
24	流速	flow_velocity	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m/s
25	室内温度	temp_indoor	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
26	室内湿度	humidity_indoor	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3
27	供水温度	inlet_temp_1	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
28	回水温度	outlet_temp_1	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
29	进水温度	inlet_temp_f	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
30	出水温度	effluent_temp	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃

BA电机设施设备系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	开关状态	switch_state	只上报（ro）	bool	0,1
2	模式手自动状态	mode	可下发可上报（rw）	enum	枚举值: 手动/manual, 自动/auto
3	故障告警	fault	只上报（ro）	bitmap	故障值: fault, 初级滤网报警/fan_filter_low, 滤网报警/filter_alarm, 防冻开关报警/freeze_pro_alarm
4	开关	switch	可下发可上报（rw）	bool	0,1
5	电池电压	battery_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
6	温度设置	temp_set	可下发可上报（rw）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
7	CO2检测值设定	eco2_set	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
8	送风机变频频率	frequency_conversion	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
9	送风机变频器频率反馈	fre_conversion_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
10	加湿阀	hum_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
11	加湿阀反馈	hum_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
12	水阀	water_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
13	水阀反馈	water_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
14	新风阀调节	freshair_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
15	AI新风风阀反馈	ai_freshair_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
16	新风温度	temp_fresh	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位:℃
17	新风湿度	humidity_fresh	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
18	防冻开关检测	antifreeze	可下发可上报（rw）	bool	0,1
19	初效过滤网开关	first_filter_switch	可下发可上报（rw）	bool	0,1
20	风机滤网开关	fan_filter_switch	可下发可上报（rw）	bool	0,1
21	送风温度	supply_temp	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
22	送风湿度	humidity_supply	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
23	室内二氧化碳	ico2_ndoor_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
24	室内VOC	voc_indoor_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
25	油位高度	oil_level	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m
26	剩余油量	oil_remain	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
27	油箱总容量	capacity_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: L
28	上报A相电压，电流及功率	phase_a	只上报（ro）	raw	/
29	上报B相电压，电流及功率	phase_b	只上报（ro）	raw	/
30	上报C相电压，电流及功率	phase_c	只上报（ro）	raw	/
31	Uab线电压	uab_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 2 单位: V
32	Ubc线电压	ubc_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
33	Uca线电压	uca_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
34	单相有功功率	sigle_phase_power	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
35	功率因数	power_factor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
36	视在功率	power_apparent	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
37	有功电量	active_energy_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
38	电网供电频率	supply_frequency	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
39	当前温度	temp_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
40	月用电量	electric_month	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW·h
41	压力值	pressure_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: Mpa

BA供水系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
2	水位设置	water_set	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: L
3	电池电压	battery_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
4	水浸检测状态	watersensor_state	只上报（ro）	enum	枚举值: water_leak_sensor, 正常/normal
5	系统水压	water_pressure	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
6	变频反馈	fre_conversion_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
7	开关状态	switch_state	可下发可上报（rw）	bool	0,1
8	故障告警	fault	只上报（ro）	bitmap	故障值: water_low, water_high, water_low_max, high_level
9	模式	mode	可下发可上报（rw）	enum	枚举值: 手动/manual, 自动/auto
10	阀门检测	valve_check	可下发可上报（rw）	bool	0,1
11	变频	frequency_conversion	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
12	开关	switch	可下发可上报（rw）	bool	0,1
13	电动蝶阀开关	butterfly_valve_switch	可下发可上报（rw）	bool	0,1
14	工作状态	work_state	只上报（ro）	enum	枚举值: 运行/run, 停止/stop
15	总运行时间	runtime_total	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: min
16	压力值	pressure_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: Kpa
17	水泵设备过载跳闸状态	trip_state	只上报（ro）	enum	枚举值: 正常/normal, 设备报警/device_alarm
18	水容量	water_capacity	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: L
19	供水温度	inlet_temp_1	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
20	回水温度	outlet_temp_1	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
21	水流量	water_flow	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
22	上报A相电压，电流及功率	phase_a	只上报（ro）	raw	voltage代表电压、current代表电流、power代表功率、electricity代表电力 { “voltage”:“”, //电压 “current”:“”, //电流 “power”:“” //功率 “electricity”:“”//电力 }
23	上报B相电压，电流及功率	phase_b	只上报（ro）	raw	voltage代表电压、current代表电流、power代表功率、electricity代表电力 { “voltage”:“”, //电压 “current”:“”, //电流 “power”:“” //功率 “electricity”:“”//电力 }
24	上报C相电压，电流及功率	phase_c	只上报（ro）	raw	voltage代表电压、current代表电流、power代表功率、electricity代表电力 { “voltage”:“”, //电压 “current”:“”, //电流 “power”:“” //功率 “electricity”:“”//电力 }
25	A相温度	phase_a_temp	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
26	B相温度	phase_b_temp	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
27	C相温度	phase_c_temp	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
28	有效功率	power_effective	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
29	功率因数	power_factor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
30	电网供电频率	supply_frequency	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
31	有功电量	active_energy_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
32	温度	irac_temperature	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ℃
33	噪声	noise_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: dB
34	日用电量数据	daily_energy	只上报（ro）	raw	/
35	月用电量数据	month_energy	只上报（ro）	raw	/

BA通风系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	送风温度	supply_temp	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
2	送风湿度	humidity_supply	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
3	回风温度	temp_return	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
4	回风湿度	humidity_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
5	排风阀反馈	exhaust_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
6	水阀反馈	water_valve_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
7	室内温度	temp_indoor	只上报（ro）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
8	室内湿度	humidity_indoor	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
9	阵风风速	windspeed_gust	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m/s
10	变频反馈	fre_conversion_return	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
11	开关状态	switch_state	可下发可上报（rw）	bool	0,1
12	故障告警	fault	可下发可上报（rw）	bitmap	故障值: 故障/fault, 初级滤网报警/fan_filter_low, 中级滤网报警/fan_filter_med, 滤网报警/filter_alarm, 防冻开关报警/freeze_pro_alarm, 风机压差告警/fan_dif_pre
13	初效过滤网开关	first_filter_switch	可下发可上报（rw）	bool	0,1
14	风机滤网开关	fan_filter_switch	可下发可上报（rw）	bool	0,1
15	旁通阀	bypass_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
16	变频	frequency_conversion	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
17	水阀	water_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
18	加湿阀	hum_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
19	回风阀调节	returnair_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
20	开关	switch	可下发可上报（rw）	bool	0,1
21	新风阀开关	freshair_valve_switch	可下发可上报（rw）	bool	0,1
22	排风阀	exhaust_valve_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
23	加湿	wet	可下发可上报（rw）	bool	0,1
24	状态	status	只上报（ro）	enum	枚举值: 正常/normal, 停止/stop, 设备故障/device_fault
25	模式	mode	可下发可上报（rw）	enum	枚举值: 自动/auto, 手动/manual
26	总运行时间	runtime_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: min

BA环境监测系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
2	风速	windspeed_gust	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m/s
3	风力	wind_power	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
4	风向	wind_direct	可下发可上报（rw）	enum	枚举值: 北/north, 北东北/north_north_east, 东北/north_east, 东东北/east_north_east, 东/east, 东东南/east_south_east, 东南/south_east, 南东南south_south_east, 南/south, 南西南/south_south_west, 西南/south_west, 西西南/west_south_west, 西/west, 西西北/west_north_west, 西北/north_west, 北西北north_north_west
5	风向度数	wind_direct_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
6	土壤1温湿度_EC_PH值	soil_data_1	只上报（ro）	raw	/
7	土壤2温湿度_EC_PH值	soil_data_2	只上报（ro）	raw	/
8	土壤3温湿度_EC_PH值	soil_data_3	只上报（ro）	raw	/
9	土壤4温湿度_EC_PH值	soil_data_4	只上报（ro）	raw	/
10	室外湿度	humidity_outdoor	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
11	室外温度	temp_outdoor	可下发可上报（rw）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
12	噪声	noise_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: dB
13	大气压强	atmospheric_pressture	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: Kpa
14	光照强度	light_intensity	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: lux
15	雨雪状态	rain_snow_state	只上报（ro）	enum	枚举值: 下雪/snowy, 正常/normal
16	紫外线指数	uv_index	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
17	总辐射	radiation_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
18	光合有效辐射	radiation_pho	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
19	累计雨量	rain_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
20	当前雨量	rain_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
21	瞬时雨量	rain_instant	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
22	一小时降雨量	rain_1h	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
23	O3检测值	o3_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
24	CO检测值	co_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
25	SO2检测值	so2_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
26	O2检测值	o2_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
27	H2S检测值	h2s_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
28	蒸发量	evap_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
29	PM2.5检测值	pm25_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ug/m3
30	PM10	pm10	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ug/m3
31	氮	nitrogen_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
32	磷	phosphorus_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
33	钾	potassium_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
34	负氧离子	air_anion_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
35	NH3检测值	nh3_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
36	VOC检测值	voc_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
37	上电状态设置	relay_status	可下发可上报（rw）	enum	枚举值: 开/on, 关/off
38	状态	state	可下发可上报（rw）	enum	枚举值: 运行/run, 停止/stop
39	余氯检测值	ppm_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
40	PH值	ph	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
41	水质	water_quality	只上报（ro）	enum	枚举值: 正常/normal, 告警/alarm
42	浊度	turbidity_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
43	当前温度	temp_current	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
44	故障告警	fault	只上报（ro）	bitmap	故障值: fault, sensor_fault, amb_temp_fault
45	温度	irac_temperature	可下发可上报（rw）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
46	湿度	humidity	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
47	空气质量	air_quality_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
49	电池电量	battery_percentage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: %
50	NO2检测值	no2_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
51	CO2检测值	co2_value	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: ppm
52	剩余高度	height	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3

BA照明系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
2	开关	switch	可下发可上报（rw）	bool	0,1
3	群组控制开关	group_control_switch	可下发可上报（rw）	string	/
4	群组控制调光	group_control_light	可下发可上报（rw）	string	/
5	群组	group	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位:
6	监测状态上报	monitor_state_report	可下发可上报（rw）	string	/
7	灯带开关	lamp_switch	可下发可上报（rw）	bool	0,1
8	亮度值	bright_value	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
9	当前电流	cur_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
10	当前电压	voltage_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
11	当前功率	power_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: W

BA电梯系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	门状态	door_state	只上报（ro）	enum	枚举值: 打开中/openning, 关闭中/closing
2	上下行状态	vertical_state	只上报（ro）	enum	枚举值: 上行/upstream, 下行/downstream, 停层/stop_layer
3	运行状态	status	只上报（ro）	enum	枚举值: 运行/run, 停止/stop
4	当前楼层	floor_current_data	只上报（ro）	raw	/
5	有无人状态	have_none_state	只上报（ro）	enum	枚举值: 有人/someone, 无人/unmanned
6	呼梯	call_elevator	可下发可上报（rw）	string	/
7	运行速度	speed_realtime	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m/s
8	顶部温度	top_temp	只上报（ro）	value	数值范围: -100~999999999 间距: 1 倍数: 3 单位: ℃
9	人体感应状态	pir_state	只上报（ro）	enum	枚举值: pir
10	故障告警	fault	只上报（ro）	bitmap	故障值: 反复开关门/door_re_alarm, 不开门故障/door_failure_alarm, 开门运行故障/door_run_alarm, 困人/trapped_alarm, 长时间不关门/door_too_long_alarm, 冲顶/summit_attempt, 蹲底/squatting, 超速/speeding, 掉电/power_down, 卡层故障/stuck_layer_fault, 电梯故障/elevator_fault, 长时间不开门/not_open_time, 供电故障/power_fault, 打火告警/fire_alarm, 电瓶车报警/battery_car_alarm
11	通讯状态	comm_state	只上报（ro）	enum	枚举值: 在线/online, 掉线/offline
12	当前电流	cur_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: A
13	上报A相电压_电流_功率	phase_a	只上报（ro）	raw	/
14	上报B相电压_电流_功率	phase_b	只上报（ro）	raw	/
15	上报C相电压_电流_功率	phase_c	只上报（ro）	raw	/
16	Uab线电压	uab_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
17	Ubc线电压	ubc_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
18	Uca线电压	uca_line_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
19	当前电压	voltage_current	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
20	有效功率	power_effective	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
21	无效功率	power_reactive	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
22	视在功率	power_apparent	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
23	正向总有功电量	forward_energy_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kW
24	水浸检测状态	watersensor_state	只上报（ro）	enum	枚举值: 水浸/water_leak_sensor
25	室内温度	temp_indoor	可下发可上报（rw）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
26	室内湿度	humidity_indoor	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3
27	开关门传感器	sensor_probe	只上报（ro）	enum	枚举值: 打开中/openning, 关闭中/closing
28	激光测距距离	target_dis_closest	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
29	传感器模式	sensor_choose	可下发可上报（rw）	enum	枚举值: 设备报警/device_alarm, 正常/normal
30	总次数	times_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
31	传感器状态	sensor_state	只上报（ro）	enum	枚举值: 设备报警/device_alarm, 正常/normal
32	运行参考高度	height	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
33	日用电量数据	daily_energy	只上报（ro）	raw	/
34	月用电量数据	month_energy	只上报（ro）	raw	/
35	电池电压	battery_voltage	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: V
36	总_距离	distance_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: mm
37	当前载重	load_current	可下发可上报（rw）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: kg
38	超重状态	overweight_state	只上报（ro）	enum	枚举值: 上限报警/upper_alarm, 正常/normal
39	平层状态	parallel_state	可下发可上报（rw）	enum	枚举值: 正常/normal
40	机房温度	com_room_temp	可下发可上报（rw）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
41	卡层数	stuck_layer	只上报（ro）	value	数值范围: -10~999999999 间距: 1 倍数: 3
42	开启次数	open_times	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
43	检修状态	maintenance_state	只上报（ro）	enum	枚举值: 检测中/detecting, 检查成功/check_success, 检查失败/check_failure
44	门闸锁状态	gate_lock_state	只上报（ro）	enum	枚举值: 开启中/opening, 关闭中/closing
45	警铃状态	alarm_bell_state	只上报（ro）	enum	枚举值: 告警/alarm, 正常/normal

BA水表系统

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
1	供水温度	inlet_temp_1	可下发可上报（rw）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
2	回水温度	outlet_temp_1	可下发可上报（rw）	value	数值范围: -200~999999999 间距: 1 倍数: 3 单位: ℃
3	水流量	water_flow	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
4	开关	switch	可下发可上报（rw）	bool	0,1
5	故障告警	fault	只上报（ro）	bitmap	故障值: 水流故障/flow_fault, 用水异常告警/abnormal_water_alarm, 水表硬件故障告警/meter_body_alarm, 水泵卡死/pump_blocked, 水流量过低/flow_low
6	冷摊用量	cold_stall_userdata	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
7	冷摊方式	cold_stall_type	可下发可上报（rw）	enum	枚举值: 平方面积/square_area, 忽略/ignore, 用量/consumption, 占比/proportion, 租赁/lease, 功率/power
8	热摊用量	hot_stall_userdata	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3
9	热摊方式	hot_stall_type	可下发可上报（rw）	enum	枚举值: 平方面积/square_area, 忽略/ignore, 用量/consumption, 占比/proportion, 租赁/lease, 功率/power
10	阀开启度	valve_open_degree	可下发可上报（rw）	value	数值范围: -400~999999999 间距: 1 倍数: 3 单位: %
11	阀门状态	valve_state	可下发可上报（rw）	enum	枚举值: 已开启/opened, 已关闭/closed, 开启中/opening, 关闭中/closing
12	月总用水量	monthly_water_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
13	日总用水量	daily_water_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
14	日初始用水量	d_begin_water_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
15	日终用水量	d_end_water_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
16	日初始读取时间	d_begin_time	只上报（ro）	string	/
17	日终读取时间	d_end_time	只上报（ro）	string	/
18	月初用水量	m_begin_water_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
19	月终用水量	m_end_water_total	只上报（ro）	value	数值范围: 0~999999999 间距: 1 倍数: 3 单位: m3
20	月初始读取时间	m_begin_time	可下发可上报（rw）	string	/
21	月终读取时间	m_end_time	可下发可上报（rw）	string	/

API 参考

设备侧 MQTT 接口参考

MQTT 消息由固定报头（Fixed header）、可变报头（Variable header）和有效载荷（Payload）三部分组成。

其中固定报头（Fixed header）和可变报头（Variable header）格式的填写请参考MQTT 标准规范，有效载荷（Payload）的格式由涂鸦定义，具体请产考下文。

MQTT 的语法和接口细节，请以 MQTT 标准规范为准。

常见 MQTT 消息类型主要有 CONNECT、SUBSCRIBE、PUBLISH。

CONNECT：指客户端请求和服务端连接。有效载荷（Payload）的主要参数，参考设备连接鉴权填写。
SUBSCRIBE：指客户端订阅请求。有效载荷（Payload）中的主要参数“Topic name”，参考Topic 定义中订阅者为设备的 Topic。
PUBLISH：平台发布消息。
- 可变报头（Variable header）中的主要参数“Topic name”，指设备上报到物联网平台时发布者为设备的 Topic。详细请参考Topic 定义。
- 有效载荷（Payload）中的主要参数为完整的数据上报和命令下发的消息内容，目前是一个 JSON 对象。

使用限制

上行 Topic 是指设备向平台发送请求，或上报数据，或回复响应。
下行 Topic 是指平台向设备下发指令，或回复响应。
设备与平台建立连接后，需要订阅下行 Topic，否则无法收到平台下发的指令或回复的响应。

设备与平台间通信方式概述

设备接入涂鸦边缘网关，通过边缘网关进行通信。设备、涂鸦边缘网关和涂鸦开发者平台的通信流程示意图如下。

BA 楼宇自控系统接入

设备发送数据到涂鸦边缘网关

设备接入涂鸦边缘网关后，便可与涂鸦边缘网关进行通信。设备可通过以下方式发送数据到平台：

设备属性上报：用于设备按产品模型中定义的格式将属性数据上报给平台。

应用服务器下发指令给设备

设备接入涂鸦边缘网关后，涂鸦网关可通过以下方式发送指令到设备。

平台命令下发：应用服务器按产品模型中定义的命令格式下发控制命令给设备。

Topic 定义

设备使用 MQTT 协议接入涂鸦边缘网关时，平台和设备通过 Topic 进行通信。平台预置的 topic 列表如下：

Topic 分类	Topic	Publisher	Subscriber	用途
设备同步相关 Topic	gateway_id/{gateway_id}/devices/sync	设备	平台	设备激活
设备同步相关 Topic	gateway_id/{gateway_id}/devices/sync/response	平台	设备	平台返回激活响应
设备命令相关 Topic	gateway_id/{gateway_id}/commands	平台	设备	平台下发命令给设备
设备命令相关 Topic	gateway_id/{gateway_id}/commands/response	设备	平台	设备返回命令响应
设备属性相关 Topic	gateway_id/{gateway_id}/properties/report	设备	平台	设备属性上报
设备属性相关 Topic	gateway_id/{gateway_id}/properties/report/response	平台	设备	平台返回上报属性响应
设备上下线 Topic	gateway_id/{gateway_id}/devices/status	设备	平台	设备上下线上报

{gateway_id}用于标识 Topic 路由的目标设备，设备侧订阅该 topic 或往 topic 推送消息时，该值需要替换为设备与平台建立 MQTT 连接时使用的网关 ID 参数值。

QoS 等级设置

MQTT 协议中规定了消息服务质量（Quality of Service），它保证了在不同的网络环境下消息传递的可靠性，MQTT 设计了 3 个 QoS 等级。

QoS 0：消息最多传递一次，如果当时客户端不可用，则会丢失该消息。
QoS 1：消息传递至少 1 次。
QoS 2：消息仅传送 1 次。

QoS 级别越高，流程越复杂，系统资源消耗越大。应用程序可以根据自己的网络场景和业务需求，选择合适的 QoS 级别。

建议设备对接方在消息的推送和订阅上将 QoS 设置为 1。

连接鉴权

接口说明

开发者平台设备侧支持 MQTT 协议的 connect 消息接口，鉴权通过后建立设备与平台间的 MQTT 连接。

参数说明

参数	必选/可选	类型	参数描述
broker	必选	String	边缘⽹关 ip 地址，对接时由涂鸦提供。
port	必选	String	TCP 固定为 58090，SSL/TLS 固定为 21883。
clientId	必选	String	第三方的网关 id，此参数要保证唯一。
username	必选	String	第三⽅⼚商标识，对接时由涂鸦提供。
password	必选	String	Password 的值为使用“md5”加密算法生成，具体请参考密码生成规则。

SSL/TLS 为单向认证模式。

密码生成规则

拼接 clientId 和 username 变量，然后用 md5 加密算法对拼接后的变量加密。

下面用 Go 语言生成连接密码例子，供参考。

func generatePassword() string {
	var (
		clientId string
		username string
		password string
	)
	// clientId username 请先赋值
	password = md5V(clientId + username)
	return password
}

// md5 加密算法函数
func md5V(str string) string {
	h := md5.New()
	h.Write([]byte(str))
	return hex.EncodeToString(h.Sum(nil))
}

原生 MQTT 协议接入建链返回码

原生 MQTT 协议设备和平台建链时，常见返回码如下：

返回码	标示	返回码描述	原因
0x00	connection accepted	连接成功	连接成功
0x01	unacceptable protocol version	请求拒绝，协议版本错误	服务器不支持客户端请求 MQTT 协议版本
0x02	identifier rejected	请求拒绝，无效的客户端标识符	clientId 不符合格式要求或者心跳时间间隔不满足平台要求
0x03	server Unavailable	请求拒绝，服务器不可用	平台服务不可用
0x04	bad user name or password	请求拒绝，用户名或密码错误	用户名或密码错误
0x05	not Authorized	请求拒绝，没有授权	客户端没有权限连接

设备同步

用于设备同步，在设备网关连接上涂鸦边缘网关的 MQTT 服务器后，要发送设备同步指令。涂鸦边缘网关会对上报的设备进行新增或更新。

必须先同步子设备才可进行后续操作，否则会出现找不到设备的错误。

Topic

上行：gateway_id/{gateway_id}/devices/sync
下行：gateway_id/{gateway_id}/devices/sync/response

上行参数说明

字段名	必选/可选	类型	参数描述
t	必选	Integer	Unix 时间戳（Unix timestamp）
request_id	必选	String	请求标示，建议用 UUID 算法生成。
param	必选	Object	对象
param.cid	必选	String	第三方设备 ID，由设备侧定义。建议采⽤设备端可读取的唯⼀标识作为 cid，例如设备的 SN 号、IMEI 号等。
param.product_id	必选	String	产品对应的 product_id
param.vendor_code	可选	String	厂商 Code
param.comm_type	可选	String	设备和网关通讯方式，请填写“MQTT”
param.device_ip	可选	String	设备 IP 地址
param.mac_address	可选	String	设备 MAC 地址
param.device_desc	可选	String	设备描述
param.install_location	可选	String	设备安装位置
param.device_server_id	可选	String	设备服务 ID
param.product_sub_type	可选	String	子产品类型

下行参数说明

字段名	必选/可选	类型	参数描述
t	必选	Integer	Unix 时间戳（Unix timestamp）
request_id	必选	String	请求唯一标示。
param	必选	Object	对象
param.cid	必选	String	设备 cid
param.msg	必选	String	含义请参考全局错误码。
param.code	必选	Integer	标识命令的执行结果，0 表示成功，其他表示失败。

上行参数示例

Topic: gateway_id/{gateway_id}/devices/sync
数据格式:
{
    "t":1627280679,
    "request_id":"cd0fd3c3-bd15-42f6-8bf9-d2***",
    "param":{
        "cid":"92dda538fc***",
        "product_id":"sie4***",//请填写产品对应的 pid
        "vendor_code":"",//设备厂商标识
        "comm_type":"",
        "device_ip":"",
        "mac_address":"",
        "device_name":"",
        "device_desc":"",
        "install_location":"",
        "device_server_id":"",
        "product_sub_type":""
    }
}

下行参数示例

Topic: gateway_id/{gateway_id}/devices/sync/response
数据格式:
{
    "t":1627280***,
    "request_id":"cd0fd3c3-bd15-42f6-8bf9-d23***",
    "param":{
        "cid":"92dda538fc***",
        "msg":"success",
        "code":0
    }
}

设备命令

平台命令下发

用于平台向设备下发设备控制命令。平台下发命令后，需要设备及时将命令的执行结果返回给平台，如果设备没回响应，平台会认为命令执行超时。

Topic

下行： gateway_id/{gateway_id}/commands
上行：gateway_id/{gateway_id}/commands/response

下行请求参数说明

字段名	必选/可选	类型	参数描述
t	必选	Integer	Unix 时间戳（Unix timestamp）
cid	必选	String	第三方设备 ID，由设备侧定义。建议采⽤设备端可读取的唯⼀标识作为 cid，例如设备的 SN 号、IMEI 号等。
request_id	必选	String	请求标示，建议用 UUID 算法生成。
param	必选	Object	对象
param.id	必选	String	设备功能点 ID。
param.value	必选	类型不固定	设备命令的执行参数。

上行响应参数说明

命令应答的 JSON 格式。

字段名	必选/可选	类型	参数描述
t	必选	Integer	Unix 时间戳（Unix timestamp）
cid	必选	String	第三方设备 ID，由设备侧定义。建议采⽤设备端可读取的唯⼀标识作为 cid，例如设备的 SN 号、IMEI 号等。
request_id	必选	String	请求唯一标示，建议用 UUID 算法生成。
param	必选	Object	对象
param.msg	必选	String	执行结果，如果成功，请填写 success。
param.code	必选	Integer	标识命令的执行结果，0 表示成功，其他表示失败。

下行请求示例

Topic: gateway_id/{gateway_id}/commands
数据格式：  
{
  "t":1627280***,
  "cid": "92dda538fc2e636fd4b0***",
  "request_id":"cd0fd3c3-bd15-42f6-8bf9-d23***",
  "param": {
    "id":"1",
    "value": "1"
  }
}

上行响应示例

Topic：gateway_id/{gateway_id}/commands/response
数据格式：  
{
  "t":1627280***,
  "cid": "92dda538fc2e636fd4***",
  "request_id":"cd0fd3c3-bd15-42f6-8bf9-d23***",
  "param": {
    "msg": "success",
    "code":0
  }
}

设备属性

设备属性上报

用于设备按产品模型中定义的格式将属性数据上报给平台。平台在接到上报消息后，会将执行结果返回给设备。

Topic

上行：gateway_id/{gateway_id}/properties/report
下行：gateway_id/{gateway_id}/properties/report/response

上行参数说明

字段	必选/可选	类型	参数描述
t	必选	Integer	时间戳：为设备连接平台时的 UTC 时间。
request_id	必选	String	请求唯一标示，建议用 UUID 算法生成。
param	必选	Object	对象
param.cid	必选	String	第三方设备 ID，由设备侧定义。建议采⽤设备端可读取的唯⼀标识作为 cid，例如设备的 SN 号、IMEI 号等。
param.product_id	必选	String	产品的 product_id，请参考自己产品的 ID 进行填写。
param.id	必选	String	产品下面某一个功能点 ID。
param.value	必选	参考功能点类型	设备的属性值

下行参数说明

字段名	必选/可选	类型	参数描述
t	必选	Integer	Unix 时间戳（Unix timestamp）
request_id	必选	String	请求唯一标示。
param	必选	Object	对象
param.cid	必选	String	第三方设备 ID，由设备侧定义。建议采⽤设备端可读取的唯⼀标识作为 cid，例如设备的 SN 号、IMEI 号等。
param.msg	必选	String	含义请参考全局错误码。
param.code	必选	Integer	标识命令的执行结果，0 表示成功，其他表示失败。

上行参数示例

gateway_id/{gateway_id}/properties/report
{
    "t":1627280***,
    "request_id":"cd0fd3c3-bd15-42f6-8bf9-d23***",
    "param":{
        "cid":"ee1880aca***",
        "product_id":"r2fz6uv6a***",
        "id":"1",
        "value":"run"
    }
}

下行参数示例

Topic：gateway_id/{gateway_id}/properties/report/response
数据格式：  
{
    "t":1627280***,
    "request_id":"cd0fd3c3-bd15-42f6-8bf9-d23***",
    "param":{
        "cid":"92dda538***",
        "msg":"success",
        "code":0
    }
}

设备上下线

设备上下线上报

设备网关需要定时把设备的上线下线状态同步给涂鸦边缘网关，建议至少每隔一分钟上报一次子设备状态。

Topic

上行：gateway_id/{gateway_id}/devices/status

上行参数说明

字段	必选/可选	类型	参数描述
t	必选	Integer	时间戳：为设备连接平台时的 UTC 时间。
request_id	必选	String	请求唯一标示，建议用 UUID 算法生成。
param	必选	Object	对象数组
param.cid	必选	String	第三方设备 ID，由设备侧定义。建议采⽤设备端可读取的唯⼀标识作为 cid，例如设备的 SN 号、IMEI 号等。
param.status	必选	Bool	设备状态。true 代表上线、false 代表离线。

上行参数示例

Topic：gateway_id/{gateway_id}/devices/status
数据格式：  
{
  "t":1627280***,
  "request_id":"cd0fd3c3-bd15-42f6-8bf9-d23***",
  "param": [{
    "cid": "92dda538fc2e6***",
    "status":true
  },
  {
    "cid": "da538fc2eb***",
    "status":false
  }         
 ]
}

应用示例

为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发例子，演示了服务连接、验证、敏感信息加/解密、推送订阅等基础功能（更多语言版本的开发库将在近期陆续提供）

JAVA

将下面显示的依赖性定义添加到 maven pom 文件中。

<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        <version>1.2.0</version>
    </dependency>
</dependencies>

//消息发布
public class Publish {
    public static void main(String[] args) {
        String clientId = "";                     // 即 gatewayID, 第三⽅⼚商⽹关 ID
        String topic = ""; 												// 主题
        String content = "";                      // 内容
        int qos = 1;                              // 服务质量
        String broker = "";                       // 服务器 IP 地址
        String userName = "";                     // 用户名，由涂鸦提供
        String password = "";                     // 密码，请参考密码生成规则
        // 内存存储
        MemoryPersistence persistence = new MemoryPersistence();

        try {
            // 创建客户端
            MqttClient sampleClient = new MqttClient(broker, clientId, persistence);
            // 创建链接参数
            MqttConnectOptions connOpts = new MqttConnectOptions();
            // 在重新启动和重新连接时记住状态
            connOpts.setCleanSession(false);
            // 设置连接的用户名
            connOpts.setUserName(userName);
            connOpts.setPassword(password.toCharArray());
            // 建立连接
            sampleClient.connect(connOpts);
            // 创建消息
            MqttMessage message = new MqttMessage(content.getBytes());
            // 设置消息的服务质量
            message.setQos(qos);
            // 发布消息
            sampleClient.publish(topic, message);
            // 断开连接
            sampleClient.disconnect();
            // 关闭客户端
            sampleClient.close();
        } catch (MqttException me) {
            System.out.println("reason " + me.getReasonCode());
            System.out.println("msg " + me.getMessage());
            System.out.println("loc " + me.getLocalizedMessage());
            System.out.println("cause " + me.getCause());
            System.out.println("excep " + me);
            me.printStackTrace();
        }
    }
}

//消息订阅
public class Subscribe {

    public static void main(String[] args) throws MqttException {  
        String clientId = "";                     // 即 gatewayID, 第三⽅⼚商⽹关 ID 
        String host = "";                         // 服务器 IP 地址
        String topic = "gateway/in/" + clientId;  // 主题
        int qos = 1;                              // 服务质量
        String userName = "";                     // 用户名，由涂鸦提供
        String password = "";                     // 密码，请参考密码生成规则
        try {
            //MemoryPersistence 设置 clientid 的保存形式，默认为以内存保存
            MqttClient client = new MqttClient(host, clientid, new MemoryPersistence());
            // MQTT 的连接设置
            MqttConnectOptions options = new MqttConnectOptions();
            // 设置是否清空 session,这里如果设置为 false 表示服务器会保留客户端的连接记录，这里设置为 true 表示每次连接到服务器都以新的身份连接
            options.setCleanSession(true);
            // 设置连接的用户名
            options.setUserName(userName);
            // 设置连接的密码
            options.setPassword(passWord.toCharArray());
            // 设置超时时间 单位为秒
            options.setConnectionTimeout(10);
            // 设置会话心跳时间 单位为秒 
            options.setKeepAliveInterval(20);
            // 设置回调函数
            client.setCallback(new MqttCallback() {

                public void connectionLost(Throwable cause) {
    
                }
                public void messageArrived(String topic, MqttMessage message) throws Exception {
                  	// 消息处理部分
                    System.out.println("message content:"+new String(message.getPayload()));
                    
                }
                public void deliveryComplete(IMqttDeliveryToken token) {
                   
                }

            });
            client.connect(options);
            //订阅消息
            client.subscribe(topic, qos);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

GO

package main

import (
	"fmt"
	mqtt "github.com/eclipse/paho.mqtt.golang"
	"log"
	"os"
	"time"
)

const broker = ""               // 服务器 IP 地址，请联系涂鸦管理员获取
const username = ""             // 用户名，由涂鸦提供
const password = ""             // 密码，请参考密码生成规则
const clientID = ""             // 即 gatewayID, 第三⽅⼚商⽹关 ID
const topic = ""      					// 主题
const port = "21883"            // 服务端口号

// 订阅消息 topic = "gateway/in/" + clientID
// 发布消息 topic = "gateway/out/" + clientID

var f mqtt.MessageHandler = func(client mqtt.Client, msg mqtt.Message) {
	fmt.Printf("TOPIC: %s\n", msg.Topic())
	fmt.Printf("MSG: %s\n", msg.Payload())
}

func main() {
	mqtt.DEBUG = log.New(os.Stdout, "", 0)
	mqtt.ERROR = log.New(os.Stdout, "", 0)
	opts := mqtt.NewClientOptions().AddBroker(fmt.Sprintf("tcp://%s:%s", broker, port)).SetClientID(clientID).
		SetUsername(username).SetPassword(password)
	
	opts.SetKeepAlive(60 * time.Second)
	// 设置消息回调处理函数
	opts.SetDefaultPublishHandler(f)
	opts.SetPingTimeout(1 * time.Second)
	
	c := mqtt.NewClient(opts)
	if token := c.Connect(); token.Wait() && token.Error() != nil {
		panic(token.Error())
	}
	
	// 订阅主题
	if token := c.Subscribe(topic, 0, nil); token.Wait() && token.Error() != nil {
		fmt.Println(token.Error())
		os.Exit(1)
	}
	
	// 发布消息
	token := c.Publish(topic, 0, false, "Hello World")
	token.Wait()
	
	time.Sleep(6 * time.Second)
	
	// 取消订阅
	if token := c.Unsubscribe(topic); token.Wait() && token.Error() != nil {
		fmt.Println(token.Error())
		os.Exit(1)
	}
	
	// 断开连接
	c.Disconnect(250)
	time.Sleep(1 * time.Second)
}

PHP

消息推送：

<?php
require("");                                // 引入 mqtt 类文件
$server    = '';                            // 服务器 IP 地址，请联系涂鸦管理员获取 
$port      = 21883;                         // 服务器端口
$username  = '';                            // 用户名，由涂鸦提供
$password  = '';                            // 密码，请参考密码生成规则
$client_id = ''                             // 即 gatewayID, 第三⽅⼚商⽹关 ID

$mqtt = new Bluerhinos\phpMQTT($server, $port, $client_id); // 实例化 MQTT 类

if ($mqtt->connect(true, NULL, $username, $password))       // 建立连接
{
    $topic = 'gateway/out/'.$client_id;		  // 主题
    $key = 	''                              // 加密密钥 请填写连接认证时⽤的 password
    $msg = '';															// 推送消息，请参考上方消息格式
    // qos ＝ 0：仅发一次，不管是否能收到
    // qos ＝ 1：没返回一直发，可能有重复接收
    // qos ＝ 2：保证必须收到，并且不重复
    $mqtt->publish($topic, $msg, 0);//发送数据
    $mqtt->close();							            //关闭连接
}
else
{
    echo "Time out!\n";
}

消息订阅：

<?php
require("");                                // 引入 mqtt 类文件
$server    = '';                            // 服务器 IP 地址，请联系涂鸦管理员获取 
$port      = 21883;                         // 服务器端口
$username  = '';                            // 用户名，由涂鸦提供
$password  = '';                            // 密码，请参考秘密生成规则
$client_id = ''                             // 即 gatewayID, 第三⽅⼚商⽹关 ID

$mqtt = new Bluerhinos\phpMQTT($server, $port, $client_id);

$mqtt->debug = true;

if(!$mqtt->connect(true, NULL, $username, $password))
{
    echo "连接失败!\n";
    exit(1);
}
$topic = 'gateway/in/'.$client_id;          // 主题
																						// 订阅列表
$topics = [
    $topic => ['qos' => 0, 'function' => 'procmsg'],
];

$mqtt->subscribe($topics, 0);

while ($mqtt->proc()){}

$mqtt->close();

                                            
function procmsg($topic, $msg)							// 消息处理函数
{
    $key =  ''                              
  	echo $msg;	
}

全局错误码

当调用接口发生错误时，会返回自定义错误信息。本文介绍全局错误码的含义。

错误码 code	错误信息 msg	说明
400	tedge error: 上游具体错误信息	上游错误，具体信息由上游定义
500	system error,please contact the admin	系统错误，请联系管理员。
1001	request time is invalid	无效的请求时间。
1100	params is empty	参数为空。
1101	params range invalid	无效的参数范围。
1102	params is null	参数为 Null。
1103	params type is incorrect	参数类型错误。
1104	request pid is invalid	无效的 pid
1105	id does not exist in pid	此 pid 内无此功能点 ID
2001	device is offline	设备已离线。
2002	command or value not support	不支持的指令或值。
2003	device not exist	设备不存在。

上一篇智能电表接入