363f76b26f
- 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.
140 lines
3.8 KiB
Markdown
140 lines
3.8 KiB
Markdown
# 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
|
||
|