homebridge-lanternic 0.1.3 → 0.2.1

package/README.md

@@ -40,6 +40,14 @@ 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
 
@@ -48,9 +56,12 @@ 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`.
+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 the `Light Strips` list.
+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:
 
@@ -68,7 +79,7 @@ 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.
+`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
 
@@ -138,6 +149,7 @@ Start with discovery enabled and no devices:
 {
   "platform": "LanternIC",
   "name": "LanternIC",
+  "showAdvanced": false,
   "devices": [],
   "discovery": {
     "enabled": true,
@@ -156,6 +168,7 @@ Restart Homebridge and look for candidate device addresses in the logs. Then add
     {
       "name": "TV Strip",
       "address": "BE:16:70:00:08:2A",
+      "showAdvanced": false,
       "model": "Magic Lantern RGBIC",
       "colorOrder": "rgb",
       "powerMode": "both",
@@ -165,6 +178,7 @@ Restart Homebridge and look for candidate device addresses in the logs. Then add
   "discovery": {
     "enabled": true,
     "autoAdd": false,
+    "showAdvanced": false,
     "scanSeconds": 20,
     "minRssi": -95,
     "namePrefixes": [

package/config.schema.json

@@ -15,12 +15,18 @@
         "type": "string",
         "default": "LanternIC"
       },
+      "showAdvanced": {
+        "title": "Show Advanced Settings",
+        "type": "boolean",
+        "default": false,
+        "description": "Show Bluetooth transport, discovery filters, and protocol tuning options. Most users can leave this off."
+      },
       "devices": {
-        "title": "Light Strips",
+        "title": "Configured 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.",
+        "description": "Add strips discovered in the logs. Usually only Name and Bluetooth Address are needed.",
         "items": {
           "type": "object",
           "required": [
@@ -37,23 +43,39 @@
             "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.",
+              "description": "Use the address printed in LanternIC discovery logs. Colons are optional.",
               "placeholder": "BE:16:70:00:08:2A"
             },
+            "showAdvanced": {
+              "title": "Show Advanced Strip Settings",
+              "type": "boolean",
+              "default": false,
+              "description": "Show color order and protocol fallback settings for this strip."
+            },
             "model": {
               "title": "Model",
               "type": "string",
-              "default": "Magic Lantern RGBIC"
+              "default": "Magic Lantern RGBIC",
+              "condition": {
+                "functionBody": "return model.devices && model.devices.showAdvanced === true;"
+              }
             },
             "manufacturer": {
               "title": "Manufacturer",
               "type": "string",
-              "default": "Magic Lantern"
+              "default": "Magic Lantern",
+              "condition": {
+                "functionBody": "return model.devices && model.devices.showAdvanced === true;"
+              }
             },
             "colorOrder": {
               "title": "Color Order",
               "type": "string",
               "default": "rgb",
+              "description": "Change this only if red, green, and blue appear swapped in HomeKit.",
+              "condition": {
+                "functionBody": "return model.devices && model.devices.showAdvanced === true;"
+              },
               "oneOf": [
                 {
                   "title": "RGB",
@@ -98,6 +120,9 @@
               "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.",
+              "condition": {
+                "functionBody": "return model.devices && model.devices.showAdvanced === true;"
+              },
               "oneOf": [
                 {
                   "title": "Native + RGB Black Fallback",
@@ -124,6 +149,9 @@
               "type": "string",
               "default": "rgb",
               "description": "RGB scaling dims by changing RGB values, which works on strips that ignore native brightness frames.",
+              "condition": {
+                "functionBody": "return model.devices && model.devices.showAdvanced === true;"
+              },
               "oneOf": [
                 {
                   "title": "RGB Scaling",
@@ -149,28 +177,37 @@
         }
       },
       "discovery": {
-        "title": "Discovery",
+        "title": "Setup & Discovery",
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "enabled": {
-            "title": "Log Discovered Candidate Devices",
+            "title": "Scan For Light Strips On Startup",
             "type": "boolean",
             "default": true,
-            "description": "Scan on Homebridge startup and print candidate devices plus copy/paste JSON snippets to the logs."
+            "description": "Print nearby Magic Lantern candidates in the Homebridge logs with copy/paste device snippets."
           },
           "autoAdd": {
-            "title": "Auto-Add Discovered Devices",
+            "title": "Automatically Add Discovered Strips",
             "type": "boolean",
             "default": false,
-            "description": "Automatically create HomeKit accessories for matching discovered BLE devices. Leave off until your filters only match your strips."
+            "description": "Create HomeKit accessories for matching candidates. Leave off unless you are nearby and ready to test."
+          },
+          "showAdvanced": {
+            "title": "Show Advanced Discovery Filters",
+            "type": "boolean",
+            "default": false,
+            "description": "Show scan duration, RSSI, name prefix, and service UUID filters."
           },
           "scanSeconds": {
             "title": "Scan Time",
             "type": "integer",
             "default": 15,
             "minimum": 3,
-            "maximum": 120
+            "maximum": 120,
+            "condition": {
+              "functionBody": "return model.showAdvanced === true || (model.discovery && model.discovery.showAdvanced === true);"
+            }
           },
           "minRssi": {
             "title": "Minimum RSSI",
@@ -178,7 +215,10 @@
             "default": -95,
             "minimum": -127,
             "maximum": 0,
-            "description": "Ignore very weak candidates. Higher values are stricter; for example -70 only finds nearby devices."
+            "description": "Ignore very weak candidates. Higher values are stricter; for example -70 only finds nearby devices.",
+            "condition": {
+              "functionBody": "return model.showAdvanced === true || (model.discovery && model.discovery.showAdvanced === true);"
+            }
           },
           "namePrefixes": {
             "title": "Candidate Name Prefixes",
@@ -192,6 +232,9 @@
             ],
             "items": {
               "type": "string"
+            },
+            "condition": {
+              "functionBody": "return model.showAdvanced === true || (model.discovery && model.discovery.showAdvanced === true);"
             }
           },
           "serviceUuids": {
@@ -203,6 +246,9 @@
             "description": "Also treat devices advertising these services as candidates.",
             "items": {
               "type": "string"
+            },
+            "condition": {
+              "functionBody": "return model.showAdvanced === true || (model.discovery && model.discovery.showAdvanced === true);"
             }
           }
         }
@@ -211,6 +257,9 @@
         "title": "Bluetooth",
         "type": "object",
         "additionalProperties": false,
+        "condition": {
+          "functionBody": "return model.showAdvanced === true;"
+        },
         "properties": {
           "binding": {
             "title": "Noble Binding",

package/dist/types.d.ts

@@ -8,6 +8,7 @@ export type WriteMode = 'auto' | 'withResponse' | 'withoutResponse';
 export interface LanternIcDeviceConfig {
     name: string;
     address: string;
+    showAdvanced?: boolean;
     manufacturer?: string;
     model?: string;
     colorOrder?: ColorOrder;
@@ -17,6 +18,7 @@ export interface LanternIcDeviceConfig {
 export interface LanternIcDiscoveryConfig {
     enabled?: boolean;
     autoAdd?: boolean;
+    showAdvanced?: boolean;
     scanSeconds?: number;
     minRssi?: number;
     namePrefixes?: string[];
@@ -45,6 +47,7 @@ export interface LanternIcBleConfig {
 }
 export interface LanternIcPlatformConfig extends PlatformConfig {
     name?: string;
+    showAdvanced?: boolean;
     devices?: LanternIcDeviceConfig[];
     discovery?: LanternIcDiscoveryConfig;
     ble?: LanternIcBleConfig;

package/package.json

@@ -2,7 +2,7 @@
   "name": "homebridge-lanternic",
   "displayName": "LanternIC",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Homebridge plugin for BLE RGBIC/RGBWIC light strips controlled by the Magic Lantern app.",
   "author": "Gibson Bell",
   "license": "MIT",