SigMesh Gateway - Home Assistant 集成

通过串口连接 SigMesh 网关，将蓝牙 Mesh 设备集成到 Home Assistant。

功能特性

• 📡 串口通信 - 支持 USB 转 TTL 串口，波特率 115200
• 🔗 蓝牙 Mesh 协议解析 - 支持标准 Bluetooth Mesh 模型
• 🏠 多平台实体 - 自动创建传感器、开关、灯光、设备追踪器等实体
• ⚡ 即插即用 - 支持 UI 配置，自动发现串口

支持的设备类型

设备类型	实体类型	说明
开关	switch, binary_sensor	支持 On/Off 控制
灯光	light	支持亮度、色温、RGB 控制
温度传感器	sensor	设备类别：temperature
湿度传感器	sensor	设备类别：humidity
光照传感器	sensor	设备类别：illuminance
人体感应	binary_sensor	设备类别：motion
电池设备	sensor	设备类别：battery
所有设备	device_tracker	蓝牙追踪

安装

方式一：本地部署（开发/测试推荐）

快速部署命令:

# 克隆或进入项目目录
cd /path/to/impress_sig_mesh_hacs

# 复制到 Home Assistant 配置目录
cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/

# 重启 Home Assistant
ha core restart

部署脚本（如已创建 deploy.sh）:

chmod +x deploy.sh
./deploy.sh

方式二：通过 HACS 安装

前提: 需要将代码发布到 Git 仓库并创建 Release

1. 打开 HACS
2. 点击 "Integrations"
3. 点击右上角菜单 → "Custom repositories"
4. 添加仓库：http://192.168.124.9:33001/impressionyang/impress_sig_mesh_hacs
5. 选择类别：Integration
6. 点击 "Add"
7. 找到 "SigMesh Gateway" 并点击 "Download"
8. 重启 Home Assistant

方式三：手动安装（生产环境）

1. 从 Releases 页面下载最新版本的 sigmesh_gateway.zip
2. 解压到 <HA 配置目录>/custom_components/sigmesh_gateway/
3. 重启 Home Assistant

---

更新

从 Git 拉取最新代码并部署:

cd /path/to/impress_sig_mesh_hacs

# 拉取最新代码
git pull origin main

# 重新部署
cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/

# 重启 Home Assistant
ha core restart

配置

UI 配置（推荐）

1. 进入 设置 → 设备与服务
2. 点击右下角 "添加集成"
3. 搜索 "SigMesh Gateway"
4. 选择你的串口设备（如 /dev/ttyUSB0）
5. 配置波特率（默认 115200）
6. 点击提交

YAML 配置

# configuration.yaml
sigmesh_gateway:
  serial_device: /dev/ttyUSB0
  baudrate: 115200
  poll_interval: 30

Web UI 配网管理

添加 Lovelace 面板

方式一：手动部署（推荐）

1. 运行部署脚本

   chmod +x deploy.sh
   ./deploy.sh
   

   或者手动执行：

   # 复制集成文件
   cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/
   
   # 复制 Lovelace 卡片文件
   mkdir -p ~/.homeassistant/www/sigmesh_gateway
   cp custom_components/sigmesh_gateway/sigmesh-gateway-panel.js ~/.homeassistant/www/sigmesh_gateway/
   

2. 配置 frontend

   在 configuration.yaml 中添加：

   frontend:
     extra_module_url:
       - /local/sigmesh_gateway/sigmesh-gateway-panel.js
   

3. 重启 Home Assistant

   ha core restart
   

4. 添加卡片到 Dashboard

   • 编辑仪表板 → 添加卡片 → 自定义卡片
   • 输入：custom:sigmesh-gateway-panel

方式二：通过 HACS 安装

通过 HACS 安装后，前端模块会自动加载。

常见问题

错误：Custom element not found: sigmesh-gateway-panel

解决方法：

1. 确认卡片文件已复制到正确位置：~/.homeassistant/www/sigmesh_gateway/sigmesh-gateway-panel.js
2. 确认 configuration.yaml 中配置了 extra_module_url
3. 清除浏览器缓存或硬刷新（Ctrl+Shift+R）
4. 检查浏览器控制台是否有加载错误

Web UI 功能

• 📡 设备扫描 - 扫描可用的 Bluetooth Mesh 设备
• 🔐 配网管理 - 开始/停止配网，绑定 App Key
• 📋 分组管理 - 添加/移除设备到组
• 📊 状态监控 - 实时查看配网状态和设备列表

详细说明请参考：[UI 使用指南](docs/UI 使用指南.md)

串口连接

接线方式

USB 转 TTL	SigMesh 网关
GND	GND
TX	RX
RX	TX
5V/3.3V	VCC (根据网关电压)

串口权限（Linux）

如果遇到权限问题，运行：

sudo usermod -a -G dialout homeassistant

然后重启 Home Assistant。

实体说明

传感器 (Sensor)

实体 ID	说明	单位
sensor.sigmesh_sensor_<mac>	主传感器值	根据类型
sensor.sigmesh_battery_<mac>	电池电量	%

开关 (Switch)

实体 ID	说明
switch.sigmesh_switch_<mac>	开关控制

灯光 (Light)

实体 ID	说明
light.sigmesh_light_<mac>	灯光控制

设备追踪 (Device Tracker)

实体 ID	说明
device_tracker.sigmesh_tracker_<mac>	设备位置追踪

开发调试

查看日志

# configuration.yaml
logger:
  default: warning
  logs:
    custom_components.sigmesh_gateway: debug

串口测试

使用 screen 或 minicom 测试串口通信：

# 安装 screen
sudo apt install screen

# 连接串口
screen /dev/ttyUSB0 115200

# 发送 AT 命令测试
AT
# 应返回 OK

# 退出 (Ctrl+A, 然后按 K, 再按 Y)

故障排除

问题：串口无法连接

解决方案：

1. 检查串口设备路径是否正确
2. 检查串口权限
3. 确认没有其他进程占用串口

问题：设备不显示实体

解决方案：

1. 检查网关是否正常发送数据
2. 查看日志确认协议解析是否成功
3. 尝试重新添加集成

问题：实体状态不更新

解决方案：

1. 增加 poll_interval 值
2. 检查网关是否主动上报数据

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

致谢

• Home Assistant
• HACS
• Bluetooth SIG Mesh