acd23e6f64
- 添加 .asset/impress_sig_mesh_hacs.png 作为 HACS 集成图标 - 在 hacs.json 中配置 icon 字段 - 在 README.md 顶部显示图标 - 更新 .gitignore 仅保留图标文件 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
223 lines
4.9 KiB
Markdown
223 lines
4.9 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` | 蓝牙追踪 |
|
||
|
||
## 安装
|
||
|
||
### 方式一：本地部署（开发/测试推荐）
|
||
|
||
**快速部署命令**:
|
||
```bash
|
||
# 克隆或进入项目目录
|
||
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`）:
|
||
```bash
|
||
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 拉取最新代码并部署**:
|
||
```bash
|
||
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 配置
|
||
|
||
```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/)
|