impressionyang fa7a03b9eb docs: 创建配网使用指南

新增 docs/配网使用指南.md，包含:
- 配网流程说明（首次配置、扫描、配网、绑定）
- 分组管理操作（添加/移除设备到组）
- 高级功能（VENDOR 命令、停止配网）
- 组地址规划建议
- 配网状态事件说明
- 故障排查指南
- 服务列表参考

2026-04-16 12:06:12 +08:00

6.1 KiB

Raw Blame History

SigMesh Gateway 配网使用指南

概述

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

配网流程

第一步：首次配置

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

串口配置
- 选择串口设备（如 /dev/ttyUSB0）
- 设置波特率（默认 115200）
配网参数（首次使用需要）
- Network Key: 16 字节网络密钥（32 字符十六进制）
- App Key: 16 字节应用密钥（32 字符十六进制）
- Network ID: 2 字节网络 ID（4 字符十六进制）
- IV Index: 4 字节 IV 索引（整数）
- 组地址起始值: 组地址范围起始（默认 0xC000）

注意: 如果网关已经配置过，可以使用默认值（全 0）。

第二步：扫描设备

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

方法 1: 通过 Options Flow（推荐）

进入 HA 设置 → 设备与服务
找到 SigMesh Gateway 集成
点击"配置"
选择"开始扫描设备"

方法 2: 通过服务调用

service: sigmesh_gateway.start_scan
data: {}

第三步：配网设备

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

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

配网过程：

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

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

如果需要手动绑定 App Key：

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

分组管理

添加设备到组

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

SIG 标准分组:

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 自定义分组:

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

从组中移除设备

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

高级功能

发送 VENDOR 命令

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

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

停止配网

service: sigmesh_gateway.stop_provisioning
data: {}

组地址规划

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

组地址配置示例

假设有一个灯光场景：

客厅主灯（设备地址 0001）
客厅灯带（设备地址 0002）
餐厅主灯（设备地址 0003）

将客厅灯具分到一组：

# 客厅主灯加入组 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	配网超时

监听配网状态事件：

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

故障排查

问题 1: 配网超时

现象: 配网状态变为 timeout

可能原因:

设备未进入配网模式
网络密钥配置不正确
信号强度不足

解决方法:

确认设备已进入配网模式（参考设备说明书）
检查 Network Key 配置
将网关靠近设备

问题 2: 设备无法加入组

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