4c3eb62dfb
新增 Web UI 组件: - web_ui.py: RESTful API 端点（状态、扫描、配网、分组、设备） - sigmesh-gateway-panel.js: Lovelace Dashboard 自定义卡片 - 设备扫描和发现 - 配网操作（开始/停止/绑定 App Key） - 分组管理（添加/移除） - 实时状态监控 配置更新: - __init__.py: 集成 Web UI 和服务注册 - const.py: 添加服务常量定义 - services.py: 保留服务调用用于向后兼容 - README.md: 添加 Web UI 配置说明 - docs/UI 使用指南.md: 详细的 UI 使用文档 使用方式: 1. 配置 frontend.extra_module_url 加载 JS 面板 2. 在 Lovelace Dashboard 添加 custom:sigmesh-gateway-panel 卡片 3. 通过 UI 完成所有配网和分组操作 API 端点: - GET /api/sigmesh_gateway/status - 获取配网状态 - POST /api/sigmesh_gateway/scan - 开始扫描 - POST /api/sigmesh_gateway/provisioning - 配网操作 - POST /api/sigmesh_gateway/group - 分组管理 - GET /api/sigmesh_gateway/devices - 设备列表
257 lines
5.8 KiB
Markdown
257 lines
5.8 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
|
||
```
|
||
|
||
## Web UI 配网管理
|
||
|
||
### 添加 Lovelace 面板
|
||
|
||
1. **复制前端文件**
|
||
```bash
|
||
mkdir -p /config/www/sigmesh_gateway
|
||
cp custom_components/sigmesh_gateway/sigmesh-gateway-panel.js /config/www/sigmesh_gateway/
|
||
```
|
||
|
||
2. **配置 frontend**
|
||
|
||
在 `configuration.yaml` 中添加：
|
||
```yaml
|
||
frontend:
|
||
extra_module_url:
|
||
- /local/sigmesh_gateway/sigmesh-gateway-panel.js
|
||
```
|
||
|
||
3. **重启 Home Assistant**
|
||
|
||
4. **添加卡片到 Dashboard**
|
||
- 编辑仪表板 → 添加卡片 → 自定义卡片
|
||
- 输入：`custom:sigmesh-gateway-panel`
|
||
|
||
### Web UI 功能
|
||
|
||
- 📡 **设备扫描** - 扫描可用的 Bluetooth Mesh 设备
|
||
- 🔐 **配网管理** - 开始/停止配网，绑定 App Key
|
||
- 📋 **分组管理** - 添加/移除设备到组
|
||
- 📊 **状态监控** - 实时查看配网状态和设备列表
|
||
|
||
详细说明请参考：[UI 使用指南](docs/UI 使用指南.md)
|
||
|
||
## 串口连接
|
||
|
||
### 接线方式
|
||
|
||
| 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/)
|