149 lines
4.0 KiB
Markdown
149 lines
4.0 KiB
Markdown
# 问题修复记录
|
||
|
||
## 2026-04-16: 修复平台加载和 OptionsFlow 错误
|
||
|
||
### 问题描述
|
||
配置集成时出现错误，无法加载平台实体
|
||
|
||
### 错误日志
|
||
|
||
#### 错误 1: 平台模块加载失败
|
||
```
|
||
ModuleNotFoundError: No module named 'custom_components.sigmesh_gateway.sensor'
|
||
```
|
||
|
||
**原因**: 平台文件放在 `platforms/` 子目录中，但 HA 期望平台文件直接在集成根目录下
|
||
|
||
#### 错误 2: OptionsFlow config_entry 错误
|
||
```
|
||
AttributeError: property 'config_entry' of 'SigMeshGatewayOptionsFlow' object has no setter
|
||
```
|
||
|
||
**原因**: 新版 HA 中 OptionsFlow 自动提供 `self.config_entry`，不需要手动设置
|
||
|
||
### 解决方案
|
||
|
||
#### 修复 1: 移动平台文件到集成根目录
|
||
```bash
|
||
# 从 platforms/ 移到根目录
|
||
mv platforms/sensor.py .
|
||
mv platforms/binary_sensor.py .
|
||
mv platforms/switch.py .
|
||
mv platforms/light.py .
|
||
mv platforms/device_tracker.py .
|
||
rmdir platforms
|
||
```
|
||
|
||
#### 修复 2: 修复 OptionsFlow
|
||
```diff
|
||
class SigMeshGatewayOptionsFlow(config_entries.OptionsFlow):
|
||
"""SigMesh Gateway 选项流程."""
|
||
|
||
- def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
|
||
- """初始化选项流程."""
|
||
- self.config_entry = config_entry
|
||
|
||
async def async_step_init(self, user_input: dict[str, Any] | None = None) -> FlowResult:
|
||
```
|
||
|
||
#### 修复 3: 添加集成图标
|
||
- 复制图标到 `custom_components/sigmesh_gateway/icons/icon.png`
|
||
- HA 会自动识别该图标并显示在集成页面
|
||
|
||
### 提交记录
|
||
| Commit | 说明 |
|
||
|--------|------|
|
||
| 19774a4 | fix: 修复平台加载和 OptionsFlow 错误 |
|
||
|
||
### 部署步骤
|
||
```bash
|
||
# 复制更新后的集成文件
|
||
cp -r /home/ubuntu/workspace/cherry-studio/enginneer/impress_sig_mesh_hacs/custom_components/sigmesh_gateway \
|
||
<HA 配置目录>/custom_components/
|
||
|
||
# 重启 Home Assistant
|
||
ha core restart
|
||
```
|
||
|
||
### 验证
|
||
重启后，在 HA UI 中重新尝试添加集成，应能正常显示配置表单和创建实体。
|
||
|
||
---
|
||
|
||
## 2026-04-15: 修复配置向导 500 错误
|
||
|
||
### 问题描述
|
||
添加集成时出现 500 Internal Server Error
|
||
|
||
### 根本原因
|
||
1. **类型注解错误**：`config_flow.py` 使用了小写 `any` 而非 `Any`
|
||
2. **依赖包不存在**：`manifest.json` 中引用了不存在的 `bleak-mesh>=0.2.0`
|
||
3. **导入错误**：`coordinator.py` 从错误的模块导入 `MeshMessageEvent` 和 `ProvDeviceEvent`
|
||
|
||
### 错误日志
|
||
|
||
#### 错误 1: 依赖包不存在
|
||
```
|
||
homeassistant.requirements.RequirementsNotFound:
|
||
Requirements for sigmesh_gateway not found: ['bleak-mesh>=0.2.0'].
|
||
```
|
||
|
||
#### 错误 2: 导入错误
|
||
```
|
||
Error occurred loading flow for integration sigmesh_gateway:
|
||
cannot import name 'MeshMessageEvent' from 'custom_components.sigmesh_gateway.protocol_parser'
|
||
```
|
||
|
||
### 解决方案
|
||
|
||
#### 修复 1: config_flow.py 类型注解
|
||
```diff
|
||
+ from typing import Any
|
||
|
||
- async def async_step_user(self, user_input: dict[str, any] | None = None) -> FlowResult:
|
||
+ async def async_step_user(self, user_input: dict[str, Any] | None = None) -> FlowResult:
|
||
```
|
||
|
||
#### 修复 2: manifest.json 依赖
|
||
```diff
|
||
- "requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"],
|
||
+ "requirements": ["pyserial-asyncio-fast>=0.6"],
|
||
```
|
||
|
||
#### 修复 3: coordinator.py 导入
|
||
```diff
|
||
from .protocol_parser import (
|
||
DeviceManager,
|
||
DeviceState,
|
||
- MeshMessageEvent,
|
||
ParsedMeshMessage,
|
||
- ProvDeviceEvent,
|
||
ProtocolParser,
|
||
)
|
||
+ from .serial_reader import (
|
||
+ MeshMessageEvent,
|
||
+ ProvDeviceEvent,
|
||
+ SerialReader,
|
||
+ )
|
||
```
|
||
|
||
### 提交记录
|
||
| Commit | 说明 |
|
||
|--------|------|
|
||
| 472fec4 | fix: 修复 coordinator.py 导入错误 |
|
||
| e905410 | fix: 修复 manifest.json 依赖错误 |
|
||
| 66b86e3 | fix: 修复 config_flow.py 类型注解错误 |
|
||
|
||
### 部署步骤
|
||
```bash
|
||
# 复制更新后的集成文件
|
||
cp -r /home/ubuntu/workspace/cherry-studio/enginneer/impress_sig_mesh_hacs/custom_components/sigmesh_gateway \
|
||
<HA 配置目录>/custom_components/
|
||
|
||
# 重启 Home Assistant
|
||
ha core restart
|
||
```
|
||
|
||
### 验证
|
||
重启后，在 HA UI 中重新尝试添加集成，应能正常显示配置表单。
|