impress_sig_mesh_hacs/问题修复记录.md

问题修复记录

2026-04-16: 修复 callback 导入缺失错误

问题描述

配置集成时出现 "Invalid handler specified" 错误

错误日志

错误：配置流程无法加载

无法加载配置向导：{"message":"Invalid handler specified"}

原因: config_flow.py 中使用了 @callback 装饰器但没有导入

解决方案

修复：添加 callback 导入

from homeassistant.core import callback

提交记录

Commit	说明
4031747	fix: 添加缺失的 callback 导入

部署步骤

cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/
ha core restart

---

2026-04-16: 修复平台加载和 OptionsFlow 错误（第二次修复）

问题描述

平台文件设置时出现 'NoneType' object has no attribute 'values' 错误

错误日志

错误 1: 平台文件访问 None 数据

AttributeError: 'NoneType' object has no attribute 'values'
File: sensor.py, line 40
File: binary_sensor.py, line 37
File: switch.py, line 34
File: light.py, line 40
File: device_tracker.py, line 34

原因: coordinator.data 在初始化时为 None

错误 2: OptionsFlow 初始化错误

TypeError: SigMeshGatewayOptionsFlow() takes no arguments
File: config_flow.py, line 74

原因: async_get_options_flow 是静态方法，传递了 config_entry 参数，但 __init__ 不接受参数

解决方案

修复 1: 平台文件添加 None 检查

async def async_setup_entry(...):
    if coordinator.data is None:
        _LOGGER.debug("协调器数据为空，等待设备数据")
        return

    for device in coordinator.data.values():
        ...

修复 2: 修复 async_get_options_flow

@callback
def async_get_options_flow(self) -> SigMeshGatewayOptionsFlow:
    """获取选项流程."""
    return SigMeshGatewayOptionsFlow()

修复 3: OptionsFlow 添加 init

class SigMeshGatewayOptionsFlow(config_entries.OptionsFlow):
    def __init__(self) -> None:
        """初始化选项流程."""
        self._errors: dict[str, str] = {}

提交记录

Commit	说明
311cfbb	fix: 修复平台文件和 OptionsFlow 错误

部署步骤

cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/
ha core restart

---

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 中重新尝试添加集成，应能正常显示配置表单。