impress_sig_mesh_hacs/README.md

# SigMesh Gateway - Home Assistant 集成

![logo](.asset/impress_sig_mesh_hacs.png)

[![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)
[![GitHub Release](https://img.shields.io/github/release/impress-sig-mesh/sigmesh_gateway.svg)](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
   chmod +x deploy.sh
   ./deploy.sh
   ```

   或者手动执行：
   ```bash
   # 复制集成文件
   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` 中添加：
   ```yaml
   frontend:
     extra_module_url:
       - /local/sigmesh_gateway/sigmesh-gateway-panel.js
   ```

3. **重启 Home Assistant**
   ```bash
   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）

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

```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/)