数据传输格式说明

概述

Energy Monitor 系统使用 MQTT 协议进行数据传输，包含两个主要的通信方向：

Home Assistant → 设备: 发送数据获取请求
设备 → Home Assistant: 返回设备数据

数据流图

Home Assistant 集成
        │
        ▼
   /data/data-get (请求)
        │
        ▼
    设备端处理
        │
        ▼
   /device/data (响应)
        │
        ▼
   Home Assistant 集成
        │
        ▼
    更新传感器状态

数据格式

1. 数据获取请求

主题: /data/data-get
格式: 纯文本
内容: get_data
频率: 每秒5次（每0.2秒一次）

主题: /data/data-get
内容: get_data

2. 设备数据响应

主题: /device/data
格式: JSON
编码: UTF-8

完整数据格式

{
  "solar_power": 1500.5,
  "home_power": 1200.0,
  "grid_import": 300.0,
  "grid_export": 0.0,
  "battery_charge": 200.0,
  "battery_discharge": 0.0,
  "battery_soc": 85.5
}

字段说明

字段名	类型	单位	说明
`solar_power`	float	W	太阳能发电功率
`home_power`	float	W	家庭用电功率
`grid_import`	float	W	从电网购买功率
`grid_export`	float	W	向电网出售功率
`battery_charge`	float	W	电池充电功率
`battery_discharge`	float	W	电池放电功率
`battery_soc`	float	%	电池电量百分比

使用示例

Python 设备端示例

import json
import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    if msg.topic == "/data/data-get":
        # 收到数据请求，发送设备数据
        data = {
            "solar_power": 1500.5,
            "home_power": 1200.0,
            "grid_import": 300.0,
            "grid_export": 0.0,
            "battery_charge": 200.0,
            "battery_discharge": 0.0,
            "battery_soc": 85.5
        }
        
        # 发送到 /device/data 主题
        client.publish("/device/data", json.dumps(data))

# 设置 MQTT 客户端
client = mqtt.Client()
client.on_message = on_message
client.connect("192.168.0.101", 1883, 60)
client.subscribe("/data/data-get")
client.loop_forever()

测试命令

使用 mosquitto 客户端测试：

# 监听数据获取请求
mosquitto_sub -h 192.168.0.101 -t "/data/data-get"

# 监听设备数据
mosquitto_sub -h 192.168.0.101 -t "/device/data"

# 手动发送数据请求
mosquitto_pub -h 192.168.0.101 -t "/data/data-get" -m "get_data"

# 手动发送设备数据
mosquitto_pub -h 192.168.0.101 -t "/device/data" -m '{"solar_power": 1500.5, "home_power": 1200.0}'

注意事项

JSON 格式: 设备数据必须是有效的 JSON 格式
数值类型: 所有功率值应为数字类型（int 或 float）
电量范围: battery_soc 应在 0-100 之间
功率单位: 所有功率值单位为瓦特 (W)
实时性: 数据应尽可能实时更新
错误处理: 设备端应处理数据请求失败的情况

数据验证

Home Assistant 集成会验证接收到的数据：

JSON 格式正确性
必需字段存在性
数值类型正确性
数值范围合理性

如果数据格式不正确，会在日志中记录警告信息。

3.3 KiB Raw Blame History Unescape Escape