homebridge-samsung-aircon

⚠️ Personal-use plugin. This is reverse-engineered against one specific Samsung combo system (FAC_BORA_17K Stand + FAC_BORA_RAC_17K Room) in the author's own home, over the unit's local HTTP API. Other Samsung aircon models, other firmware revisions, or other regions may not match the wire shape the code assumes. There are no guarantees, no general-purpose driver claim, and no support channel — fork it, adapt it for your unit, or skip it. The reverse-engineering notes in docs/ are the only thing that travels well.

Homebridge plugin that exposes Samsung air conditioners (local HTTP API) to Apple Home (HomeKit).

Overview

A Homebridge dynamic platform plugin that wraps the Samsung aircon local HTTP API and surfaces it as HomeKit accessories. Targets one personal home-server deployment — single-controller (Apple Home) environment, single combo system, single firmware build.

Supported hardware

• Stand (FAC_BORA_17K) — verified with live PUT probes and the full sweep documented in docs/lessons.md. Surfaces as two HomeKit accessories (see ADR-0008): a primary aircon accessory with Thermostat + Fanv2 + optional Blooming vent switches, plus a separate purifier accessory with AirPurifier + AirQualitySensor.
• Room (FAC_BORA_RAC_17K prefix) — discovered and read-verified as the auxiliary indoor unit of the same combo system. Single Thermostat + Fanv2 accessory (no Sensors[], no purifier accessory, no Blooming on this hardware).
• Anything else — untested. Don't expect it to work.

Requirements

• Node.js 18.17 LTS or newer
• Homebridge 1.8+ (or 2.0 beta)
• Samsung aircon reachable on the local network via its HTTP API. Transport-layer setup (TLS / mTLS / cert-proxy) is environment-specific and out of scope here; the plugin speaks plain HTTP to whichever URL you configure.

Install

npm install
npm run build

Then add the plugin to your Homebridge config — the Homebridge UI consumes config.schema.json so the form is rendered automatically. The only required field is baseUrl (the Samsung HTTP API base); per-aircon overrides are optional metadata keyed by manufacturer serial number (see ADR-0003 / ADR-0004).

Development

npm run watch       # homebridge -D with auto-rebuild
npm run build       # tsc → dist/
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run fmt         # biome check --write
npm run fmt:check   # biome check (verify only)

Git hooks are wired via husky (activated on npm install):

• pre-commit — fmt:check + typecheck
• pre-merge-commit — build + test
• pre-push — full chain (fmt:check + typecheck + build + test)

Documentation

• CONTEXT.md — domain vocabulary, state synchronisation, discovery model
• docs/adr/0001..0007 — architectural decisions (composite accessory, ModeComposition, serial-number identity, discovery-first, optimistic writes, option presets, Room uuid fallback)
• docs/samsung-aircon-api.md — Samsung HTTP API endpoints, PUT semantics, danger tokens
• docs/samples/device-status.json — verbatim Stand-aircon response sample
• docs/lessons.md — option-write reverse-engineering lessons (cycle triggers, lock tokens)

License

MIT — see LICENSE.