@matthall0726/homebridge-oasis-lights
v1.0.1
Published
Homebridge plugin exposing Oasis (heyoasis / Mixtiles Ambient) smart lamps to HomeKit.
Maintainers
Readme
homebridge-oasis-lights
A Homebridge dynamic platform plugin that exposes Oasis smart lamps (the heyoasis app, sold by Mixtiles as "Ambient") to Apple HomeKit.
Each lamp on your account shows up as a HomeKit Lightbulb with:
| HomeKit characteristic | Oasis param | Range |
| --- | --- | --- |
| On | Power | on / off |
| Brightness | Brightness | 0-100 (1:1) |
| Color Temperature | CCT | 2000K-4000K (250-500 mireds) |
Requirements
- Node.js 18 or newer
- Homebridge 1.6.0 or newer
- Your Oasis account email + password (the same credentials you use in the app)
No AWS credentials are needed. Sign-in uses the Cognito SRP flow against the public app client, which is an unauthenticated API.
Install
From the Homebridge UI, search for @matthall0726/homebridge-oasis-lights and
install it.
Or from a shell — a local/dev install straight from the working copy:
sudo npm install -g /Users/matthall/homebridge-oasis-lightsOr, once it is published to npm under the @matthall0726 scope:
sudo npm install -g @matthall0726/homebridge-oasis-lightsConfigure
Add this platform block to your Homebridge config.json (or fill in the form in
the Homebridge UI):
{
"platforms": [
{
"platform": "OasisLights",
"name": "Oasis Lights",
"username": "[email protected]",
"password": "your-oasis-password",
"pollInterval": 60
}
]
}| Option | Required | Default | Notes |
| --- | --- | --- | --- |
| platform | yes | — | Must be OasisLights. |
| username | yes | — | Oasis account email. |
| password | yes | — | Oasis account password. |
| pollInterval | no | 60 | Seconds between cloud refreshes. Minimum 30. |
| nodeIds | no | all | Allow-list of node IDs; omit to expose every lamp. |
Restart Homebridge. Every lamp on the account is discovered automatically, and lamps that later disappear from the account are removed from HomeKit.
Tokens
After the first sign-in, tokens are cached in your Homebridge storage folder as
oasis-tokens.json with file mode 0600. They are refreshed automatically and
a full re-login happens only if the refresh token stops working. Your password
is never written to that file, and neither passwords nor tokens are ever logged.
If you change your Oasis password, just update config.json and restart; a
stale cache is discarded on the next failed refresh.
Two gotchas worth knowing
These are properties of the Oasis cloud and the lamps, not bugs in the plugin.
1. Cloud reads lag writes by 20-30 seconds
The Oasis cloud reports the state a lamp has published, not the state you just requested. For roughly 20-30 seconds after a change, a read still returns the old value.
The plugin works around this by optimistically caching whatever it just wrote and serving that to HomeKit for ~30 seconds, so sliders do not snap back. The side effect: if you change a lamp from the Oasis app (or its physical controls), HomeKit may show slightly stale state until the next poll picks up the published value — up to about half a minute.
2. The heyoasis app can revert cloud writes over Bluetooth
If the heyoasis app is open on your phone and within Bluetooth range of a lamp, it re-asserts the lamp's state directly over BLE, which can undo a change made through the cloud (and therefore through HomeKit). The lamp will appear to snap back to its previous setting a second or two later.
Close the heyoasis app (or walk out of Bluetooth range) when controlling the lamps from HomeKit. There is nothing the plugin can do about this.
Troubleshooting
- "username and password are required" — the platform block is missing credentials; the plugin disables itself rather than crashing Homebridge.
- A lamp shows "No Response" — the Oasis cloud is reporting that node as
disconnected (
status.connectivity.connected: false). Check the lamp's power and Wi-Fi; the plugin recovers on its own once the cloud reports it online. - Sign-in fails with an MFA or new-password challenge — those challenges are not auto-answered. Complete them in the Oasis app first.
- Color temperature won't go warmer/cooler than expected — 2000K-4000K is the lamp's measured range. Values outside it are clamped (e.g. HomeKit's 6500K becomes 4000K).
Development
npm install
npm run build # tsc -> dist/
npm test # build + node --test
npm run watch # tsc --watchThe test suite stubs fetch and mocks amazon-cognito-identity-js, so it
needs no credentials and makes no network calls.
License
MIT
