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. 准备新版本发布
|
||||
|
||||
Reference in New Issue
Block a user