homebridge-iport-bezel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Kutergin
+
+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,179 @@
+# homebridge-iport-bezel
+
+A [Homebridge](https://homebridge.io) platform plugin for [iPort Surface Mount Buttons](https://www.iportproducts.com/products/surface-mount-buttons/) (SM Buttons / SM Bezel — 6- and 10-button models).
+
+Each bezel is exposed to HomeKit as a single accessory whose buttons appear as numbered `StatelessProgrammableSwitch` services. Button presses are surfaced as **single press**, **double press**, and **long press** events that can drive any HomeKit automation.
+
+## Features
+
+- Multiple bezels in one platform — list them in `config.json`.
+- Persistent caching of accessories across Homebridge restarts.
+- Automatic TCP reconnect to each bezel (5 s back-off) and periodic LED-query keep-alive (60 s).
+- Single / double / long press detection (server-side, see [Gesture timing](#gesture-timing)).
+- HomeKit "ServiceLabel" pattern — buttons appear numbered 1…10 in the Home app and can be individually renamed.
+- Auto-reconciliation with the bezel's auto-repeat behavior — one held button produces exactly one long-press event.
+- Per-bezel **Lightbulb** service for full HSB color control of the LEDs.
+- Visual press confirmation — every recognized press briefly flicks the LEDs to green (or its inverse if the LEDs are already green) so the user sees the gesture was registered.
+- All timing thresholds (long-press, double-press window, flick durations) configurable via `config.json`.
+
+## Requirements
+
+- Homebridge ≥ 1.0
+- Node.js ≥ 18
+- iPort SM Buttons hardware from April 2016 or later (firmware V6+). The earlier "DDM" hardware is not supported (see iPort's spec).
+- Each bezel reachable on TCP port `10001` and assigned a stable IP (DHCP reservation or static).
+
+## Installation
+
+### Via Homebridge UI
+
+Search for `homebridge-iport-bezel` in the Plugins tab (once published to npm).
+
+### From source (git)
+
+```bash
+git clone git@github.com:dmitry-kutergin/iport-homebridge.git
+cd iport-homebridge
+npm install
+npm run build
+sudo npm install -g .
+```
+
+Then restart Homebridge.
+
+## Configuration
+
+Add a platform entry to `~/.homebridge/config.json` (or use the Homebridge UI's JSON editor):
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "IportBezelPlatform",
+      "name": "iPort Bezels",
+      "longPressMs": 500,
+      "doublePressMs": 500,
+      "singleFlickMs": 300,
+      "longFlickMs": 1000,
+      "doubleFlickGapMs": 150,
+      "ips": [
+        {
+          "ip": "192.168.1.50",
+          "accessoryName": "Lobby Bezel",
+          "buttonCount": 10
+        },
+        {
+          "ip": "192.168.1.51",
+          "accessoryName": "Office Bezel",
+          "buttonCount": 10
+        },
+        {
+          "ip": "192.168.1.52",
+          "accessoryName": "Living Room Bezel",
+          "buttonCount": 6
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Field reference
+
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `platform` | yes | — | Must be `"IportBezelPlatform"`. |
+| `name` | yes | — | Display name for the platform (free text). |
+| `ips` | yes | — | Array of bezel definitions. |
+| `ips[].ip` | yes | — | LAN IP of the bezel. The bezel must be reachable on TCP `10001`. |
+| `ips[].accessoryName` | no | `"iPort Bezel"` | HomeKit accessory name. |
+| `ips[].buttonCount` | no | `10` | Number of buttons on the bezel (6 or 10). |
+| `longPressMs` | no | `500` | Press-and-hold duration before a `LONG_PRESS` fires. |
+| `doublePressMs` | no | `500` | Time window after release in which a second tap is registered as a `DOUBLE_PRESS`. Also sets the `SINGLE_PRESS` emit delay (we must wait this long after release to know it's not a double). |
+| `singleFlickMs` | no | `300` | Duration of a single green flick (used for `SINGLE_PRESS` confirmation and each half of the double flick). |
+| `longFlickMs` | no | `1000` | Duration of the green flick used for `LONG_PRESS` confirmation. |
+| `doubleFlickGapMs` | no | `150` | Restore-color gap between the two flicks of a `DOUBLE_PRESS` confirmation. |
+
+Hosting multiple bezels under a [Child Bridge](https://github.com/homebridge/homebridge/wiki/Child-Bridges) is recommended so a single misbehaving bezel can't slow the main bridge.
+
+## Gesture timing
+
+Per-button state machine (all thresholds configurable — see [Field reference](#field-reference)):
+
+- **Single press** — quick tap. Emitted `doublePressMs` (default 500 ms) **after release** (the wait is required so a possible second tap can be detected as a double press).
+- **Double press** — second tap arrives within `doublePressMs` after release of the first.
+- **Long press** — fires the moment the hold crosses `longPressMs` (default 500 ms), then ignores everything else until you let go. One hold = one event.
+
+The bezel auto-repeats `state:1` every ~300 ms while held; the plugin coalesces those into a single gesture.
+
+## LED control and visual feedback
+
+Each bezel exposes a **Lightbulb** service with On / Brightness / Hue / Saturation. The plugin converts HomeKit HSB → RGB and sends `led=#RRGGBB` to the bezel. The bezel's LED command sets all LEDs to the same color, so it is one Lightbulb per bezel rather than per button.
+
+**At startup** the bezel is queried (`led=?`) and its reply seeds both the LedController and the HomeKit Lightbulb characteristics — so the slider in Home accurately reflects what the LEDs are physically showing on first connect. After that, HomeKit is the source of truth: subsequent bezel replies (keep-alive echoes) are ignored so they can't drift the slider. If the bezel doesn't reply within 5 s of connect, the plugin falls back to pushing HomeKit's cached value to the bezel.
+
+Every recognized button press briefly flicks the LEDs to **green** so the user gets immediate confirmation:
+
+| Gesture | LED flick pattern |
+| --- | --- |
+| Single press | `singleFlickMs` green → restore. |
+| Double press | `singleFlickMs` green → `doubleFlickGapMs` restore → `singleFlickMs` green → restore. |
+| Long press | `longFlickMs` green → restore. |
+
+If the current LED color is already greenish, the flick uses the **bitwise inverse** of the current color (e.g. pure green flicks to pure magenta) so the confirmation stays visible.
+
+## HomeKit usage
+
+`StatelessProgrammableSwitch` services have no visible on/off state in the Home app's main UI. To use them:
+
+1. In Home, **+ → Add Automation → An Accessory Is Controlled**.
+2. Pick the bezel accessory; each numbered button shows up.
+3. Choose **Single Press / Double Press / Long Press** and configure the action.
+
+Buttons can also be renamed individually — open the accessory's settings, tap a button, edit its name. The plugin stores user-set names via the HomeKit `ConfiguredName` characteristic and they persist across restarts.
+
+## Development
+
+```bash
+npm install
+npm run build       # compile TypeScript → dist/
+```
+
+To iterate against a real Homebridge install, link the package:
+
+```bash
+npm link
+# in your homebridge install dir:
+npm link homebridge-iport-bezel
+```
+
+The full TypeScript source is in `src/index.ts`.
+
+## Logging
+
+By default the plugin emits info-level lines for one-time events (`Registering new iPort Bezel:`, `connection restored`, `seeded from bezel: led=#…`) and warnings for connection loss. Per-press logs (`button N single/double/long pressed`) and per-step LED flick traces are emitted at **debug** level so the Homebridge log stays quiet during normal use. To see them temporarily, start Homebridge with `-D` or enable debug in the UI.
+
+## Troubleshooting
+
+**New services don't appear in the Home app.** iOS / macOS HomeKit aggressively caches the HAP database for paired bridges. After adding a new service (e.g., the Lightbulb), the client may not refetch the schema on its own.
+
+1. Force-quit Home (swipe up on iPhone, ⌘Q on Mac) and reopen.
+2. If still missing, unpair the child bridge in the Homebridge UI (`Status → Bridge → Child Bridges → ⋮ → Unpair Bridge`) and re-add it from the QR code.
+
+**Repeated "MaxListenersExceededWarning: shutdown listeners".** Not from this plugin — usually `homebridge-camera-ui` registers many shutdown listeners. Harmless; restart with `NODE_OPTIONS=--trace-warnings` to confirm the source.
+
+## Protocol reference
+
+This plugin implements the JSON-over-TCP protocol described in *iPort SM Buttons API and Driver Development, Rev. G*:
+
+- Bezel listens on **TCP 10001** as the server; the plugin is the client.
+- On connect, the bezel sends a "connection" report (with `keys[]`) listing the current state of all buttons.
+- On press/release, the bezel sends an "event" report with `events[]` containing `{label: "key N", state: "0"|"1"}`.
+- The bezel auto-repeats `state:1` events every ~300 ms while a button is held — the plugin coalesces these into a single gesture.
+- LED commands are framed as `<CR>led=…<CR>` (leading **and** trailing carriage return, per spec page 16). The plugin sends:
+  - `led=#RRGGBB` to set color (used for HomeKit changes and for the flick animation).
+  - `led=?` to query — the bezel replies in **9-digit decimal RGB** form (e.g. `led=000255000` for pure green). The parser handles both hex and decimal reply formats.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/config.schema.json

@@ -0,0 +1,130 @@
+{
+  "pluginAlias": "IportBezelPlatform",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Exposes [iPort Surface Mount Buttons](https://www.iportproducts.com/products/surface-mount-buttons/) (SM Buttons / SM Bezel) to HomeKit. Each bezel becomes one accessory with numbered button services and a per-bezel Lightbulb for LED color control.",
+  "footerDisplay": "Each bezel must be reachable on TCP port `10001` and assigned a stable IP (DHCP reservation or static).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform name",
+        "type": "string",
+        "default": "iPort Bezels",
+        "required": true,
+        "description": "Display name shown in the Homebridge log."
+      },
+      "ips": {
+        "title": "Bezels",
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "object",
+          "properties": {
+            "ip": {
+              "title": "IP address",
+              "type": "string",
+              "required": true,
+              "format": "ipv4",
+              "placeholder": "192.168.1.50",
+              "description": "LAN IP of this bezel. Bezel must be reachable on TCP 10001."
+            },
+            "accessoryName": {
+              "title": "Accessory name",
+              "type": "string",
+              "default": "iPort Bezel",
+              "description": "How this bezel appears in the Home app."
+            },
+            "buttonCount": {
+              "title": "Button count",
+              "type": "integer",
+              "default": 10,
+              "oneOf": [
+                { "title": "6 buttons", "enum": [6] },
+                { "title": "10 buttons", "enum": [10] }
+              ],
+              "description": "Number of physical buttons on this bezel."
+            }
+          }
+        }
+      },
+      "longPressMs": {
+        "title": "Long-press threshold (ms)",
+        "type": "integer",
+        "default": 500,
+        "minimum": 100,
+        "maximum": 5000,
+        "description": "Press-and-hold duration before a LONG_PRESS fires."
+      },
+      "doublePressMs": {
+        "title": "Double-press window (ms)",
+        "type": "integer",
+        "default": 500,
+        "minimum": 100,
+        "maximum": 2000,
+        "description": "Window after release for a second tap to register as DOUBLE_PRESS. Also the delay before SINGLE_PRESS emits."
+      },
+      "singleFlickMs": {
+        "title": "Single-press flick duration (ms)",
+        "type": "integer",
+        "default": 300,
+        "minimum": 50,
+        "maximum": 2000,
+        "description": "Length of the green LED flick on SINGLE_PRESS (also each half of the double-press flick)."
+      },
+      "longFlickMs": {
+        "title": "Long-press flick duration (ms)",
+        "type": "integer",
+        "default": 1000,
+        "minimum": 100,
+        "maximum": 5000,
+        "description": "Length of the green LED flick on LONG_PRESS."
+      },
+      "doubleFlickGapMs": {
+        "title": "Double-flick gap (ms)",
+        "type": "integer",
+        "default": 150,
+        "minimum": 0,
+        "maximum": 1000,
+        "description": "Restore-color gap between the two flicks of a DOUBLE_PRESS confirmation."
+      }
+    }
+  },
+  "layout": [
+    "name",
+    {
+      "key": "ips",
+      "type": "array",
+      "title": "Bezels",
+      "buttonText": "Add bezel",
+      "items": [
+        "ips[].ip",
+        "ips[].accessoryName",
+        "ips[].buttonCount"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced — gesture timings",
+      "expandable": true,
+      "expanded": false,
+      "description": "Defaults work for most users. Adjust only if the built-in single / double / long press detection feels off.",
+      "items": [
+        "longPressMs",
+        "doublePressMs"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced — LED flick timings",
+      "expandable": true,
+      "expanded": false,
+      "description": "Length of the green LED flash used to confirm each press.",
+      "items": [
+        "singleFlickMs",
+        "longFlickMs",
+        "doubleFlickGapMs"
+      ]
+    }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { API } from 'homebridge';
+declare const _default: (api: API) => void;
+export default _default;

package/dist/index.js

@@ -0,0 +1,618 @@
+"use strict";
+// ─── Protocol types ──────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+function parseKey(k) {
+    const m = /(\d+)/.exec(k.label || '');
+    return {
+        num: m ? parseInt(m[1], 10) : 0,
+        state: k.state === '1' ? 1 : 0,
+    };
+}
+// ─── Color helpers ───────────────────────────────────────────────────────────
+function hexToHsb(hex) {
+    const r = parseInt(hex.substring(0, 2), 16) / 255;
+    const g = parseInt(hex.substring(2, 4), 16) / 255;
+    const b = parseInt(hex.substring(4, 6), 16) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const d = max - min;
+    let h = 0;
+    if (d !== 0) {
+        if (max === r)
+            h = ((g - b) / d) % 6;
+        else if (max === g)
+            h = (b - r) / d + 2;
+        else
+            h = (r - g) / d + 4;
+        h *= 60;
+        if (h < 0)
+            h += 360;
+    }
+    const s = max === 0 ? 0 : (d / max) * 100;
+    const bri = max * 100;
+    return { h, s, bri };
+}
+function hsbToHex(h, s, b) {
+    const sn = Math.max(0, Math.min(100, s)) / 100;
+    const bn = Math.max(0, Math.min(100, b)) / 100;
+    const hh = ((h % 360) + 360) % 360;
+    const c = bn * sn;
+    const x = c * (1 - Math.abs(((hh / 60) % 2) - 1));
+    const m = bn - c;
+    let r = 0, g = 0, bl = 0;
+    if (hh < 60) {
+        r = c;
+        g = x;
+        bl = 0;
+    }
+    else if (hh < 120) {
+        r = x;
+        g = c;
+        bl = 0;
+    }
+    else if (hh < 180) {
+        r = 0;
+        g = c;
+        bl = x;
+    }
+    else if (hh < 240) {
+        r = 0;
+        g = x;
+        bl = c;
+    }
+    else if (hh < 300) {
+        r = x;
+        g = 0;
+        bl = c;
+    }
+    else {
+        r = c;
+        g = 0;
+        bl = x;
+    }
+    const to = (n) => Math.round((n + m) * 255).toString(16).padStart(2, '0').toUpperCase();
+    return to(r) + to(g) + to(bl);
+}
+function isGreenish(hex) {
+    const r = parseInt(hex.substring(0, 2), 16);
+    const g = parseInt(hex.substring(2, 4), 16);
+    const b = parseInt(hex.substring(4, 6), 16);
+    return g > 128 && g > r && g > b;
+}
+function invertHex(hex) {
+    const r = 255 - parseInt(hex.substring(0, 2), 16);
+    const g = 255 - parseInt(hex.substring(2, 4), 16);
+    const b = 255 - parseInt(hex.substring(4, 6), 16);
+    return [r, g, b].map(n => n.toString(16).padStart(2, '0').toUpperCase()).join('');
+}
+const FLICK_GREEN = '00FF00';
+// ─── TCP Client ──────────────────────────────────────────────────────────────
+const TCP_PORT = 10001;
+const DELIMITER = '\r\n';
+const RECONNECT_MS = 5000;
+const HEALTH_MS = 60000;
+class TcpClient {
+    constructor(host, onReconn) {
+        this.host = host;
+        this.onReconn = onReconn;
+        this.socket = null;
+        this.buf = '';
+        this.tmrReconn = null;
+        this.tmrHealth = null;
+        this.alive = false;
+        this.lastSentLed = null;
+    }
+    connect() {
+        this.tmrReconn = null;
+        const net = require('net');
+        this.socket = net.connect(TCP_PORT, this.host, () => {
+            this.alive = true;
+            this.buf = '';
+            this.startHealth();
+            this.onUp?.();
+        });
+        this.socket.on('data', (d) => {
+            this.buf += d.toString();
+            let i;
+            while ((i = this.buf.indexOf(DELIMITER)) !== -1) {
+                const line = this.buf.substring(0, i).trim();
+                this.buf = this.buf.substring(i + DELIMITER.length);
+                if (line)
+                    this.parse(line);
+            }
+        });
+        this.socket.on('error', () => this.crash('sock err'));
+        this.socket.on('close', () => this.crash('closed'));
+    }
+    destroy() {
+        this.killHealth();
+        if (this.tmrReconn) {
+            clearTimeout(this.tmrReconn);
+            this.tmrReconn = null;
+        }
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.alive = false;
+    }
+    writeLed(hex) {
+        if (!this.alive || !this.socket)
+            return;
+        // Per spec page 16, LED commands are framed as <CR>led=...<CR>.
+        // Without the leading CR the bezel processes the first command of a
+        // connection but ignores back-to-back commands (the second one is appended
+        // to the trailing-CR state of the first).
+        this.socket.write(`\rled=#${hex}\r`);
+        this.lastSentLed = hex;
+    }
+    queryLed() {
+        if (!this.alive || !this.socket)
+            return;
+        this.socket.write('\rled=?\r');
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    // Per SM Buttons API spec (Rev. G, page 13): reports have no `type` field.
+    // A connection report carries `keys[]`; an event report carries `events[]`.
+    // Each entry is {label: "key N", state: "0"|"1"}.
+    // Non-JSON lines are LED responses (either "led=#RRGGBB" hex or
+    // "led=RRRGGGBBB" 9-digit decimal per spec page 16).
+    parse(line) {
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            // Per spec page 16, the bezel uses two LED formats:
+            //   hex     :  led=#1791EF
+            //   decimal :  led=023145239     (9-digit, 3+3+3 zero-padded RGB)
+            // Match the hex form (with required '#') OR the 9-digit decimal form
+            // explicitly. The previous regex matched 6 hex chars first and would
+            // mis-parse "led=000255000" as hex 0x000255 instead of decimal R=0/G=255/B=0.
+            const m = /led\s*=\s*(?:#([0-9A-Fa-f]{6})|(\d{9}))/.exec(line);
+            if (m) {
+                let hex;
+                if (m[1]) {
+                    hex = m[1].toUpperCase();
+                }
+                else {
+                    const p = m[2];
+                    const r2 = parseInt(p.substring(0, 3), 10);
+                    const g2 = parseInt(p.substring(3, 6), 10);
+                    const b2 = parseInt(p.substring(6, 9), 10);
+                    hex = [r2, g2, b2].map(n => Math.min(255, n).toString(16).padStart(2, '0')).join('').toUpperCase();
+                }
+                this.onLed?.(hex);
+            }
+            return;
+        }
+        if (r.events && r.events.length) {
+            this.onEvent?.(r.events.map(parseKey));
+        }
+        else if (r.keys && r.keys.length) {
+            this.onKeys?.(r.keys.map(parseKey));
+        }
+    }
+    crash(reason) {
+        this.alive = false;
+        this.killHealth();
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.onLost?.();
+        this.tmrReconn = setTimeout(() => {
+            this.onReconn();
+            this.connect();
+        }, RECONNECT_MS);
+        this.tmrReconn.unref?.();
+    }
+    startHealth() {
+        this.killHealth();
+        this.tmrHealth = setInterval(() => {
+            if (!this.alive)
+                this.crash('health timeout');
+            else
+                this.queryLed();
+        }, HEALTH_MS);
+        this.tmrHealth.unref?.();
+    }
+    killHealth() {
+        if (this.tmrHealth) {
+            clearInterval(this.tmrHealth);
+            this.tmrHealth = null;
+        }
+    }
+}
+const DEFAULT_TIMINGS = {
+    longPressMs: 500,
+    doublePressMs: 500,
+    singleFlickMs: 300,
+    longFlickMs: 1000,
+    doubleFlickGapMs: 150,
+};
+class LedController {
+    constructor(tcp, timings, log) {
+        this.tcp = tcp;
+        this.timings = timings;
+        this.log = log;
+        this.h = 0;
+        this.s = 0;
+        this.bri = 100;
+        this.on = true;
+        this.applyTimer = null;
+        this.flickTimer = null;
+        this.flicking = false;
+    }
+    setHue(v) { this.h = v; this.schedule(); }
+    setSaturation(v) { this.s = v; this.schedule(); }
+    setBrightness(v) { this.bri = v; this.schedule(); }
+    setOn(v) { this.on = !!v; this.schedule(); }
+    // Push the current HSB/on state to the bezel right away (no debounce).
+    applyImmediate() {
+        if (this.applyTimer) {
+            clearTimeout(this.applyTimer);
+            this.applyTimer = null;
+        }
+        if (!this.flicking)
+            this.tcp.writeLed(this.userHex());
+    }
+    // Sync internal state from a hex value the bezel reported (no write back).
+    // Returns the HSB so callers can mirror to HomeKit characteristics.
+    applyFromBezel(hex) {
+        if (this.applyTimer) {
+            clearTimeout(this.applyTimer);
+            this.applyTimer = null;
+        }
+        const on = hex.toUpperCase() !== '000000';
+        const hsb = hexToHsb(hex);
+        this.on = on;
+        this.h = hsb.h;
+        this.s = hsb.s;
+        this.bri = on ? hsb.bri : this.bri; // keep last bri when "off" so toggling back restores it
+        return { on, h: hsb.h, s: hsb.s, bri: hsb.bri };
+    }
+    flick(pattern) {
+        if (this.flickTimer) {
+            clearTimeout(this.flickTimer);
+            this.flickTimer = null;
+        }
+        const orig = this.userHex();
+        const accent = isGreenish(orig) ? invertHex(orig) : FLICK_GREEN;
+        const single = this.timings.singleFlickMs;
+        const long = this.timings.longFlickMs;
+        const gap = this.timings.doubleFlickGapMs;
+        let steps;
+        switch (pattern) {
+            case 'single':
+                steps = [{ hex: accent, ms: single }, { hex: orig, ms: 0 }];
+                break;
+            case 'double':
+                steps = [
+                    { hex: accent, ms: single }, { hex: orig, ms: gap },
+                    { hex: accent, ms: single }, { hex: orig, ms: 0 },
+                ];
+                break;
+            case 'long':
+                steps = [{ hex: accent, ms: long }, { hex: orig, ms: 0 }];
+                break;
+        }
+        this.flicking = true;
+        this.runFlick(steps);
+    }
+    schedule() {
+        if (this.applyTimer)
+            clearTimeout(this.applyTimer);
+        this.applyTimer = setTimeout(() => { this.applyTimer = null; this.apply(); }, 50);
+        this.applyTimer.unref?.();
+    }
+    apply() {
+        if (!this.flicking)
+            this.tcp.writeLed(this.userHex());
+    }
+    userHex() {
+        return this.on ? hsbToHex(this.h, this.s, this.bri) : '000000';
+    }
+    runFlick(steps) {
+        if (steps.length === 0) {
+            this.flicking = false;
+            this.flickTimer = null;
+            this.tcp.writeLed(this.userHex());
+            this.log?.debug(`flick done → restore ${this.userHex()}`);
+            return;
+        }
+        const [head, ...tail] = steps;
+        this.tcp.writeLed(head.hex);
+        this.log?.debug(`flick step → ${head.hex} (next in ${head.ms}ms, ${tail.length} step(s) remaining)`);
+        if (tail.length === 0) {
+            this.flicking = false;
+            this.flickTimer = null;
+            return;
+        }
+        this.flickTimer = setTimeout(() => this.runFlick(tail), head.ms);
+        this.flickTimer.unref?.();
+    }
+}
+const PLUGIN_NAME = 'homebridge-iport-bezel';
+const PLATFORM_NAME = 'IportBezelPlatform';
+class IportBezelPlatform {
+    constructor(log, config, api) {
+        this.log = log;
+        this.config = config;
+        this.api = api;
+        this.cached = new Map();
+        // Runtime state kept off `accessory.context` so Homebridge's JSON
+        // serialization of the cache doesn't choke on TCP sockets / Timeout objects.
+        this.runtime = new Map();
+        const cfg = config;
+        const num = (key) => {
+            const v = cfg[key];
+            const n = typeof v === 'number' ? v : typeof v === 'string' ? parseInt(v, 10) : NaN;
+            return Number.isFinite(n) && n >= 0 ? n : DEFAULT_TIMINGS[key];
+        };
+        this.timings = {
+            longPressMs: num('longPressMs'),
+            doublePressMs: num('doublePressMs'),
+            singleFlickMs: num('singleFlickMs'),
+            longFlickMs: num('longFlickMs'),
+            doubleFlickGapMs: num('doubleFlickGapMs'),
+        };
+        this.log.debug(`Timings: ${JSON.stringify(this.timings)}`);
+        this.api.on('didFinishLaunching', () => this.discoverDevices());
+    }
+    configureAccessory(acc) {
+        this.cached.set(acc.UUID, acc);
+    }
+    discoverDevices() {
+        const ips = this.config.ips || [];
+        const seen = new Set();
+        for (const ipCfg of ips) {
+            if (!ipCfg.ip) {
+                this.log.warn('Skipping iPort config entry with no ip');
+                continue;
+            }
+            const uuid = this.api.hap.uuid.generate(`iport-bezel-${ipCfg.ip}`);
+            seen.add(uuid);
+            const existing = this.cached.get(uuid);
+            if (existing) {
+                this.log.info(`Restoring cached iPort Bezel: ${existing.displayName} (${ipCfg.ip})`);
+                this.configureBezel(existing, ipCfg, false);
+            }
+            else {
+                const name = ipCfg.accessoryName || 'iPort Bezel';
+                this.log.info(`Registering new iPort Bezel: ${name} (${ipCfg.ip})`);
+                const acc = new this.api.platformAccessory(name, uuid);
+                this.configureBezel(acc, ipCfg, true);
+                this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [acc]);
+            }
+        }
+        // Remove cached accessories that are no longer in config.
+        for (const [uuid, acc] of this.cached) {
+            if (!seen.has(uuid)) {
+                this.log.info(`Removing stale iPort Bezel from cache: ${acc.displayName}`);
+                this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [acc]);
+            }
+        }
+    }
+    // ── wire up services + TCP for one accessory ────────────────────────────
+    configureBezel(acc, cfg, fresh) {
+        const hap = this.api.hap;
+        const ip = cfg.ip;
+        const name = cfg.accessoryName || acc.displayName || 'iPort Bezel';
+        const count = cfg.buttonCount || 10;
+        // Only plain-serializable values may live in acc.context — Homebridge
+        // JSON-stringifies it for cachedAccessories.
+        acc.context.ip = ip;
+        acc.context.buttonCount = count;
+        // Tear down any previous runtime for this UUID (re-discovery).
+        const prev = this.runtime.get(acc.UUID);
+        if (prev)
+            prev.tcp.destroy();
+        // ServiceLabel makes the Home app present sub-services as numbered buttons
+        // (canonical HomeKit pattern for multi-button accessories).
+        let labelSvc = acc.getService(hap.Service.ServiceLabel);
+        if (!labelSvc)
+            labelSvc = acc.addService(hap.Service.ServiceLabel);
+        labelSvc.setCharacteristic(hap.Characteristic.ServiceLabelNamespace, hap.Characteristic.ServiceLabelNamespace.ARABIC_NUMERALS);
+        const services = [];
+        for (let i = 1; i <= count; i++) {
+            const subtype = `btn${i}`;
+            const label = `${name} - Btn ${i}`;
+            let svc = acc.getServiceById(hap.Service.StatelessProgrammableSwitch, subtype);
+            if (!svc) {
+                svc = acc.addService(hap.Service.StatelessProgrammableSwitch, label, subtype);
+            }
+            else {
+                svc.setCharacteristic(hap.Characteristic.Name, label);
+            }
+            // Numbered button index in the Home app.
+            svc.setCharacteristic(hap.Characteristic.ServiceLabelIndex, i);
+            // ConfiguredName lets the user rename each button individually in Home.
+            // Declare it optional first to silence the "not in optional section" warning.
+            svc.addOptionalCharacteristic(hap.Characteristic.ConfiguredName);
+            if (!svc.testCharacteristic(hap.Characteristic.ConfiguredName)
+                || !svc.getCharacteristic(hap.Characteristic.ConfiguredName).value) {
+                svc.setCharacteristic(hap.Characteristic.ConfiguredName, label);
+            }
+            services.push(svc);
+        }
+        // Drop any leftover button services beyond `count` from previous configs.
+        const keep = new Set(services);
+        for (const svc of acc.services.slice()) {
+            if (svc.UUID === hap.Service.StatelessProgrammableSwitch.UUID && !keep.has(svc)) {
+                acc.removeService(svc);
+            }
+        }
+        // ── Lightbulb (LED color) ───────────────────────────────────────────────
+        const bulbName = `${name} LEDs`;
+        let bulb = acc.getService(hap.Service.Lightbulb);
+        let bulbJustCreated = false;
+        if (!bulb) {
+            bulb = acc.addService(hap.Service.Lightbulb, bulbName, 'leds');
+            bulbJustCreated = true;
+        }
+        else {
+            bulb.setCharacteristic(hap.Characteristic.Name, bulbName);
+        }
+        bulb.addOptionalCharacteristic(hap.Characteristic.ConfiguredName);
+        if (!bulb.testCharacteristic(hap.Characteristic.ConfiguredName)
+            || !bulb.getCharacteristic(hap.Characteristic.ConfiguredName).value) {
+            bulb.setCharacteristic(hap.Characteristic.ConfiguredName, bulbName);
+        }
+        // Ensure HSB characteristics exist on the Lightbulb service.
+        for (const ch of [hap.Characteristic.Brightness, hap.Characteristic.Hue, hap.Characteristic.Saturation]) {
+            if (!bulb.testCharacteristic(ch))
+                bulb.addCharacteristic(ch);
+        }
+        // Initialize sensible defaults exactly once per accessory. The flag lives
+        // in acc.context so it survives Homebridge restarts. Without this, freshly
+        // added (or previously bezel-mirrored, now-corrupted) Lightbulbs default
+        // to off / bri=0 / random hue.
+        if (bulbJustCreated || !acc.context.lightbulbInitialized) {
+            this.log.info(`[${ip}] initializing Lightbulb to white at 100% on`);
+            bulb.setCharacteristic(hap.Characteristic.On, true);
+            bulb.setCharacteristic(hap.Characteristic.Brightness, 100);
+            bulb.setCharacteristic(hap.Characteristic.Hue, 0);
+            bulb.setCharacteristic(hap.Characteristic.Saturation, 0);
+            acc.context.lightbulbInitialized = true;
+        }
+        const tcp = new TcpClient(ip, () => { });
+        const led = new LedController(tcp, this.timings, { debug: (m) => this.log.debug(`[${ip}] ${m}`) });
+        const btnState = Array.from({ length: count }, () => ({ held: false, consumed: false, singleTimer: null, longTimer: null }));
+        const rt = { services, btnState, tcp, led };
+        this.runtime.set(acc.UUID, rt);
+        // On first connect, the bezel is the source of truth: we send led=? and
+        // mirror the reply into both LedController and HomeKit. Subsequent led=
+        // responses (periodic keep-alives, echoes from our own writes) are ignored
+        // so they don't drift the slider.
+        let seededFromBezel = false;
+        tcp.onLed = (hex) => {
+            if (seededFromBezel) {
+                this.log.debug(`[${ip}] bezel led=#${hex} (post-seed, ignored)`);
+                return;
+            }
+            seededFromBezel = true;
+            const { on, h, s, bri } = led.applyFromBezel(hex);
+            this.log.info(`[${ip}] seeded from bezel: led=#${hex} (on=${on}, h=${h.toFixed(0)}, s=${s.toFixed(0)}, bri=${bri.toFixed(0)})`);
+            bulb.updateCharacteristic(hap.Characteristic.On, on);
+            if (on) {
+                bulb.updateCharacteristic(hap.Characteristic.Hue, h);
+                bulb.updateCharacteristic(hap.Characteristic.Saturation, s);
+                bulb.updateCharacteristic(hap.Characteristic.Brightness, Math.max(1, Math.round(bri)));
+            }
+        };
+        // Seed LedController provisionally from HomeKit cache. If the bezel
+        // responds to our query in time, applyFromBezel will overwrite this.
+        const seedOn = !!bulb.getCharacteristic(hap.Characteristic.On).value;
+        const seedHue = Number(bulb.getCharacteristic(hap.Characteristic.Hue).value ?? 0);
+        const seedSat = Number(bulb.getCharacteristic(hap.Characteristic.Saturation).value ?? 0);
+        const seedBri = Number(bulb.getCharacteristic(hap.Characteristic.Brightness).value ?? 100);
+        led.setOn(seedOn);
+        led.setHue(seedHue);
+        led.setSaturation(seedSat);
+        led.setBrightness(seedBri);
+        bulb.getCharacteristic(hap.Characteristic.On)
+            .onSet((v) => led.setOn(!!v));
+        bulb.getCharacteristic(hap.Characteristic.Brightness)
+            .onSet((v) => led.setBrightness(Number(v)));
+        bulb.getCharacteristic(hap.Characteristic.Hue)
+            .onSet((v) => led.setHue(Number(v)));
+        bulb.getCharacteristic(hap.Characteristic.Saturation)
+            .onSet((v) => led.setSaturation(Number(v)));
+        const PSE = hap.Characteristic.ProgrammableSwitchEvent;
+        // The bezel auto-repeats state:1 every ~300ms while held. Gesture rules:
+        //   - First state:1: start hold; schedule LONG_PRESS at LONG_PRESS_MS.
+        //   - LONG_PRESS fires: mark `consumed`; ignore every subsequent state:1
+        //     and the eventual state:0 (no further events for this hold).
+        //   - state:1 while still held (auto-repeat): ignore.
+        //   - state:0 (release):
+        //       • if not consumed: short tap → schedule SINGLE_PRESS at DOUBLE_PRESS_MS.
+        //       • if a 2nd state:1 arrives in that window → DOUBLE_PRESS, consume,
+        //         and ignore the upcoming release.
+        tcp.onEvent = (events) => {
+            for (const evt of events) {
+                const idx = evt.num - 1;
+                const btn = rt.services[idx];
+                const st = rt.btnState[idx];
+                if (!btn || !st) {
+                    this.log.debug(`${ip} event for unknown button ${evt.num}`);
+                    continue;
+                }
+                if (evt.state === 1) {
+                    if (st.held)
+                        continue; // auto-repeat while still pressed — ignore
+                    st.held = true;
+                    if (st.singleTimer) {
+                        // 2nd distinct press within the double-press window → DOUBLE.
+                        clearTimeout(st.singleTimer);
+                        st.singleTimer = null;
+                        st.consumed = true; // don't fire anything on this press's release
+                        this.log.debug(`${ip} button ${evt.num} double pressed`);
+                        btn.updateCharacteristic(PSE, PSE.DOUBLE_PRESS);
+                        rt.led.flick('double');
+                    }
+                    else {
+                        // First press of a new gesture — schedule LONG_PRESS at longPressMs.
+                        st.longTimer = setTimeout(() => {
+                            st.longTimer = null;
+                            st.consumed = true; // ignore auto-repeats and release until next gesture
+                            this.log.debug(`${ip} button ${evt.num} long pressed`);
+                            btn.updateCharacteristic(PSE, PSE.LONG_PRESS);
+                            rt.led.flick('long');
+                        }, this.timings.longPressMs);
+                        st.longTimer.unref?.();
+                    }
+                }
+                else {
+                    // Release.
+                    st.held = false;
+                    if (st.longTimer) {
+                        clearTimeout(st.longTimer);
+                        st.longTimer = null;
+                    }
+                    if (st.consumed) {
+                        st.consumed = false; // gesture already emitted — reset for next press
+                        continue;
+                    }
+                    // Short tap — wait doublePressMs for a possible 2nd press before firing SINGLE.
+                    st.singleTimer = setTimeout(() => {
+                        st.singleTimer = null;
+                        this.log.debug(`${ip} button ${evt.num} single pressed`);
+                        btn.updateCharacteristic(PSE, PSE.SINGLE_PRESS);
+                        rt.led.flick('single');
+                    }, this.timings.doublePressMs);
+                    st.singleTimer.unref?.();
+                }
+            }
+        };
+        tcp.onKeys = () => { };
+        tcp.onUp = () => {
+            this.log.info(`${ip} connection restored`);
+            if (!seededFromBezel) {
+                // First connect after Homebridge start — read the bezel.
+                tcp.queryLed();
+                // Fallback: if no reply in 5s, lock the seed flag and push HomeKit's
+                // value so the bezel reflects the cached UI state.
+                setTimeout(() => {
+                    if (!seededFromBezel) {
+                        seededFromBezel = true;
+                        this.log.warn(`[${ip}] bezel did not reply to led=?; pushing HomeKit state`);
+                        rt.led.applyImmediate();
+                    }
+                }, 5000).unref?.();
+            }
+            else {
+                // Reconnect: push HomeKit's current state in case the bezel rebooted.
+                rt.led.applyImmediate();
+            }
+        };
+        tcp.onLost = () => { this.log.warn(`${ip} connection lost`); };
+        tcp.connect();
+        if (!fresh)
+            this.api.updatePlatformAccessories([acc]);
+    }
+}
+// ─── Entry Point ─────────────────────────────────────────────────────────────
+exports.default = (api) => {
+    api.registerPlatform('homebridge-iport-bezel', 'IportBezelPlatform', IportBezelPlatform);
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "homebridge-iport-bezel",
+  "version": "1.0.0",
+  "description": "Homebridge platform plugin for iPort Surface Mount Buttons (SM Buttons / SM Bezel) — 6 and 10 button models. Exposes each button as a HomeKit stateless switch and the LEDs as a Lightbulb with full HSB color control.",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "config.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "homebridge": "^1.0.0",
+    "rimraf": "^3.0.2",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "homebridge": ">=1.0.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rimraf ./dist && tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmitry-kutergin/iport-homebridge.git"
+  },
+  "keywords": [
+    "iPort",
+    "iPort SM",
+    "iPort Bezel",
+    "SM Buttons",
+    "Homebridge",
+    "Home Automation",
+    "HomeKit",
+    "homebridge-plugin"
+  ],
+  "author": "Dmitry Kutergin",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dmitry-kutergin/iport-homebridge/issues"
+  },
+  "homepage": "https://github.com/dmitry-kutergin/iport-homebridge#readme"
+}