node-red-contrib-shico-mqtt

v1.0.0

Published

14 days ago

Node-RED node for Shico smart home protocol to MQTT bridge with Home Assistant auto-discovery

0High
0Medium
0Low

symi-daguo

node-red shico mqtt home-assistant smart-home homekit matter iot

node-red-contrib-shico-mqtt

Node-RED节点，用于将中科易讯(Shico)智能家居设备协议转换为标准MQTT协议，支持Home Assistant自动发现、原生HomeKit和Matter集成。

运行环境

Node.js 18.x / 20.x / 22.x (推荐 20.x LTS)
Node-RED 3.0+
注意: Node.js 23.x 可能会出现 hap-nodejs 的 EBADENGINE 警告，但不影响功能使用

功能特性

支持所有Shico设备类型：继电器、调光器、色温灯、窗帘、新风、地暖、按键面板、人体感应器
自动发现 + 手动录入：支持设备自动发现，也支持手动添加设备
设备唯一性保证：基于设备地址+类型+回路生成UUID，确保设备和MQTT实体不重复
设备名称管理：支持修改设备名称，名称会同步到HomeKit和Matter实体
原生 HomeKit/Matter 支持：专用的 Shico HomeKit 和 Shico Matter 节点
设备控制看板：Shico Dashboard 节点提供宽屏设备控制看板（2000px宽度）
可视化管理面板：设备列表支持查看、添加、编辑、删除操作（高度1000px）
特性匹配算法：统一处理亮度 (0-255 vs 0-100)、色温 (128-255 vs 153-500 mireds) 等单位转换
跨节点事件同步：Bridge 与 HomeKit/Matter 节点通过全局事件实时同步实体状态与名称变更
宽屏UI优化：Bridge/HomeKit/Matter 宽度1000px，Dashboard 宽度2000px，设备列表高度1000px
Home Assistant MQTT自动发现 (Discovery)
设备状态持久化：断电断网恢复后自动恢复状态
稳定性增强：内置防抖机制、内存优化、无调试日志

节点说明

本插件包含以下节点：

Shico Bridge (核心节点)

核心桥接节点，负责与物理设备通信，支持自动发现并生成标准 HA 实体。

设备管理功能：

自动发现：勾选"启用 Home Assistant 自动发现"后，节点会自动扫描并注册设备
手动添加：通过界面输入设备地址(1-199)、类型、回路号和名称
完整编辑：点击编辑按钮可修改设备的所有属性（地址、类型、回路、名称）
删除设备：点击删除按钮移除设备
实时状态：设备列表显示实时在线状态和当前值（列表高度1000px）
设备控制面板：点击控制按钮可直接控制设备（开关、亮度、色温、窗帘）

名称同步说明：

在Bridge节点中设置的设备名称会自动同步到：
- Home Assistant 实体名称
- HomeKit 配件名称
- Matter 端点名称
修改名称后，HomeKit和Matter会自动更新显示

Shico Dashboard (设备控制看板)

可视化设备控制面板节点，在节点配置界面提供宽屏设备控制看板（宽度2000px）。

配置说明：

Bridge 选择：从下拉菜单选择已配置的 Shico Bridge 节点
必须先创建并部署 Bridge 节点，才能在下拉菜单中看到

功能特点：

双栏布局：左侧设备卡片列表（高度1000px），右侧控制面板
设备卡片：以卡片形式展示所有设备，显示类型图标、名称、状态
实时状态：在线/离线状态、开关状态、亮度百分比等
快捷控制：点击设备卡片，右侧显示对应控制面板
类型匹配：根据设备类型自动显示对应的控制界面
支持控制类型：
- 继电器 (0xA1)：开关按钮
- 调光器 (0xA2)：开关 + 亮度滑块
- 色温灯 (0xA3)：开关 + 亮度 + 色温滑块
- 窗帘 (0xA4)：开/停/关按钮 + 位置滑块
- 新风 (0xB1)：开关按钮
- 地暖 (0xB2)：开关按钮
- 人体感应 (0xA5)：只读状态显示（有人/无人、温度、照度）
- 按键面板 (0xA6)：只读状态显示（8个按键状态）

使用方法：

先创建并部署 Shico Bridge 节点
拖入 Shico Dashboard 节点
双击节点打开配置界面
从下拉菜单选择关联的 Bridge 节点
设备列表自动加载，点击设备卡片进行控制

Shico HomeKit

原生 Apple HomeKit 网桥节点，无需 Home Assistant 即可直接在 Apple Home 中发现。

配置说明：

Bridge 选择：从下拉菜单选择已配置的 Shico Bridge 节点
配对码：默认 031-45-154，可自定义
桥接 ID：MAC 地址格式，每个 HomeKit 网桥需唯一
监听端口：默认 51826

Shico Matter

原生 Matter 网桥节点，支持 Apple Home, Google Home, Alexa 和 SmartThings。

配置说明：

Bridge 选择：从下拉菜单选择已配置的 Shico Bridge 节点
配对码：默认 20202021
鉴别器：默认 3840

MQTT Config

共享的 MQTT Broker 配置节点，支持自定义名称以便区分多个 MQTT 服务器。

配置说明：

名称：自定义名称，如"本地MQTT"、"云端MQTT"
Broker：MQTT 服务器地址
Port：端口号（默认 1883）
Username/Password：认证信息（可选）
Topic Prefix：主题前缀（默认 shico）
Discovery Prefix：HA 自动发现前缀（默认 homeassistant）

Connection Config (网关配置)

共享的 TCP/Serial 连接配置节点，支持自定义名称以便区分多个网关。

配置说明：

网关名称：自定义名称，如"客厅网关"、"卧室网关"
连接类型：TCP 网络连接或 Serial 串口连接
TCP 配置：主机地址、端口号、超时时间、重连间隔
串口配置：串口设备、波特率、数据位、停止位、校验位

安装

通过npm安装

cd ~/.node-red
npm install node-red-contrib-shico-mqtt

本地开发安装

cd ~/.node-red
npm install /path/to/node-red-contrib-shico-mqtt

或使用npm link：

cd /path/to/node-red-contrib-shico-mqtt
npm link

cd ~/.node-red
npm link node-red-contrib-shico-mqtt

安装后重启Node-RED。

快速开始

1. 配置Bridge节点

拖入 Shico Bridge 节点
配置 MQTT 服务（选择或新建 MQTT Broker）
配置网关（选择或新建网关配置，可设置名称如"客厅网关"）
勾选"启用 Home Assistant 自动发现"
部署后，设备会自动出现在列表中

2. 手动添加设备

如果设备未被自动发现，可以手动添加：

点击"添加设备"按钮
在弹出的对话框中输入设备地址 (1-199)
选择设备类型（界面会自动显示该类型的专属配置项）
输入回路号 (1-8)
输入设备名称（用于在HomeKit/Matter中显示）
根据设备类型配置专属参数：
- 调光器：默认亮度、调光速度
- 色温灯：默认亮度、默认色温、调光速度
- 窗帘：默认位置
- 新风：默认风速
- 地暖：目标温度
- 按键面板：按键数量
点击"保存"

3. 编辑设备

在设备列表中找到要修改的设备
点击编辑按钮（铅笔图标）
在弹出的对话框中可修改所有属性：地址、类型、回路、名称
点击"保存"
名称会自动同步到HomeKit和Matter

4. 控制设备

在设备列表中找到在线的设备
点击控制按钮（滑块图标）
在控制面板中可以：
- 继电器：开关控制
- 调光器：开关 + 亮度滑块
- 色温灯：开关 + 亮度 + 色温滑块
- 窗帘：开启/停止/关闭按钮

平台集成

Home Assistant (MQTT Discovery)

确保 Node-RED 能够连接到 Home Assistant 使用的 MQTT Broker
在 Bridge 节点中开启"自动发现"
设备联网后，HA 将自动识别并添加对应的实体

Apple HomeKit (原生支持)

部署一个 Shico HomeKit 节点
设置名称、配对码（默认 031-45-154）
部署后打开节点配置，查看配对二维码
使用 iPhone 的"家庭"App 扫描二维码完成添加

Matter (原生支持)

部署一个 Shico Matter 节点
设置配对码（默认 20202021）和鉴别器
部署后，通过 UI 面板获取 Matter 二维码
在任何支持 Matter 的 App 中选择"添加设备"并扫描二维码

MQTT主题规范

状态主题

{prefix}/{device_id}/state

控制主题

{prefix}/{device_id}/set

可用性主题

{prefix}/{device_id}/availability

HA Discovery主题

homeassistant/{component}/{node_id}/{object_id}/config

状态消息格式

继电器/开关

{ "state": "ON" }

调光器

{ "state": "ON", "brightness": 255 }

色温灯

{ "state": "ON", "brightness": 255, "color_temp": 370 }

窗帘

{ "state": "open", "position": 100 }

人体感应器

{ "occupancy": "true", "temperature": 25, "illuminance": 500 }

控制命令

查询设备列表

{ "action": "queryDevices" }

手动添加设备

{ "action": "addDevice", "address": 1, "funcCode": 161, "loop": 1, "name": "客厅灯" }

控制设备

{ "action": "control", "deviceId": "xxx-xxx-xxx", "power": true }

刷新自动发现

{ "action": "refresh" }

支持的设备

| 设备类型 | 功能码 | HA组件 | 功能 | |---------|--------|--------|------| | 继电器模块 | 0xA1 | switch | 开关控制 | | 调光模块 | 0xA2/0xD1/0xD7/0xD8/0xD9 | light | 开关/亮度/预设/亮度+/亮度- | | 色温灯模块 | 0xA3/0xD2 | light | 开关/亮度+色温 | | 窗帘模块 | 0xA4/0xD4 | cover | 开/关/停/位置控制 | | 新风模块 | 0xB1 | switch | 开关控制 | | 地暖模块 | 0xB2 | switch | 开关控制 | | 按键面板 | 0xA6/0xA7/0xA9 | binary_sensor | 8按键状态/人体感应/场景 | | 人体感应器 | 0xA5/0xD6 | binary_sensor/sensor | 占用/温度/照度 |

单位转换说明

| 特性 | Shico 范围 | HomeKit/Matter/HA 范围 | 转换逻辑 | |------|-----------|----------------------|----------| | 亮度 | 0 - 255 | 0 - 100 (%) | round((val/255)*100) | | 色温 | 128 - 255 | 153 - 500 (mireds) | 线性映射 | | 窗帘位置 | 0 - 100 | 0 - 100 | 直接映射 |

设备唯一性说明

设备ID基于以下三个参数生成UUID：

设备地址 (1-199)
设备类型 (继电器/调光器/色温灯等)
回路号 (1-8)

生成公式：UUID = SHA1("shico_{address}_{deviceType}_{loop}")

这确保了：

同一设备不会重复注册
MQTT实体不会重复生成
断电重启后设备ID保持不变
HomeKit/Matter配件ID稳定

常见问题

设备未被自动发现？

确保设备已上电并连接到网络
检查TCP/串口连接是否正常
可以手动添加设备

名称修改后HomeKit未更新？

HomeKit可能需要几秒钟同步
如果仍未更新，尝试在Home App中重新加载

Matter配对失败？

确保Matter依赖已正确安装：npm install @matter/node @matter/nodejs
检查端口是否被占用

更新记录

2025-12-25

MQTT 配置节点新增名称字段，支持自定义名称以便区分多个 MQTT 服务器
网关配置节点新增名称字段，支持自定义名称以便区分多个网关
"设备连接"改名为"网关配置"
设备添加界面根据协议文档智能显示/隐藏回路选择：
- 需要回路选择：继电器、调光器、色温灯、窗帘、按键面板、新风、地暖（支持多回路/通道）
- 不需要回路选择：人体感应器（单设备，无回路字段）
新增设备类型专属配置界面：添加/编辑设备时根据类型显示对应配置项
- 调光器：默认亮度、调光速度
- 色温灯：默认亮度、默认色温、调光速度
- 窗帘：默认位置
- 新风：默认风速
- 地暖：目标温度
- 按键面板：按键数量
- 继电器/人体感应：显示设备说明
新增 Shico Dashboard 节点（设备控制看板，宽度2000px）
修复 Dashboard/HomeKit/Matter 节点的 Bridge 选择下拉菜单
Dashboard 根据设备类型自动匹配对应控制界面
人体感应器和按键面板显示只读状态（不显示控制按钮）
设备唯一性保证：基于地址+类型+回路生成UUID
MQTT实体唯一性：避免重复生成实体
设备列表高度增加到 1000px，支持显示更多设备
新增设备完整编辑功能（地址、类型、回路、名称全部可编辑）
新增设备控制面板（支持开关、亮度、色温、窗帘控制）
设备列表显示自动发现和手动添加的设备
名称修改自动同步到HomeKit和Matter
优化UI图标和文字对齐
状态显示更友好（亮度百分比、中文状态）

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

node-red-contrib-shico-mqtt

运行环境

功能特性

节点说明

Shico Bridge (核心节点)

Shico Dashboard (设备控制看板)

Shico HomeKit

Shico Matter

MQTT Config

Connection Config (网关配置)

安装

通过npm安装

本地开发安装

快速开始

1. 配置Bridge节点

2. 手动添加设备

3. 编辑设备

4. 控制设备

平台集成

Home Assistant (MQTT Discovery)

Apple HomeKit (原生支持)

Matter (原生支持)

MQTT主题规范

状态主题

控制主题

可用性主题

HA Discovery主题

状态消息格式

继电器/开关

调光器

色温灯

窗帘

人体感应器

控制命令

查询设备列表

手动添加设备

控制设备

刷新自动发现

支持的设备

单位转换说明

设备唯一性说明

常见问题

设备未被自动发现？

名称修改后HomeKit未更新？

Matter配对失败？

更新记录

2025-12-25

许可证