impressionyang b4643fa408 feat: 添加调试日志用于排查扫描问题

1. provisioning.py: 添加 start_scanning 调用日志
2. config_flow.py: 添加 coordinator 调用日志
3. serial_reader.py: 添加命令发送和接收的原始数据日志

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

7.0 KiB

Raw Blame History

SigMesh Gateway 配网使用指南

概述

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

重要说明：配网参数来源

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

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

配网流程

第一步：首次配置

1. 使用 danglo 工具配置网关

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

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

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

2. 在 HA 中配置集成

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

串口配置
- 选择串口设备（如 /dev/ttyUSB0）
- 设置波特率（默认 115200）
配网参数（必须与 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（推荐）

进入 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 后设备无响应