timoschneider/homeassistant-jackery
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

51
CHANGELOG.md
View File

@@ -1,51 +0,0 @@
# Changelog
所有重要的项目更改都将记录在此文件中。
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
## [未发布]
### 计划中
- 增加更多能源监控功能
- 支持更多设备类型
## [1.1.1] - 2024-12-19
### 新增
- 在数据传输示例中增加能源数据模拟发送功能
- 支持所有能源类型的累积数据：太阳能、家庭用电、电网购买/出售、电池充放电
- 能源数据基准从1kWh开始，每次根据功率值增加0.1kWh
### 改进
- 简化传感器处理逻辑，直接显示累积值而不进行复杂计算
- 优化数据传输格式，包含完整的功率和能源数据
### 修复
- 修复能源传感器数据处理逻辑
- 移除不必要的能源累积计算代码
## [1.1.0] - 2024-12-18
### 新增
- 完整的能源监控传感器支持
- MQTT数据传输示例
- 支持功率和能源两种数据类型
- 电池状态监控
### 改进
- 优化传感器配置
- 改进错误处理
## [1.0.6] - 2024-12-17
### 修复
- 修复传感器初始化问题
## [1.0.5] - 2024-12-16
### 新增
- 初始版本发布
- 基础传感器功能
- MQTT集成

145
DATA_FORMAT.md
View File

@@ -1,145 +0,0 @@
# 数据传输格式说明
## 概述
Energy Monitor 系统使用 MQTT 协议进行数据传输，包含两个主要的通信方向：
1. **Home Assistant → 设备**: 发送数据获取请求
2. **设备 → Home Assistant**: 返回设备数据
## 数据流图
```
Home Assistant 集成
│
▼
/data/data-get (请求)
│
▼
设备端处理
│
▼
/device/data (响应)
│
▼
Home Assistant 集成
│
▼
更新传感器状态
```
## 数据格式
### 1. 数据获取请求
**主题**: `/data/data-get`
**格式**: 纯文本
**内容**: `get_data`
**频率**: 每秒5次（每0.2秒一次）
```bash
主题: /data/data-get
内容: get_data
```
### 2. 设备数据响应
**主题**: `/device/data`
**格式**: JSON
**编码**: UTF-8
#### 完整数据格式
```json
{
"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 设备端示例
```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 客户端测试：
```bash
# 监听数据获取请求
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}'
```
## 注意事项
1. **JSON 格式**: 设备数据必须是有效的 JSON 格式
2. **数值类型**: 所有功率值应为数字类型（int 或 float）
3. **电量范围**: battery_soc 应在 0-100 之间
4. **功率单位**: 所有功率值单位为瓦特 (W)
5. **实时性**: 数据应尽可能实时更新
6. **错误处理**: 设备端应处理数据请求失败的情况
## 数据验证
Home Assistant 集成会验证接收到的数据：
- JSON 格式正确性
- 必需字段存在性
- 数值类型正确性
- 数值范围合理性
如果数据格式不正确，会在日志中记录警告信息。

202
HACS_PUBLISHING_GUIDE.md
View File

@@ -1,202 +0,0 @@
# HACS 发布指南
本指南将帮助您将 JackeryHome 集成发布到 HACS (Home Assistant Community Store)。
## 发布前检查清单
### 1. 项目结构检查
确保项目结构符合 HACS 要求：
```
jackery_home/
├── hacs.json # HACS 配置文件
├── README.md # 项目主文档
├── LICENSE # 许可证文件
└── custom_components/
└── JackeryHome/
├── __init__.py # 集成入口
├── manifest.json # 集成元数据
├── config_flow.py # 配置流程
├── sensor.py # 传感器实现
├── strings.json # 本地化字符串
├── translations/ # 翻译文件
│ └── zh-Hans.json
└── README.md # 集成技术文档
```
### 2. 配置文件检查
#### hacs.json
```json
{
"name": "JackeryHome",
"content_in_root": false,
"render_readme": true,
"domains": [
"jackery_home"
],
"iot_class": "Local Push",
"homeassistant": "2024.1.0"
}
```
#### manifest.json
```json
{
"domain": "jackery_home",
"name": "JackeryHome",
"codeowners": [
"@suyulin"
],
"config_flow": true,
"dependencies": [
"mqtt"
],
"documentation": "https://github.com/suyulin/jackery_home",
"issue_tracker": "https://github.com/suyulin/jackery_home/issues",
"iot_class": "local_push",
"requirements": [
"paho-mqtt>=1.6.0"
],
"version": "1.0.0"
}
```
### 3. 代码质量检查
- [ ] 所有 Python 文件符合 PEP 8 规范
- [ ] 没有语法错误
- [ ] 所有导入都正确
- [ ] 日志记录适当
- [ ] 错误处理完善
## 发布步骤
### 步骤 1: 准备发布
使用提供的发布脚本：
```bash
./prepare_release.sh
```
或手动执行以下步骤：
1. **检查未提交的更改**
```bash
git status
```
2. **提交所有更改**
```bash
git add .
git commit -m "准备发布到 HACS"
```
3. **更新版本号**
编辑 `custom_components/JackeryHome/manifest.json` 中的版本号
4. **提交版本更新**
```bash
git add custom_components/JackeryHome/manifest.json
git commit -m "版本更新至 v1.0.0"
```
### 步骤 2: 推送到 GitHub
```bash
git push origin main
```
### 步骤 3: 创建 Git Tag
```bash
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
```
### 步骤 4: 创建 GitHub Release
#### 方法一：使用 GitHub Web 界面
1. 访问 GitHub 仓库
2. 点击 "Releases" → "Create a new release"
3. 选择刚创建的 tag (v1.0.0)
4. 填写 Release 标题和描述
5. 点击 "Publish release"
#### 方法二：使用 GitHub CLI
```bash
gh release create v1.0.0 --title "v1.0.0" --notes "JackeryHome 集成首次发布"
```
### 步骤 5: 验证发布
1. 检查 GitHub Release 是否创建成功
2. 验证下载链接是否正常
3. 测试从 HACS 安装是否正常
## 用户安装指南
### 通过 HACS 安装
1. **添加自定义存储库**
- 打开 HACS
- 点击右上角三个点 → "自定义存储库"
- 添加仓库 URL：`https://github.com/suyulin/jackery_home`
- 类别选择：`Integration`
- 点击"添加"
2. **安装集成**
- 在 HACS 中搜索 "JackeryHome"
- 点击"安装"
- 重启 Home Assistant
3. **配置集成**
- 进入 **设置** → **设备与服务** → **添加集成**
- 搜索 "JackeryHome"
- 按照配置向导完成设置
## 常见问题
### Q: HACS 中找不到我的集成？
A: 检查以下几点：
- 确保 `hacs.json` 文件存在且格式正确
- 确保 `manifest.json` 中的 `domain` 与 `hacs.json` 中的 `domains` 匹配
- 确保 GitHub Release 已创建
- 等待 HACS 缓存更新（通常需要几分钟）
### Q: 安装后集成无法加载？
A: 检查以下几点：
- 查看 Home Assistant 日志中的错误信息
- 确保所有依赖项已安装
- 检查 `manifest.json` 中的 `requirements` 字段
- 确保代码没有语法错误
### Q: 如何更新集成？
A: 更新流程：
1. 修改代码
2. 更新 `manifest.json` 中的版本号
3. 提交更改并推送到 GitHub
4. 创建新的 Git tag 和 Release
5. 用户在 HACS 中会看到更新通知
## 最佳实践
1. **版本管理**
- 使用语义化版本控制 (SemVer)
- 每次发布都要更新版本号
- 在 Release 中详细描述更改内容
2. **文档维护**
- 保持 README.md 更新
- 提供清晰的安装和使用说明
- 包含故障排除指南
3. **代码质量**
- 定期检查代码质量
- 添加适当的错误处理
- 使用类型提示
4. **用户支持**
- 及时回复 Issues
- 提供清晰的错误信息
- 保持文档更新
## 相关链接
- [HACS 官方文档](https://hacs.xyz/)
- [Home Assistant 开发文档](https://developers.home-assistant.io/)
- [HACS 集成要求](https://hacs.xyz/docs/publish/requirements)
- [GitHub Actions 示例](https://github.com/hacs/integration/tree/main/.github/workflows)

195
MQTT_FIX_SUMMARY.md
View File

@@ -1,195 +0,0 @@
# MQTT 连接问题修复摘要
## 问题描述
用户遇到 MQTT 连接错误：
```
[Errno 113] Host is unreachable
WARNING (MainThread) [custom_components.jackery_home.sensor] MQTT not ready: Error talking
```
## 根本原因
JackeryHome 集成依赖 Home Assistant 的内置 MQTT 组件，但存在以下问题：
1. **配置流程误导**：配置界面收集了 `mqtt_broker` 和 `mqtt_port` 参数，但这些参数从未被使用
2. **缺少依赖检查**：没有验证 MQTT 集成是否已配置和可用
3. **错误提示不明确**：当 MQTT 不可用时，错误消息不够清晰
## 实施的修复
### 1. 更新 `__init__.py` - 添加 MQTT 可用性检查
**变更**：
- 导入 `homeassistant.components.mqtt` 模块
- 在 `async_setup_entry` 中添加 `mqtt.async_wait_for_mqtt_client()` 检查
- 如果 MQTT 不可用，返回 `False` 并记录清晰的错误消息
**代码**：
```python
# 检查 MQTT 集成是否已配置和可用
if not await mqtt.async_wait_for_mqtt_client(hass):
_LOGGER.error(
"MQTT integration is not available or not configured. "
"Please set up the MQTT integration first: "
"Settings -> Devices & Services -> Add Integration -> MQTT"
)
return False
```
### 2. 更新 `config_flow.py` - 简化配置并验证 MQTT
**变更**：
- 移除 `mqtt_broker` 和 `mqtt_port` 配置参数（不再需要）
- 保留 `topic_prefix` 参数（可选配置）
- 在配置时验证 MQTT 集成是否可用
- 添加 `mqtt_not_configured` 错误处理
**更新的配置架构**：
```python
DATA_SCHEMA = vol.Schema(
{
vol.Optional(
"topic_prefix",
default="homeassistant/sensor"
): str,
}
)
```
### 3. 更新 `sensor.py` - 改进错误处理
**变更**：
- 在 `async_start()` 中添加 try-except 块捕获订阅错误
- 改进 MQTT 发布失败时的错误消息
- 提供更清晰的故障排除指导
**改进的错误消息**：
```python
except Exception as mqtt_error:
_LOGGER.warning(
f"MQTT publish failed: {mqtt_error}. "
f"Please check MQTT broker connection. "
f"Will retry in {REQUEST_INTERVAL} seconds..."
)
```
### 4. 更新翻译文件
**`strings.json` 和 `zh-Hans.json`**：
- 更新配置描述，说明需要先配置 MQTT 集成
- 移除 `mqtt_broker` 和 `mqtt_port` 相关文本
- 添加 `mqtt_not_configured` 错误消息
- 更新 `single_instance_allowed` 错误消息
### 5. 创建故障排除文档
**新建 `TROUBLESHOOTING.md`**：
- 详细说明 MQTT 连接问题的原因和解决方案
- 提供 Mosquitto Add-on 和外部 broker 的配置指南
- 包含调试步骤和常用命令
- 说明如何启用详细日志
### 6. 更新集成文档
**更新 `custom_components/JackeryHome/README.md`**：
- 添加"前置要求"章节，强调 MQTT 依赖
- 更新安装步骤，包含 HACS 和手动安装方法
- 更新 MQTT 主题格式说明，反映实际使用的主题
- 扩展故障排除章节，添加常见问题解决方案
- 添加调试日志配置示例
## manifest.json 中的依赖声明
确认 `manifest.json` 中已正确声明 MQTT 依赖：
```json
{
"dependencies": [
"mqtt"
]
}
```
这确保 Home Assistant 在加载 JackeryHome 之前先加载 MQTT 组件。
## 用户需要采取的操作
### 立即操作（修复当前问题）：
1. **配置 MQTT 集成**：
- 进入 Home Assistant：**设置** → **设备与服务**
- 点击 **添加集成**，搜索 **MQTT**
- 输入正确的 MQTT broker 地址和端口
- 如果使用 Mosquitto Add-on，broker 地址通常是 `core-mosquitto` 或 `localhost`
2. **验证 MQTT 连接**：
- 在 MQTT 集成中检查连接状态
- 应显示"已连接"状态
3. **重新加载 JackeryHome 集成**：
- 进入 **设置** → **设备与服务**
- 找到 JackeryHome 集成
- 点击"重新加载"
### 更新后操作：
1. 更新 JackeryHome 集成到最新版本
2. 如果之前配置过 `mqtt_broker` 和 `mqtt_port`，可以删除这些配置（它们不再使用）
3. 确保 MQTT 集成已正确配置
## 技术改进
1. **依赖检查**：明确验证 MQTT 组件可用性
2. **错误处理**：更好的异常捕获和错误消息
3. **用户体验**：清晰的配置指导和错误提示
4. **文档完善**：详细的故障排除指南和使用说明
## 测试建议
### 测试场景 1：MQTT 未配置
1. 确保 MQTT 集成未配置
2. 尝试添加 JackeryHome 集成
3. **预期结果**：显示"MQTT 集成未配置"错误
### 测试场景 2：MQTT 配置但不可达
1. 配置 MQTT 集成但使用错误的 broker 地址
2. 添加 JackeryHome 集成
3. **预期结果**：集成显示错误，日志中有清晰的错误消息
### 测试场景 3：正常工作
1. 正确配置 MQTT 集成并连接
2. 添加 JackeryHome 集成
3. 运行数据模拟器
4. **预期结果**：传感器正常创建并显示数据
## 向后兼容性
- 移除了未使用的 `mqtt_broker` 和 `mqtt_port` 配置选项
- 保留了 `topic_prefix` 配置选项
- 现有安装需要确保 MQTT 集成已配置
## 相关文件
修改的文件：
- `custom_components/JackeryHome/__init__.py`
- `custom_components/JackeryHome/config_flow.py`
- `custom_components/JackeryHome/sensor.py`
- `custom_components/JackeryHome/strings.json`
- `custom_components/JackeryHome/translations/zh-Hans.json`
- `custom_components/JackeryHome/README.md`
新增的文件：
- `TROUBLESHOOTING.md`
- `MQTT_FIX_SUMMARY.md`（本文件）
## 下一步
1. 测试修复是否解决用户的问题
2. 根据用户反馈进一步优化
3. 考虑添加 MQTT 连接状态传感器
4. 更新 CHANGELOG.md
5. 准备新版本发布

75
README.md
View File

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

139
TROUBLESHOOTING.md
View File

@@ -1,139 +0,0 @@
# JackeryHome 故障排除指南
## MQTT 连接问题
### 问题：Host is unreachable 错误
如果您在 Home Assistant 日志中看到以下错误：
```
ERROR (MainThread) [homeassistant.components.mqtt.client] Error re-connecting to MQTT server due to exception: [Errno 113] Host is unreachable
WARNING (MainThread) [custom_components.jackery_home.sensor] MQTT not ready: Error talking
```
**原因：**
JackeryHome 集成依赖于 Home Assistant 的内置 MQTT 集成。该错误表明 Home Assistant 无法连接到配置的 MQTT broker。
**解决方案：**
#### 1. 确认已安装并配置 MQTT 集成
1. 进入 Home Assistant：**设置** → **设备与服务**
2. 检查是否已添加 **MQTT** 集成
3. 如果没有，点击 **添加集成**，搜索并添加 **MQTT**
#### 2. 配置正确的 MQTT Broker 地址
在 MQTT 集成配置中，确保：
- **Broker 地址**：填写您的 MQTT broker 的 IP 地址或主机名
- 如果使用 Mosquitto Add-on：通常是 `localhost` 或 `core-mosquitto`
- 如果使用独立 MQTT broker：填写其 IP 地址（例如 `192.168.1.100`）
- **端口**：默认为 `1883`（或 TLS 加密使用 `8883`）
- **用户名/密码**：如果 broker 需要认证，请填写
#### 3. 检查网络连接
确保 Home Assistant 可以访问 MQTT broker：
```bash
# 在 Home Assistant 容器/主机中测试连接
ping <mqtt_broker_ip>
telnet <mqtt_broker_ip> 1883
```
#### 4. 检查 MQTT Broker 是否运行
如果使用 Mosquitto Add-on：
1. 进入 **设置** → **加载项**
2. 找到 **Mosquitto broker**
3. 确认状态为 **已启动**
4. 查看日志确认没有错误
#### 5. 重新配置 JackeryHome 集成
在 MQTT 集成正确配置后：
1. 进入 **设置** → **设备与服务**
2. 找到 **JackeryHome** 集成
3. 如果仍有问题，尝试删除并重新添加该集成
### 问题：MQTT publish failed
如果看到 "MQTT publish failed" 错误，但 MQTT 集成已配置：
1. **重启 MQTT broker**
2. **重启 Home Assistant**
3. 检查 MQTT broker 日志中是否有连接错误
4. 确认 MQTT broker 没有达到连接限制
### 问题：数据未更新
如果传感器显示"不可用"或数据不更新：
1. **检查 MQTT 主题**：确认设备正在向正确的主题发布数据
- LWT 主题：`v1/iot_gw/gw_lwt`
- 数据主题：`v1/iot_gw/gw/data`
2. **使用 MQTT Explorer 监控**：
- 安装 MQTT Explorer（桌面应用）
- 连接到您的 broker
- 订阅 `v1/iot_gw/#` 查看是否有数据
3. **检查设备序列号**：
- 查看传感器的属性，确认 `device_sn` 是否正确
- 确认设备已上线并发送了 LWT 消息
## 常见配置问题
### 使用 Mosquitto Add-on
推荐配置：
- **Broker**: `core-mosquitto` 或 `localhost`
- **Port**: `1883`
### 使用外部 MQTT Broker
1. 确保防火墙允许 1883 端口
2. 如果使用 Docker，确保网络配置正确
3. 考虑使用 TLS 加密连接（端口 8883）
## 调试步骤
### 启用详细日志
在 `configuration.yaml` 中添加：
```yaml
logger:
default: info
logs:
custom_components.jackery_home: debug
homeassistant.components.mqtt: debug
```
重启 Home Assistant 后，日志将显示更详细的 MQTT 交互信息。
### 手动测试 MQTT 连接
使用 `mosquitto_pub` 和 `mosquitto_sub` 工具测试：
```bash
# 订阅主题
mosquitto_sub -h <broker_ip> -t "v1/iot_gw/#" -v
# 发布测试消息
mosquitto_pub -h <broker_ip> -t "v1/iot_gw/test" -m "test message"
```
## 获取帮助
如果问题仍未解决，请在 GitHub 上提交 issue，并提供：
1. Home Assistant 版本
2. JackeryHome 集成版本
3. MQTT broker 类型和版本
4. 完整的错误日志（启用调试日志后）
5. MQTT 集成配置（隐藏敏感信息）
GitHub 仓库：https://github.com/your-repo/jackery_home

142
custom_components/JackeryHome/README.md
View File

@@ -4,7 +4,9 @@
## 功能特性 ## 功能特性
该集成会自动创建以下传感器： 该集成采用**协调器模式**（Coordinator Pattern），所有传感器共享一个 `JackeryDataCoordinator` 实例，统一管理 MQTT 订阅和数据请求，提高效率并减少资源占用。
### 功率传感器（实时监测）
- **Solar Power** (太阳能发电功率) - 单位：W - **Solar Power** (太阳能发电功率) - 单位：W
- **Home Power** (家庭负载功率) - 单位：W - **Home Power** (家庭负载功率) - 单位：W
@@ -14,6 +16,15 @@
- **Battery Discharge** (电池放电功率) - 单位：W - **Battery Discharge** (电池放电功率) - 单位：W
- **Battery State of Charge** (电池电量) - 单位：% - **Battery State of Charge** (电池电量) - 单位：%
### 能源传感器（用于能源仪表板）
- **Solar Energy** (太阳能发电总量) - 单位：kWh
- **Home Energy** (家庭用电总量) - 单位：kWh
- **Grid Import Energy** (电网购买总量) - 单位：kWh
- **Grid Export Energy** (电网出售总量) - 单位：kWh
- **Battery Charge Energy** (电池充电总量) - 单位：kWh
- **Battery Discharge Energy** (电池放电总量) - 单位：kWh
## 前置要求 ## 前置要求
⚠️ **重要：本集成依赖 Home Assistant 的 MQTT 集成** ⚠️ **重要：本集成依赖 Home Assistant 的 MQTT 集成**
@@ -66,18 +77,90 @@ config/
如果 MQTT 集成未配置或不可用，将显示错误提示。 如果 MQTT 集成未配置或不可用，将显示错误提示。
## 架构设计
### 协调器模式
集成使用 `JackeryDataCoordinator` 类统一管理所有传感器的数据获取：
- **单一协调器实例**：所有传感器共享一个协调器，避免重复订阅和请求
- **统一数据请求**：每 5 秒发送一次 `data_get` 请求，包含所有传感器的 `meter_sn`
- **自动分发数据**：协调器接收响应后，根据 `meter_sn` 自动分发给对应的传感器
- **设备序列号管理**：通过 LWT 消息自动获取和更新设备序列号
### 数据流程
1. **启动阶段**：
- 协调器订阅 LWT 主题 (`v1/iot_gw/gw_lwt`) 获取设备序列号
- 协调器订阅数据响应主题 (`v1/iot_gw/gw/data`)
- 启动定时任务，每 5 秒发送一次数据请求
2. **数据请求**：
- 协调器收集所有传感器的 `meter_sn`
- 构造包含所有 `meter_sn` 的 `data_get` 请求
- 发送到 `v1/iot_gw/cloud/data` 主题
3. **数据处理**：
- 接收设备响应（JSON 格式）
- 解析 `meter_list` 中的 `[meter_sn, meter_value]` 数据
- 根据 `meter_sn` 匹配对应的传感器实体
- 调用传感器的 `_process_meter_value()` 处理特殊值（如正负分离）
- 更新传感器状态并通知 Home Assistant
## MQTT 主题格式 ## MQTT 主题格式
集成会订阅以下 MQTT 主题来接收设备数据： 集成会订阅以下 MQTT 主题来接收设备数据：
- **LWT 主题**: `v1/iot_gw/gw_lwt` - 接收设备上线/离线状态和序列号 - **LWT 主题**: `v1/iot_gw/gw_lwt` - 接收设备上线/离线状态和序列号
- **数据主题**: `v1/iot_gw/gw/data` - 接收设备响应的传感器数据 ```json
{
"gw_sn": "26392658575364"
}
```
- **数据响应主题**: `v1/iot_gw/gw/data` - 接收设备响应的传感器数据
```json
{
"cmd": "data_get",
"info": {
"dev_list": [
{
"dev_sn": "ems_26392658575364",
"meter_list": [
["1026001", 2500.0],
["21171201", 1800.0],
...
]
}
]
}
}
```
集成会定期向以下主题发送数据请求： 集成会定期向以下主题发送数据请求：
- **请求主题**: `v1/iot_gw/cloud/data` - 发送 `data_get` 命令请求传感器数据 - **请求主题**: `v1/iot_gw/cloud/data` - 发送 `data_get` 命令请求传感器数据
```json
{
"cmd": "data_get",
"gw_sn": "26392658575364",
"timestamp": "1234567890123",
"token": "5678",
"info": {
"dev_list": [
{
"dev_sn": "ems_26392658575364",
"meter_list": ["1026001", "21171201", "16930817", ...]
}
]
}
}
```
消息格式遵循 Jackery 设备的标准协议（JSON 格式），包含设备序列号、meter 列表等信息。 ### 数据请求间隔
- **默认间隔**：5 秒（`REQUEST_INTERVAL = 5`）
- 所有传感器共享同一个请求，减少 MQTT 消息数量
## 与模拟器配合使用 ## 与模拟器配合使用
@@ -95,8 +178,12 @@ config/
配置完成后，你可以在以下位置查看传感器： 配置完成后，你可以在以下位置查看传感器：
- **开发者工具** → **状态** → 搜索 "energy_monitor" - **开发者工具** → **状态** → 搜索 "jackery" 或传感器名称
- 传感器实体 ID 格式：`sensor.solar_power`、`sensor.home_power` 等 - 传感器实体 ID 格式：`sensor.solar_power`、`sensor.home_power`、`sensor.solar_energy` 等
- 每个传感器包含以下属性：
- `sensor_id`: 传感器内部标识
- `meter_sn`: 对应的 meter 序列号
- `device_sn`: 设备序列号（从 LWT 消息获取）
## 在 Lovelace 中使用 ## 在 Lovelace 中使用
@@ -140,6 +227,9 @@ entities:
3. 使用 MQTT Explorer 监听 `v1/iot_gw/#` 主题查看消息 3. 使用 MQTT Explorer 监听 `v1/iot_gw/#` 主题查看消息
4. 查看 Home Assistant 日志：**设置** → **系统** → **日志** 4. 查看 Home Assistant 日志：**设置** → **系统** → **日志**
5. 确认传感器属性中的 `device_sn` 是否正确 5. 确认传感器属性中的 `device_sn` 是否正确
6. 检查协调器是否已启动：日志中应看到 "Coordinator subscribed to LWT topic" 和 "Coordinator subscribed to data topic"
7. 确认数据请求是否发送：日志中应看到 "Coordinator sent data_get request"
8. 验证设备响应格式：响应应包含 `cmd: "data_get"` 和正确的 `meter_list` 结构
### 启用调试日志 ### 启用调试日志
@@ -153,13 +243,47 @@ logger:
homeassistant.components.mqtt: debug homeassistant.components.mqtt: debug
``` ```
## 传感器值处理逻辑
集成会根据传感器类型对原始 `meter_value` 进行特殊处理：
- **Grid Import**：仅显示负值（取绝对值），正值显示为 0
- **Grid Export**：仅显示正值，负值显示为 0
- **Battery Charge**：仅显示负值（取绝对值），正值显示为 0
- **Battery Discharge**：仅显示正值，负值显示为 0
- **Battery SOC**：原始值乘以 0.1 转换为百分比
- **其他传感器**：直接使用原始值
## Meter SN 映射
每个传感器对应一个唯一的 `meter_sn`，用于在设备响应中识别数据：
| 传感器 ID | Meter SN |
|----------|----------|
| `solar_power` | 1026001 |
| `home_power` | 21171201 |
| `grid_import_power` / `grid_export_power` | 16930817 |
| `battery_charge_power` / `battery_discharge_power` | 16931841 |
| `battery_soc` | 21548033 |
| `solar_energy` | 16961537 |
| `home_energy` | 16936961 |
| `grid_import_energy` | 16959489 |
| `grid_export_energy` | 16960513 |
| `battery_charge_energy` | 16952321 |
| `battery_discharge_energy` | 16953345 |
## 技术细节 ## 技术细节
- **架构模式**: 协调器模式（Coordinator Pattern）
- **依赖**: Home Assistant MQTT 集成 - **依赖**: Home Assistant MQTT 集成
- **协议**: MQTT - **协议**: MQTT (QoS 1)
- **更新方式**: Push（实时推送） - **更新方式**: 主动请求 + 推送响应（每 5 秒）
- **传感器类型**: 功率传感器、电池传感器 - **传感器类型**: 功率传感器、能源传感器、电池传感器
- **状态类**: Measurement（测量值） - **状态类**:
- 功率传感器：`MEASUREMENT`（测量值）
- 能源传感器：`TOTAL_INCREASING`（累计递增）
- 电池传感器：`MEASUREMENT`（测量值）
- **设备类**: `POWER`、`ENERGY`、`BATTERY`
## 许可证 ## 许可证

97
test_mqtt.py
View File

@@ -1,97 +0,0 @@
#!/usr/bin/env python3
"""
测试 MQTT 数据发送脚本
用于测试 JackeryHome 集成是否能正确接收数据
"""
import json
import time
import paho.mqtt.client as mqtt
import random
# MQTT 配置
MQTT_BROKER = "192.168.0.101" # 修改为你的 MQTT Broker 地址
MQTT_PORT = 1883
TOPIC_PREFIX = "homeassistant/sensor"
def on_connect(client, userdata, flags, rc):
"""连接回调"""
if rc == 0:
print("✅ 成功连接到 MQTT Broker")
else:
print(f"❌ 连接失败，错误代码: {rc}")
def on_publish(client, userdata, mid):
"""发布回调"""
print(f"📤 消息已发布，ID: {mid}")
def main():
"""主函数"""
print("🚀 启动 JackeryHome MQTT 测试脚本")
print(f"📡 MQTT Broker: {MQTT_BROKER}:{MQTT_PORT}")
print(f"📂 Topic Prefix: {TOPIC_PREFIX}")
print("-" * 50)
# 创建 MQTT 客户端
client = mqtt.Client(client_id="jackery_home_test", callback_api_version=mqtt.CallbackAPIVersion.VERSION2)
client.on_connect = on_connect
client.on_publish = on_publish
try:
# 连接到 MQTT Broker
print("🔗 正在连接到 MQTT Broker...")
client.connect(MQTT_BROKER, MQTT_PORT, 60)
client.loop_start()
# 等待连接
time.sleep(2)
# 模拟数据
sensors = {
"solar_power": {"min": 200, "max": 3000, "unit": "W"},
"home_power": {"min": 500, "max": 3500, "unit": "W"},
"grid_import": {"min": 0, "max": 2000, "unit": "W"},
"grid_export": {"min": 0, "max": 1500, "unit": "W"},
"battery_charge": {"min": 0, "max": 1000, "unit": "W"},
"battery_discharge": {"min": 0, "max": 1000, "unit": "W"},
"battery_soc": {"min": 20, "max": 100, "unit": "%"},
}
print("📊 开始发送测试数据...")
print("按 Ctrl+C 停止")
print("-" * 50)
count = 0
while True:
count += 1
print(f"\n🔄 第 {count} 轮数据发送:")
for sensor_id, config in sensors.items():
# 生成随机值
value = random.randint(config["min"], config["max"])
# 构建主题
topic = f"{TOPIC_PREFIX}/{sensor_id}/state"
# 发送数据
result = client.publish(topic, str(value))
if result.rc == mqtt.MQTT_ERR_SUCCESS:
print(f" ✅ {sensor_id}: {value} {config['unit']} -> {topic}")
else:
print(f" ❌ {sensor_id}: 发送失败")
# 等待 5 秒
time.sleep(5)
except KeyboardInterrupt:
print("\n\n⏹️ 用户中断，正在停止...")
except Exception as e:
print(f"\n❌ 发生错误: {e}")
finally:
# 清理资源
client.loop_stop()
client.disconnect()
print("🔚 测试脚本已停止")
if __name__ == "__main__":
main()