homebridge-lanternic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gibson Bell
+
+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,260 @@
+# Homebridge LanternIC
+
+Homebridge plugin for BLE RGBIC/RGBWIC light strips controlled by the Magic Lantern app.
+
+The goal is a reliable local-only bridge for the common unbranded Magic Lantern strips and lamps. These devices are usually BLE lights, not Magic Home Wi-Fi devices, so this plugin talks directly to the BLE service used by the Magic Lantern app.
+
+## Status
+
+LanternIC is a hardware-tested pre-release plugin. It is designed for production-style Homebridge use, with the important caveat that these unbranded Magic Lantern BLE strips ship with multiple firmware variants.
+
+- HomeKit Lightbulb service
+- On/off with RGB-black fallback plus optional native Magic Lantern power frames
+- Brightness via RGB scaling by default, with optional native Magic Lantern brightness frames
+- HomeKit on/off, brightness, and color control confirmed on a `MELK-OC21WCT31` strip
+- Homebridge UI config schema
+- BLE discovery with log snippets and optional auto-add
+- Serialized BLE writes with timeout, retry/backoff, reconnect, and optional keep-alive
+- Command-builder tests for the known Magic Lantern frames
+- Package smoke tests against Homebridge 1 and 2 on Node.js 22 and 24 in CI
+
+Effects, segment control, RGBW white-channel behavior, and startup scenes are deliberately left out until more real devices are tested.
+
+## Install
+
+Once published to npm, install it like any other Homebridge plugin:
+
+```sh
+sudo npm install -g homebridge-lanternic
+```
+
+For local development from this repository:
+
+```sh
+npm install
+npm run build
+sudo hb-service link
+```
+
+## Homebridge UI Setup
+
+LanternIC supports Homebridge UI through `config.schema.json`.
+
+1. Install the plugin.
+2. Open Homebridge UI.
+3. Go to Plugins, select LanternIC, then Settings.
+4. Enable `Log Discovered Candidate Devices`.
+5. Restart Homebridge and open the logs.
+6. Copy the `LanternIC device config: {...}` line for your strip into the `Light Strips` list.
+
+You can also use the local scanner:
+
+```sh
+lanternic-scan
+```
+
+Useful scanner filters:
+
+```sh
+LANTERNIC_MIN_RSSI=-75 lanternic-scan
+LANTERNIC_SCAN_SECONDS=45 lanternic-scan
+LANTERNIC_SCAN_ALL=1 lanternic-scan
+```
+
+When working from this repository instead of a global install, use `npm run scan` in place of `lanternic-scan`.
+
+`Auto-Add Discovered Devices` can create HomeKit accessories automatically for matching BLE candidates. Leave it off until the discovery filters only match your strips, because nearby BLE devices may advertise similar services.
+
+## CLI Tools
+
+LanternIC ships a few BLE helpers for setup and firmware troubleshooting:
+
+```sh
+lanternic-scan
+lanternic-explore <address>
+lanternic-send <address> rgb ff0000
+lanternic-send <address> brightness 50
+lanternic-send-sequence <address> 7e070503ff000010ef 7e07050300ff0010ef
+lanternic-calibrate <address>
+```
+
+All tools default to Noble's cross-platform `default` binding. Override it only when needed:
+
+```sh
+LANTERNIC_BINDING=hci lanternic-scan
+LANTERNIC_BINDING=mac lanternic-scan
+```
+
+## Linux / Raspberry Pi
+
+This plugin uses `@stoprocent/noble`, which ships Linux prebuilds for common Raspberry Pi and x64 platforms. Homebridge should run on Node.js 22 or 24.
+
+Install Bluetooth dependencies:
+
+```sh
+sudo apt-get update
+sudo apt-get install -y bluetooth bluez libbluetooth-dev libudev-dev libcap2-bin
+```
+
+Allow the Node binary used by Homebridge to access BLE:
+
+```sh
+sudo setcap cap_net_raw,cap_net_admin+eip "$(eval readlink -f "$(which node)")"
+```
+
+If Homebridge runs under `hb-service`, make sure you run the `setcap` command against the same `node` binary that service uses. The safest path is to run it in the same shell/environment where Homebridge was installed, or from the Homebridge UI terminal.
+
+Recommended Linux BLE settings:
+
+```json
+{
+  "ble": {
+    "binding": "default",
+    "hciDriver": "native",
+    "hciDeviceId": 0,
+    "writeMode": "withoutResponse"
+  }
+}
+```
+
+`binding: "default"` auto-selects Linux HCI on Linux. Set `hciDeviceId` to `1` for `hci1`, etc. If scanning sees nothing on a Raspberry Pi, try adding this to `/etc/bluetooth/main.conf`, then reboot:
+
+```ini
+DisablePlugins=pnat
+```
+
+If Linux discovery works from the CLI but Homebridge cannot connect, run the `setcap` command against the exact Node binary used by `hb-service`, then restart Homebridge. If `keepConnected` is enabled, expect the Magic Lantern iPhone app to fail or hang while Homebridge owns the BLE connection.
+
+## Homebridge Config
+
+Start with discovery enabled and no devices:
+
+```json
+{
+  "platform": "LanternIC",
+  "name": "LanternIC",
+  "devices": [],
+  "discovery": {
+    "enabled": true,
+    "scanSeconds": 20
+  }
+}
+```
+
+Restart Homebridge and look for candidate device addresses in the logs. Then add your strip:
+
+```json
+{
+  "platform": "LanternIC",
+  "name": "LanternIC",
+  "devices": [
+    {
+      "name": "TV Strip",
+      "address": "BE:16:70:00:08:2A",
+      "model": "Magic Lantern RGBIC",
+      "colorOrder": "rgb",
+      "powerMode": "both",
+      "brightnessMode": "rgb"
+    }
+  ],
+  "discovery": {
+    "enabled": true,
+    "autoAdd": false,
+    "scanSeconds": 20,
+    "minRssi": -95,
+    "namePrefixes": [
+      "MELK",
+      "Triones",
+      "ELK-BLEDOM",
+      "LED",
+      "OA"
+    ],
+    "serviceUuids": [
+      "fff0"
+    ]
+  },
+  "ble": {
+    "writeMode": "withoutResponse",
+    "keepConnected": true
+  }
+}
+```
+
+## Test Loop With A Real Strip
+
+1. Pair/configure the strip in the Magic Lantern app first so it is powered, reachable, and known-good.
+2. Fully quit the Magic Lantern app before testing Homebridge. BLE devices usually allow only one active central connection.
+3. Start Homebridge in debug mode and confirm the plugin logs your strip during discovery.
+4. Add the address to config and restart.
+5. Test in this order: On, Off, Brightness 10/50/100, Red, Green, Blue, White-ish.
+6. If colors are swapped, change `colorOrder`.
+7. If Off leaves the strip visibly on, keep `powerMode` as `both` or try `rgbBlack`.
+8. If brightness does not change, keep `brightnessMode` as `rgb`; if it double-dims, try `native`.
+
+## Protocol Notes
+
+Known Magic Lantern BLE writes go to:
+
+- Service UUID: `FFF0`
+- Characteristic UUID: `FFF3`
+
+Confirmed through HomeKit against a `MELK-OC21WCT31` / firmware string `WCKJ3016FV25HCV6` strip:
+
+- RGB: `7e070503RRGGBB10ef`
+- Off fallback: `7e07050300000010ef`
+- Brightness: RGB scaling through the same RGB frame
+
+The core frames available here are:
+
+- On: `7e0404f00001ff00ef`
+- Off: `7e0404000000ff00ef`
+- RGB: `7e070503RRGGBB10ef`
+- Brightness: `7e0401xx01ffff00ef`, where `xx` is 0-100 decimal encoded as one byte
+- Effect speed: `7e0402xxffffff00ef`, where `xx` is 0-100 decimal encoded as one byte
+- Basic effect: `7e0503xx06ffff00ef`
+
+These protocol notes come from Home Assistant community reverse-engineering reports and BLE packet examples:
+
+- Home Assistant Core issue: <https://github.com/home-assistant/core/issues/145934>
+- Home Assistant community thread: <https://community.home-assistant.io/t/new-integration-for-ble-magic-lantern/454055>
+- Magic Lantern app overview: <https://magiclantern.app/>
+- Modern Noble fork used for BLE: <https://github.com/stoprocent/noble>
+
+The default `powerMode` is `both`, which sends RGB black before the native off frame. The default `brightnessMode` is `rgb`, which scales RGB values instead of relying on the native brightness frame. These defaults favor the RGB command that is confirmed on real hardware.
+
+The command builders are isolated so we can add variants if your strip uses a slightly different firmware.
+
+## Known Hardware Notes
+
+- HomeKit on/off, brightness, and RGB color control are confirmed on the MELK firmware above.
+- Native power and brightness frames are implemented, but still need more real-strip validation because some Magic Lantern-family firmware appears to accept RGB frames while ignoring one or both native frames.
+- If color works but power or brightness does not, use `lanternic-send <address> raw <hex-frame>` while testing candidate frames and open an issue with the model name, firmware string from `lanternic-explore`, and the working frame.
+- Avoid enabling discovery `autoAdd` until your filters are tight. Some nearby BLE devices can share generic names or services and should not be bridged as lights.
+
+## Reliability Choices
+
+This plugin avoids the usual BLE plugin failure pattern of overlapping scans, overlapping writes, and stale connections:
+
+- All BLE operations are serialized through a single manager queue.
+- Every characteristic write has a timeout and is retried with exponential backoff.
+- Failed writes force a disconnect and rediscovery.
+- Desired HomeKit state is cached and resent after a background reconnect when `keepConnected` is enabled.
+- Connections are closed after an idle timeout by default, so the Magic Lantern app or another controller is less likely to be locked out forever.
+- Set `ble.keepConnected` to `true` for the most reliable HomeKit behavior. This keeps Homebridge attached to the strip and automatically reconnects after drops, but the Magic Lantern app may not be able to connect until Homebridge releases the device.
+
+Useful reliability settings:
+
+```json
+{
+  "ble": {
+    "keepConnected": true,
+    "writeMode": "withoutResponse",
+    "writeTimeoutMs": 5000,
+    "retryAttempts": 4,
+    "retryDelayMs": 500,
+    "maxRetryDelayMs": 5000,
+    "reconnectDelayMs": 1000,
+    "maxReconnectDelayMs": 60000
+  }
+}
+```

package/config.schema.json

@@ -0,0 +1,412 @@
+{
+  "pluginAlias": "LanternIC",
+  "pluginType": "platform",
+  "singular": true,
+  "strictValidation": false,
+  "schema": {
+    "type": "object",
+    "required": [
+      "name"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "LanternIC"
+      },
+      "devices": {
+        "title": "Light Strips",
+        "type": "array",
+        "buttonText": "Add Light Strip",
+        "default": [],
+        "description": "Use discovery logs or lanternic-scan to find Magic Lantern BLE device ids. On Linux this is usually the MAC address; on macOS it may be a long CoreBluetooth id.",
+        "items": {
+          "type": "object",
+          "required": [
+            "name",
+            "address"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "default": "LED Strip"
+            },
+            "address": {
+              "title": "Bluetooth Address / Id",
+              "type": "string",
+              "description": "MAC address or Noble peripheral id. Colons are optional. Use the value printed as address= in LanternIC discovery logs.",
+              "placeholder": "BE:16:70:00:08:2A"
+            },
+            "model": {
+              "title": "Model",
+              "type": "string",
+              "default": "Magic Lantern RGBIC"
+            },
+            "manufacturer": {
+              "title": "Manufacturer",
+              "type": "string",
+              "default": "Magic Lantern"
+            },
+            "colorOrder": {
+              "title": "Color Order",
+              "type": "string",
+              "default": "rgb",
+              "oneOf": [
+                {
+                  "title": "RGB",
+                  "enum": [
+                    "rgb"
+                  ]
+                },
+                {
+                  "title": "RBG",
+                  "enum": [
+                    "rbg"
+                  ]
+                },
+                {
+                  "title": "GRB",
+                  "enum": [
+                    "grb"
+                  ]
+                },
+                {
+                  "title": "GBR",
+                  "enum": [
+                    "gbr"
+                  ]
+                },
+                {
+                  "title": "BRG",
+                  "enum": [
+                    "brg"
+                  ]
+                },
+                {
+                  "title": "BGR",
+                  "enum": [
+                    "bgr"
+                  ]
+                }
+              ]
+            },
+            "powerMode": {
+              "title": "Power Mode",
+              "type": "string",
+              "default": "both",
+              "description": "Both sends RGB black before the native off frame. This is the safest default for firmware that accepts RGB colors but ignores native power frames.",
+              "oneOf": [
+                {
+                  "title": "Native + RGB Black Fallback",
+                  "enum": [
+                    "both"
+                  ]
+                },
+                {
+                  "title": "Native Power Frames Only",
+                  "enum": [
+                    "native"
+                  ]
+                },
+                {
+                  "title": "RGB Black Only",
+                  "enum": [
+                    "rgbBlack"
+                  ]
+                }
+              ]
+            },
+            "brightnessMode": {
+              "title": "Brightness Mode",
+              "type": "string",
+              "default": "rgb",
+              "description": "RGB scaling dims by changing RGB values, which works on strips that ignore native brightness frames.",
+              "oneOf": [
+                {
+                  "title": "RGB Scaling",
+                  "enum": [
+                    "rgb"
+                  ]
+                },
+                {
+                  "title": "Native Brightness Frame",
+                  "enum": [
+                    "native"
+                  ]
+                },
+                {
+                  "title": "Native + RGB Scaling",
+                  "enum": [
+                    "both"
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      },
+      "discovery": {
+        "title": "Discovery",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "title": "Log Discovered Candidate Devices",
+            "type": "boolean",
+            "default": true,
+            "description": "Scan on Homebridge startup and print candidate devices plus copy/paste JSON snippets to the logs."
+          },
+          "autoAdd": {
+            "title": "Auto-Add Discovered Devices",
+            "type": "boolean",
+            "default": false,
+            "description": "Automatically create HomeKit accessories for matching discovered BLE devices. Leave off until your filters only match your strips."
+          },
+          "scanSeconds": {
+            "title": "Scan Time",
+            "type": "integer",
+            "default": 15,
+            "minimum": 3,
+            "maximum": 120
+          },
+          "minRssi": {
+            "title": "Minimum RSSI",
+            "type": "integer",
+            "default": -95,
+            "minimum": -127,
+            "maximum": 0,
+            "description": "Ignore very weak candidates. Higher values are stricter; for example -70 only finds nearby devices."
+          },
+          "namePrefixes": {
+            "title": "Candidate Name Prefixes",
+            "type": "array",
+            "default": [
+              "Triones",
+              "MELK",
+              "ELK-BLEDOM",
+              "LED",
+              "OA"
+            ],
+            "items": {
+              "type": "string"
+            }
+          },
+          "serviceUuids": {
+            "title": "Candidate Service UUIDs",
+            "type": "array",
+            "default": [
+              "fff0"
+            ],
+            "description": "Also treat devices advertising these services as candidates.",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ble": {
+        "title": "Bluetooth",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "binding": {
+            "title": "Noble Binding",
+            "type": "string",
+            "default": "default",
+            "description": "Default auto-selects macOS, Windows, or Linux HCI. Use Linux HCI when you need explicit HCI settings.",
+            "oneOf": [
+              {
+                "title": "Default",
+                "enum": [
+                  "default"
+                ]
+              },
+              {
+                "title": "Linux HCI",
+                "enum": [
+                  "hci"
+                ]
+              },
+              {
+                "title": "macOS",
+                "enum": [
+                  "mac"
+                ]
+              },
+              {
+                "title": "Windows",
+                "enum": [
+                  "win"
+                ]
+              }
+            ]
+          },
+          "hciDriver": {
+            "title": "Linux HCI Driver",
+            "type": "string",
+            "default": "native",
+            "description": "Native is the normal Linux/Raspberry Pi driver. USB/UART are for dedicated adapters.",
+            "oneOf": [
+              {
+                "title": "Native",
+                "enum": [
+                  "native"
+                ]
+              },
+              {
+                "title": "Default",
+                "enum": [
+                  "default"
+                ]
+              },
+              {
+                "title": "USB",
+                "enum": [
+                  "usb"
+                ]
+              },
+              {
+                "title": "UART",
+                "enum": [
+                  "uart"
+                ]
+              }
+            ]
+          },
+          "hciDeviceId": {
+            "title": "Linux HCI Device Id",
+            "type": "integer",
+            "default": 0,
+            "minimum": 0,
+            "description": "For hci0 use 0, hci1 use 1, and so on."
+          },
+          "hciUserChannel": {
+            "title": "Linux HCI User Channel",
+            "type": "boolean",
+            "default": false,
+            "description": "Advanced Linux option. Usually leave off unless raw HCI permissions conflict with bluetoothd."
+          },
+          "hciExtended": {
+            "title": "BLE 5 Extended Features",
+            "type": "boolean",
+            "description": "Optional advanced setting. Leave blank/default unless your adapter needs extended feature behavior forced."
+          },
+          "serviceUuid": {
+            "title": "Service UUID",
+            "type": "string",
+            "default": "fff0"
+          },
+          "characteristicUuid": {
+            "title": "Characteristic UUID",
+            "type": "string",
+            "default": "fff3"
+          },
+          "keepConnected": {
+            "title": "Keep Connected",
+            "type": "boolean",
+            "default": false,
+            "description": "Maintain a BLE connection and automatically reconnect after disconnects. Improves HomeKit responsiveness but may prevent the Magic Lantern app from connecting at the same time."
+          },
+          "connectTimeoutMs": {
+            "title": "Connect Timeout",
+            "type": "integer",
+            "default": 15000,
+            "minimum": 1000,
+            "maximum": 60000
+          },
+          "scanTimeoutMs": {
+            "title": "Scan Timeout",
+            "type": "integer",
+            "default": 15000,
+            "minimum": 1000,
+            "maximum": 120000
+          },
+          "writeTimeoutMs": {
+            "title": "Write Timeout",
+            "type": "integer",
+            "default": 5000,
+            "minimum": 500,
+            "maximum": 60000
+          },
+          "retryAttempts": {
+            "title": "Retry Attempts",
+            "type": "integer",
+            "default": 3,
+            "minimum": 1,
+            "maximum": 10
+          },
+          "retryDelayMs": {
+            "title": "Retry Delay",
+            "type": "integer",
+            "default": 500,
+            "minimum": 0,
+            "maximum": 10000
+          },
+          "maxRetryDelayMs": {
+            "title": "Max Retry Delay",
+            "type": "integer",
+            "default": 5000,
+            "minimum": 0,
+            "maximum": 60000
+          },
+          "reconnectDelayMs": {
+            "title": "Reconnect Delay",
+            "type": "integer",
+            "default": 1000,
+            "minimum": 0,
+            "maximum": 60000
+          },
+          "maxReconnectDelayMs": {
+            "title": "Max Reconnect Delay",
+            "type": "integer",
+            "default": 60000,
+            "minimum": 1000,
+            "maximum": 600000
+          },
+          "writeDelayMs": {
+            "title": "Delay Between Writes",
+            "type": "integer",
+            "default": 120,
+            "minimum": 0,
+            "maximum": 5000
+          },
+          "idleDisconnectMs": {
+            "title": "Idle Disconnect",
+            "type": "integer",
+            "default": 30000,
+            "minimum": 0,
+            "maximum": 600000
+          },
+          "writeMode": {
+            "title": "Write Mode",
+            "type": "string",
+            "default": "auto",
+            "oneOf": [
+              {
+                "title": "Auto",
+                "enum": [
+                  "auto"
+                ]
+              },
+              {
+                "title": "With Response",
+                "enum": [
+                  "withResponse"
+                ]
+              },
+              {
+                "title": "Without Response",
+                "enum": [
+                  "withoutResponse"
+                ]
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}