impress_sig_mesh_hacs/调试检查清单.md

SigMesh Gateway - 调试检查清单

用途: 系统化排查问题，确保不遗漏任何步骤

---

阶段 1: 部署前检查

1.1 硬件检查

• 网关已正确供电
• USB 转 TTL 模块工作正常
• 接线正确（TX→RX, RX→TX, GND→GND）
• 电压匹配（3.3V 或 5V）

1.2 系统检查

• HAOS 版本 ≥ 2024.1.0
• HACS 已安装且版本 ≥ 1.34.0
• 串口驱动已安装

# 检查串口设备
ls -l /dev/ttyUSB*
# 预期输出：crw-rw---- 1 root dialout ... /dev/ttyUSB0

1.3 权限检查

• homeassistant 用户在 dialout 组
• 串口设备权限正确

# 检查用户组
groups homeassistant

# 如需添加权限
sudo usermod -a -G dialout homeassistant
# 然后重启 HA

---

阶段 2: 安装检查

2.1 文件完整性

• custom_components/sigmesh_gateway/ 目录存在
• __init__.py 存在
• manifest.json 存在且格式正确
• const.py 存在
• config_flow.py 存在
• coordinator.py 存在
• serial_reader.py 存在
• protocol_parser.py 存在
• platforms/ 目录及所有平台文件存在

2.2 HACS 注册

• hacs.json 存在且格式正确
• README.md 存在

2.3 安装验证

# 检查文件结构
find ~/.homeassistant/custom_components/sigmesh_gateway/ -type f

---

阶段 3: 配置检查

3.1 UI 配置

• 集成出现在"添加集成"列表中
• 串口设备可选择
• 配置可提交
• 配置后集成状态为"已加载"

3.2 YAML 配置（如使用）

# 检查 YAML 语法
ha core check

# 预期输出：Configuration check completed

---

阶段 4: 启动检查

4.1 启动日志

# 查看启动日志
tail -f ~/.homeassistant/home-assistant.log | grep sigmesh

检查项：

• 看到"设置 SigMesh Gateway 集成"
• 看到"串口已连接"
• 看到"SigMesh Gateway 协调器已启动"
• 无 ERROR 级别日志

4.2 实体创建

• 进入"设置 → 设备与服务"
• 看到 SigMesh Gateway 集成
• 点击后看到设备列表
• 实体出现在"设置 → 实体"

---

阶段 5: 数据接收检查

5.1 串口通信验证

# 手动测试串口
screen /dev/ttyUSB0 115200

# 发送测试命令
AT
# 预期返回：OK

# 退出：Ctrl+A, 然后 K, 然后 Y

5.2 数据接收验证

• 日志中看到"串口接收：+EVENT=..."
• 无"解码失败"错误
• 无"无效的 Mesh 消息格式"警告

5.3 协议解析验证

• Opcode 正确识别
• Payload 正确解析
• 设备状态正确更新

---

阶段 6: 实体功能检查

6.1 传感器

• 传感器实体存在
• 状态值合理
• 单位正确显示
• 状态随时间更新

6.2 开关（如有）

• 开关实体存在
• 状态显示正确
• （如已实现）开关操作响应

6.3 灯光（如有）

• 灯光实体存在
• 亮度调节响应
• 开关操作响应

6.4 设备追踪

• tracker 实体存在
• 状态为"home"或"not_home"

---

阶段 7: 压力测试

7.1 多设备测试

• 连接 10 个设备，系统稳定
• 连接 50 个设备，系统稳定
• 连接 100 个设备，系统稳定
• 连接 200 个设备，系统稳定

7.2 性能监控

# 查看内存占用
ps aux | grep homeassistant

# 查看 CPU 占用
top -p $(pgrep -f homeassistant)

检查项：

• 内存占用 < 50MB
• CPU 占用 < 5%
• 无明显内存泄漏

---

阶段 8: 异常处理检查

8.1 串口断开测试

• 拔掉 USB 转 TTL 模块
• 日志中看到"串口连接已断开"
• 系统尝试重连
• 插回后自动恢复连接

8.2 异常数据处理

• 发送畸形数据
• 系统不崩溃
• 日志中记录错误
• 正常数据继续处理

---

阶段 9: 日志分析

9.1 日志级别验证

# 临时启用详细日志
logger:
  logs:
    custom_components.sigmesh_gateway: debug

检查项：

• DEBUG 日志显示原始数据
• DEBUG 日志显示解析过程
• INFO 日志显示关键事件
• WARNING 日志显示警告
• ERROR 日志显示错误详情

9.2 日志清理

• 测试完成后恢复日志级别
• 生产环境不启用 DEBUG

---

阶段 10: 文档记录

10.1 配置记录

• 记录实际使用的配置参数
• 记录调整过的参数值
• 记录参数调整原因

10.2 问题记录

• 记录遇到的问题
• 记录解决方案
• 记录排查步骤

---

快速诊断流程

问题现象
    ↓
┌─────────────────┐
│ 1. 检查集成状态 │
│    设置 → 设备与服务 │
└────────┬────────┘
         │ 未加载
         ↓
┌─────────────────┐
│ 2. 检查日志错误 │
│    home-assistant.log │
└────────┬────────┘
         │ 串口错误
         ↓
┌─────────────────┐
│ 3. 检查串口权限 │
│    groups homeassistant │
└────────┬────────┘
         │ 权限正常
         ↓
┌─────────────────┐
│ 4. 手动测试串口 │
│    screen /dev/ttyUSB0 │
└────────┬────────┘
         │ 无响应
         ↓
┌─────────────────┐
│ 5. 检查硬件连接 │
│    电源/接线/电压 │
└─────────────────┘

---

常用诊断命令

# 1. 查看串口设备
ls -l /dev/ttyUSB*

# 2. 查看用户组
groups homeassistant

# 3. 查看实时日志
tail -f ~/.homeassistant/home-assistant.log | grep sigmesh

# 4. 查看集成状态
ha integrations info sigmesh_gateway

# 5. 重启集成
ha integrations reload sigmesh_gateway

# 6. 查看内存占用
ps aux | grep homeassistant | grep -v grep

# 7. 测试串口通信
screen /dev/ttyUSB0 115200

# 8. 查看系统资源
top -p $(pgrep -f homeassistant)

---

检查清单完成确认

• 所有阶段检查完成
• 所有问题已解决
• 配置参数已记录
• 系统运行稳定

检查人: ______________ 检查日期: ______________ 系统版本: HA __________, HACS __________