homebridge-samsung-rac 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# homebridge-samsung-rac
+
+Control a Samsung room air conditioner from HomeKit over its **local network API**
+(`https://<ip>:8888`, mutual TLS) instead of the SmartThings cloud.
+
+The local API is richer than the cloud one. Most importantly it exposes the vane
+position — `Wind.direction` — which the SmartThings API does not expose at all,
+and which is the reason this plugin exists.
+
+Developed against a **TP6X_RAC_16K** (SmartThings vendor id `DA-AC-RAC-100001`).
+Other units of the same generation should work; older port-2878 models will not.
+
+## What it exposes
+
+A single `HeaterCooler` accessory per unit:
+
+| HomeKit | Comes from |
+|---|---|
+| On / off | `Operation.power` |
+| Current temperature | `Temperatures[0].current` |
+| Target temperature | `Temperatures[0].desired`, with the range the unit reports |
+| Mode | `Mode.modes`, limited to the modes the unit says it supports |
+| Fan speed | `Wind.speedLevel` / `Wind.maxSpeedLevel` |
+| Swing | `Wind.direction` |
+| Filter indicator | the `FilterAlarm` entry in `Alarms` |
+
+Dry and fan-only modes have no HomeKit equivalent. The plugin reports them as
+Auto/Idle and leaves them alone rather than overwriting a mode you chose in the
+Samsung app.
+
+A service only appears once the unit has actually published a reading for it, and
+is never withdrawn afterwards — some units publish nothing until they are running.
+
+## Setup
+
+1. Install the plugin and open its settings in the Homebridge UI.
+2. **Fetch the certificate.** The local API requires a client certificate that
+   bundles a private key. It is not shipped with this plugin: it is downloaded
+   once and stored next to your Homebridge config, on your machine only.
+3. **Add your air conditioner's IP address** and save. Give it a fixed DHCP lease
+   on your router — the plugin cannot follow a unit that moves. You can add
+   several units.
+4. **Pair.** This is the awkward part, and the order matters:
+   - power the air conditioner **off**
+   - press *Start pairing*
+   - power it back **on** when the UI asks
+
+   The unit does not hand out a token on request. It calls back to Homebridge on
+   port 8889 the moment it powers on, and that callback carries the token.
+
+The token is stored alongside the certificate, outside `config.json`.
+
+### If pairing never completes
+
+The air conditioner connects back to whatever address asked it for a token, so
+the callback has to be able to reach Homebridge:
+
+- **Homebridge in Docker without host networking** — the callback cannot arrive.
+  Pair from the host with the probe CLI below and paste the token into the
+  *Paste token* box:
+
+  ```bash
+  npx homebridge-samsung-rac-probe pair --host 10.0.0.9
+  ```
+- **A firewall on the Homebridge machine** — allow inbound TCP on port 8889.
+- **A listener left over from an earlier attempt** — it keeps the port and the
+  next run fails in a way that looks identical to the unit never calling back.
+
+## Probe CLI
+
+A command-line driver over the plugin's own transport code, for setting a unit up
+without the UI and for working out what a misbehaving one is doing.
+
+```bash
+npx homebridge-samsung-rac-probe cert                   # download the certificate
+npx homebridge-samsung-rac-probe pair   --host 10.0.0.9 # run the pairing ritual
+npx homebridge-samsung-rac-probe dump   --host 10.0.0.9 # print the device state
+npx homebridge-samsung-rac-probe writes --host 10.0.0.9 --power-on
+```
+
+It ships with the plugin, so it works from an ordinary install. From a checkout,
+`npm run probe -- dump --host 10.0.0.9` runs the same thing through ts-node.
+
+Progress goes to stderr and the payload to stdout, so either can be redirected
+without the running commentary landing in the file:
+
+```bash
+npx homebridge-samsung-rac-probe dump --host 10.0.0.9 > unit.json
+npx homebridge-samsung-rac-probe writes --host 10.0.0.9 --power-on > report.md
+```
+
+`dump` is the first thing to ask for in a bug report about an unfamiliar model:
+it separates a parsing bug from a genuine hardware difference, and its stdout is
+the device's own JSON.
+
+`writes` matters more than it sounds. **This hardware answers HTTP 200 to commands
+it silently discards.** The probe writes a value, reads it back, and counts only a
+*changed read-back* as success. It restores everything it touched and leaves a
+report, printed to stdout (`--out <path>` saves it to a file instead). The
+findings for the reference unit are summarised below.
+
+Always pass `--power-on`. On the reference unit **every write except power is
+silently discarded while it is off** — 200, no error, no effect — so a run without
+it says nothing about whether a field is writable.
+
+The plugin applies the same rule at runtime: every write is confirmed by a
+read-back, and a value the unit quietly refuses is corrected in the Home app
+rather than left showing something that never happened.
+
+### What the reference unit accepts
+
+Measured on a TP6X_RAC_16K, 2026-09-15:
+
+| | |
+|---|---|
+| Method | `PUT` only — `POST` returns 405 |
+| Power, fan speed, setpoint, mode | all applied |
+| Vane | `Fix` and `Up_And_Low` applied; `Vertical` and `SwingUD` rejected with 400; `All` accepted and then ignored |
+
+Consequence worth knowing: **changing anything in the Home app while the unit is
+off does nothing**, and the tile will snap back after a second. Turn it on first.
+That is the hardware's behaviour, not the plugin's — the plugin reports it
+honestly rather than pretending the change stuck.
+
+## Configuration
+
+Everything is editable in the Homebridge UI. The equivalent `config.json`:
+
+```json
+{
+  "platform": "SamsungRacLocal",
+  "devices": [
+    { "name": "Lounge", "host": "10.0.0.9" }
+  ],
+  "updateInterval": 10,
+  "swingDirection": "Up_And_Low"
+}
+```
+
+| Key | Default | |
+|---|---|---|
+| `devices[].host` | — | The unit's IP address. Required. |
+| `devices[].name` | the unit's own name | Shown in the Home app. |
+| `devices[].token` | — | Only if you paired outside this plugin. |
+| `updateInterval` | `10` | Seconds between polls; minimum 5. |
+| `swingDirection` | `Up_And_Low` | What to set the vane to for "swing on". Units differ; the log says if yours ignores it. |
+| `requestTimeout` | `5` | Seconds. |
+| `certificateUrl` | community URL | Only if you mirror the certificate yourself. |
+
+## Security notes
+
+- The client certificate contains a private key and is **not** in this
+  repository. It is fetched at setup time and written `0600` under your
+  Homebridge storage path.
+- Device tokens grant full local control of the air conditioner. They are stored
+  `0600` in the same directory, not in `config.json`.
+- The connection to the unit uses TLS 1.0 with OpenSSL security level 0, because
+  that is all its firmware speaks. It never leaves your network.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run lint
+npm run build
+npm run watch    # rebuild and restart Homebridge on change
+```
+
+Unit tests never touch the network: `nock` is locked down and `fetch` is replaced
+outright. The fixture in `tests/fixtures/devices.json` is a real capture from the
+reference unit.

package/config.schema.json

@@ -0,0 +1,85 @@
+{
+  "pluginAlias": "SamsungRacLocal",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "headerDisplay": "Controls a Samsung room air conditioner over its local network API. Add each unit's IP address below, then pair it from the card above — pairing needs the unit powered off and back on, so it cannot be done from this form alone.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "devices": {
+        "title": "Air conditioners",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "description": "Shown in the Home app. Leave empty to use the name the unit reports."
+            },
+            "host": {
+              "title": "IP address",
+              "type": "string",
+              "required": true,
+              "format": "ipv4",
+              "description": "The unit's address on your network. Give it a fixed DHCP lease on your router — the plugin cannot follow it if it moves."
+            },
+            "token": {
+              "title": "Device token (optional)",
+              "type": "string",
+              "description": "Only needed if you paired outside this plugin. Leave empty and use Pair above; tokens paired there are stored outside config.json."
+            }
+          }
+        }
+      },
+      "updateInterval": {
+        "title": "Status poll interval (seconds)",
+        "type": "integer",
+        "default": 10,
+        "minimum": 5,
+        "description": "How often to read the unit. This is a local network request, so it can be frequent."
+      },
+      "swingDirection": {
+        "title": "Swing direction",
+        "type": "string",
+        "default": "Up_And_Low",
+        "oneOf": [
+          { "title": "Up and down (confirmed working)", "enum": ["Up_And_Low"] },
+          { "title": "All directions", "enum": ["All"] },
+          { "title": "Vertical", "enum": ["Vertical"] },
+          { "title": "Swing up/down", "enum": ["SwingUD"] }
+        ],
+        "description": "What to set the vane to when swing is switched on in HomeKit. On a TP6X_RAC_16K only Up_And_Low works: Vertical and SwingUD are rejected outright, and All is accepted and then ignored. The others are kept for units that differ; the log says if yours refuses the one you pick."
+      },
+      "requestTimeout": {
+        "title": "Request timeout (seconds)",
+        "type": "integer",
+        "default": 5,
+        "minimum": 1
+      },
+      "certificateUrl": {
+        "title": "Client certificate URL",
+        "type": "string",
+        "description": "Advanced. Where to download the Samsung client certificate from. Change this only if you mirror it yourself."
+      }
+    }
+  },
+  "layout": [
+    {
+      "key": "devices",
+      "type": "array",
+      "buttonText": "Add an air conditioner",
+      "items": ["devices[].name", "devices[].host", "devices[].token"]
+    },
+    "updateInterval",
+    "swingDirection",
+    {
+      "type": "fieldset",
+      "title": "Advanced",
+      "expandable": true,
+      "expanded": false,
+      "items": ["requestTimeout", "certificateUrl"]
+    }
+  ]
+}

package/dist/cli/probe.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Command-line driver over the plugin's own transport modules.
+ *
+ * It answered the question this plugin was built around — does the hardware
+ * apply writes, or accept and discard them the way the SmartThings cloud does? —
+ * and stays as the tool to reach for when the plugin meets real hardware:
+ *
+ * - `dump` tells a parsing bug apart from a hardware difference when someone
+ *   reports a model that behaves unlike the reference unit;
+ * - `writes` establishes what a different model accepts, which matters because
+ *   the accepted values ARE model-specific (this unit rejects `Vertical`
+ *   outright while accepting `Up_And_Low`);
+ * - `pair` is the way through when Homebridge runs in a container that the air
+ *   conditioner's callback cannot reach.
+ *
+ * Shipped as a bin, so it is reachable from an ordinary install rather than only
+ * from a checkout:
+ *
+ *   npx homebridge-samsung-rac-probe dump --host 172.24.0.125
+ *
+ * From a checkout, `npm run probe -- dump --host ...` runs it through ts-node.
+ */
+export {};