A HACS-compatible Home Assistant integration for Arctic Spas hot tubs. Supports two connection modes: Direct (local WebSocket, no cloud) and Cloud (dealer portal + AWS IoT MQTT).
| Platform | Entities | Notes |
|---|---|---|
| Climate | Water temperature control | Set target temp; current temp display |
| Binary Sensor | Connected, Problem, Exhaust fan, Economy mode | Problem = any active error code (diagnostic) |
| Sensor | Water temp, setpoint, pH, ORP (chlorine), filter status, heater state, power consumption, error codes | pH & ORP require Spa Boy® |
| Switch | Lights, Filter suspension, Pumps 2–5, Blowers 1–2, SDS, YESS, Fogger | Optional hardware only shown if present |
| Select | Pump 1 speed, SpaBoy CL range | off / low / high |
| Button | Filter boost, SpaBoy boost, Easy Mode | |
| Number | Filter frequency, Filter duration | Schedule configuration |
Optional features (Spa Boy®, SDS, YESS, fogger, blowers, pump 4/5, exhaust) are only exposed when present in your spa's configuration. Easy Mode and Filter Suspension are Cloud-only.
- Home Assistant 2024.1.0 or newer
- HACS installed
- Arctic Spas hot tub running YOC firmware 3.x or newer
- Direct mode: spa reachable on your local network
- Cloud mode: a My Arctic Spa portal account (dealer.myarcticspa.com)
| Feature | Direct | Cloud |
|---|---|---|
| Internet required | No | Yes |
| Update frequency | ~500ms real-time push | Real-time push |
| Power monitoring | Yes | Yes |
| Heater state sensors | Yes | Yes |
| Economy / exhaust sensors | Yes | Yes |
| Easy Mode button | — | Yes |
| Filter suspension | — | Yes |
| SpaBoy pH/ORP | Yes | Yes |
| Filter schedule config | Yes | Yes |
Connects directly to the spa over WebSocket on port 8765. No internet required. ~500ms push updates, power monitoring, and full control with just the spa's local IP address.
If the spa's IP changes (e.g. DHCP reassignment), the integration will automatically find the new IP via the spa's MAC address in the ARP table and persist the change.
Authenticates with the My Arctic Spa dealer portal (dealer.myarcticspa.com) using your email and password, then connects to AWS IoT Core MQTT for real-time telemetry and commands. Unlocks Easy Mode and Filter Suspension controls not available in Direct mode. Your credentials are stored in HA's encrypted config storage. JWT tokens are refreshed automatically.
- In HACS, click the three-dot menu → Custom repositories
- Add
https://github.com/jkol/ha-arctic-spaswith category Integration - Find "Arctic Spas" in the HACS store and install it
- Restart Home Assistant
Copy custom_components/arctic_spas/ into your HA config/custom_components/ directory and restart.
- Go to Settings → Devices & Services → Add Integration
- Search for Arctic Spas
- Choose your connection mode and follow the prompts:
- Direct: enter your spa's local IP address
- Cloud: enter your My Arctic Spa portal email and password (dealer.myarcticspa.com)
If your Cloud account has multiple spas, you'll be prompted to choose one.
A DHCP reservation is recommended for Direct mode so the spa's IP doesn't change between reboots.
The water chemistry sensors work well as gauge cards. Requires Spa Boy®.
type: gauge
entity: sensor.spa_ph_level
name: Spa pH level
min: 6.2
max: 8.8
needle: true
segments:
- from: 6.2
color: "#db4437"
- from: 6.8
color: "#ffa600"
- from: 7.2
color: "#43a047"
- from: 7.8
color: "#ffa600"
- from: 8.2
color: "#db4437"type: gauge
entity: sensor.spa_chlorine_level
name: Spa chlorine level
min: 350
max: 950
needle: true
segments:
- from: 350
color: "#db4437"
- from: 400
color: "#ffa600"
- from: 500
color: "#43a047"
- from: 750
color: "#ffa600"
- from: 900
color: "#db4437"- WebSocket endpoint:
ws://<spa-ip>:8765 - On connect, sends
{"query": 0}to trigger a full state dump; spa then streamsliveat ~500ms - Commands are JSON sent on the same connection (e.g.
{"P1next": 1},{"setTSP": 102}) - Reconnects automatically with exponential backoff (5 s → 10 s → 30 s → 60 s → 120 s)
- A 30 s WebSocket ping keeps the TCP connection alive; if no data is received for 90 s the connection is dropped and reconnected
- Power consumption is
current_adc × 1.87 W(calibrated against an external watt meter)
- Authenticates at
https://dealer-api.myarcticspa.com/api/login→ JWT (RS256, ~1 hr expiry) - Connects to AWS IoT Core MQTT over port 443 using WebSocket transport
- Subscribes to per-spa topics:
live,sett,const,error,connection-status - Commands published to
arcticspa/{dealership_id}/{spa_id}/command - Token refreshed automatically via
/api/refreshbefore expiry; falls back to full re-login if needed
- Confirm the spa's IP address in your router's DHCP client list
- Ensure port 8765 is reachable from your HA host
- Verify the spa is running YOC firmware 3.x — earlier firmware uses a different protocol not supported by this integration
- Check HA logs (Settings → System → Logs) for details
- Use the email and password for the My Arctic Spa dealer portal (
dealer.myarcticspa.com), not the mobile app - To update credentials: Settings → Devices & Services → Arctic Spas → Configure
- Ensure at least one spa is registered to your account in the dealer portal
- Check the Connected binary sensor — if it's off, the spa or network is unreachable
- Direct mode reconnects automatically; Cloud mode re-authenticates and reconnects automatically
- Entities are only created when the spa's
setttopic reports the hardware as present - Spa Boy® is required for pH and ORP sensors
- Easy Mode and Filter Suspension are Cloud-only — they will not appear in Direct mode
- Power and heater state sensors require the spa to report a CT clamp value
- Some commands are blocked by the spa's internal state (e.g. temperature change during overtemperature, certain commands during filter boost)
- Check the Filter Status and Errors sensors for active blocking conditions
Pull requests are welcome. For major changes, please open an issue first.
- Report bugs: GitHub Issues
MIT