homebridge-oasis-bridge

Homebridge plugin for Oasis Smart (Dontek) pool controllers. Puts the pump, heater, lights, jets and blower into HomeKit and runs a small local REST API on the hub.

The controller has no local API. The plugin talks to Dontek's AWS cloud the same way the Oasis app does (anonymous Cognito guest credentials, MQTT over WebSockets, Modbus registers as JSON). Protocol and register map from jbyoll/dontek-aquatek-ha (MIT).

Anyone who knows the controller serial can control the pool. Keep it private.

Accessories

• Pool Pump: fan with 4 speeds, plus a Pump Auto switch (returns it to its schedule)
• Pool Heater: thermostat (Off / Heat / Auto, 10 to 40 C in 0.5 steps, follows the spa setpoint while in spa mode)
• Pool Water: temperature sensor
• One lightbulb or switch per assigned socket (Sanitiser, Jet Pump, Blower, Pool Light ...), each with an Auto switch
• Spa Mode switch (opt in, once verified on your unit)

Local API (port 8765)

GET /state, GET /raw, GET /health POST /pump {"mode":"on|off|auto","speed":1..4} POST /heater {"mode":"on|off|auto","setpoint":30,"spaSetpoint":37} POST /socket/2 {"mode":"on|off|auto"} POST /spa {"on":true} Set apiToken in the config to require an X-Token header.

A CSV of water temperature and heater activity is written every poll to oasis-pool-log.csv in the Homebridge storage folder.

0.1.1

• Auto switches are now separate, properly named accessories ("Pool Light Auto") and only for things that run on a schedule: pump, sanitiser, lights, solar, cleaner. Jets and blower are plain on/off.
• Every service carries a ConfiguredName so HomeKit shows real names instead of "Switch 2".
• Config autoSwitches: true (default), false, or a list of type names.
• Fixed the online flag in /state on first connect.

0.1.2

• Tiles now mean: on = run it now, off = back to the controller's schedule (Auto). If the schedule currently has it running, off turns it Off and the plugin returns it to Auto at autoRevertTime (default 23:55) so the next day's timers run. Jets, blower and other unscheduled gear are plain on/off.
• Auto tiles are off by default (autoSwitches: true brings them back).

0.2.0

• Pump manual mode encodes the speed (register 65485 = speed x 256 + 1, mapped live). Setting the fan speed in HomeKit now starts the pump at that speed; Off = 0, Auto = 65535.
• Pool Heat Boost switch: heats now for boostHours (default 4) using the controller's heat demand Run Once (57625 / 57645 / 57665), on while it runs. Off cancels.
• Timer windows for every output are decoded into /state (heater.timers, sockets[].timers) and writable: POST /heater/timers, POST /socket/N/timers, POST /heater/boost, POST /socket/N/runonce.

0.3.0

• Weather aware scheduler (schedule.enabled). Each evening at decideAt it sets tomorrow's pool setpoint from the Open-Meteo forecast for Mount Macedon: forecast max 32+: 30, 28+: 31, 24+: 32.5, below 24: 35, plus 0.5 for a windy or mostly cloudy day. Swim days (Fri to Sun, VIC school holidays, VIC public holidays, or the Swim Day switch) get the full target; other days hold weekdayFloor; rainy days hold the floor. The 6am setpoint adds the expected daytime drop (daytimeDrop, scaled down on hot days), moves at most maxStep per night and never exceeds maxSetpoint.
• Spa nights (Thu and Fri in spaMonths, or the Spa Tonight switch): setpoint spaSetpoint overnight and a boostHours boost ending at spaReadyBy.
• Optional daily sample pump run (schedule.sampleRun, Filter Time 2) so the afternoon water reading is real.
• HomeKit: Pool Swim Day and Pool Spa Tonight switches when the scheduler is on.
• API: GET /log (CSV tail), GET /schedule (state and a dry run of tomorrow), POST /schedule/decide, /schedule/swimday, /schedule/spa.

0.3.1

• Hourly sample runs (schedule.sampleRun.mode: "hourly"): a low speed run every hour through the day so the water temperature is a real reading. Each run ends once the pump has been on for 3 minutes and the reading has settled, or at minutes (default 10). Skipped when the pump is already running; the pump goes back to Auto afterwards, including after a restart.
• CSV log gains a flow_ok column (1 once the pump has been on for 3 minutes); older files are migrated in place.

0.3.2

• HomeKit writes no longer wait on the controller. A write gets 1.5 s (setWaitMs) to complete; after that HomeKit gets an immediate OK and the write finishes in the background, with the next state update correcting the tile if it failed. Stops the "write handler ... was slow to respond" errors on Pool Light and Heat Boost.

0.3.3

• Scheduler times (decideAt, spa boost, sample runs, swim day and holiday dates) are now evaluated in schedule.timezone (default Australia/Melbourne) rather than the host clock; a HOOBS box on UTC was deciding at 9am.
• Missed decision (restart, offline) is caught up on the next tick before midnight.

0.3.4

• waterTemp (HomeKit Pool Water, the thermostat's current temperature, /state) now holds the last reading taken with water moving, so between pump runs it shows the pool rather than the pipe. waterTempRaw is the live probe, waterTempAt the time of the held reading. The held value survives restarts (oasis-last-temp.json). The CSV water_c column stays the raw probe value; use flow_ok to pick real readings.

0.3.5

• Ecowitt pool float (ecowitt.host, ecowitt.channel). The plugin reads the gateway's local /get_livedata_info every minute; while the float is fresh it is the Pool Water reading, the heater's current temperature and waterTemp in /state (waterTempSource: float). Falls back to the pipe probe after staleMinutes.
• With the float in place, hourly sample runs (schedule.sampleRun) are no longer needed; turn them off.

0.3.6

• Reconnect fix: after a failed poll the old cloud connection is fully detached before the new one starts, so its late events can no longer mark the new connection as down. After a reconnect the plugin logs "back online" and pushes every tile to HomeKit again. Pump and socket tiles answer HomeKit reads from live state. Fixes pump and socket tiles showing Not Responding after a reconnect until the bridge was restarted.