impress_sig_mesh_hacs/docs/配网使用指南.md

# SigMesh Gateway 配网使用指南

## 概述

本指南介绍如何使用 SigMesh Gateway 集成的配网功能，将 Bluetooth Mesh 设备添加到网络中。

## 重要说明：配网参数来源

**配网参数（Network Key, App Key, Network ID, IV Index）是通过 danglo 工具设置到网关的，而不是从网关读取的。**

- **首次使用网关**：必须先用 danglo 组网工具设置配网参数
- **HA 配置时**：输入与 danglo 工具中相同的参数（或使用默认值）
- **原因**：网关芯片（Nordic nRF52840）写入参数后无法通过命令读取，需用户自行记录

## 配网流程

### 第一步：首次配置

#### 1. 使用 danglo 工具配置网关

添加集成前，先用亿佰特官方 danglo 组网工具配置网关：

1. 打开 danglo 工具，连接 E104-BT12USP 网关
2. 进入 **PROV** 选项卡
3. 设置配网参数并点击 **PROV** 写入网关

> **提示**：建议记录这些参数，后续 HA 配置和其他网关需要使用相同参数

#### 2. 在 HA 中配置集成

添加集成时，需要配置以下参数：

1. **串口配置**
   - 选择串口设备（如 `/dev/ttyUSB0`）
   - 设置波特率（默认 115200）

2. **配网参数**（必须与 danglo 工具中一致）
   - **Network Key**: 16 字节网络密钥（32 字符十六进制）
   - **App Key**: 16 字节应用密钥（32 字符十六进制）
   - **Network ID**: 2 字节网络 ID（4 字符十六进制）
   - **IV Index**: 4 字节 IV 索引（整数）
   - **组地址起始值**: 组地址范围起始（默认 0xC000）

> **注意**: 如果网关已经配置过且参数已知，可以在 HA 配置时直接输入；如果不确定，可以使用默认值（全 0），但需确保网关中的参数与 HA 配置一致

### 第二步：扫描设备

配置完成后，通过以下方式开始扫描设备：

**方法 1: 通过 Options Flow（推荐）**
1. 进入 HA 设置 → 设备与服务
2. 找到 SigMesh Gateway 集成
3. 点击"配置"
4. 选择"开始扫描设备"

**方法 2: 通过服务调用**
```yaml
service: sigmesh_gateway.start_scan
data: {}
```

### 第三步：配网设备

扫描到设备后，可以通过服务调用进行配网：

```yaml
service: sigmesh_gateway.start_provisioning
data:
  device_address: "001A"  # 设备地址（16 进制）
```

配网过程：
1. 发送配网启动命令
2. 等待设备加入（超时时间 180 秒）
3. 配网完成后自动绑定 App Key

### 第四步：绑定 App Key（可选）

如果需要手动绑定 App Key：

```yaml
service: sigmesh_gateway.bind_appkey
data:
  device_address: "001A"
  element_address: 0
```

## 分组管理

### 添加设备到组

将设备添加到组地址，实现组控制：

**SIG 标准分组**:
```yaml
service: sigmesh_gateway.add_to_group
data:
  target_address: "001A"      # 目标设备地址
  element_address: 0           # 元素地址
  group_address: "C001"        # 组地址（16 进制）
  model_id: 4352               # Model ID (0x1100 传感器)
  is_sig: true                 # SIG 标准分组
```

**VENDOR 自定义分组**:
```yaml
service: sigmesh_gateway.add_to_group
data:
  target_address: "001A"
  element_address: 0
  group_address: "C001"
  model_id: 4354               # VENDOR Model ID
  is_sig: false
```

### 从组中移除设备

```yaml
service: sigmesh_gateway.remove_from_group
data:
  target_address: "001A"
  element_address: 0
  group_address: "C001"
  model_id: 4352
  is_sig: true
```

## 高级功能

### 发送 VENDOR 命令

发送自定义 VENDOR 命令到设备：

```yaml
service: sigmesh_gateway.send_vendor_command
data:
  target_address: "001A"
  element_address: 0
  opcode: "1102"              # VENDOR 操作码
  payload: "0000"             # 数据负载（16 进制）
```

### 停止配网

```yaml
service: sigmesh_gateway.stop_provisioning
data: {}
```

## 组地址规划

### 推荐组地址范围

| 用途 | 地址范围 | 说明 |
|------|----------|------|
| 灯光组 | 0xC001 - 0xC0FF | 照明设备分组 |
| 传感器组 | 0xC100 - 0xC1FF | 传感器分组 |
| 开关组 | 0xC200 - 0xC2FF | 开关设备分组 |

### 组地址配置示例

假设有一个灯光场景：
- 客厅主灯（设备地址 0001）
- 客厅灯带（设备地址 0002）
- 餐厅主灯（设备地址 0003）

将客厅灯具分到一组：
```yaml
# 客厅主灯加入组 0xC001
service: sigmesh_gateway.add_to_group
data:
  target_address: "0001"
  group_address: "C001"
  model_id: 4872           # 0x1308 灯光模型

# 客厅灯带加入组 0xC001
service: sigmesh_gateway.add_to_group
data:
  target_address: "0002"
  group_address: "C001"
  model_id: 4872
```

之后可以通过组地址 0xC001 同时控制客厅所有灯具。

## 配网状态

配网过程中会触发 `sigmesh_gateway_prov_state` 事件，包含以下状态：

| 状态 | 说明 |
|------|------|
| idle | 空闲，无配网操作 |
| scanning | 扫描设备中 |
| prov_starting | 配网启动中 |
| prov_in_progress | 配网进行中 |
| prov_completed | 配网完成 |
| prov_failed | 配网失败 |
| timeout | 配网超时 |

监听配网状态事件：
```yaml
automation:
  - alias: "配网状态通知"
    trigger:
      platform: event
      event_type: sigmesh_gateway_prov_state
    action:
      - service: notify.notify
        data:
          message: "配网状态：{{ trigger.event.data.state }}"
```

## 故障排查

### 问题 1: 配网超时

**现象**: 配网状态变为 timeout

**可能原因**:
- 设备未进入配网模式
- 网络密钥配置不正确
- 信号强度不足

**解决方法**:
1. 确认设备已进入配网模式（参考设备说明书）
2. 检查 Network Key 配置
3. 将网关靠近设备

### 问题 2: 设备无法加入组

**现象**: 调用 add_to_group 后设备无响应

**可能原因**:
- 设备未完成配网
- 设备不支持该 Model
- 组地址超出范围

**解决方法**:
1. 确认设备已完成配网
2. 检查 model_id 是否正确
3. 使用 0xC000 以上的组地址

### 问题 3: 低功耗设备无法接收组消息

**现象**: 低功耗设备不响应组控制

**解决方法**:
将 Lightness Model 和 Vendor Model 分配到同一组：
```yaml
# 添加 Lightness Model 到组
service: sigmesh_gateway.add_to_group
data:
  target_address: "0001"
  group_address: "C001"
  model_id: 4864           # 0x1300 LIGHT_LIGHTNESS_SERVER
  is_sig: true

# 添加 Vendor Model 到同一组
service: sigmesh_gateway.add_to_group
data:
  target_address: "0001"
  group_address: "C001"
  model_id: 4610           # VENDOR Model
  is_sig: false
```

## 服务列表

| 服务名称 | 功能 |
|----------|------|
| `sigmesh_gateway.start_scan` | 开始扫描设备 |
| `sigmesh_gateway.stop_provisioning` | 停止配网 |
| `sigmesh_gateway.start_provisioning` | 开始配网指定设备 |
| `sigmesh_gateway.bind_appkey` | 绑定 App Key |
| `sigmesh_gateway.add_to_group` | 添加设备到组 |
| `sigmesh_gateway.remove_from_group` | 从组中移除设备 |
| `sigmesh_gateway.send_vendor_command` | 发送 VENDOR 命令 |

---

**文档版本**: 1.0
**最后更新**: 2026-04-16