homebridge-eliot-smart-control 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] — 2026-09-18
+
+### Added
+
+- **The desk's child lock as a switch.** It shows the real state: unlike every
+  other setting the app can change, this one the control box reads back.
+
+### Changed
+
+- **The desk is now given a height and left to drive there itself.** Its
+  control box has a *go to height* command and a *stop* command; neither
+  appears in the published write-ups of this protocol, and both were found in
+  the Eliot Android app and verified on hardware. Moves land exactly on target
+  instead of within about 1%, on the control box's own ramp, and stopping part
+  way coasts 13 mm rather than 18.
+- Step commands remain as a fallback for a control box that does not know
+  *go to height*: if the desk has not moved shortly after being told where to
+  go, the old loop takes over. Untested against such a box, since none was to
+  hand.
+
+### Added
+
+- `docs/PROTOCOL.md` records the twelve commands the published write-ups are
+  missing, and what the app's *Automatischer Reset* actually does — it is not
+  a command at all, but a drive to the physical bottom so the control box can
+  find its zero. It also records the two commands that do nothing on this
+  control box, measured rather than assumed, which is why no switches were
+  built for them.
+
+## [0.3.1] — 2026-09-18
+
+### Fixed
+
+- **Memory switches did nothing after a restart.** Homebridge restores an
+  accessory's services from its cache but not their handlers, and the switches
+  were adopted without being wired up again — present in the Home app,
+  unresponsive, and silent about it. They worked only in the session that
+  created them.
+
+### Changed
+
+- The accessory accepts an injected transport, so its behaviour can be tested
+  without a desk in the room. The fix above was untestable before.
+
+## [0.3.0] — 2026-09-18
+
+### Added
+
+- **Find your desk** in the plugin's settings page. The dongle advertises as
+  `Schreibtisch` with no manufacturer name, a random-static address and often
+  nothing printed on the sticker, so a scan list gives nothing to go on.
+  Candidates are confirmed by the serial service rather than by name, and the
+  page reports the two states that otherwise look like failure: a dongle
+  already connected to something else, and a signal weak enough to predict
+  dropouts.
+- `tools/find-desks.js`, the same discovery from the command line.
+
+## [0.2.1] — 2026-09-18
+
+### Fixed
+
+- **A memory move can be stopped after all.** The previous release documented
+  the opposite. There is no stop command, but any step command cancels a move
+  the control box is driving — verified on hardware. `HoldPosition` works
+  during a preset, and a second move now cancels the first rather than racing
+  it.
+
+## [0.2.0] — 2026-09-18
+
+### Added
+
+- **The desk's memory positions as momentary switches.** The control box drives
+  to them itself on its own ramp, easing into the target within about 2 mm,
+  which is better than this plugin manages with step commands. Only memories
+  the desk actually has appear.
+
+### Fixed
+
+- Services set `ConfiguredName` as well as `Name`; without it the Home app
+  shows every switch under the accessory's own name.
+
+## [0.1.1] — 2026-09-18
+
+### Fixed
+
+- **Measurement noise read as somebody using the handset.** The control box's
+  reported height wanders a few millimetres between reports, and the threshold
+  sat inside that noise, so the target was reset constantly. Movement is now
+  judged against the height the desk was last settled at, which also catches a
+  slow handset move that consecutive readings would miss entirely.
+
+## [0.1.0] — 2026-09-18
+
+First release.
+
+### Added
+
+- Control an Eliot sit-stand desk from the Home app over Bluetooth, as a window
+  covering. 0% is the lowest height the desk is configured to allow, 100% the
+  highest, both read from the desk rather than configured here.
+- Position, direction of travel and a stop control; the Home app follows the
+  handset as well as the other way round.
+- An unreachable desk reports a communication failure rather than the height it
+  had an hour ago.
+- `docs/PROTOCOL.md`: the protocol, reverse-engineered for this desk and
+  verified against hardware, including the measured travel speed and stopping
+  distance.
+
+[Unreleased]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/rummeyer/homebridge-eliot-smart-control/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/rummeyer/homebridge-eliot-smart-control/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Rummeyer
+
+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,172 @@
+<h1 align="center">homebridge-eliot-smart-control</h1>
+
+<p align="center">
+  Your <b>Eliot sit-stand desk</b> in the Apple Home app &mdash; over Bluetooth, with no account and no cloud.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/homebridge-eliot-smart-control"><img src="https://img.shields.io/npm/v/homebridge-eliot-smart-control?label=npm" alt="npm"></a>
+  <a href="https://github.com/rummeyer/homebridge-eliot-smart-control/actions/workflows/build.yml"><img src="https://github.com/rummeyer/homebridge-eliot-smart-control/actions/workflows/build.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/rummeyer/homebridge-eliot-smart-control/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-MIT-blue" alt="Licence"></a>
+  <img src="https://img.shields.io/badge/homebridge-%E2%89%A5%202.0.0-purple" alt="Homebridge 2.0.0+">
+  <img src="https://img.shields.io/badge/node-22%20%7C%2024%20%7C%2026-green" alt="Node 22, 24 or 26">
+</p>
+
+---
+
+## What it looks like in the Home app
+
+**The desk itself**, as a slider from 0 to 100%.
+
+0% is the lowest height your desk is set to allow and 100% the highest. Those
+come from the desk, not from this plugin, so if you change the limits on the
+handset the ends of the slider follow.
+
+*"Hey Siri, set the desk to 100%."* Or put it in an automation: up for the
+morning meeting, down at the end of the day.
+
+**Your memory positions**, as buttons &mdash; the same ones as on the handset.
+Press one and the desk goes there; the button springs back, the way a scene
+does. Only positions you have actually stored appear.
+
+**The child lock**, as a switch. It shows the desk's real state, so if someone
+locks it at the handset the Home app knows.
+
+Everything follows the desk, not just the other way round. Use the handset and
+the Home app keeps up. A desk out of range says *No Response* rather than
+showing you the height it had an hour ago.
+
+## What you need
+
+| | |
+|---|---|
+| **Desk** | An Eliot with the Smart Dongle, or the Procontroller |
+| **Homebridge** | 2.0.0 or newer, **on Linux** |
+| **Node.js** | 22.18, 24 or 26 |
+| **Range** | Homebridge has to stay within Bluetooth range of the desk |
+
+**Linux only.** The plugin talks to BlueZ over D-Bus, and macOS and Windows
+have no equivalent. A Raspberry Pi running Homebridge is the usual home for it.
+In a container, mount the host's `/var/run/dbus/system_bus_socket`.
+
+**One connection at a time.** The dongle accepts a single Bluetooth connection.
+While Homebridge has it, the Eliot app on your phone cannot connect — and while
+the app has it, this plugin cannot.
+
+## Setting it up
+
+**1. Install it.** In the Homebridge UI, go to **Plugins**, search for
+`homebridge-eliot-smart-control` and choose **Install**.
+
+**2. Give it a child bridge.** In the plugin's **⋮** menu, choose **Bridge
+Settings** and turn the child bridge on. Bluetooth links drop and reconnect;
+in a child bridge that churn stays in its own process instead of unsettling
+your other accessories.
+
+**3. Find your desk.** Open the plugin's **Settings** and press **Scan for
+desks**.
+
+This is the part worth having help with. The dongle does not announce itself:
+it appears as **`Schreibtisch`**, with no manufacturer name, and many units
+have nothing printed on them — in a scan list it sits among forty anonymous
+phones with nothing to tell them apart. The page looks for the Bluetooth
+service the desk actually speaks, so a result marked *confirmed* is the right
+device and not a good guess.
+
+Press **Use this** next to yours, name it, and save.
+
+*Nothing found?* Something else probably has it. Close the Eliot app and turn
+Bluetooth off on any phone that has been paired with the desk, then unplug the
+dongle for five seconds.
+
+**4. Add it to the Home app.** The child bridge has its own QR code under
+**Bridge Settings**. Scan it the same way you paired Homebridge itself.
+
+## Settings
+
+| | | |
+|---|---|---|
+| **Name** | required | What the desk is called in the Home app |
+| **Dongle address** | required | Filled in for you by the scan |
+| **Idle refresh** | 30 s | How often to ask a standing desk for its height. It reports by itself while moving, so this only catches the handset being used. 0 turns it off |
+| **Memory switches** | on | Offer your stored positions as buttons |
+| **Memory names** | — | What to call them. Defaults to *Memory 1*…*Memory 4* |
+| **Child lock switch** | on | Offer the desk's child lock |
+
+Or by hand, in `config.json`:
+
+```json
+{
+  "platform": "EliotSmartControl",
+  "desks": [
+    {
+      "name": "Schreibtisch",
+      "mac": "E5:11:22:33:44:55",
+      "memoryNames": ["Sitzen", "Stehen", "Besprechung"]
+    }
+  ]
+}
+```
+
+## Things worth knowing
+
+**Positions land exactly.** The desk is handed a height and drives there on its
+own ramp, easing in and stopping within a couple of millimetres — the same
+mechanism as the memory buttons on the handset.
+
+**Stopping works, and coasts about 13 mm.** There is no instant brake on a desk.
+
+**Using the handset during a move is safe.** The control box gives the handset
+priority and stops; it never drives against you. A brief press pauses the move
+and it carries on, holding the button ends it, and the Home app settles on
+wherever the desk actually is rather than trying again.
+
+**An unset memory gets no button.** If you store a new position on the handset,
+its button appears the next time the plugin connects.
+
+**The desk's own safety features are untouched.** Anti-collision and the soft
+limits live in the control box. The plugin adds limits of its own on top: it
+gives up if the desk stops making progress, if a move takes longer than the
+distance can account for, or if the desk stops saying where it is.
+
+## When something is wrong
+
+**The scan finds nothing.** Close the Eliot app and turn Bluetooth off on any
+phone that has been paired with the desk — closing the app does not always
+release the connection, and the dongle will not advertise while something holds
+it. Then unplug it for five seconds; it advertises immediately on power-up.
+
+**It connects, then drops.** Check the signal. The settings page shows it beside
+each result and warns when it is weak; anything near -90 dBm comes and goes.
+Move Homebridge closer, or put a second one near the desk.
+
+**A dongle that stays silent while plugged in and powered is broken.** Obvious
+written down, indistinguishable from a range problem in practice, and worth
+ruling out early by trying another one. It cost a day here.
+
+**"No D-Bus system bus"** means BlueZ is not reachable: you are not on Linux, or
+you are in a container without `/var/run/dbus/system_bus_socket` mounted.
+
+**Everything looks right but nothing moves.** Check the dongle is in the port
+marked **F** on the control box, not **HS** — that one is for the handset.
+
+## How it works
+
+The Smart Dongle is a Lierda `LSD4BT-E95ALSP001` presenting a transparent
+Bluetooth-to-serial bridge; behind it the control box speaks the Jiecang
+handset protocol. None of that was written down anywhere for this desk, so
+[`docs/PROTOCOL.md`](docs/PROTOCOL.md) writes it down now: the framing, the
+command set, the measured travel speed and stopping distance, what the app's
+*Automatischer Reset* really does, and which parts are verified against
+hardware rather than assumed. Including the commands that turned out to do
+nothing, which is worth knowing too.
+
+Credit where it is due: the serial protocol was reverse-engineered for other
+desks by [phord/Jarvis](https://github.com/phord/Jarvis) and
+[Rocka84/jiecang_desk_controller](https://github.com/Rocka84/jiecang_desk_controller).
+Working out that an Eliot speaks it, what the Bluetooth side looks like, and
+the several commands those write-ups are missing is what this project added.
+
+## Licence
+
+MIT

package/config.schema.json

@@ -0,0 +1,100 @@
+{
+  "pluginAlias": "EliotSmartControl",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Control an Eliot sit-stand desk with the Smart Dongle from the Home app, over Bluetooth. Requires Linux — the plugin talks to BlueZ.",
+  "footerDisplay": "The dongle advertises as **Schreibtisch** and has no vendor name, so it can be hard to spot. Run `node tools/eliot-probe.js scan` on the Homebridge host to find its address.\n\nThe desk appears as a window covering: 0% is the lowest height it is set to allow, 100% the highest. Those come from the desk's own limits, so changing them on the handset changes what 0% and 100% mean.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Eliot Smart Control",
+        "description": "Only the log prefix. Each desk is named separately below."
+      },
+      "desks": {
+        "title": "Desks",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "required": true,
+              "default": "Schreibtisch",
+              "placeholder": "Schreibtisch",
+              "description": "What the desk is called in the Home app."
+            },
+            "mac": {
+              "title": "Dongle address",
+              "type": "string",
+              "required": true,
+              "placeholder": "E5:11:22:33:44:55",
+              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
+              "description": "Bluetooth address of the Smart Dongle."
+            },
+            "idlePollSeconds": {
+              "title": "Idle refresh (seconds)",
+              "type": "integer",
+              "default": 30,
+              "minimum": 0,
+              "description": "How often to ask a standing desk for its height. The desk reports by itself while moving, so this only catches the handset being used. 0 turns it off."
+            },
+            "memorySwitches": {
+              "title": "Memory-Schalter",
+              "type": "boolean",
+              "default": true,
+              "description": "Die Speicherplätze des Tisches als Schalter anbieten. Sie springen nach dem Drücken zurück, wie eine Szene. Nur belegte Plätze erscheinen."
+            },
+            "memoryNames": {
+              "title": "Namen der Memory-Schalter",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "title": "Name"
+              },
+              "description": "Optionale Namen für Memory 1 bis 4, in dieser Reihenfolge. Leer lassen für \"Memory 1\", \"Memory 2\" und so weiter."
+            },
+            "childLockSwitch": {
+              "title": "Kindersicherung als Schalter",
+              "type": "boolean",
+              "default": true,
+              "description": "Die Kindersicherung des Tisches in der Home-App anbieten. Sie ist die einzige Einstellung, die die Controlbox zurückmeldet, also die einzige, die ehrlich angezeigt werden kann."
+            }
+          }
+        }
+      }
+    }
+  },
+  "layout": [
+    {
+      "key": "name"
+    },
+    {
+      "key": "desks",
+      "type": "array",
+      "orderable": false,
+      "buttonText": "Add desk",
+      "items": [
+        "desks[].name",
+        "desks[].mac",
+        "desks[].idlePollSeconds",
+        "desks[].childLockSwitch",
+        "desks[].memorySwitches",
+        {
+          "key": "desks[].memoryNames",
+          "type": "array",
+          "orderable": false,
+          "buttonText": "Namen hinzufügen",
+          "items": [
+            "desks[].memoryNames[]"
+          ]
+        }
+      ]
+    }
+  ],
+  "customUi": true,
+  "customUiPath": "./homebridge-ui"
+}

package/dist/accessory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One desk as a HomeKit window covering.
+ *
+ * A covering rather than a light, because a desk is a positional actuator that
+ * takes time to get there: `PositionState` says which way it is going and
+ * `HoldPosition` stops it, neither of which a dimmer can express. It also
+ * keeps the desk out of "turn off all the lights", which would otherwise drive
+ * it to its lowest setting at bedtime.
+ */
+import type { PlatformAccessory } from 'homebridge';
+import type { DeskConfig } from './config.ts';
+import type { Transport } from './eliot/desk.ts';
+import type { EliotPlatform } from './platform.ts';
+export declare class EliotAccessory {
+    #private;
+    /**
+     * @param transport Stand-in for the Bluetooth link. Only tests pass one;
+     *   in normal use the accessory builds its own. Without this seam there is
+     *   no way to exercise the accessory without a desk in the room, and the
+     *   handler wiring is exactly the part that needs exercising.
+     */
+    constructor(platform: EliotPlatform, accessory: PlatformAccessory, config: DeskConfig, transport?: Transport);
+    get name(): string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}