node-red-contrib-symi-starloop 1.0.2

Node-RED nodes for SYMI-STARLOOP device control with MQTT/HomeKit/Matter integration support

npm install node-red-contrib-symi-starloop

node-red-contrib-symi-starloop

SYMI-STARLOOP 设备的 Node-RED 专业控制节点,支持四种使用方案,满足不同客户需求。

核心特性

• 100%协议覆盖 - 实现所有官方协议功能,一个都不少
• 四种使用方案 - 直接控制 / MQTT→HA / HomeKit / Matter,满足不同需求
• 自动重连机制 - 网络断开自动恢复,节点稳定运行不死机
• 自动设备发现 - mDNS/Bonjour协议,一键搜索局域网设备
• 完整示例集 - 5个场景示例,开箱即用
• 错误处理 - 命令失败自动重试,双输出(成功/错误)
• Siri语音控制 - 支持HomeKit和Home Assistant桥接

四种使用方案对比

特性	方案一: 直接控制	方案二: MQTT→HA	方案三: HomeKit	方案四: Matter
需要额外软件	无	HA + MQTT	HAP-NodeJS	Matter库
配置复杂度	简单	中等	中等	中等
语音控制	否	是	Siri	多平台
HA自动化	否	是	否	是
跨平台	否	是	仅Apple	全平台
所有功能	17种	30+实体	全部	全部
适用场景	简单自动化	智能家居集成	Apple生态	跨平台智能家居
网络断线恢复	是	是	是	是

支持的所有功能

基本控制

• 电源开关 - 开机/关机/切换
• 音量调节 - 0-70,可选显示音量条
• 静音 - 静音/取消静音/切换
• 输入源切换 - 本地/HDMI1/HDMI2/AUX/光纤/ARC/蓝牙

遥控器按键 (14种)

• 方向键: 上/下/左/右/确认
• 系统键: 电源/主页/菜单/返回
• 播放控制: 播放/暂停
• 音量键: 音量+/音量-/静音

播放控制

• 循环模式 - 单次/列表循环/单曲循环/随机
• 播放进度 - 千分比(0-1000)或精确毫秒值
• 演示文件 - 播放指定目录文件

设备控制

• 休眠/唤醒 - 设备休眠或唤醒
• 麦克风 - 开启/关闭/切换
• 功能按键 - 文件夹/应用/音效

高级功能

• 截图 - 截取当前画面
• 录制 - 开始/停止语音录制
• 订阅语音识别 - 接收智能家居语音识别结果
• 订阅设备状态 - 实时监控设备状态变化

快速开始

重要说明

本节点通过局域网UDP协议直接与星环设备通信，无需网关或云服务。只要设备和Node-RED在同一局域网，即可使用全部功能。

核心优势：

• 本地控制，无需互联网
• 响应速度快，延迟低
• 隐私安全，数据不上云
• 稳定可靠，不受云服务影响

安装

方法1: 通过 Node-RED 面板管理器 (推荐)

1. 打开 Node-RED
2. 菜单 → 管理面板 → 安装
3. 搜索 node-red-contrib-symi-starloop
4. 点击安装

方法2: 通过 npm

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

配置设备连接

步骤1: 添加设备配置节点

1. 右上角菜单 → 配置节点
2. 点击"添加" → 选择 starloop-device
3. 配置设备:
   • 方式A: 自动发现 (推荐)
     • 勾选"启用自动发现"
     • 点击"搜索局域网设备"
     • 从列表中选择设备
   • 方式B: 手动配置
     • 输入设备IP地址 (例如: 192.168.1.100)
     • UDP端口默认 44654
     • 设备序列号通常留空
4. 点击"添加"保存

步骤2: 使用功能节点

1. 从节点面板拖入 starloop 节点
2. 双击节点配置:
   • 选择刚才配置的设备
   • 选择功能类型 (电源/音量/输入源等)
   • 配置参数
3. 部署流程

安装验证

安装完成后,验证节点是否正常工作:

1. 检查节点面板

   • 在Node-RED左侧面板中,应该能看到"SYMI STARLOOP"分类
   • 包含4个节点: starloop-device, starloop, starloop-homekit, starloop-matter

2. 测试基本功能

   • 拖入一个inject节点和starloop节点
   • 配置设备IP地址
   • 部署并点击inject按钮
   • 检查调试输出是否有响应

3. 测试HomeKit功能 (可选)

   • 安装依赖: cd ~/.node-red && npm install hap-nodejs
   • 拖入starloop-homekit节点并配置
   • 部署后查看日志,应该显示"HomeKit桥接已启动"
   • 在iPhone"家庭"App中添加配件,输入配对码: 031-45-154

4. 测试Matter功能 (可选)

   • 确保已安装matter库: cd ~/.node-red && npm install @project-chip/matter-node.js
   • 拖入starloop-matter节点
   • 配置设备连接
   • 部署后查看日志,应该显示"Matter桥接已启动"
   • 在Matter控制器中添加设备,输入配对码: 20202021

部署检查清单

在部署流程前,请确认以下事项:

基本配置

• 设备IP地址正确
• 设备和Node-RED在同一局域网
• 所有starloop节点都已关联到设备配置节点
• 没有红色三角形警告(未配置的节点)

HomeKit配置 (如果使用)

• 已安装hap-nodejs库 (>=0.11.1): npm install hap-nodejs@^0.11.1
• username格式正确 (MAC地址格式,如: CC:22:3D:E3:CE:30)
• pinCode格式正确 (XXX-XX-XXX,如: 031-45-154)
• 端口未被占用 (默认: 51826 和 51827)
• setupID已设置 (默认: STAR 和 STAR2)
• 如遇输入源名称异常或配对失败,清理持久化目录后重试: rm -rf ~/.node-red/homekit-persist

Matter配置 (如果使用)

• 已安装matter库
• passcode格式正确(8位数字,如: 20202021)
• discriminator已设置(默认: 3840)
• 端口未被占用(默认: 5540)
• vendorId和productId已设置

网络配置

• 防火墙允许UDP 44654端口(命令)
• 防火墙允许UDP 44655端口(语音)
• 防火墙允许UDP 5353端口(mDNS)
• 防火墙允许TCP 51826端口(HomeKit)
• 防火墙允许TCP 5540端口(Matter)

导入示例

最快的上手方式是导入示例流程:

1. 菜单 → 导入 → 示例
2. 选择 node-red-contrib-symi-starloop
3. 选择示例:
   • complete-examples - 完整示例集(推荐)
   • automation-flow - 自动化场景
   • homekit-integration - HomeKit集成
4. 修改设备配置为你的设备
5. 部署测试

使用方案详解

方案一: 直接控制 (最简单)

无需任何额外软件,直接在Node-RED中控制设备。

示例1: 基本控制流程

[inject:触发] → [starloop:开机] → [delay:2秒] → [starloop:音量50] → [starloop:HDMI1]

示例2: 通过消息动态控制

// Function节点
msg.payload = {
    command: "volume",
    params: { volume: 50, showBar: true }
};
return msg;

连接到 starloop 节点(action设置为"通过消息控制")。

所有可用命令

// 电源控制
{ command: "power", params: { on: true } }

// 音量控制
{ command: "volume", params: { volume: 50, showBar: true } }

// 静音
{ command: "mute", params: { mute: true } }

// 输入源切换
{ command: "source", params: { source: "hdmi1" } }
// 可选: local, hdmi1, hdmi2, aux, optical, arc, bluetooth

// 遥控器按键
{ command: "key", params: { key: "UP" } }
// 可选: UP, DOWN, LEFT, RIGHT, OK, POWER, HOME, MENU, BACK, MUTE, VOLUME_UP, VOLUME_DOWN, PLAY_PAUSE

// 循环模式
{ command: "loop", params: { mode: "list" } }
// 可选: single, list, single_loop, random

// 播放进度
{ command: "play_progress", params: { value: 500, useMilliseconds: false } }
// value: 0-1000(千分比) 或 毫秒值

// 休眠/唤醒
{ command: "sleep", params: { sleep: true } }

// 麦克风
{ command: "microphone", params: { state: "toggle" } }
// 可选: on, off, toggle

// 功能按键
{ command: "function_key", params: { key: "folder" } }
// 可选: folder, app, sound

// 截图
{ command: "screenshot", params: {} }

// 录制
{ command: "recording_start", params: {} }
{ command: "recording_stop", params: {} }

// 演示文件
{ command: "demo_file", params: { directory: 1 } }

// 订阅语音识别
{ command: "voice_subscribe", params: { clientId: "nodered_001", enable: true } }

// 订阅设备状态
{ command: "state_subscribe", params: { clientId: "nodered_001", enable: true } }

方案二: MQTT → Home Assistant

通过MQTT自动发现协议,将设备集成到Home Assistant。

前置要求

1. 已安装并配置 Home Assistant
2. 已安装并配置 MQTT Broker (如 Mosquitto)
3. HA中已配置MQTT集成

配置步骤

1. 添加MQTT服务器配置

   • 在Node-RED中添加 mqtt-broker 配置节点
   • 配置MQTT服务器地址、端口、用户名、密码

2. 启用MQTT集成

   • 在 starloop 节点中勾选"启用MQTT"
   • 选择MQTT服务器
   • 配置发现前缀 (默认: homeassistant)
   • 配置基础主题 (默认: starloop)

3. 部署流程

   • 部署后,节点会自动发送MQTT发现消息
   • 在HA中查看: 设置 → 设备与服务 → MQTT → 设备
   • 会看到一个名为"星环设备"的设备,包含30+个实体

HA中的实体列表

媒体播放器 (1个)

• media_player.starloop_device - 主控制器

开关 (14个)

• 电源开关
• 13个遥控器按键开关

数字输入 (1个)

• 音量控制 (0-70)

选择器 (3个)

• 输入源选择
• 循环模式选择
• 播放进度选择

按钮 (11个)

• 截图、录制、演示文件等功能按钮

桥接到HomeKit

在HA中配置HomeKit集成:

1. 设置 → 设备与服务 → 添加集成 → HomeKit
2. 选择要桥接的实体
3. 在iPhone的"家庭"App中添加配件

方案三: 直接HomeKit

无需Home Assistant,直接创建HomeKit配件。

前置要求

需要安装 HAP-NodeJS 库:

cd ~/.node-red
npm install hap-nodejs

配置步骤

1. 添加HomeKit桥接节点

   • 从节点面板拖入 starloop-homekit 节点
   • 配置设备连接
   • 设置桥接名称和配对码
   • 选择要启用的服务 (电视/扬声器/开关)

2. 部署流程

   • 部署后,节点会自动创建HomeKit桥接
   • 查看日志获取配对信息

3. 在iPhone上添加配件

   • 打开"家庭"App
   • 点击右上角"+" → "添加配件"
   • 选择"更多选项"
   • 找到"星环影音"和"星环配件"（需要分别添加2个桥接）
   • 输入配对码: 031-45-154（两个桥接使用相同配对码）
   • 完成配对

HomeKit配件结构

本节点创建2个独立的HomeKit桥接：

桥接1: 星环影音 (端口 51826)

• 星环影音 (Television - 电视图标 📺)
  • 电源控制（开/关）
  • 7个输入源（每个都有正确的名称显示）：
    1. 本地 (OTHER)
    2. HDMI 1 (HDMI)
    3. HDMI 2 (HDMI)
    4. AUX (OTHER)
    5. 光纤 (OTHER)
    6. ARC (HDMI)
    7. 蓝牙 (OTHER)
  • 集成遥控器 (方向键、确定、返回、主页、播放/暂停、菜单)
  • 集成扬声器 (音量调节 0-100%、静音开关)

桥接2: 星环配件 (端口 51827)

• 4个配件（每个配件包含多个Switch服务，点开配件后每个按钮显示正确的功能名称）：

1. 星环-基础控制（3个Switch）

• 开关麦克风（协议：101, 10, 0关闭/1开启）
• 休眠/唤醒（协议：101, 13, 0休眠/1唤醒）
• 静音（协议：101, 14, 0静音/1解除静音）

2. 星环-功能按钮（6个Switch点动）

• 音效键（协议：101, 6, 0）
• 文件夹（协议：101, 8, 0）
• 应用键（协议：101, 9, 0）
• 截图（协议：101, 5, 0）
• 切换蓝牙（协议：101, 11, 0）
• 录音（协议：101, 7, 0）

3. 星环-输入源（7个Switch）

• 切换本机（协议：101, 1, 0）
• 切换HDMI1（协议：101, 1, 1）
• 切换HDMI2（协议：101, 1, 2）
• 切换AUX（协议：101, 2, 0）
• 切换光纤（协议：101, 3, 0）
• 切换ARC（协议：101, 4, 0）
• 切换蓝牙源（协议：101, 11, 0）

4. 星环-遥控器（9个Switch点动）

• 上键（协议：100, 19, 0按下/1抬起）
• 下键（协议：100, 20, 0按下/1抬起）
• 左键（协议：100, 21, 0按下/1抬起）
• 右键（协议：100, 22, 0按下/1抬起）
• 确定键（协议：100, 66, 0按下/1抬起）
• 返回键（协议：100, 4, 0按下/1抬起）
• 主页键（协议：100, 3, 0按下/1抬起）
• 暂停播放（协议：100, 127, 0按下/1抬起）
• 菜单键（协议：100, 82, 0按下/1抬起）

重要说明：

• ✅ 遥控器和扬声器已正确集成在电视配件内，不是独立配件
• ✅ 音量控制已集成在遥控器界面的扬声器服务中（0-100%），无需独立配件
• ✅ 4个配件，每个服务名称正确显示：只需添加4次到房间，每个服务名称与协议一致
• ✅ 使用Outlet服务（圆形图标）：比Switch更紧凑，不占用屏幕空间，直接点击无弹窗
• ✅ 名称与协议一致：所有服务名称与协议文档完全一致，降低学习成本
• ✅ 每个服务都可单独用于场景和自动化：
  • 开关类服务有真实的开/关状态，可同步设备状态
  • 点动按钮自动关闭500ms，实现点动效果
  • 输入源服务互斥（打开一个会自动关闭其他）

场景示例：

• "打开切换HDMI1" = 切换到HDMI1
• "打开暂停播放" = 按播放键
• "打开开关麦克风" = 开启麦克风

自动化示例：

• "当切换HDMI1打开时，打开客厅灯" = 当切换到HDMI1时，打开客厅灯
• "当开关麦克风打开时，关闭其他设备" = 当开启麦克风时，关闭其他设备
• "当截图打开时，发送通知" = 当按截图键时，发送通知
• ✅ 两个桥接使用不同端口和MAC地址，互不冲突
• ✅ 输入源名称正确显示（本地、HDMI 1、HDMI 2、AUX、光纤、ARC、蓝牙）
• ✅ 兼容 iOS 18-26，遥控器界面在长按电视配件后显示

Siri语音命令

电视控制

"嘿Siri,打开星环电视"
"嘿Siri,关闭星环电视"
"嘿Siri,把星环切换到HDMI1"
"嘿Siri,把星环切换到HDMI2"

音量控制

"嘿Siri,把星环音量调到50"
"嘿Siri,静音星环"
"嘿Siri,取消星环静音"
"嘿Siri,把星环音量调大"
"嘿Siri,把星环音量调小"

功能控制

"嘿Siri,打开星环麦克风"
"嘿Siri,关闭星环麦克风"
"嘿Siri,打开星环睡眠模式"
"嘿Siri,关闭星环睡眠模式"

HomeKit使用说明

配对方式：

• 需要分别配对2个桥接（在"家庭"App中会看到2个配件）
• 桥接1（星环影音）：配对码 031-45-154，端口 51826
• 桥接2（星环配件）：配对码 031-45-154，端口 51827
• 重要：删除旧配对记录后需要重新配对：rm -rf ~/.node-red/homekit-persist

遥控器使用 (iOS/iPadOS 18-26):

1. 打开"家庭"App
2. 找到"星环影音"配件（电视图标📺）
3. 点击配件图标进入控制界面
4. 在控制界面中可以看到：
   • 电源开关
   • 输入源选择
   • 遥控器按钮（方向键、确定、返回、播放、菜单等）
   • 音量控制

重要说明：

• 遥控器按钮在电视配件的控制界面中，不是在"配件设置"里
• iOS 控制中心也可以快速访问电视遥控器
• 如未显示遥控器：删除配件重新配对/更新iOS/重启家庭App

HomeKit 故障排除（输入源名称与桥接）

问题：输入源名称显示成“输入源1/2/3…”或英文“Input Source 1/2/3…”

• 现象：iOS 18 存在重命名 bug，可能将已设置的输入源改成默认名称
• 解决：代码已同时设置 ConfiguredName 与 Name，并在检测到默认名称时自动恢复
• 如仍异常：
  1. 删除“家庭”App中的两个配件（星环影音、星环配件）
  2. 清理持久化目录：rm -rf ~/.node-red/homekit-persist
  3. 重新部署并重新配对

问题：桥接无法启动或端口占用

• 查看日志是否有 Error: port in use
• 改用不同端口或关闭正在运行的 Node-RED
• 默认端口：电视桥接 51826，配件桥接 51827

**预期的输入源列表（名称完全一致）

• 本地, HDMI 1, HDMI 2, AUX, 光纤, ARC, 蓝牙

问题：Node-RED 里 HomeKit Bridge 显示“初始化失败”，但家庭 App 正常可用

• 常见原因：
  • 端口冲突：另一个 HomeKit Bridge（如 node-red-contrib-homekit-bridged）使用了 51826，与本节点默认端口相同
  • 存储路径冲突：HAP-NodeJS 的 HAPStorage 只允许设置一次存储路径，两个模块同时设置会导致其中一个报错
• 解决方案：
  • 仅保留一种桥接方式：若使用本节点自带桥接，禁用或移除 homekit-bridged 的 Bridge 配置节点
  • 如需同时使用：确保使用不同端口（建议本节点设置为 51828 和 51829；homekit-bridged 使用 51826）
  • 清理并重启：删除 ~/.node-red/homekit-persist 后重启 Node-RED，再重新配对
  • 说明：本节点的存储路径设置已做防重入处理（忽略“已初始化”错误），但第三方插件未必处理，故建议由插件统一初始化存储路径

扬声器控制:

1. 打开"星环电视"配件
2. 点击右下角设置图标（齿轮）
3. 在设置页面可以看到：
   • 音量滑块（0-100%）
   • 静音开关

输入源切换:

1. 长按"星环电视"配件
2. 在弹出界面中选择输入源（每个都有正确的名称）：
   • 本地 - 本地播放器
   • HDMI 1 - HDMI 输入1
   • HDMI 2 - HDMI 输入2
   • AUX - AUX 音频输入
   • 光纤 - 光纤音频输入
   • ARC - HDMI ARC 音频回传
   • 蓝牙 - 蓝牙音频输入

功能按钮使用:

• 8个功能按钮在"星环配件"桥接中
• 显示为插座图标（Outlet），不会被"打开所有开关"触发
• 点击即可执行对应功能，自动关闭

关于功能按钮（Outlet点动按钮）:

• 8个功能按钮使用 Outlet（插座）点动模式
• 点动效果：点击后自动关闭（500ms），模拟物理按钮
• 优点：
  • ✅ 不会被 Siri "打开所有开关"触发
  • ✅ 不会被 Siri "打开所有灯"触发
  • ✅ 可以主动控制设备
  • ✅ 点击即触发，无需手动关闭
• 缺点：
  • ⚠️ 会被 Siri "打开所有插座"触发（但很少使用）
• 为什么不用 StatelessProgrammableSwitch：
  • 只读，无法主动控制设备
  • 只能作为触发器，不适合设备控制

兼容性说明:

• ✅ 兼容 iOS 18-26（2025年11月最新版本）
• ✅ 兼容 iPadOS 18-26
• ⚠️ Mac版"家庭"App 不支持遥控器功能（Apple 限制）
• ✅ 遥控器和扬声器集成在电视配件内，符合 Apple HomeKit 标准

方案四: Matter

跨平台智能家居标准,支持Apple、Google、Amazon等多个生态系统。

前置要求

需要安装 Matter 库:

cd ~/.node-red
npm install @project-chip/matter-node.js

或使用替代方案:

npm install @sammachin/node-red-matter-bridge

配置步骤

1. 添加Matter桥接节点

   • 从节点面板拖入 starloop-matter 节点
   • 配置设备连接
   • 设置桥接名称和配对信息
   • 选择要启用的服务 (电视/扬声器/开关)

2. 部署流程

   • 部署后,节点会自动创建Matter桥接
   • 查看日志获取配对信息

3. 在Matter控制器中添加设备

   • Apple Home: 打开"家庭"App → 添加配件 → 输入配对码
   • Google Home: 打开Google Home App → 添加设备 → Matter设备
   • Amazon Alexa: 打开Alexa App → 添加设备 → Matter设备
   • Samsung SmartThings: 打开SmartThings App → 添加设备 → 扫描Matter设备
   • Home Assistant: 设置 → 设备与服务 → 添加集成 → Matter

Matter配件结构

星环Matter桥接 (Bridge)

• 星环电视 (Television)
  • 电源开关
  • 输入源切换 (本地/HDMI1/HDMI2/AUX/光纤/ARC/蓝牙)
  • 遥控器控制 (上/下/左/右/确认/返回/主页/播放/菜单等)
• 星环扬声器 (Speaker)
  • 音量调节 (0-100%,自动映射到0-70)
  • 静音开关
• 星环麦克风 (Switch)
  • 麦克风开关
• 星环睡眠 (Switch)
  • 睡眠模式开关

Matter服务

电视服务

• 电源开关
• 输入源切换 (7种输入源)
• 遥控器控制 (方向键、确认、菜单、返回等)

扬声器服务

• 音量调节 (0-100%,自动映射到0-70)
• 静音开关

开关服务

• 快速电源开关

配对信息

部署后查看日志:

========================================
Matter桥接已启动
========================================
配对码: 20202021
识别码: 3840
手动配对码: MT:Y.K20202021C00KA0F00FFF18000
========================================

支持的平台

• ✅ Apple Home (iOS 16.1+, macOS 13+)
• ✅ Google Home
• ✅ Amazon Alexa
• ✅ Samsung SmartThings
• ✅ Home Assistant
• ✅ 其他支持Matter的平台

语音命令示例

Apple Siri

"嘿Siri,打开星环"
"嘿Siri,把星环音量调到50"

Google Assistant

"Ok Google,打开星环"
"Ok Google,把星环音量调到50"

Amazon Alexa

"Alexa,打开星环"
"Alexa,把星环音量调到50"

Matter vs HomeKit

特性	Matter	HomeKit
支持平台	Apple、Google、Amazon等	仅Apple
开放性	开放标准	封闭生态
配置	8位数字配对码	XXX-XX-XXX格式
兼容性	跨平台	Apple设备
推荐场景	多平台用户	纯Apple用户

静音控制

msg.payload = {
    command: "mute",
    params: { mute: true }
};

订阅设备状态

msg.payload = {
    command: "subscribe_state",
    params: {
        deviceId: "unique_device_id",
        subscribe: true
    }
};

语音控制

订阅语音命令:

msg.payload = {
    command: "subscribe_voice"
};

发送语音响应:

msg.payload = {
    command: "voice_response",
    params: { text: "已打开灯光" }
};

列出已发现的设备

msg.payload = {
    command: "list_devices"
};

Home Assistant 实体组织

启用 MQTT 集成后,会在 HA 中创建一个设备,包含以下实体(共 30+ 个标准 MQTT 实体):

设备信息

• 制造商: 星环(Starloop)
• 型号: 思谋大锅
• 所有实体归属于同一设备 - 在 HA 中集中显示在一个设备卡片中

实体列表

媒体播放器 (1个)

• 播放器 - 主控制界面,支持播放/暂停/停止/音量控制

开关 (2个)

• 电源 - 设备开/关
• 静音 - 音频静音/取消静音

数字 (1个)

• 音量 - 设置音量 (0-70)

选择器 (2个)

• 信号源 - 切换输入源(本地/HDMI1/HDMI2/AUX/光纤/ARC/蓝牙)
• 循环模式 - 设置播放循环模式(单曲/列表循环/单曲循环/随机)

按钮 (24个)

功能按钮 (9个):

• 截图、开始录制、停止录制
• 文件夹、应用、音效
• 麦克风切换、睡眠、唤醒

遥控器按键 (15个):

• 方向键: 上、下、左、右
• 功能键: 确认、主页、返回、菜单
• 电源键
• 音量键: 音量+、音量-、静音键
• 播放控制: 播放、暂停

HA 中的显示效果

在 Home Assistant 设备页面,你会看到:

• 一个设备: "星环设备" (或你设置的名称)
• 30+ 个实体: 全部归属于这个设备
• 便于管理: 所有控制集中在一个设备卡片中

HomeKit 和 Matter 支持

通过 Home Assistant 可以将设备桥接到 HomeKit 或 Matter:

桥接步骤

1. 在 Home Assistant 中,进入 配置 -> 集成
2. 配置 HomeKit Bridge 或 Matter 集成
3. 选择要暴露的星环设备
4. 设备将出现在 Apple 家庭 App 或 Matter 兼容应用中

HomeKit 中的效果

• 媒体播放器 显示为"电视"或"扬声器"
• Siri 语音控制: "嘿Siri,把客厅音量调到50"
• 所有开关和按钮 可在"家庭"App中控制
• 自动化场景: 如"回家时自动打开设备"
• 远程控制: 通过 iCloud 远程控制

直接集成到 HomeKit (方式三)

如果你不使用 Home Assistant,可以直接在 Node-RED 中创建 HomeKit 配件。

安装 HomeKit 插件

cd ~/.node-red
npm install node-red-contrib-homekit-bridged

重启 Node-RED 后,在左侧面板会出现 HomeKit 相关节点。

导入示例流程

1. 在 Node-RED 菜单中选择 导入
2. 选择 示例 标签
3. 找到 node-red-contrib-symi-starloop -> homekit-integration
4. 点击导入

或者手动导入 examples/homekit-integration.json 文件。

配置 HomeKit Bridge

1. 双击任意 homekit-service 节点
2. 点击 Add new homekit-bridge...
3. 设置配置:
   • Bridge Name: 星环设备
   • PIN Code: 任意8位数字 (如 123-45-678)
   • Port: 默认 (自动分配)
4. 点击 Add 和 Done
5. 部署流程

在 iPhone 上添加配件

1. 打开 家庭 App
2. 点击右上角 +
3. 选择 添加配件
4. 选择 更多选项...
5. 找到 星环影音 和 星环配件 两个桥接
6. 手动输入配对码（默认：031-45-154）
7. 完成配置

可用的 HomeKit 服务

示例流程包含以下 HomeKit 服务:

Television (电视)

• 开/关: 控制设备电源
• 输入源: 切换信号源 (本地/HDMI1/HDMI2/AUX/光纤/ARC/蓝牙)
• 遥控器: 方向键、确认、返回、菜单等

Speaker (扬声器)

• 音量: 0-100 (自动转换为设备的 0-70)
• 静音: 开启/关闭静音
• 音量调节: 音量+/音量-

Switch (开关)

• 电源开关: 快速开关设备

Siri 语音控制示例

"嘿 Siri, 打开星环设备"
"嘿 Siri, 关闭星环设备"
"嘿 Siri, 把星环设备音量调到 50"
"嘿 Siri, 静音星环设备"
"嘿 Siri, 取消静音星环设备"

自定义 HomeKit 服务

你可以根据需要添加更多 HomeKit 服务:

1. 从左侧面板拖入 homekit-service 节点
2. 选择服务类型 (Switch, Lightbulb, Fan 等)
3. 添加 function 节点转换 HomeKit 命令为 Starloop 命令
4. 连接到 starloop 节点

参考示例流程中的 function 节点代码。

协议说明

本节点使用UDP协议与星环设备通信，端口44654用于控制命令，端口44655用于语音数据。所有通信均在局域网内完成，无需互联网连接。

使用示例

简单遥控器控制

[
    {
        "id": "inject1",
        "type": "inject",
        "name": "音量增加",
        "topic": "",
        "payload": "{\"command\":\"key\",\"params\":{\"key\":\"VOLUME_UP\"}}",
        "payloadType": "json",
        "wires": [["starloop1"]]
    },
    {
        "id": "starloop1",
        "type": "starloop",
        "name": "我的星环",
        "autoDiscover": true,
        "mqttEnabled": false
    }
]

Home Assistant 集成

[
    {
        "id": "starloop1",
        "type": "starloop",
        "name": "客厅星环",
        "autoDiscover": true,
        "mqttEnabled": true,
        "mqttBroker": "mqtt://192.168.1.100:1883",
        "mqttUsername": "homeassistant",
        "mqttPassword": "your_password"
    }
]

故障排除

设备未被发现

1. 确保设备和 Node-RED 在同一网络
2. 检查防火墙设置允许 mDNS 流量
3. 在配置中手动指定设备 IP
4. 点击"立即搜索设备"按钮手动触发搜索

MQTT 连接失败

1. 验证 MQTT 服务器正在运行
2. 检查服务器地址和凭据
3. 确保服务器允许来自 Node-RED 主机的连接

命令不工作

1. 验证设备 IP 是否正确
2. 检查网络连接
3. 确保 UDP 端口 44654 未被阻止

关于设备SN码

通常情况下不需要填写设备SN码。根据协议文档:

• 设备SN码是协议中的一个可选字段(20字节)
• 可以留空(填充空白字节)
• 仅在特殊情况下需要指定(如多设备环境中精确控制某一台设备)
• 大多数用户只需填写设备IP地址即可

License

MIT

Author

symi-daguo

Repository

https://github.com/symi-daguo/node-red-contrib-symi-starloop

稳定性特性

自动重连机制

节点内置智能重连机制,确保网络断开后自动恢复:

• 健康检查 - 每30秒自动检查设备连接状态
• 智能重连 - 连接断开后自动尝试重连，永不放弃
• 指数退避 - 重连间隔逐渐增加(5秒、10秒、15秒...),避免网络拥塞
• 静默重连 - 设备长时间离线时静默等待，不反复提示错误
• 自动恢复 - 设备上线后自动连接，无需手动干预
• 状态指示 - 节点状态实时显示连接状态
  • 绿点: 已连接
  • 黄圈: 重连中（前3次）
  • 灰圈: 等待设备上线（静默重连）
  • 红圈: 连接断开

命令重试机制

命令执行失败时自动重试:

• 自动重试 - 失败命令自动重试,最多3次
• 双输出 - 节点有两个输出端口
  • 第一个输出: 命令执行成功
  • 第二个输出: 命令执行失败(含错误信息)
• 命令队列 - 设备未连接时命令自动加入队列,连接后执行
• 超时处理 - 每个命令5秒超时,避免无限等待

错误处理示例

[inject] → [starloop节点]
              ├─ 输出1(成功) → [debug:成功]
              └─ 输出2(错误) → [debug:错误] → [email通知]

持久化支持

• 配置持久化 - 设备配置保存在Node-RED配置中
• 重启恢复 - Node-RED重启后自动恢复连接
• 状态同步 - 自动同步设备状态

故障排除

设备未被发现

问题: 点击"搜索局域网设备"没有找到设备

解决方案:

1. 确保设备和Node-RED在同一局域网
2. 检查防火墙是否允许mDNS流量(UDP 5353端口)
3. 尝试手动输入设备IP地址
4. 检查设备是否已开机并连接到网络
5. 使用 avahi-browse -a (Linux) 或 dns-sd -B _starloop._tcp (Mac) 命令验证mDNS服务

命令执行失败

问题: 发送命令后设备无响应

解决方案:

1. 检查设备IP地址是否正确
2. 确保UDP端口44654未被防火墙阻止
3. 查看节点的错误输出(第二个输出端口)
4. 检查网络连接是否稳定
5. 尝试重启设备和Node-RED

网络断开后无法恢复

问题: 网络恢复后节点仍显示断开

解决方案:

1. 节点会自动重连，无需手动干预
2. 前3次重连会显示"重连中"状态
3. 之后会显示"等待设备上线..."并静默重连
4. 设备上线后会自动连接并显示"已连接"
5. 如果设备IP发生变化，建议配置静态IP地址
6. 如需立即重连，可重新部署流程

MQTT集成问题

问题: Home Assistant中看不到设备

解决方案:

1. 确认MQTT Broker正常运行
2. 检查MQTT服务器地址、用户名、密码是否正确
3. 在HA中检查MQTT集成是否已启用
4. 查看Node-RED日志,确认MQTT消息已发送
5. 在HA中手动刷新MQTT设备列表
6. 检查MQTT发现前缀是否与HA配置一致(默认: homeassistant)

HomeKit配对失败

问题: iPhone无法找到或配对HomeKit配件

解决方案:

1. 确认已安装 hap-nodejs 库: cd ~/.node-red && npm install hap-nodejs
2. 检查配对码格式是否正确(XXX-XX-XXX,默认: 031-45-154)
3. 确保端口未被占用(默认51826)
4. 查看Node-RED日志,确认显示"HomeKit桥接已启动"
5. 确保iPhone和Node-RED在同一局域网
6. 尝试更换端口号或username(MAC地址格式)
7. 删除旧的配对记录: 删除 ~/.node-red/persist/ 目录下的HomeKit文件
8. 重启Node-RED后重新配对

HomeKit显示错误图标:

• 如果显示水龙头图标而不是电视图标,说明category设置错误
• 确保使用最新版本的代码(v1.0.2+)
• Bridge的category应该是BRIDGE,电视配件的category应该是TELEVISION

Matter配对失败

问题: Matter控制器无法找到或配对设备

解决方案:

1. 确认已安装Matter库: cd ~/.node-red && npm install @project-chip/matter-node.js
2. 检查配对码格式是否正确(8位数字,默认: 20202021)
3. 确保端口未被占用(默认5540)
4. 查看Node-RED日志,确认显示"Matter桥接已启动"
5. 确保控制器和Node-RED在同一局域网
6. 尝试更换端口号或discriminator
7. 重启Node-RED后重新配对
8. 注意: Matter功能目前为框架实现,可能需要进一步开发
9. 确保iPhone和Node-RED在同一网络

设备SN码问题

问题: 是否需要填写设备SN码?

解答:

• 通常不需要 - 大多数情况下留空即可
• 何时需要 - 仅在以下情况需要填写:
  • 同一网络有多台相同型号设备
  • 需要精确控制特定设备
  • 设备厂商明确要求
• 如何获取 - 查看设备背面标签或设备设置菜单

示例库

导入示例

菜单 → 导入 → 示例 → node-red-contrib-symi-starloop

可用示例

1. complete-examples - 完整示例集 (推荐)

   • 三种使用方案的完整示例
   • 5个实用场景
   • 开箱即用

2. automation-flow - 自动化场景

   • 开机流程
   • 观影模式
   • 音乐模式
   • 定时控制

3. homekit-integration - HomeKit集成

   • 电视服务
   • 扬声器服务
   • 开关服务

4. test-flow - 功能测试

   • 测试所有17种功能
   • 调试工具

相关链接

• npm包: https://www.npmjs.com/package/node-red-contrib-symi-starloop
• GitHub仓库: https://github.com/symi-daguo/node-red-contrib-symi-starloop
• 问题反馈: https://github.com/symi-daguo/node-red-contrib-symi-starloop/issues
• Node-RED官网: https://nodered.org

License

MIT

Author

symi-daguo

Changelog

1.0.2 (2025-11-08)

紧急修复

• 修复HomeKit节点setupID未定义导致的初始化失败错误
• 移除内部协议文档，不再发布到npm仓库

文档优化

• 以客户友好模式完善README文档
• 移除内部协议文档引用，改为简洁的协议说明
• 优化相关链接，添加npm包链接

1.0.1 (2025-11-08)

稳定性优化

• 完全静默重连：设备离线时不再显示任何warn或info日志
• 优化健康检查：失败时静默处理，不影响Node-RED日志清洁度
• 智能日志管理：只在设备重新连接时记录一次恢复日志
• 永不放弃：达到最大重连次数后继续静默重连，等待设备上线

HomeKit优化

• 移除二维码生成功能：改为手动输入配对码，更稳定可靠
• 简化配对流程：直接在iOS家庭App中输入8位配对码即可
• 优化启动日志：更清晰的配对说明

用户体验提升

• 设备长时间离线时不会刷屏日志
• 状态显示更友好：灰色圆圈表示"等待设备上线..."
• 设备上线后自动连接，无需任何手动操作
• 不影响Node-RED和节点的稳定性与性能