6a66c9b474
项目结构： - custom_components/sigmesh_gateway/ - Home Assistant 集成 - serial_reader.py - 串口读取器 - protocol_parser.py - 协议解析器 - coordinator.py - 数据协调器 - platforms/ - 传感器/开关/灯光/设备追踪实体 文档： - PRD.md - 产品需求文档 - README.md - 用户使用指南 - 可行性分析.md - 技术可行性分析 - 参数配置表.md - 配置参数记录 - 调试检查清单.md - 问题排查指南 功能特性： - 串口通信 (115200 波特率) - Bluetooth Mesh 协议解析 - 支持 200+ 设备接入 - UI 配置界面 - 多平台实体支持 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
181 lines
4.1 KiB
Markdown
181 lines
4.1 KiB
Markdown
# SigMesh Gateway - Home Assistant 集成
|
||
|
||
[](https://github.com/hacs/integration)
|
||
[](https://github.com/impress-sig-mesh/sigmesh_gateway/releases)
|
||
|
||
通过串口连接 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` | 蓝牙追踪 |
|
||
|
||
## 安装
|
||
|
||
### 通过 HACS 安装（推荐）
|
||
|
||
1. 打开 HACS
|
||
2. 点击 "Integrations"
|
||
3. 点击右上角菜单 → "Custom repositories"
|
||
4. 添加仓库：`https://github.com/impress-sig-mesh/sigmesh_gateway`
|
||
5. 选择类别：`Integration`
|
||
6. 点击 "Add"
|
||
7. 找到 "SigMesh Gateway" 并点击 "Download"
|
||
8. 重启 Home Assistant
|
||
|
||
### 手动安装
|
||
|
||
1. 下载最新版本的 `sigmesh_gateway.zip`
|
||
2. 解压到 `config/custom_components/sigmesh_gateway/`
|
||
3. 重启 Home Assistant
|
||
|
||
## 配置
|
||
|
||
### UI 配置（推荐）
|
||
|
||
1. 进入 **设置** → **设备与服务**
|
||
2. 点击右下角 **"添加集成"**
|
||
3. 搜索 **"SigMesh Gateway"**
|
||
4. 选择你的串口设备（如 `/dev/ttyUSB0`）
|
||
5. 配置波特率（默认 115200）
|
||
6. 点击提交
|
||
|
||
### YAML 配置
|
||
|
||
```yaml
|
||
# configuration.yaml
|
||
sigmesh_gateway:
|
||
serial_device: /dev/ttyUSB0
|
||
baudrate: 115200
|
||
poll_interval: 30
|
||
```
|
||
|
||
## 串口连接
|
||
|
||
### 接线方式
|
||
|
||
| USB 转 TTL | SigMesh 网关 |
|
||
|-----------|-------------|
|
||
| GND | GND |
|
||
| TX | RX |
|
||
| RX | TX |
|
||
| 5V/3.3V | VCC (根据网关电压) |
|
||
|
||
### 串口权限（Linux）
|
||
|
||
如果遇到权限问题，运行：
|
||
|
||
```bash
|
||
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>` | 设备位置追踪 |
|
||
|
||
## 开发调试
|
||
|
||
### 查看日志
|
||
|
||
```yaml
|
||
# configuration.yaml
|
||
logger:
|
||
default: warning
|
||
logs:
|
||
custom_components.sigmesh_gateway: debug
|
||
```
|
||
|
||
### 串口测试
|
||
|
||
使用 `screen` 或 `minicom` 测试串口通信：
|
||
|
||
```bash
|
||
# 安装 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](https://www.home-assistant.io/)
|
||
- [HACS](https://hacs.xyz/)
|
||
- [Bluetooth SIG Mesh](https://www.bluetooth.com/technologies/mesh/)
|