impress_sig_mesh_hacs/问题修复记录.md

问题修复记录

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: 移动平台文件到集成根目录

# 从 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

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 错误

部署步骤

# 复制更新后的集成文件
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 类型注解

+ 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 依赖

- "requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"],
+ "requirements": ["pyserial-asyncio-fast>=0.6"],

修复 3: coordinator.py 导入

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 类型注解错误

部署步骤

# 复制更新后的集成文件
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 中重新尝试添加集成，应能正常显示配置表单。