Arctic SPA No Cloud API - SPA Boii

Share your Projects!
21

Hi Dave,

That nmap scan is your friend here… The fact that port 65534 is closed (it doesn’t show up in your open ports list) explains exactly why SpaBoii is failing with Connection refused. That is the standard port the controller uses for the local API, so if it’s not listening there, the script has nowhere to connect.

Since you mentioned this is a new Tundra spa and the official app is also giving you errors about firmware versions (specifically the 1.x vs 2.x warning), it sounds like your spa might be in a weird state where the local API server simply isn’t running or has crashed.

Here is what I would recommend trying, in order:

The “Hard” Reboot The remote API interruption you mentioned suggests the controller might be hung or in a partial state.

Flip the GFCI breaker for the spa completely OFF.

Leave it off for at least 30 seconds to fully drain the capacitors on the motherboard.

Flip it back on and wait about 2-3 minutes for it to fully boot.

Run your nmap scan again. If you see port 65534 pop up, SpaBoii should work immediately.

Check the ports If 65534 is still closed after a hard reboot, that port 42131 in your scan is very suspicious. Arctic Spas sometimes moves ports around on newer firmware revisions.

Try changing the port in SpaBoii.py to 42131.

    Edit line: client.connect((spaIP, 65534)) -> client.connect((spaIP, 42131))

It’s a long shot, but sometimes newer “Smart” controllers use dynamic high ports.

The Firmware Issue If the official app can’t connect locally either, this might be a genuine firmware issue on the spa’s Linux controller. The Yoktub: 1.0.43 version you listed is generally compatible, but if the main board thinks it needs 2.x, the local server process might be failing to start on boot.

You mentioned you see “It works!” on port 80. That’s just the Apache/Nginx default page, which confirms the Linux OS connects to WiFi, but it doesn’t mean the actual spa control software (the “Java” part usually) is running correctly.

Let us know if the hard breaker reset brings port 65534 back to life!

Wlater

1 Like
22

Hi Kdem,

That socket.gaierror: [Errno -2] Name or service not known is telling you where the problem is. It basically means the script is trying to look up a hostname (like my-ha-server or mqtt.local) and the container has no idea what that name resolves to.

Here is how to fix it:

1. The “Name or Service” Error
Since you are running this in Docker, DNS resolution can be tricky depending on your network setup. The easiest fix is to stop using hostnames in your settings.yaml and switch to raw IP addresses.

  • Open settings.yaml.
  • Ensure spa_ip and host (for MQTT) are actual numbers like 192.168.1.50, not names like homeassistant.local.

2. Network Configuration
You mentioned adding ports: 1883:1883—you actually don’t want to do that. That setting tells Docker to listen on port 1883 (like a server), but SpaBoii is just a client connecting out to a broker.

Instead, make sure your docker-compose.yaml has this specific line:
network_mode: host

It bypasses the Docker “bridge” network entirely and lets the container use your host machine’s network card directly. This solves two things:

  1. It lets the container find the Spa (which requires local network broadcasting).
  2. It lets the container talk to your remote MQTT broker just like your host machine can.

3. The “Ghost” Containers
SpaBoii definitely doesn’t spawn other containers. If you are seeing entries with random names or things that look like MAC addresses (long hex strings like a1b2c3d4...), those are almost certainly intermediate build images or “dangling” layers created while Docker was building the application from the source code.

It happens when a build fails or updates. You can ignore them, or clean them up by running docker system prune (just be careful as this cleans up unused data for all docker projects).

In Summary:

  1. Edit settings.yaml: Use IPs, not names.
  2. Edit docker-compose.yaml: Add network_mode: host and remove the ports section.
  3. Run sudo docker-compose up -d --build --force-recreate to wipe the slate clean and rebuild.

Let us know if that gets it connecting!

1 Like
23

Thanks for the reply, re:
Edit settings.yaml: Use IPs, not names.
I had 192.168.4.17:1883, I think the port may have messed it up?

Edit docker-compose.yaml: Add network_mode: host and remove the ports section.
I had this and had removed the ports attempt. After each try I removed all the containers and images, and started new container
Run sudo docker-compose up -d --build --force-recreate to wipe the slate clean and rebuild
I did this after removing everything, and it built and connected, however there are three other containers that are built and not running, I have removed them with Portainer.

Thanks for your help
PS, great improvements on the project.

1 Like
24

Just an added note

The app and code has a UDP part for locating the spa on network.
I stopped using it early, as it mostly fails on mine🤣

1 Like
25

Hi all — looking for some help getting SpaBoii working with my Arctic Spa module.

Setup

  • Running SpaBoii in a Docker container on Unraid (--network host), publishing to my MQTT broker (MQTT side is working — I can see the topics in MQTT Explorer).
  • Spa module is on my normal LAN (not IoT VLAN), static IP 192.168.1.241.
  • UniFi shows the device as hostname imx7-var-som (vendor/MAC resolves to Variscite).

What’s working

  • MQTT connectivity is fine (topics publish, including SPABoii-ConnectionStatus).

What’s not working

  • SpaBoii can’t connect to the spa locally. When I run it in the foreground I get repeated:
    • Spa IP: 192.168.1.241
    • An error occurred: [Errno 111] Connection refused. Restarting...

What I’ve checked

  • Confirmed SpaBoii is hardcoded to connect to TCP 65534:
    • client.connect((spaIP, 65534)) in SpaBoii.py (around line 315).
  • From Unraid, a direct TCP test to 192.168.1.241:65534 is Connection refused (same result after breaker power cycle + waiting ~5 minutes).
  • Also tested TCP 42131 (same result: connection refused).

Open ports on the spa module
Since Unraid doesn’t have nmap/python, I ran nmap via a Docker container:

  • docker run --rm --network host instrumentisto/nmap -p- -T4 --min-rate 1000 192.168.1.241

Results (open TCP ports):

  • 22 (ssh)
  • 80 (http)
  • 111 (rpcbind)
  • 515 (printer)
  • 8080 (http-proxy)
  • 12121 (nupaper-ss)
  • 58737 (unknown)

Web pages

  • http://192.168.1.241/ is just the default Lighttpd “It works!” page.
  • http://192.168.1.241:8080/ is a “Software Upgrade and Recovery / Software Update” page (firmware upload UI).

So at this point it looks like my spa module either:

  1. doesn’t expose the local control service on 65534 at all (different firmware/hardware than what SpaBoii expects), or
  2. uses a different protocol/port (maybe one of the other open ports, or UDP).

If anyone has seen this exact imx7-var-som / Variscite module variant, or knows which port/protocol the local control runs on for it, I’d really appreciate a nudge on where to look next.

26

HI all. Just added this to my Docker server, works great! Love that it’s using MQTT. I have a 2009 Arctic Yukon with a new Ecopak. 2 pumps 1 heater. All good. If I could make one suggestion, if possible add an entity for error. I know when all is well the controller doesn’t return any data, maybe that’s a problem, but I think we’d all like to know about FLO and high limit errors.

27

Hi Jay,

First off, huge props for that detailed troubleshooting report.

You are 100% correct that your spa is not listening on the standard port 65534. The Connection refused error combined with your scan confirms the door is shut there.

However, your scan did pick up Port 58737 as open.

Question: Have you already tried pointing the script to that port (58737) to see what happens?

If not, it is definitely the first thing to try. You can edit SpaBoii.py:

change this line
client.connect((spaIP, 65534))

to
client.connect((spaIP, 58737))

The “Custom Dev” Warning: If you change the port and it connects instantly—great!

However, if it connects but crashes immediately, shows garbage data, or still refuses the connection, then we are looking at a bigger issue. On these newer imx7 modules, Arctic Spas might have not just moved the port, but changed the communication protocol entirely.

If that happens, changing the port won’t be enough. Someone will need to do custom development to support this new board.

Let us know if the port swap works!

28

Hi Steve,

That is great news! It’s really valuable to know this is running smoothly.

Regarding the Error Sensor (FLO, HL, etc.): That is absolutely high on the wishlist.

The challenge we face is exactly what you guessed: because the protocol is reverse-engineered, we can only identify the “Error” bytes when they actually appear. When the tub is working fine, those specific bytes are likely just zeros, indistinguishable from empty padding.

Here is how you can help us add it: If your tub ever throws a code (like FLO or HL), and you can grab the log output from the container while that error is active on the topside display, please post it here!

We are looking for the Information or Live packet. If we can capture a “sick” packet and compare it to a “healthy” one, identifying the specific byte that flags the error is usually pretty straightforward. Once we have that, mapping it to a text sensor in Home Assistant is easy.

Until then, enjoy the new setup!

29

Hey everyone,

Forums like this are naturally biased toward troubleshooting—people usually only post when something breaks or they hit a wall.

I’m curious to know how many “silent” users are out there where the integration is just humming along perfectly?

If you are running SpaBoii successfully, drop a quick reply with your stats. It would be really helpful to build a list of “Verified Working” hardware for future users.

Format:

  • Spa Model: (e.g., Summit, Yukon, Klondiker)
  • Year:
  • Controller: (e.g., EcoPack, Global, Custom)
  • Setup: (Docker or Python venv)

Cheers!

2 Likes
30

I’m having the same issue as @jayw on a new Yukon. I tried the add’l port he identified (58737) and still get connection refused… :cry:

The remote API’s are working but would have preferred a local connection. I’ll keep monitoring this thread to see if anyone finds a way to make it work.

Thanks for putting this together

31

Thanks for all of the information.

Unfortunately, switching the port did not work but it was worth a try. I am also on a new 2025 Yukon so we’ll likely see this not work for the newer models.

Appreciate all the effort you’ve put in regardless.

32

Is the official Arctic spa direct connect app still working?

If not, then they have probably removed local control