feat: add MQTT connection issue summary and troubleshooting guide
- Introduced a comprehensive summary of MQTT connection issues and their resolutions in `MQTT_FIX_SUMMARY.md`. - Created a detailed troubleshooting guide in `TROUBLESHOOTING.md` to assist users in resolving common MQTT-related problems. - Updated `README.md` to include prerequisites for MQTT integration and enhanced error handling instructions. - Improved user experience by clarifying configuration steps and providing clear error messages for MQTT integration issues.
This commit is contained in:
不求圣剑
195
MQTT_FIX_SUMMARY.md
Normal file
195
MQTT_FIX_SUMMARY.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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. 准备新版本发布
|
||||
|
||||
139
TROUBLESHOOTING.md
Normal file
139
TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 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
|
||||
|
||||
@@ -14,63 +14,70 @@
|
||||
- **Battery Discharge** (电池放电功率) - 单位：W
|
||||
- **Battery State of Charge** (电池电量) - 单位：%
|
||||
|
||||
## 前置要求
|
||||
|
||||
⚠️ **重要：本集成依赖 Home Assistant 的 MQTT 集成**
|
||||
|
||||
在安装 JackeryHome 之前，您必须先配置 MQTT 集成：
|
||||
|
||||
1. 进入 Home Assistant 的 **设置** → **设备与服务**
|
||||
2. 点击 **添加集成**，搜索 **MQTT**
|
||||
3. 配置您的 MQTT broker 连接信息：
|
||||
- **Broker**: MQTT broker 地址（例如：`localhost`、`core-mosquitto` 或 IP 地址）
|
||||
- **Port**: 端口号（默认：`1883`）
|
||||
- **Username/Password**: 如需要认证，请填写
|
||||
|
||||
## 安装步骤
|
||||
|
||||
### 1. 复制文件到 Home Assistant
|
||||
### 方式 A：通过 HACS 安装（推荐）
|
||||
|
||||
将 `custom_components/energy_monitor` 文件夹复制到 Home Assistant 的 `config/custom_components/` 目录下：
|
||||
1. 确保已安装 [HACS](https://hacs.xyz/)
|
||||
2. 进入 HACS → 集成
|
||||
3. 点击右上角菜单 → 自定义仓库
|
||||
4. 添加此仓库 URL 并选择类别为"集成"
|
||||
5. 搜索 "JackeryHome" 并安装
|
||||
6. 重启 Home Assistant
|
||||
|
||||
### 方式 B：手动安装
|
||||
|
||||
将 `custom_components/JackeryHome` 文件夹复制到 Home Assistant 的 `config/custom_components/` 目录下：
|
||||
|
||||
```
|
||||
config/
|
||||
custom_components/
|
||||
energy_monitor/
|
||||
JackeryHome/
|
||||
__init__.py
|
||||
manifest.json
|
||||
sensor.py
|
||||
config_flow.py
|
||||
README.md
|
||||
```
|
||||
|
||||
### 2. 重启 Home Assistant
|
||||
|
||||
复制文件后，重启 Home Assistant 以加载新的集成。
|
||||
|
||||
### 3. 配置集成
|
||||
|
||||
有两种配置方式：
|
||||
|
||||
#### 方式 A：通过 UI 配置（推荐）
|
||||
|
||||
1. 进入 Home Assistant 的 **设置** → **设备与服务**
|
||||
2. 点击右下角的 **添加集成** 按钮
|
||||
3. 搜索 "JackeryHome"
|
||||
4. 输入 MQTT 主题前缀（默认：`homeassistant/sensor`）
|
||||
5. 点击提交完成配置
|
||||
|
||||
#### 方式 B：通过 configuration.yaml 配置
|
||||
|
||||
在 `configuration.yaml` 中添加：
|
||||
|
||||
```yaml
|
||||
energy_monitor:
|
||||
topic_prefix: "homeassistant/sensor"
|
||||
strings.json
|
||||
translations/
|
||||
```
|
||||
|
||||
然后重启 Home Assistant。
|
||||
|
||||
### 配置集成
|
||||
|
||||
1. 进入 Home Assistant 的 **设置** → **设备与服务**
|
||||
2. 点击右下角的 **添加集成** 按钮
|
||||
3. 搜索 "JackeryHome"
|
||||
4. 输入 MQTT 主题前缀（可选，默认：`homeassistant/sensor`）
|
||||
5. 点击提交完成配置
|
||||
|
||||
如果 MQTT 集成未配置或不可用，将显示错误提示。
|
||||
|
||||
## MQTT 主题格式
|
||||
|
||||
集成会订阅以下 MQTT 主题（假设 topic_prefix 为 `homeassistant/sensor`）：
|
||||
集成会订阅以下 MQTT 主题来接收设备数据：
|
||||
|
||||
- `homeassistant/sensor/solar_power/state`
|
||||
- `homeassistant/sensor/home_power/state`
|
||||
- `homeassistant/sensor/grid_import/state`
|
||||
- `homeassistant/sensor/grid_export/state`
|
||||
- `homeassistant/sensor/battery_charge/state`
|
||||
- `homeassistant/sensor/battery_discharge/state`
|
||||
- `homeassistant/sensor/battery_soc/state`
|
||||
- **LWT 主题**: `v1/iot_gw/gw_lwt` - 接收设备上线/离线状态和序列号
|
||||
- **数据主题**: `v1/iot_gw/gw/data` - 接收设备响应的传感器数据
|
||||
|
||||
每个主题接收的消息格式为纯数字，例如：`1234.56`
|
||||
集成会定期向以下主题发送数据请求：
|
||||
|
||||
- **请求主题**: `v1/iot_gw/cloud/data` - 发送 `data_get` 命令请求传感器数据
|
||||
|
||||
消息格式遵循 Jackery 设备的标准协议（JSON 格式），包含设备序列号、meter 列表等信息。
|
||||
|
||||
## 与模拟器配合使用
|
||||
|
||||
@@ -115,16 +122,36 @@ entities:
|
||||
|
||||
## 故障排除
|
||||
|
||||
### MQTT 连接错误
|
||||
|
||||
如果看到 "Host is unreachable" 或 "MQTT not ready" 错误：
|
||||
|
||||
1. **检查 MQTT 集成**：确保 MQTT 集成已配置且连接正常
|
||||
2. **验证 Broker 地址**：确认 MQTT broker 地址和端口正确
|
||||
3. **测试连接**：在终端使用 `mosquitto_sub` 测试 MQTT 连接
|
||||
4. **查看详细日志**：启用调试日志查看更多信息
|
||||
|
||||
详细的故障排除指南请参考：[TROUBLESHOOTING.md](../../../TROUBLESHOOTING.md)
|
||||
|
||||
### 传感器不显示数据
|
||||
|
||||
1. 检查 MQTT broker 是否正常运行
|
||||
2. 检查 Home Assistant 的 MQTT 集成是否已配置
|
||||
3. 检查 `main.py` 中的 MQTT broker 地址是否正确
|
||||
2. 确认设备已连接并发送 LWT 消息到 `v1/iot_gw/gw_lwt`
|
||||
3. 使用 MQTT Explorer 监听 `v1/iot_gw/#` 主题查看消息
|
||||
4. 查看 Home Assistant 日志：**设置** → **系统** → **日志**
|
||||
5. 确认传感器属性中的 `device_sn` 是否正确
|
||||
|
||||
### 查看 MQTT 消息
|
||||
### 启用调试日志
|
||||
|
||||
使用 MQTT 客户端工具（如 MQTT Explorer）监听 `homeassistant/sensor/#` 主题，确认消息是否正常发布。
|
||||
在 `configuration.yaml` 中添加：
|
||||
|
||||
```yaml
|
||||
logger:
|
||||
default: info
|
||||
logs:
|
||||
custom_components.jackery_home: debug
|
||||
homeassistant.components.mqtt: debug
|
||||
```
|
||||
|
||||
## 技术细节
|
||||
|
||||
|
||||
Reference in New Issue
Block a user