[10]entry 10 of 34
Paperclip
this entry is written twice, in full
- 1.in brief
a Homebridge plugin that puts Samsung air conditioners in Apple Home
- 2.in general
Siri, a HomePod and the Home app for a Samsung air conditioner, laid out the way the Samsung app lays it out.
- 3.in particular
One HomeKit tile per Samsung AC, built from the capabilities the unit reports, with the Home app’s separate writes batched into one SmartThings request and an OAuth sign-in that renews itself across two processes.
- 1.in brief
an add-on that lets Apple’s Home app control a Samsung air conditioner
- 2.in general
Siri, a HomePod and the Home app for a Samsung air conditioner, set out the way Samsung’s own app sets it out.
- 3.in particular
Each air conditioner appears as one control built from what that unit can actually do, a burst of changes from the Home app is sent to Samsung as a single message, and it keeps itself signed in to Samsung’s service on its own.
context
Paperclip (homebridge-paperclip) is a Homebridge3 plugin that puts Samsung air conditioners in Apple Home through SmartThings5, so the Home app, Control Center, Siri and a HomePod can run them, with automations and control away from home through a home hub. It was written for and tested on a Samsung AR50H18D1ZHNNA, a 1.5-ton split AC sold in India (SmartThings5 model DA-AC-RAC-01011), and works with any Samsung room AC that SmartThings5 sees. It is TypeScript1 on Node 22, 24 and 26 with one runtime dependency, a settings page inside the Homebridge3 UI and a command-line helper, under the Apache-2.0 licence.
the problem
HomeKit4 and SmartThings5 disagree about what an air conditioner is, and SmartThings5 does not make staying signed in easy. Apple fixes the mode menu at Off, Cool, Auto and Heat, so Samsung’s Dry, fan-only, WindFree, Turbo and Quiet need somewhere a person will find them; the Home app sends power, mode and temperature as separate writes, which a cloud API should not receive as three requests; SmartThings5 reports a change seconds late, so a naive poll snaps the dial back; and personal access tokens created after 30 December 2024 stop working after 24 hours, so the only way to stay connected is OAuth, which needs an app registered in the owner’s own account and a redirect address SmartThings5 will accept, and it refuses localhost.
what i built
- 1.
One tile per AC, ordered the way the Samsung app is: a HeaterCooler with Off, Cool and Auto (Heat only on heat pumps), a Fan inside it with Low to Turbo, an Auto toggle and Oscillate, filter life with a cleaning alert and humidity, and Samsung’s optional modes as switches under the dial, so a room shows one accessory per air conditioner
- 2.
A profile built at discovery from what each unit reports (its modes, fan speeds, swing axes, optional modes and setpoint range, minus the capabilities it marks disabled), so a control appears only when the unit has it; a Fahrenheit unit gets half-degree steps so every setpoint stays reachable
- 3.
Samsung’s modes mapped onto Apple’s fixed menu: Dry shows as Cool with its own toggle and turning it off returns the unit to its previous mode, fan-only is the Fan on while the AC is off, only one optional mode runs at a time and Turbo only while cooling, and a switch the unit would reject flips back, as it greys out in the Samsung app
- 4.
Writes batched: the Home app’s separate power, mode and temperature writes are collected for 250 ms and sent as one SmartThings5 request, power on first and power off last so nothing in the batch turns the unit back on, with a later power write replacing an earlier one
- 5.
A dial that does not snap back: a change shows at once and is held for 12 s against polled values that still say otherwise, then confirmed by a re-read 3 s after the command, and a command that fails reports a communication error to HomeKit4 instead of leaving a wrong value on screen
- 6.
A SmartThings5 client that degrades plainly: a 15 s timeout on every request, a 401 renewed and retried once, Retry-After honoured up to 15 minutes, a 200 response that reports a failed command treated as a failure, and No Response shown only after three refreshes fail in a row
- 7.
OAuth that stays signed in: a private OAuth-In app created through the API from a personal access token that is used once and never stored, asking for three scopes, with the code returned through httpbin.org because SmartThings5 refuses localhost; the access token is renewed ten minutes early in a single flight, and the credential file is re-read before each renewal so a reconnect made in the settings page, a separate process, is picked up without a restart
- 8.
Credentials kept out of config.json in a file of their own, owner-only and written atomically (a temporary file, fsync, rename), because SmartThings5 rotates the refresh token on every renewal and that file holds the only valid copy; a setup wizard in the Homebridge3 UI that needs no terminal, and a CLI with setup, devices, status, doctor and disconnect
outcome
3,117 lines of TypeScript1 in 13 files with one runtime dependency, and 72 tests in Vitest7, run here against main and all passing, covering the capability profile, the HomeKit4 mapping, the accessory’s batching and holds, the OAuth exchange and the parsing of a pasted code, token renewal, the credential file and the SmartThings5 client. CI lints with no warnings allowed, typechecks, tests and builds on Node 22, 24 and 26. Version 0.4.0 installs from GitHub; it has not been published to npm.
A Samsung air conditioner arrives in Apple Home as one tile with only the controls the unit really has, answers Siri and a HomePod, and stays signed in to SmartThings without anyone pasting a fresh token every day.
context
Paperclip is an add-on for Homebridge, a free program that lets Apple’s Home app control devices Apple doesn’t support itself. It brings in Samsung air conditioners through Samsung’s own app and service, so the Home app, the iPhone’s quick controls, Siri and a HomePod can run them, including schedules and control from outside the house through a home hub. It was written for and tested on one particular Samsung split air conditioner sold in India, and works with any Samsung room air conditioner that Samsung’s app can see. It runs on the current versions of Node, needs only one other package to run, has a settings page inside Homebridge and a helper you can type commands into, and is free to use and change under an open licence.
the problem
Apple and Samsung disagree about what an air conditioner is, and Samsung’s service does not make staying connected easy. Apple only allows four modes in its menu (off, cool, auto and heat), so Samsung’s drying, fan-only and special comfort and boost modes need a place where people will find them; the Home app sends power, mode and temperature as three separate changes, which an internet service should not receive as three separate messages; Samsung’s service reports a change a few seconds late, so a careless check snaps the dial back to the old value; and the simple access codes Samsung issues stopped lasting longer than a day at the end of 2024, so the only lasting way to connect is a proper sign-in, which needs an app registered in the owner’s own Samsung account and a return address Samsung will accept, and Samsung will not accept one on the owner’s own computer.
what i built
- 1.
One control per air conditioner, arranged like Samsung’s app: a temperature dial with off, cool and auto (heat only on units that can heat), a fan inside it with low to turbo, an automatic setting and a swing toggle, how much life the filter has left with a reminder to clean it, the humidity, and Samsung’s extra modes as switches under the dial, so each room shows one item per air conditioner.
- 2.
A description of each unit put together when it is first found, from what the unit says it can do (its modes, fan speeds, swing directions, extra modes and temperature range, leaving out anything it says is switched off), so a control only appears if the unit really has it; a unit that works in Fahrenheit gets half-degree steps so every temperature can still be set.
- 3.
Samsung’s modes fitted onto Apple’s fixed menu: drying shows as cooling with its own switch, and turning it off puts the unit back in the mode it was in; fan-only is the fan running while the cooling is off; only one extra mode can run at a time and the turbo boost only while cooling; and a switch the unit would refuse flips straight back, just as Samsung’s app greys it out.
- 4.
Changes sent together: the separate power, mode and temperature changes the Home app makes are gathered for a quarter of a second and sent to Samsung as one message, with power on first and power off last so nothing in the message switches the unit back on, and a later power change replaces an earlier one.
- 5.
A dial that does not jump back: a change shows straight away and is kept for twelve seconds even if Samsung still reports the old value, then checked again three seconds after it was sent, and a change that fails is reported to the Home app as a failure instead of leaving the wrong value showing.
- 6.
A connection to Samsung that fails clearly: every request gives up after fifteen seconds, a rejected sign-in is renewed and tried once more, a request to slow down is respected for as long as Samsung asks (up to fifteen minutes), a reply that says a change failed counts as a failure even when it looks successful, and the control only shows as not responding after three checks in a row have failed.
- 7.
A sign-in that lasts: it registers a private app in the owner’s Samsung account using a short-lived access code that is used once and never kept, asks only for the three permissions it needs, and receives its sign-in code through a public page that just shows its own address, because Samsung will not send it to the owner’s computer; it renews its access ten minutes before it runs out, only once even when several parts ask at the same time, and re-reads its saved sign-in first, so reconnecting in the settings page is noticed without restarting anything.
- 8.
Sign-in details kept out of the main settings file, in a file of their own that only the owner can read, saved in a way that can never leave half a file behind, because Samsung changes the renewal code every time it is used and that file holds the only working copy; a setup page inside Homebridge that needs no typed commands, and a helper that can list units, show their raw status, check the connection and sign out.
outcome
About 3,100 lines of code needing only one other package to run, and 72 automated tests, all passing when run here on the current version, covering the description of each unit, how it maps onto Apple’s controls, the gathering and holding of changes, the sign-in and reading a pasted code, renewing access, the saved sign-in file and the connection to Samsung. Every change is checked automatically for style, types and tests on three versions of Node. It installs straight from GitHub; it has not yet been published to the usual package directory.
A Samsung air conditioner arrives in Apple’s Home app as one control showing only what that unit can really do, answers Siri and a HomePod, and stays signed in to Samsung’s service without anyone having to paste in a new password-like code every day.