refactor: remove outdated documentation files and enhance README for JackeryHome integration

- Deleted obsolete files including CHANGELOG.md, DATA_FORMAT.md, HACS_PUBLISHING_GUIDE.md, MQTT_FIX_SUMMARY.md, TROUBLESHOOTING.md, and test_mqtt.py to streamline the project.
- Updated README.md to include detailed architecture design, sensor value processing logic, and improved MQTT topic format explanations.
- Enhanced clarity on the integration's coordinator pattern and data flow, ensuring users have comprehensive guidance on setup and usage.
This commit is contained in:
不求圣剑
2025-11-19 10:43:47 +08:00
parent 27fd2e98a2
commit 11ef141bd7
8 changed files with 190 additions and 856 deletions

View File

@@ -20,17 +20,36 @@
1. **MQTT 模拟器** (`main.py`) - 模拟发送能源监控数据到 MQTT broker
2. **Home Assistant 自定义集成** (`custom_components/JackeryHome/`) - 接收 MQTT 数据并创建传感器实体
### 集成架构
集成采用**协调器模式**Coordinator Pattern
- 所有传感器共享一个 `JackeryDataCoordinator` 实例
- 统一管理 MQTT 订阅和数据请求
- 每 5 秒发送一次包含所有传感器 `meter_sn` 的数据请求
- 自动解析响应并分发给对应的传感器实体
## 传感器列表
本项目会创建以下传感器:
- `sensor.solar_power`: 太阳能发电功率W
- `sensor.home_power`: 家庭用电功率W
- `sensor.grid_import`: 从电网购买功率W
- `sensor.grid_export`: 向电网出售功率W
- `sensor.battery_charge`: 电池充电功率W
- `sensor.battery_discharge`: 电池放电功率W
- `sensor.battery_soc`: 电池电量百分比(%
### 功率传感器(实时监测
- `sensor.jackeryhome_solar_power`: 太阳能发电功率W
- `sensor.jackeryhome_home_power`: 家庭用电功率W
- `sensor.jackeryhome_grid_import`: 从电网购买功率W
- `sensor.jackeryhome_grid_export`: 向电网出售功率W
- `sensor.jackeryhome_battery_charge`: 电池充电功率W
- `sensor.jackeryhome_battery_discharge`: 电池放电功率W
- `sensor.jackeryhome_battery_state_of_charge`: 电池电量百分比(%
### 能源传感器(用于能源仪表板)
- `sensor.jackeryhome_solar_energy`: 太阳能发电总量kWh
- `sensor.jackeryhome_home_energy`: 家庭用电总量kWh
- `sensor.jackeryhome_grid_import_energy`: 电网购买总量kWh
- `sensor.jackeryhome_grid_export_energy`: 电网出售总量kWh
- `sensor.jackeryhome_battery_charge_energy`: 电池充电总量kWh
- `sensor.jackeryhome_battery_discharge_energy`: 电池放电总量kWh
## 安装
@@ -102,7 +121,8 @@
3. **查看传感器数据**
- 进入 **开发者工具** → **状态**
- 搜索 "solar_power"、"home_power" 等传感器
- 搜索 "jackeryhome" 或传感器名称(如 "Solar Power"、"Home Power" 等
- 实体 ID 格式:`sensor.jackeryhome_{sensor_id}`
## Energy Flow Card Plus 配置
@@ -137,24 +157,42 @@
type: custom:energy-flow-card-plus
entities:
solar:
entity: sensor.solar_power
entity: sensor.jackeryhome_solar_power
name: 太阳能
icon: mdi:solar-power
grid:
entity:
consumption: sensor.grid_import # 从电网购买
production: sensor.grid_export # 向电网出售
consumption: sensor.jackeryhome_grid_import # 从电网购买
production: sensor.jackeryhome_grid_export # 向电网出售
name: 电网
icon: mdi:transmission-tower
battery:
entity:
consumption: sensor.battery_charge # 充电
production: sensor.battery_discharge # 放电
state_of_charge: sensor.battery_soc
consumption: sensor.jackeryhome_battery_charge # 充电
production: sensor.jackeryhome_battery_discharge # 放电
state_of_charge: sensor.jackeryhome_battery_state_of_charge
name: 电池
icon: mdi:battery
home:
entity: sensor.home_power
entity: sensor.jackeryhome_home_power
name: 家庭用电
icon: mdi:home-lightning-bolt
display_zero_lines:
mode: show
transparency: 50
grey_color:
- 189
- 189
- 189
w_decimals: 0
kw_decimals: 2
color_icons: true
animation_speed: 10
energy_date_selection: false
```
**注意**:实体 ID 格式为 `sensor.jackeryhome_{sensor_id}`,其中 `{sensor_id}` 对应传感器 ID如 `solar_power`、`grid_import` 等)。
更多配置选项请查看 `energy_flow_card_config.yaml` 文件。
## 项目文件说明
@@ -164,11 +202,11 @@ entities:
- `custom_components/JackeryHome/`: Home Assistant 自定义集成
- `__init__.py`: 集成入口
- `manifest.json`: 集成元数据
- `sensor.py`: 传感器平台实现
- `sensor.py`: 传感器平台实现(包含协调器模式和所有传感器逻辑)
- `config_flow.py`: UI 配置流程
- `strings.json`: 本地化字符串
- `translations/zh-Hans.json`: 中文翻译
- `README.md`: 集成技术文档
- `README.md`: 集成技术文档包含架构设计、MQTT 协议格式等)
### 文档和工具
- `INTEGRATION_GUIDE.md`: 详细的集成使用指南
@@ -193,8 +231,9 @@ entities:
- 确保 Home Assistant 已配置好 MQTT 集成
- MQTT Broker 需要在运行此脚本之前启动
- 传感器会每 5 秒更新一次数据
- 集成会每 5 秒主动请求一次数据(所有传感器共享同一个请求)
- 数据为模拟值,用于演示目的
- 集成会自动从 LWT 消息获取设备序列号,无需手动配置
## 文档