node-red-contrib-symi-mesh 1.2.3

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 SYMI 亖米
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,592 @@
+# node-red-contrib-symi-mesh
+
+一个为Node-RED设计的Symi蓝牙Mesh网关集成包，提供完整的设备控制和Home Assistant MQTT Discovery自动发现功能。
+
+[![npm version](https://badge.fury.io/js/node-red-contrib-symi-mesh.svg)](https://www.npmjs.com/package/node-red-contrib-symi-mesh)
+[![Node-RED](https://img.shields.io/badge/Node--RED-%3E%3D3.0.0-red)](https://nodered.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 功能特性
+
+- **完整协议支持**：TCP/串口双模式，严格遵循蓝牙MESH网关串口协议V1.0
+- **自动设备发现**：连接后自动发现所有设备，无需手动配置
+- **MQTT Discovery**：自动发布HA Discovery配置，设备即插即用
+- **双向状态同步**：支持0x80状态事件，实时反馈设备状态变化
+- **多设备类型**：支持开关、灯光、窗帘、温控器、传感器等12+种设备
+- **三合一面板**：完整支持空调+新风+地暖三合一控制面板
+- **KNX集成**：支持与KNX系统双向同步
+- **稳定可靠**：完善的错误处理和自动重连机制
+
+## 快速开始
+
+### 1. 安装
+
+**方式一：通过npm安装（推荐）**
+```bash
+cd ~/.node-red
+npm install node-red-contrib-symi-mesh
+```
+
+**方式二：通过Node-RED界面安装**
+1. 打开Node-RED界面
+2. 点击右上角菜单 → 节点管理
+3. 搜索 `node-red-contrib-symi-mesh`
+4. 点击安装
+
+**方式三：本地开发安装**
+```bash
+cd ~/.node-red
+npm install /path/to/node-red-contrib-symi-mesh
+```
+
+安装后重启Node-RED：
+```bash
+node-red-restart
+```
+
+### 2. 配置网关节点
+
+添加"Symi Gateway"配置节点：
+
+**TCP模式**（推荐）:
+- 主机地址: 网关IP（如 192.168.2.110）
+- 端口: 4196（默认）
+
+**串口模式**:
+- 串口路径: /dev/ttyUSB0
+- 波特率: 115200
+
+### 3. 配置MQTT节点
+
+添加"Symi MQTT"节点：
+
+- **网关**: 选择已配置的网关节点
+- **MQTT Broker**: mqtt://localhost:1883
+- **用户名/密码**: MQTT认证信息（可选）
+- **Discovery前缀**: homeassistant（默认）
+
+### 4. 部署并验证
+
+1. 点击右上角"部署"按钮
+2. 检查调试面板确认连接状态：
+   - `Gateway connected` - 网关连接成功
+   - `Device discovery complete` - 设备发现完成
+   - `MQTT已连接` - MQTT连接成功
+   - `发布设备 XXX` - 设备发布到MQTT
+3. 在Home Assistant中查看自动发现的设备
+4. 测试设备控制和状态反馈
+
+## 支持的设备类型
+
+| 设备类型 | 类型码 | 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+亮度+色温调节 |
+
+
+### 三合一设备说明
+
+三合一设备集成了空调、新风和地暖控制，在Home Assistant中自动创建3个独立实体：
+
+#### 实体说明
+
+**1. 空调（climate实体）**
+- 温度调节：16-30°C
+- 工作模式：制冷/制热/送风/除湿/关闭
+- 风速控制：高/中/低/自动
+
+**2. 新风（fan实体）**
+- 开关控制：ON/OFF
+- 风速档位：高/中/低/自动
+- 送风/排风：支持送风和排风方向控制
+
+**3. 地暖（climate实体）**
+- 温度调节：18-32°C
+- 工作模式：制热/关闭
+
+#### 使用方式
+
+**自动识别**：部署后自动区分普通温控器和三合一设备，无需手动配置
+
+**控制方式**：
+- HA中直接控制：设置温度/模式自动开启设备
+- 面板物理操作：状态自动同步到HA
+- MQTT直接控制：支持完整的MQTT命令
+
+**KNX同步**：
+在Symi Device节点中选择三合一设备，通过"子实体"下拉选项选择与KNX同步的功能：
+- 空调 ↔ KNX空调控制器
+- 新风 ↔ KNX新风控制器
+- 地暖 ↔ KNX地暖控制器
+
+每个功能独立同步，互不干扰。
+
+## 协议说明
+
+### 核心协议格式
+
+```
+[Header(0x53)] [Opcode] [Status] [Length] [Data] [Checksum]
+```
+
+### 关键操作码
+
+| 操作码 | 名称 | 方向 | 说明 |
+|-------|------|------|------|
+| 0x12 | 设备列表查询 | 主机→网关 | 查询所有设备 |
+| 0x92 | 设备列表响应 | 网关→主机 | 返回设备信息 |
+| 0x30 | 设备控制 | 主机→网关 | 控制指定设备 |
+| 0xB0 | 控制响应 | 网关→主机 | 控制结果 |
+| 0x80 | 状态事件 | 网关→主机 | 设备状态主动上报 |
+| 0x32 | 状态查询 | 主机→网关 | 查询设备状态 |
+
+### 开关状态编码（重要）
+
+**协议规则**: 每2位表示1路，b01=关，b10=开
+
+| 路数 | 全关 | 全开 | 示例 |
+|-----|------|------|------|
+| 1路 | 0x01 | 0x02 | 直接值 |
+| 2路 | 0x05 | 0x0A | 0x06=第1路开、第2路关 |
+| 3路 | 0x15 | 0x2A | 从低位开始 |
+| 4路 | 0x55 | 0xAA | 每2位1路 |
+| 6路 | 0x5555 | 0xAAAA | 2字节小端序 |
+
+### 常用消息类型
+
+| 消息类型 | 代码 | 数据格式 | 范围/说明 |
+|---------|------|---------|----------|
+| 开关状态 | 0x02 | 1-2字节 | 见上表 |
+| 亮度 | 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=有卡 |
+| RGB颜色 | 0x11 | 5字节 | R(0-255)/G/B/WW(0-100)/CW |
+| 当前温度 | 0x16 | 2字节LE | 温度*100 |
+| 目标温度 | 0x1B | 2字节LE | 16-30°C, *100 |
+| 风速 | 0x1C | 1字节 | 1=高/2=中/3=低/4=自动 |
+| 模式 | 0x1D | 1字节 | 1=制冷/2=制热/3=送风/4=除湿 |
+
+## 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系统的互联互通。
+
+### 配置步骤
+
+#### 1. 安装KNX节点
+```bash
+cd ~/.node-red
+npm install node-red-contrib-knx-ultimate
+```
+
+#### 2. 导入示例Flow
+在Node-RED中：
+- 菜单 → 导入 → 选择文件
+- 导入 `examples/knx-sync-example.json`
+- 修改网关IP地址和设备MAC地址
+- 修改KNX组地址匹配您的系统
+
+#### 3. 设备类型映射
+
+| Symi设备 | KNX类型 | DPT | 说明 |
+|---------|--------|-----|------|
+| 开关 | 开关执行器 | 1.001 | 布尔开关 |
+| 双色调光 | 调光执行器 | 1.001 + 5.001 | 开关+亮度(0-255) |
+| 五色调光 | RGB调光器 | 1.001 + 5.001 + 232.600 | 开关+亮度+RGB |
+| 窗帘 | 窗帘执行器 | 1.008 + 5.001 | 上下+位置(0-255) |
+| 温控器 | 空调控制器 | 1.001 + 9.001 + 20.102 | 开关+温度+模式 |
+| 人体感应 | 移动传感器 | 1.002 | 布尔值 |
+| 插卡取电 | 开关+传感器 | 1.001 + 1.002 | 开关+插卡检测 |
+| 三合一-空调 | 空调控制器 | 1.001 + 9.001 + 20.102 | 开关+温度+模式 |
+| 三合一-新风 | 风机控制器 | 1.001 + 5.001 | 开关+风速 |
+| 三合一-地暖 | 地暖控制器 | 1.001 + 9.001 | 开关+温度 |
+
+### 同步逻辑
+
+#### Symi → KNX（状态反馈）
+1. Symi设备状态变化
+2. symi-device节点输出状态
+3. function节点转换格式
+4. knxUltimate-out发送到KNX总线
+
+#### KNX → Symi（远程控制）
+1. KNX总线命令
+2. knxUltimate-in接收命令
+3. function节点转换为MQTT格式
+4. mqtt-out发送到symi_mesh topic
+5. symi-mqtt节点处理并控制设备
+
+### 转换函数示例
+
+#### 开关转换
+```javascript
+// Symi→KNX
+const value = msg.payload ? 1 : 0;
+msg.destination = '1/1/1';
+return msg;
+
+// KNX→Symi
+const mac = 'device_mac_clean';
+return {
+    topic: `symi_mesh/${mac}/switch/set`,
+    payload: msg.payload === 1 ? 'ON' : 'OFF'
+};
+```
+
+#### 调光灯转换
+```javascript
+// Symi→KNX (亮度)
+const brightness = Math.round(msg.payload.brightness * 255 / 100);
+msg.destination = '2/1/2';
+msg.dpt = '5.001';
+return msg;
+
+// KNX→Symi
+return {
+    topic: `symi_mesh/${mac}/light/set`,
+    payload: JSON.stringify({
+        brightness: msg.payload  // 0-255
+    })
+};
+```
+
+#### 窗帘转换
+```javascript
+// Symi→KNX (位置)
+const position = Math.round(msg.payload.curtainPosition * 255 / 100);
+msg.destination = '3/1/2';
+msg.dpt = '5.001';
+return msg;
+
+// KNX→Symi
+return {
+    topic: `symi_mesh/${mac}/cover/position/set`,
+    payload: Math.round(msg.payload * 100 / 255).toString()
+};
+```
+
+#### 三合一设备转换
+
+##### 空调转换（使用climate主题）
+```javascript
+// Symi→KNX (温度)
+msg.destination = '4/1/1';
+msg.dpt = '9.001';
+msg.payload = parseFloat(msg.payload.temp);
+return msg;
+
+// KNX→Symi (温度)
+return {
+    topic: `symi_mesh/${mac}/climate/target_temp/set`,
+    payload: msg.payload.toString()
+};
+
+// Symi→KNX (模式)
+const modeMap = { 'cool': 1, 'heat': 2, 'fan_only': 3, 'dry': 4 };
+msg.destination = '4/1/2';
+msg.dpt = '20.102';
+msg.payload = modeMap[msg.payload.mode] || 0;
+return msg;
+
+// KNX→Symi (模式)
+const modes = ['off', 'cool', 'heat', 'fan_only', 'dry'];
+return {
+    topic: `symi_mesh/${mac}/climate/mode/set`,
+    payload: modes[msg.payload] || 'off'
+};
+```
+
+##### 新风转换
+```javascript
+// Symi→KNX (开关)
+msg.destination = '4/2/1';
+msg.dpt = '1.001';
+msg.payload = msg.payload.switch ? 1 : 0;
+return msg;
+
+// KNX→Symi (开关)
+return {
+    topic: `symi_mesh/${mac}/fresh_air/set`,
+    payload: msg.payload === 1 ? 'ON' : 'OFF'
+};
+
+// Symi→KNX (风速)
+msg.destination = '4/2/2';
+msg.dpt = '5.001';
+msg.payload = Math.round(msg.payload.speed * 2.55);
+return msg;
+
+// KNX→Symi (风速)
+return {
+    topic: `symi_mesh/${mac}/fresh_air/speed/set`,
+    payload: Math.round(msg.payload / 2.55).toString()
+};
+```
+
+##### 地暖转换
+```javascript
+// Symi→KNX (温度)
+msg.destination = '4/3/1';
+msg.dpt = '9.001';
+msg.payload = parseFloat(msg.payload.temp);
+return msg;
+
+// KNX→Symi (温度)
+return {
+    topic: `symi_mesh/${mac}/floor_heating/target_temp/set`,
+    payload: msg.payload.toString()
+};
+```
+
+### 注意事项
+
+1. **组地址配置**：根据您的KNX系统修改组地址
+2. **DPT类型**：确保DPT类型与KNX设备匹配
+3. **MAC地址**：使用小写无冒号格式（如：`1427c920dacc`）
+4. **双向同步**：避免循环控制，使用`outputRBE: true`防抖
+5. **测试验证**：先测试单向同步，确认正常后再启用双向
+
+## 故障排除
+
+### 网关连接失败
+
+**症状**: 日志显示连接错误
+
+**解决方法**:
+1. 检查网关IP和端口（默认4196）
+2. 确认网关电源和网络正常
+3. 尝试ping网关IP
+4. 检查防火墙设置
+
+### 设备不显示
+
+**症状**: MQTT连接正常但HA中无设备
+
+**解决方法**:
+1. 确认HA的MQTT集成已启用
+2. 检查Discovery前缀是否正确（默认homeassistant）
+3. 查看MQTT日志：`symi_mesh/#`
+4. 重启Node-RED重新发布Discovery
+
+### 状态不同步
+
+**症状**: 控制正常但状态不更新
+
+**解决方法**:
+1. 检查日志中是否有`[状态事件]`
+2. 确认0x80事件正常接收
+3. 验证设备MAC地址和网络地址映射
+4. 重启网关和Node-RED
+
+### 控制无响应
+
+**症状**: HA发送命令但设备不动作
+
+**解决方法**:
+1. 检查MQTT命令是否发送（查看Node-RED日志）
+2. 确认网络地址正确
+3. 查看是否有`[控制响应] 0xB0`
+4. 尝试手动发送控制命令测试
+
+### 常见日志说明
+
+```
+[INFO] Gateway connected - 网关连接成功
+[INFO] Device discovery complete - 设备发现完成
+[INFO] [TCP Frame] 接收: 53 80 ... - 状态事件接收
+[INFO] [状态事件] 地址=0x... - 设备状态解析成功
+[INFO] MQTT已连接 - MQTT连接成功
+[INFO] 发布设备 XXX - 设备发布到MQTT
+[WARN] 未找到topic订阅 - MQTT订阅问题
+[ERROR] Connection refused - 连接被拒绝
+```
+
+## 节点说明
+
+### Symi Gateway（网关配置节点）
+
+配置节点，管理与Symi蓝牙Mesh网关的连接。
+
+**配置项**：
+- 连接类型：TCP或串口
+- TCP模式：IP地址和端口（默认4196）
+- 串口模式：串口路径和波特率（默认115200）
+
+**功能**：
+- 自动设备发现
+- 状态事件处理
+- 自动重连机制
+
+### Symi MQTT（MQTT桥接节点）
+
+将Symi设备桥接到MQTT broker，实现Home Assistant Discovery。
+
+**配置项**：
+- MQTT Broker地址
+- 用户名/密码（可选）
+- Discovery前缀（默认homeassistant）
+
+**功能**：
+- 自动发布Discovery配置
+- 双向MQTT消息处理
+- 设备状态同步
+
+### Symi Device（设备控制节点）
+
+用于Flow中直接控制和监听Symi设备状态。
+
+**配置项**：
+- 设备MAC地址
+- 通道选择（多路开关）
+- 子实体（三合一设备）
+
+**功能**：
+- 接收设备状态变化
+- 发送控制命令
+- 支持KNX双向同步
+
+## 开发者信息
+
+### 项目结构
+
+```
+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   # 设备控制节点
+├── examples/
+│   └── knx-sync-example.json # KNX双向同步示例
+├── LICENSE
+├── README.md
+└── package.json
+```
+
+### 协议参考
+
+本项目严格遵循"蓝牙MESH网关（初级版）串口协议V1.0"文档实现。
+
+### 贡献指南
+
+欢迎提交Issue和Pull Request：
+
+1. Fork本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 提交Pull Request
+
+**开发要求**：
+- 遵循现有代码风格
+- 添加必要的注释和文档
+- 测试所有更改
+- 更新README（如需要）
+
+## 技术支持
+
+如遇问题，请提供以下信息：
+
+1. **环境信息**:
+   - Node-RED版本
+   - Node.js版本
+   - 操作系统
+
+2. **网关信息**:
+   - 网关型号
+   - 固件版本
+   - 连接方式（TCP/串口）
+
+3. **问题描述**:
+   - 完整错误日志
+   - 设备类型和数量
+   - 复现步骤
+
+4. **调试日志**:
+   - Node-RED调试日志
+   - MQTT日志（如相关）
+   - 网关串口日志（如可用）
+
+## 更新日志
+
+### v1.2.3 (2025-10-28)
+- 修复三合一设备新风方向状态同步问题
+- 优化日志输出，提升系统性能
+- 完善Home Assistant MQTT Discovery兼容性
+
+### v1.2.0 (2025-10-27)
+- 完整支持三合一设备（空调+新风+地暖）
+- 新增MQTT Discovery自动发现功能
+- 优化设备识别和状态同步机制
+
+
+## 许可证
+
+MIT License
+
+Copyright (c) 2025 SYMI 亖米
+
+---
+
+## 关于
+
+**作者**: SYMI 亖米
+**版本**: 1.2.3
+**协议**: 蓝牙MESH网关（初级版）串口协议V1.0
+**最后更新**: 2025-10-28
+**仓库**: https://github.com/symi-daguo/node-red-contrib-symi-mesh
+**npm包**: https://www.npmjs.com/package/node-red-contrib-symi-mesh