node-red-contrib-shico-mqtt 1.0.0

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

npm install node-red-contrib-shico-mqtt

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个按键状态）

使用方法：

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

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节点

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

2. 手动添加设备

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

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

3. 编辑设备

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

4. 控制设备

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

平台集成

Home Assistant (MQTT Discovery)

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

Apple HomeKit (原生支持)

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

Matter (原生支持)

  1. 部署一个 Shico Matter 节点
  2. 设置配对码（默认 20202021）和鉴别器
  3. 部署后，通过 UI 面板获取 Matter 二维码
  4. 在任何支持 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}")

这确保了：

  1. 同一设备不会重复注册
  2. MQTT实体不会重复生成
  3. 断电重启后设备ID保持不变
  4. 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

Node Info

Version: 1.0.0
Updated 9 hours ago
License: MIT
Rating: not yet rated
View on npm
View on GitHub
View Scorecard 11 1

Categories

Actions

Rate:

Downloads

0 in the last week

Nodes

  • shico-bridge
  • shico-dashboard
  • shico-homekit
  • shico-matter
  • shico-connection-config
  • shico-mqtt-config

Keywords

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

Maintainers