node-red-contrib-symi-mesh 1.6.7

Node-RED节点集合，用于通过TCP/串口连接Symi蓝牙Mesh网关，支持Home Assistant MQTT Discovery自动发现和云端数据同步

npm install node-red-contrib-symi-mesh

node-red-contrib-symi-mesh

一个为Node-RED设计的Symi蓝牙Mesh网关集成包，提供完整的设备控制和Home Assistant MQTT Discovery自动发现功能。

功能特性

完整协议支持：TCP/串口双模式，严格遵循蓝牙MESH网关串口协议V1.0
自动设备发现：连接后自动发现所有设备，无需手动配置
MQTT Discovery：自动发布HA Discovery配置，设备即插即用
双向状态同步：支持0x80状态事件，实时反馈设备状态变化
多设备类型：支持开关、灯光、窗帘、温控器、传感器等12+种设备
三合一面板：完整支持空调+新风+地暖三合一控制面板，自动识别
RS485/Modbus集成：支持第三方485设备双向同步，内置协议模板
KNX集成：支持与KNX系统双向同步
云端同步：从酒店云云平台自动获取设备名称和场景信息
稳定可靠：完善的错误处理和自动重连机制

快速开始

1. 安装

方式一：通过npm安装（推荐）

cd ~/.node-red
npm install node-red-contrib-symi-mesh

方式二：通过Node-RED界面安装

打开Node-RED界面
点击右上角菜单 → 节点管理
搜索 node-red-contrib-symi-mesh
点击安装

方式三：本地开发安装

cd ~/.node-red
npm install /path/to/node-red-contrib-symi-mesh

安装后重启Node-RED：

node-red-restart

2. 配置网关节点

添加"Symi Gateway"配置节点：

网关连接配置:

连接方式: TCP/IP 或串口
TCP模式（推荐）:
- 主机地址: 网关IP（如 192.168.2.110）
- 端口: 4196（默认）
串口模式:
- 串口路径: /dev/ttyUSB0
- 波特率: 115200

MQTT配置（用于Home Assistant集成）:

MQTT地址: mqtt://localhost:1883（默认，可修改）
用户名: MQTT认证用户名（可选）
密码: MQTT认证密码（可选）
HA前缀: homeassistant（默认，可修改）

提示: MQTT配置已集成到网关节点中，所有使用该网关的MQTT节点会自动使用这些配置。

3. 添加MQTT桥接节点

添加"Symi MQTT"节点到流程中：

网关: 选择已配置的网关节点
名称: 可选，用于标识节点

注意: MQTT连接参数从网关节点获取，无需重复配置。

4. 部署并验证

点击右上角"部署"按钮
检查调试面板确认连接状态：
- Gateway connected - 网关连接成功
- Device discovery complete - 设备发现完成
- MQTT已连接 - MQTT连接成功
- 发布设备 XXX - 设备发布到MQTT
在Home Assistant中查看自动发现的设备
测试设备控制和状态反馈

5. 多网关配置（可选）

对于大户型或多区域部署，可以配置多个网关节点：

添加第二个网关节点：
- 拖入新的"Symi Gateway"节点
- 配置不同的IP地址或串口
- 给网关起不同的名称（如"网关-客厅"、"网关-卧室"）
添加对应的MQTT节点：
- 为每个网关添加独立的"Symi MQTT"节点
- 在配置中选择对应的网关
- 使用相同的MQTT broker配置
设备隔离：
- 每个网关的设备独立存储，互不干扰
- 每个网关的设备在HA中独立显示
- 可以为不同网关配置不同的MQTT主题前缀

示例配置：

网关1（客厅）: 192.168.2.110:4196 → MQTT主题: symi_mesh/living_room/
网关2（卧室）: 192.168.2.111:4196 → MQTT主题: symi_mesh/bedroom/

支持的设备类型

设备类型	类型码	HA实体	功能说明
零火开关	0x01	switch	1-6路独立控制，状态反馈
单火开关	0x02	switch	1-6路独立控制，状态反馈
智能插座	0x03	switch	单路开关控制
双色调光灯	0x04	light	亮度+色温调节
智能窗帘	0x05	cover	开关+位置控制（0-100%）
门磁传感器	0x07	binary_sensor	门窗开关状态
人体感应	0x08	binary_sensor	人体活动检测
插卡取电	0x09	switch + binary_sensor	插卡检测+开关控制
温控器/三合一	0x0A	climate	温度/模式/风速控制，当前温度采集
温湿度传感器	0x0B	sensor	温湿度监测
五色调光灯	0x18	light	RGB+亮度+色温调节
四输入八输出	0x27 (39)	switch	8路独立控制，支持场景绑定

三合一设备说明

三合一设备集成了空调、新风和地暖控制，在Home Assistant中自动创建3个独立实体：

实体说明

1. 空调（climate实体）

温度调节：16-30°C
工作模式：制冷/制热/送风/除湿/关闭
风速控制：高/中/低/自动

2. 新风（fan实体）

开关控制：ON/OFF
风速档位：高/中/低/自动
送风/排风：支持送风和排风方向控制

3. 地暖（climate实体）

温度调节：18-32°C
工作模式：制热/关闭

使用方式

自动识别机制：

空调温控器和三合一面板属于同一设备品类（deviceType=10）
系统通过主动查询新风(0x68)和地暖(0x6B)状态来区分
有响应的识别为三合一面板，无响应的识别为普通温控器
无需手动配置，部署后自动完成识别

识别日志示例：

[三合一检测] 发现温控器类型设备: 温控器_xxx，将通过查询新风/地暖确认类型
[三合一检测] 开始检测设备 xxx (0xABCD)
[三合一检测] 收到 xxx 的新风响应 (0x68)，确认为三合一面板
[三合一检测] 确认为三合一面板（收到新风/地暖响应）

控制方式：

HA中直接控制：设置温度/模式自动开启设备
面板物理操作：状态自动同步到HA
MQTT直接控制：支持完整的MQTT命令

KNX同步：在Symi Device节点中选择三合一设备，通过"子实体"下拉选项选择与KNX同步的功能：

空调 ↔ KNX空调控制器
新风 ↔ KNX新风控制器
地暖 ↔ KNX地暖控制器

每个功能独立同步，互不干扰。

协议说明

核心协议格式

[Header(0x53)] [Opcode] [Status] [Length] [Data] [Checksum]

关键操作码

操作码	名称	方向	说明
0x12	设备列表查询	主机→网关	查询所有设备
0x92	设备列表响应	网关→主机	返回设备信息
0x30	设备控制	主机→网关	控制指定设备
0xB0	控制响应	网关→主机	控制结果
0x34	场景控制	主机→网关	执行场景（群控）
0xB4	场景控制响应	网关→主机	场景控制结果
0x80	状态事件	网关→主机	设备状态主动上报
0x32	状态查询	主机→网关	查询设备状态

开关状态编码（重要）

协议规则: 每2位表示1路，01=关，10=开，从最低位开始

路数	全关	全开	示例
1路	0x01	0x02	直接值
2路	0x05	0x0A	0x06=第1路开、第2路关
3路	0x15	0x2A	从低位开始
4路	0x55	0xAA	每2位1路
6路	0x5555	0xAAAA	2字节小端序
8路	0x5555	0xAAAA	2字节小端序

8路开关状态详解

8路开关使用2字节（16位）表示状态，小端序传输。实测帧示例：

帧格式: 53 80 [Status] [Length] [网络地址LE] [AttrType] [状态LE] [Checksum]
示例帧: 53 80 05 05 E4 01 45 56 55 70
        │  │  │  │  └─────┘ │  └───┘ └─ 校验和
        │  │  │  │     │    │    └─ 状态值 0x5556 (第1路开)
        │  │  │  │     │    └─ AttrType=0x45 (8路开关)
        │  │  │  │     └─ 网络地址 0x01E4
        │  │  │  └─ 数据长度=5字节
        │  │  └─ 状态码
        │  └─ Opcode=0x80 (事件上报)
        └─ 帧头

状态值对照表（小端序）:

状态数据	16位值	二进制	含义
55 55	0x5555	01010101 01010101	全关
56 55	0x5556	01010101 01010110	第1路开
59 55	0x5559	01010101 01011001	第2路开
65 55	0x5565	01010101 01100101	第3路开
95 55	0x5595	01010101 10010101	第4路开
55 56	0x5655	01010110 01010101	第5路开
55 59	0x5955	01011001 01010101	第6路开
55 65	0x6555	01100101 01010101	第7路开
55 95	0x9555	10010101 01010101	第8路开
AA AA	0xAAAA	10101010 10101010	全开

常用消息类型

消息类型	代码	数据格式	范围/说明
开关状态	0x02	1字节	1-4路开关，见上表
亮度	0x03	1字节	0-100%
色温	0x04	1字节	0%=暖白, 100%=冷白
窗帘动作	0x05	1字节	1=开/2=关/3=停
窗帘位置	0x06	1字节	0-100%
人体感应	0x0C	1字节	0=无活动/1=检测到
插卡状态	0x0E	1字节	0=无卡/1=有卡
湿度	0x17	1字节	0-100%
当前温度	0x16	2字节LE	温度*100（如2500=25.00°C）
目标温度	0x1B	1字节	16-30°C（直接温度值）
风速	0x1C	1字节	1=高/2=中/3=低/4=自动
模式	0x1D	1字节	1=制冷/2=制热/3=送风/4=除湿
6-8路开关	0x45	2字节LE	多路开关状态，见上表
五色RGB	0x4C	5字节	R/G/B/WW/CW (各0-255)

MQTT主题结构

Discovery主题

homeassistant/[platform]/[object_id]/config

例如：

开关：homeassistant/switch/9361c820dacc_switch/config
温控器：homeassistant/climate/142e68468cac_climate/config
三合一空调：homeassistant/climate/894ab820dacc_climate/config
三合一新风：homeassistant/fan/894ab820dacc_fresh_air/config
三合一地暖：homeassistant/climate/894ab820dacc_floor_heating/config

状态和命令主题

普通设备：

symi_mesh/[mac_clean]/[entity]/state
symi_mesh/[mac_clean]/[entity]/set

三合一设备（关键：空调使用climate主题）：

空调：symi_mesh/[mac_clean]/climate/mode
新风：symi_mesh/[mac_clean]/fresh_air/state
地暖：symi_mesh/[mac_clean]/floor_heating/mode

例如（三合一设备 894ab820dacc）：

空调状态: symi_mesh/894ab820dacc/climate/target_temp
空调命令: symi_mesh/894ab820dacc/climate/target_temp/set
新风状态: symi_mesh/894ab820dacc/fresh_air/state
新风命令: symi_mesh/894ab820dacc/fresh_air/set
地暖状态: symi_mesh/894ab820dacc/floor_heating/mode
地暖命令: symi_mesh/894ab820dacc/floor_heating/mode/set

KNX双向同步

本节点支持与node-red-contrib-knx-ultimate完整双向同步，实现Symi Mesh设备与KNX系统的互联互通。

方式一：KNX桥接节点（推荐）

v1.6.7新增：使用symi-knx-bridge节点实现一站式配置，支持KNX实体导入和批量映射。

功能特点

KNX实体库：导入KNX组地址，快速选择实体
一行映射：紧凑表格，适合大量设备映射
多设备类型：开关、调光灯、窗帘、空调、新风、地暖
双向同步：自动处理Mesh↔KNX状态同步
防死循环：内置1.5秒防抖机制

配置步骤

安装KNX节点

cd ~/.node-red
npm install node-red-contrib-knx-ultimate

添加KNX桥接节点 从"Symi Mesh"分类中拖入"KNX桥接"节点
导入KNX实体

点击"下载模板"获取导入格式
填写KNX组地址后点击"导入"

添加映射

点击"添加"按钮
选择Mesh设备和KNX实体
开关设备可选择通道

连接KNX节点

[knxUltimate-in] → [symi-knx-bridge] → [knxUltimate-out]

KNX实体导入格式

Tab分隔，每行一个实体：

名称	类型	命令地址	状态地址	扩展1	扩展2	扩展3

支持的类型和地址字段：

类型	字段	说明
switch	命令, 状态	开关 DPT1.001
light_mono	命令, 状态, 亮度	单色调光
light_cct	命令, 状态, 亮度, 色温	双色调光
light_rgb	命令, 状态, 亮度, RGB	RGB调光
light_rgbcw	命令, 状态, 亮度, 色温, RGB	RGBCW
cover	上下, 位置, 停止	窗帘
climate	开关, 温度, 模式, 风速, 当前温度	空调
fresh_air	开关, 风速	新风
floor_heating	开关, 温度, 当前温度	地暖

示例：

玄关射灯	switch	1/1/28	1/2/28
客厅吊灯	light_cct	1/1/10	1/2/10	1/3/10	1/4/10
客厅布帘	cover	2/1/5	2/2/5	2/3/5
主卧空调	climate	3/1/1	3/2/1	3/3/1	3/4/1	3/5/1

输入/输出

输入：接收来自knxUltimate-in节点的KNX消息
输出1：发送到knxUltimate-out节点的KNX命令
输出2：调试信息（连接Debug节点查看同步过程）

knxUltimate节点配置（关键）

输入节点(knxUltimate-in)：

配置项	值	说明
Listen to all GA	勾选	必须，否则收不到消息
Telegram type	写入	接收写入命令
Notify on write	勾选	接收写入事件
Notify on response	勾选	接收响应事件
RBE过滤	禁用	确保所有消息通过

输出节点(knxUltimate-out)：

配置项	值	说明
Listen to all GA	勾选	必须，Universal Mode
topic	留空	桥接节点动态设置
数据类型	0 (自动)	桥接节点动态设置
Output type	Write	写入模式
RBE过滤	禁用	确保每次都发送

示例配置见examples/knx-sync-example.json

注意事项

20秒初始化延迟：部署后前20秒不同步，等待Mesh设备发现完成
首次状态缓存：启动后第一次状态仅缓存，第二次操作才会同步
防死循环：KNX控制后1秒内，Mesh状态变化不会反向同步

故障排查

Mesh->KNX不工作：

检查日志是否有[Mesh->KNX]输出
确认映射中的MAC地址与设备列表中的MAC一致
等待20秒初始化完成
手动操作Mesh设备，观察日志

KNX->Mesh不工作：

检查knxUltimate-in节点是否收到KNX消息
确认KNX组地址与映射中的命令地址一致
查看日志是否有[KNX输入]输出
如果显示未找到映射，检查配置的组地址

RS485/Modbus双向同步

本节点支持与第三方RS485/Modbus设备进行双向状态同步，适用于对接各品牌空调、新风、地暖等设备。

功能特点

双模式连接：支持串口(RS485)和TCP/IP两种连接方式
协议模板：内置常用协议模板，支持自定义寄存器映射
双向同步：Mesh设备和485设备状态实时同步
多设备支持：单个485连接可管理多达105个设备

配置步骤

1. 添加RS485桥接节点

从"Symi Mesh"分类中拖入"RS485桥接"节点，双击打开配置：

基本配置：

Mesh网关：选择已配置的Symi Gateway（点击+号可新建）
RS485连接：点击+号新建连接配置

2. 配置RS485连接

点击RS485连接旁边的+号，创建新连接：

串口模式：

连接方式：选择串口(RS485)
串口：从下拉框选择USB串口（点击刷新按钮可重新扫描）
波特率：根据设备设置（常用9600）
校验位：无/偶校验/奇校验

TCP模式：

连接方式：选择 TCP/IP
主机地址：485转TCP网关的IP地址
端口：Modbus TCP端口（默认502）

3. 配置实体映射

点击"添加映射"按钮，每行配置一组对应关系：

列	说明
Mesh实体/按键	选择Mesh设备，开关设备会显示按键选择（第1路、第2路...）
品牌	选择RS485协议品牌（如话语前湾）
类型/按键	选择设备类型，开关类型会显示按键选择
地址	Modbus从机地址（1-255）

开关设备命名：按按键数命名，方便识别：

Mesh端：一键开关、二键开关、三键开关、四键开关、六键开关、八键开关
RS485端：一键开关、二键开关、三键开关、四键开关、六键开关、八键开关

按键独立配置：Mesh和RS485的按键可以自由对应，不必一一匹配：

Mesh 六键开关 第3路 ↔ RS485 四键开关 第1路  地址:1   ✓ 支持
Mesh 四键开关 第2路 ↔ RS485 六键开关 第5路  地址:2   ✓ 支持

4. 部署

点击"部署"按钮，所有映射自动开始双向同步

RS485调试节点

新增 RS485调试 节点用于抓取并显示原始485字节流：

功能：

实时显示RS485总线所有通信数据（TX发送/RX接收）
自动解析Modbus RTU帧结构（从机地址、功能码）
支持手动发送测试帧（输入十六进制字符串）
十六进制/ASCII显示模式
调试窗口高度自适应

输出示例：

[15:07:55.123] → TX: 01 06 10 31 00 01 6A 35 | 从机:1 写单寄存器
[15:07:55.180] ← RX: 01 06 10 31 00 01 6A 35 | 从机:1 写单寄存器

实体映射规则

Mesh实体类型	RS485实体类型	同步内容
开关-按键N	开关	开/关状态
温控器	空调	开关、温度、模式、风速
三合一面板	空调+新风+地暖	分别配置，独立同步
调光灯	调光器	开关、亮度

部分同步：如果RS485协议不提供某些功能点，只同步双方都支持的内容

三合一面板配置

三合一面板（温控器类型）可同时控制空调、新风、地暖，需要创建3个独立映射：

配置示例（话语前湾协议）

Mesh设备	RS485设备类型	从机地址	说明
三合一面板_xxx	次卧1空调	0	空调寄存器0x0FA4-0x0FA7
三合一面板_xxx	新风	60	开关0x0039，风速0x004B
三合一面板_xxx	次卧1地暖	62	开关0x0039，温度0x0043

话语前湾地暖/新风从机地址

设备	从机地址	十六进制
客餐厅地暖	60	0x3C
新风	60	0x3C
主卧地暖	61	0x3D
次卧1地暖	62	0x3E
次卧2地暖	63	0x3F

注意：新风和客餐厅地暖共用从机地址60，但开关值不同（新风开=1，地暖开=2），请分别创建映射。

内置协议支持

品牌	支持设备
话语前湾	空调（客厅/主卧/次卧1/次卧2）、地暖、新风、窗帘、1-8键开关
通用Modbus	各类标准Modbus设备
自定义协议	任意485码匹配（开关/窗帘/场景）

自定义协议模式

当内置协议无法满足需求时，可使用"自定义协议"模式，手动录入RS485十六进制码进行双向匹配：

自定义开关

打开码：当Mesh开关打开时发送此码，收到此码时触发Mesh开关打开
关闭码：当Mesh开关关闭时发送此码，收到此码时触发Mesh开关关闭

自定义窗帘

打开码：Mesh窗帘打开 ↔ RS485打开命令
关闭码：Mesh窗帘关闭 ↔ RS485关闭命令
停止码：Mesh窗帘停止 ↔ RS485停止命令

配置示例

品牌: 自定义协议
类型: 自定义窗帘
打开码: 55 02 02 03 01 49 44
关闭码: 55 02 02 03 02 09 45
停止码: 55 02 02 03 03 C8 85

工作原理

Mesh→RS485：Mesh设备状态变化时，发送对应的自定义码
RS485→Mesh：收到的RS485帧与自定义码匹配，触发对应Mesh设备
防死循环：500ms内不重复触发，避免Mesh→RS485→Mesh循环

自定义码支持任意长度的十六进制字符串，支持空格分隔（如 55 01 01 或 550101）

注意事项

Modbus地址：同一485总线上设备地址不能重复（1-255）
自动重连：网络断开后5秒自动重连，无需人工干预
事件驱动：非轮询模式，设备状态变化时才同步
防循环保护：内置同步锁机制，避免状态死循环
485转TCP网关：Node-RED只能收到自己发送请求后的设备回应，其他TCP客户端的数据不会转发（网关机制）

云端数据同步

本节点支持从酒店云云平台自动获取设备名称和场景信息，实现本地化配置的自动同步。

使用场景

酒店项目：自动同步房间设备的本地化名称（如"客厅窗帘"、"床头灯"等）
场景管理：获取云端配置的场景列表（如"全关"、"睡眠模式"等）并本地化调用
批量部署：统一管理多个房间的设备名称，无需手动配置

配置步骤

1. 添加云端同步节点

在Node-RED中添加"Symi Cloud Sync"节点：

基础配置：

网关：选择已配置的Symi Gateway节点
MQTT节点：选择Symi MQTT节点（用于更新Discovery配置）

云端认证：

App ID：请联系Symi技术支持获取
App Secret：请联系Symi技术支持获取
点击"测试连接"按钮验证认证信息

房间配置：

酒店ID：输入酒店ID或点击"加载酒店列表"自动获取
房间号：输入房间号（如：1001）
房间UUID：可选，如果有UUID可直接填写

同步选项：

自动同步：勾选后，启动时自动从云端获取数据（推荐）

2. 部署并验证

点击右上角"部署"按钮
检查调试面板确认同步状态：
- 开始从云端获取数据 - 开始同步
- 云端数据获取成功: X个设备, Y个场景 - 同步成功
- 设备名称已更新: 旧名称 -> 新名称 - 名称更新
- 重新发布MQTT Discovery配置 - 更新HA配置
在Home Assistant中查看设备名称是否已更新

3. 手动触发同步

如需手动触发同步，可以使用inject节点：

[inject] --> [cloud-sync]
payload: "sync"

4. 调用场景

云端同步后，可以通过inject节点调用场景：

[inject] --> [cloud-sync]
payload: { scene_id: 4 }  // 执行场景ID为4的场景（如"全关"）

按键场景自动触发

v1.4.0新功能：开关按键可以绑定场景，按下时自动触发场景执行，实现本地化场景联动。

工作原理

云端配置获取：从云端获取每个按键的配置信息（sub_device）
按键类型识别：
- 普通按键（sub_type="普通"）：控制本地继电器，不触发场景
- 场景按键（sub_type="场景"）：按下时触发指定场景（scene_id）
- 双控按键（sub_type="双控"）：根据当前状态触发开场景（on_scene_id）或关场景（off_scene_id）
- 总控按键（sub_type="总控"）：同双控，用于全局控制
本地化触发：按键按下时，系统自动检测并发送0x34场景控制命令到总线
状态同步：场景执行后，所有相关设备状态自动同步到Home Assistant

配置示例

云端配置（酒店云云平台）：

{
  "device_name": "床头三键",
  "sub_device": [
    {
      "sub_name": "明亮",
      "sub_type": "场景",
      "scene_id": 4
    },
    {
      "sub_name": "温馨",
      "sub_type": "场景",
      "scene_id": 6
    },
    {
      "sub_name": "睡眠",
      "sub_type": "场景",
      "scene_id": 5
    }
  ]
}

日志示例

启动时显示场景绑定：

[场景绑定] 床头三键: 按键1(明亮)→场景4, 按键2(温馨)→场景6, 按键3(睡眠)→场景5
[场景绑定] 入户二键: 按键1(廊灯)→开:场景22/关:场景21, 按键2(卫浴灯)→开:场景24/关:场景23

按键按下时触发场景：

[按键场景] 检测到按键1(明亮)状态变化: 关 → 开, 触发场景4
[按键场景] ✓ 场景4(明亮)控制命令已发送
[场景控制] 场景控制命令已被网关接受
[场景执行] 收到场景执行通知事件: 场景ID=4

注意事项

云端配置必需：需要先配置云端同步节点并成功获取设备配置
完全本地化：场景触发完全在本地进行，不依赖云端
避免循环：场景执行期间不会再次触发按键场景，防止循环
状态同步：场景执行后的设备状态变化会自动同步到HA

工作原理

数据获取流程

启动/部署
  ↓
调用云端API（房间信息接口）
  ↓
解析设备列表和场景列表
  ↓
根据MAC地址匹配本地设备
  ↓
更新设备名称（device.name）
  ↓
保存场景列表到本地
  ↓
重新发布MQTT Discovery配置
  ↓
持久化存储（缓存）
  ↓
完成（不再调用）

MAC地址匹配规则

云端返回的设备MAC地址会自动反转后与本地设备MAC地址匹配：

// 云端设备（MAC地址为反序存储）
{
  "device_name": "窗帘",
  "nick_name": "客厅窗帘",
  "mac": "14d881c086d4",  // 云端反序存储
  "naddr": 256
}

// 本地设备匹配
1. 将云端MAC转换为小写并去除分隔符: "14d881c086d4"
2. 反转MAC地址（每2位反转）: "d486c081d814"
3. 与本地设备MAC进行精确匹配
4. 匹配成功后更新 device.name = "客厅窗帘"
5. 如果云端名称为"未命名"或空，则保留设备类型标准名称（如"智能窗帘"）
6. 重新发布MQTT Discovery（使用新名称）

场景本地化调用

云端场景信息会保存到本地，可以通过网关直接调用：

// 云端场景
{
  "scene_name": "全关",
  "scene_id": 4
}

// 本地调用
通过inject节点发送: { scene_id: 4 }
节点会查找场景名称并输出到下游节点
可以连接到其他节点进行进一步处理

数据持久化

云端同步节点会将获取的数据持久化存储到Node-RED的context中：

存储内容：设备列表、场景列表、最后同步时间
存储位置：节点的context存储（重启后保留）
使用场景：
- 云端API调用失败时，自动使用缓存数据
- 禁用自动同步后，仍可使用上次获取的数据
- 网络故障时，不影响已同步的设备名称

常见问题

Q: 云端同步会影响性能吗？

A: 不会。云端同步仅在启动/部署时执行一次，不会持续轮询。同步完成后，节点处于空闲状态，不占用资源。

Q: 如果云端API调用失败怎么办？

A: 节点会自动使用上次成功获取的缓存数据。如果从未成功获取过，设备将保持原有名称。

Q: 可以禁用云端同步节点吗？

A: 可以。禁用节点不会影响其他功能（网关、MQTT、设备控制）的正常运行。已同步的设备名称会保留。

Q: 云端名称和本地设备如何匹配？

A: 通过MAC地址精确匹配。云端返回的设备MAC地址会自动反转后与本地设备MAC匹配（因为云端存储为反序）。如果云端名称为"未命名"或空，则自动保留设备类型标准名称（如"智能窗帘"、"零火开关"等）。

Q: 场景如何调用？

A: 云端同步后，场景会自动发布为Home Assistant按钮实体。在HA中点击场景按钮即可触发本地场景执行（使用0x34协议，不经过云端）。场景执行后，所有相关设备的状态会自动同步到HA，确保状态一致性。也可以通过inject节点发送 { scene_id: X } 来调用场景。

Q: 设备列表中的勾选框是做什么用的？

A: 勾选的设备会同步云端名称到本地，未勾选的设备保持原有名称不变。如果不勾选任何设备，则默认同步所有设备。场景勾选同理，勾选的场景会发布到Home Assistant。支持一键全选功能。

Q: 开关设备的按键名称如何显示？

A: 对于多键开关（1-6键），云端同步节点会显示每个按键的名称（如"床头灯"、"睡眠"等），这些名称来自云端的sub_device配置，并会同步到MQTT实体名称中。

Q: MQTT配置在哪里？

A: MQTT配置统一在网关节点中配置。所有使用该网关的节点（包括云端同步节点）都会自动使用网关中配置的MQTT客户端，无需重复配置。

Q: HA中的实体名称格式是什么？

A: HA实体名称为纯名称，不带MAC地址和ID。例如"客厅灯床头灯"而不是"客厅灯_14d881c086d4_1"。MAC地址仅用作unique_id确保实体唯一性。

Q: 多个房间如何管理？

A: 每个房间部署一个云端同步节点，配置对应的酒店ID和房间号即可。

故障排除

症状: 云端同步失败

解决方法:

检查App ID和App Secret是否正确
点击"测试连接"按钮验证认证信息
检查网络连接是否正常
查看调试日志中的详细错误信息

症状: 设备名称未更新

解决方法:

检查云端设备MAC地址是否与本地设备一致
查看调试日志中的"设备匹配完成"信息
确认MQTT节点已正确配置
手动触发同步（发送 msg.payload = "sync"）

症状: 场景无法调用

解决方法:

检查云端是否返回了场景列表
查看调试日志中的"场景列表已保存"信息
确认场景ID是否正确
检查网关连接是否正常

节点概览

节点	用途	详见章节
Symi Gateway	网关连接（TCP/串口）	快速开始
Symi MQTT	MQTT桥接，设备发布到HA	快速开始
Symi Device	Flow中单设备控制/监听	可用于KNX/自定义同步
Symi Cloud Sync	云端同步设备名称和场景	云端数据同步
Symi RS485 Bridge	RS485设备双向同步	RS485/Modbus双向同步
Symi KNX Bridge	KNX系统双向同步	KNX双向同步
RS485 Debug	RS485总线数据抓包调试	RS485调试节点

开发者信息

项目结构

node-red-contrib-symi-mesh/
├── lib/
│   ├── device-manager.js     # 设备管理和状态缓存
│   ├── mqtt-helper.js        # MQTT Discovery配置生成
│   ├── protocol.js           # 协议构建和解析
│   ├── tcp-client.js         # TCP连接客户端
│   └── serial-client.js      # 串口连接客户端
├── nodes/
│   ├── symi-gateway.js/html  # 网关配置节点
│   ├── symi-mqtt.js/html     # MQTT节点
│   ├── symi-device.js/html   # 设备控制节点
│   ├── symi-cloud-sync.js/html # 云端同步节点
│   ├── symi-485-bridge.js/html # RS485桥接节点
│   ├── symi-485-config.js/html # RS485配置节点
│   ├── symi-knx-bridge.js/html # KNX桥接节点
│   └── rs485-debug.js/html   # RS485调试节点
├── examples/
│   ├── basic-example.json    # 基础示例
│   ├── knx-sync-example.json # KNX Function节点示例
│   └── knx-bridge-example.json # KNX桥接节点示例
├── LICENSE
├── README.md
└── package.json

协议参考

本项目严格遵循"蓝牙MESH网关（初级版）串口协议V1.0"文档实现。

贡献指南

欢迎提交Issue和Pull Request：

Fork本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交Pull Request

开发要求：

遵循现有代码风格
添加必要的注释和文档
测试所有更改
更新README（如需要）

技术栈兼容性

版本要求

组件	最低版本	推荐版本	说明
Node-RED	≥3.0.0	4.0+	支持最新API
Node.js	≥18.0.0	22.x LTS	官方推荐LTS版本
MQTT Broker	任意	Mosquitto 2.x	支持MQTT 3.1.1+

Node.js 18+ 兼容性

本项目已针对Node.js 18+进行优化：

AggregateError处理：全局异常处理器捕获AggregateError，防止崩溃
Happy Eyeballs禁用：通过net.setDefaultAutoSelectFamily(false)禁用
强制IPv4连接：TCP连接使用family: 4参数，避免IPv6连接超时
网络异常恢复：自动捕获ECONNREFUSED、ETIMEDOUT等网络错误

代码质量

经2025-12-10代码审查确认：

遵循Node-RED节点开发规范
使用标准日志接口（node.log()、node.error()等）
正确处理节点关闭事件，清理事件监听器防止内存泄漏
无未处理的Promise rejection
无TODO/FIXME/HACK标记
代码无重复，模块化设计

技术支持

如遇问题，请提供以下信息：

环境信息:
- Node-RED版本
- Node.js版本
- 操作系统
网关信息:
- 网关型号
- 固件版本
- 连接方式（TCP/串口）
问题描述:
- 完整错误日志
- 设备类型和数量
- 复现步骤
调试日志:
- Node-RED调试日志
- MQTT日志（如相关）
- 网关串口日志（如可用）

常见问题排查

MQTT连接失败

问题：节点状态显示"Broker不可用"或"连接失败"

排查步骤：

检查MQTT Broker地址配置

# Docker部署时使用容器名
mqttBroker: mqtt://mosquitto:1883

# 本地安装时使用localhost
mqttBroker: mqtt://localhost:1883

确认MQTT Broker运行状态

# Docker方式
docker ps | grep mosquitto
docker start mosquitto  # 如未运行

# Homebrew方式（macOS）
brew services list | grep mosquitto
brew services start mosquitto

# 测试连接
nc -zv localhost 1883

检查防火墙/网络
- 确保1883端口未被占用或阻断
- 如使用Docker，确保网络配置正确

网关连接失败

问题：节点状态显示"连接失败"或频繁重连

排查步骤：

确认网关IP地址和端口（默认4196）
使用ping测试网络连通性
检查网关是否开启TCP服务模式
查看Node-RED日志中的详细错误信息

设备状态不同步

问题：HA中设备状态与实际不一致

排查步骤：

检查网关节点是否显示"已连接"
检查MQTT节点是否显示"已连接"
在Node-RED调试面板查看是否收到设备状态事件
确认MQTT Broker中的topic消息是否正确

更新日志

v1.6.7 (2025-12-10)

KNX双向同步完善：symi-knx-bridge节点全面升级
- knxUltimate消息格式：符合官方规范，使用destination+payload+dpt+event
- Universal Mode支持：输出节点需启用"Listen to all GA"，动态设置组地址
- 消息事件：添加event: "GroupValue_Write"，确保写入操作正确执行
- payload类型修复：DPT 1.001使用boolean类型(true/false)，不是number
- 地址映射修复：根据设备类型正确映射扩展地址到具体功能
- KNX输入匹配增强：支持所有配置地址的匹配，通过地址函数确定功能类型
- DPT格式兼容：支持"DPT1.001"和"1.001"两种格式
- 新增处理器：色温(light_color_temp)、空调风速(climate_fan)
- 防死循环：1秒防抖机制，智能防止状态回环
- 命令队列：最大100条，100ms防抖，50ms间隔
- 内存安全：节点关闭时清理所有缓存和事件监听器
KNX桥接节点功能：
- KNX实体库：支持从模板导入KNX组地址
- 一行映射：紧凑表格显示，适合大量设备配置
- 多设备类型：开关、调光灯、窗帘、空调、新风、地暖
- 智能通道选择：根据Mesh设备实际路数显示可选通道

v1.6.6 (2025-12-09)

三合一面板完整双向同步：支持空调+新风+地暖独立RS485映射
- 三合一0x94协议完整解析：空调(开关/模式/风速/温度)、地暖(开关/温度)、新风(开关/风速)
- Mesh→RS485：三合一状态变化自动发送对应RS485帧
- RS485→Mesh：RS485帧自动同步到三合一面板对应功能
- 支持climateSwitch/climateMode/fanMode/floorHeatingSwitch/freshAirSwitch等字段
开关双向同步修复：修复米家App全开/全关只触发部分按键的问题
- 命令队列防抖逻辑修复：只有完全相同映射才合并，不同映射独立处理
- 支持同一Mesh设备多通道分别绑定不同RS485设备
RS485多映射匹配：修复同一从机地址多个映射时只匹配第一个的问题
- findAllRS485Mappings返回所有匹配的映射
- rs485Channel精确匹配：根据寄存器地址确定通道
网络异常处理增强：彻底修复Node.js 18+ AggregateError导致崩溃的问题
- 全局uncaughtException/unhandledRejection处理器
- TCP连接过程同步错误捕获
- 只捕获网络相关错误，不影响其他异常
三合一面板自动识别：设备列表API返回isThreeInOne标志
窗帘双协议兼容：同时支持米家和小程序两种控制协议
- 米家协议: subOpcode=0x06, status: 0=打开中, 1=关闭中, 2=停止
- 小程序协议: subOpcode=0x05, status: 1=打开, 2=关闭, 3=停止
话语前湾协议完善：
- 空调：客厅/主卧/次卧1/次卧2，寄存器0x0FA0-0x0FAF
- 地暖：客餐厅(60)/主卧(61)/次卧1(62)/次卧2(63)，寄存器0x0039/0x0043
- 新风：从机60，开关0x0039(开=1)，风速0x004B(高=2,低=0)
地址输入修复：允许从机地址为0（话语前湾空调地址是0）
内存安全：命令队列限制100条，节点关闭时清理所有缓存
文档更新：添加三合一面板RS485配置说明和协议对照表

v1.6.5 (2025-12-06)

杜亚窗帘协议：原生支持杜亚窗帘协议(A6B6)，2字节地址，自动CRC16计算
- 帧格式：55 [地址高] [地址低] 03 [动作/位置] [CRC16低] [CRC16高]
- 支持打开(01)、关闭(02)、暂停(03)、百分比(04+位置)
窗帘控制智能判断：根据当前位置判断方向
- 位置>=50% + curtainStatus变化 → 发关闭码
- 位置<50% + curtainStatus变化 → 发打开码
- 暂停(curtainStatus=3)最高优先级
窗帘百分比模式修复：修复百分比控制后开/关命令失效的问题
- 百分比控制时进入百分比模式（inPosMode）
- 窗帘到位（curtainStatus=0）后自动退出百分比模式
- 退出后开/关命令可正常发送
发码防抖：500ms内不重复发相同码，避免Mesh状态混乱
设备类型过滤：映射只响应对应类型的状态变化
RS485调试增强：新增协议测试发送功能
初始化延迟：20秒，避免部署时误发命令