Homebridge LanternIC

Homebridge plugin for BLE RGBIC/RGBWIC light strips controlled by the Magic Lantern app.

Features

These unbranded Magic Lantern BLE strips ship with multiple firmware variants so it's hard to ensure compatibility for all strips.

• 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 across supported Node.js LTS versions in CI

Effects and segment control are not supported as there is no good way to expose them in Apple Home.

Install

Install it like any other Homebridge plugin:

sudo npm install -g homebridge-lanternic

For local development from this repository:

npm install
npm run build
sudo hb-service link

[!CAUTION]

Only the following platforms are supported:

• macOS
  • If using macOS, you'll need to give Node.js permission to use Bluetooth in System Settings → Privacy & Security → Bluetooth.
• Linux
  • 64-bit, not tested on 32-bit systems

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. Leave Scan For Light Strips On Startup enabled.
5. Restart Homebridge and open the logs.
6. Copy the LanternIC device config: {...} line for your strip into Configured Light Strips.
7. Save and restart Homebridge again.

Most setups only need a strip name and Bluetooth address. Use Show Advanced Settings only for Bluetooth adapter options, discovery filters, or protocol fallback tuning.

You can also use the local scanner:

lanternic-scan

Useful scanner filters:

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.

Automatically Add Discovered Strips can create HomeKit accessories for matching BLE candidates. Leave it off until you are nearby and ready to test, because nearby BLE devices may advertise similar services.

CLI Tools

LanternIC ships a few BLE helpers for setup and firmware troubleshooting:

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:

LANTERNIC_BINDING=hci lanternic-scan
LANTERNIC_BINDING=mac lanternic-scan

Linux / Raspberry Pi

This plugin uses @stoprocent/noble. Homebridge should run on any Node.js version supported by this package.

Install Bluetooth dependencies:

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:

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:

{
  "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:

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:

{
  "platform": "LanternIC",
  "name": "LanternIC",
  "showAdvanced": false,
  "devices": [],
  "discovery": {
    "enabled": true,
    "scanSeconds": 20
  }
}

Restart Homebridge and look for candidate device addresses in the logs. Then add your strip:

{
  "platform": "LanternIC",
  "name": "LanternIC",
  "devices": [
    {
      "name": "TV Strip",
      "address": "BE:16:70:00:08:2A",
      "showAdvanced": false,
      "model": "Magic Lantern RGBIC",
      "colorOrder": "rgb",
      "powerMode": "both",
      "brightnessMode": "rgb"
    }
  ],
  "discovery": {
    "enabled": true,
    "autoAdd": false,
    "showAdvanced": false,
    "scanSeconds": 20,
    "minRssi": -95,
    "namePrefixes": [
      "MELK",
      "Triones",
      "ELK-BLEDOM",
      "LED",
      "OA"
    ],
    "serviceUuids": [
      "fff0"
    ]
  },
  "ble": {
    "writeMode": "withoutResponse",
    "keepConnected": true
  }
}

Troubleshooting

Since each strip is different, you may need to configure your settings differently.

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.

Reconnect

If automatic reconnect fails, power cycle the strip. If it flashes, you're reconnected.

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 Magic Lantern BLE frame notes are based on packet-captures from @kassabov in Home Assistant Core issue #145934. (thanks!)

• 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

• 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:

{
  "ble": {
    "keepConnected": true,
    "writeMode": "withoutResponse",
    "writeTimeoutMs": 5000,
    "retryAttempts": 4,
    "retryDelayMs": 500,
    "maxRetryDelayMs": 5000,
    "reconnectDelayMs": 1000,
    "maxReconnectDelayMs": 60000
  }
}