SpaNet.md

SpaNet API and Client Socket

1. Logging into SpaNet

POST https://api.spanet.net.au/api/MemberLogin

Request:

{
    "login": [Username],
    "api_key": "4a483b9a-8f02-4e46-8bfa-0cf5732dbbd5",
    "password": [Password]
}

Response:

{
    "data": {
        "email": null,
        "id_member": [MemberId],
        "login": [Username],
        "name": null,
        "password": null,
        "notification_enabled": 1,
        "id_session": [SessionId]
    },
    "error": null,
    "error_code": null,
    "message": null,
    "success": true
}

2. Get Client Socket

GET https://api.spanet.net.au/api/membersockets?id_member=[MemberId]&id_session=[SessionId]

Response:

{
    "data": {
        "email": null,
        "id_member": 0,
        "login": null,
        "name": null,
        "password": null,
        "notification_enabled": 0,
        "id_session": null
    },
    "sockets": [{
        "id": [SocketId],
        "active": "1",
        "id_member": [MemberId],
        "id_sockets": [SocketId],
        "mac_addr": [MacAddress],
        "moburl": [WebSocketUrl]:9090,
        "name": [SpaName],
        "spaurl": [WebSocketUrl]:9090,
        "signalStrength": -69,
        "error": false
    }],
    "error": null,
    "error_code": null,
    "message": "",
    "success": true
}

3. Connect Client Socket

Open TCP Socket to [WebUrl] port 9090, then send..

Request:

<connect--[SocketId]--[MemberId]>

Response:

Successfully connected

4. Status

Get the current status of the spa.

Request:

RF\n

Sample Response:

RF:
,R2,18,250,51,70,4,13,50,55,19,6,2020,376,9999,1,0,490,207,34,6000,602,23,20,0,0,0,0,44,35,45,:
,R3,32,1,4,4,4,SW V5 17 05 31,SV3,18480001,20000826,1,0,0,0,0,0,NA,7,0,470,Filtering,4,0,7,7,0,0,:
,R4,NORM,0,0,0,1,0,3547,4,20,4500,7413,567,1686,0,8388608,0,0,5,0,98,0,10084,4,80,100,0,0,4,:
,R5,0,1,0,1,0,0,0,0,0,0,1,0,1,0,376,0,3,4,0,0,0,0,0,1,2,6,:
,R6,1,5,0,2,5,8,1,360,1,0,3584,5120,127,128,5632,5632,2304,1792,0,30,0,0,0,0,2,3,0,:
,R7,2304,0,1,1,1,0,1,0,0,0,253,191,253,240,483,125,77,1,0,0,0,23,200,1,0,1,31,32,35,100,5,:
,R9,F1,255,0,0,0,0,0,0,0,0,0,0,:
,RA,F2,0,0,0,0,0,0,255,0,0,0,0,:
,RB,F3,0,0,0,0,0,0,0,0,0,0,0,:
,RC,0,1,1,0,0,0,0,0,0,2,0,0,1,0,:
,RE,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,-4,13,30,8,5,1,0,0,0,0,0,:*
,RG,1,1,1,1,1,1,1-1-014,1-1-01,1-1-01,0-,0-,0,:*

5. Commands

5.1 Spa

Temperature

Set the target temperature for the spa.

Request:

W40:nnn

Response:

nnn

where nnn denotes temperature in celsius * 10 between 5.0-41.0c (ie: for 35.6c, nnn = 356)

Clean/Santise

Start (or cancel) a Clean cycle.

Request:

W12

Response:

W12

5.2 Pumps

Pump 1

Control Pump 1.

Request:

S22:n

Response:

S22-OK

where n denotes

• 0 - Off
• 1 - On
• 4 - Auto

Pump 2

Control Pump 2.

Request:

S23:n

Response:

S23-OK

where n denotes

• 0 - Off
• 1 - On

Pump 3

Control Pump 3.

Request:

S24:n

Response:

S24-OK

where n denotes

• 0 - Off
• 1 - On

5.3 Blower

Blower

Control the Blower.

Request:

S28:n

Response:

S28-OK

where n denotes

• 0 - Variable
• 1 - Ramp
• 2 - Off

Blower Variable Speed

Set the variable speed of the blower.

Request:

S13:n

Response:

n  S13

where n denotes speed 1-5

5.4 Lights

TODO

5.5 Settings

5.5.1 Operation Mode

Set the Operation mode.

Request:

W66:n

Response:

n

where n denotes

• 0 - Norm
• 1 - Econ
• 2 - Away
• 3 - Week

5.5.2 Filtration

Filtration Runtime

Set the filtration runtime.

Request:

W60:n

Response:

n

where n denotes hours between 1-24.

Time Between Filtration Cycles

Set the time between filtration cycles.

Request:

W90:n

Response:

n

where n denotes hours as

• 1 - 1 hr
• 2 - 2 hr
• 3 - 3 hr
• 4 - 4 hr
• 6 - 6 hr
• 8 - 8 hr
• 12 - 12 hr
• 24 - 24 hr

5.5.3 Sleep Timers

TODO

5.5.4 Power Save

Set the Power Save option.

Request:

W63:n

Response:

n

where n denotes

• 0 - Off
• 1 - Low
• 2 - High

5.5.5 Auto Santise

TODO

5.5.6 Time Out Mode

TODO

5.5.7 Heat Pump Mode

TODO

5.5.8 Set Time/Date

TODO

5.5.9 Support Mode

TODO

5.5.10 Lock Mode

Set the Lock Mode.

Request:

S21:n

Response:

n

where n denotes

• 0 - Off
• 1 - Partial
• 2 - Full

5.5.11 Notification

TODO

I got the first version of the pcbs and the various components I was missing ordered (likely won't receive most things until mid feb though).

In the meantime, if anyone has thoughts on what other types of sensors they might want to connect to their esp for the spa let me know. So far I've only populated the board with a 3.5mm jack and the neccesary electronics to connect a CT clamp for measuring the power consumption of the pool.

@jbergler

I got the first version of the pcbs

Is there anything that you can share at this point?

connect a CT clamp for measuring the power consumption

The controller has inbuilt voltage & amp measurements. Have a look here https://github.com/wayne-love/spanet-api/blob/main/spanet.md, I've forked @BlaT2512's document and am adding to it as I discover stuff. I have a pile of additions (such as power consumption, etc) to add to this but real life is getting in the way. I'll do a pull once it is up to date to merge back to the original.

thoughts on what other types of sensors

I've pH and ORP sensors on my todo list but they are way way way down the list.

real life is getting in the way
Tell me about it :P

This is what the PCB looks like right now. I haven't spent much time thinking about form factor, mounting, and I optimized for parts I already had on hand (especially for the voltage regulators and usb->serial)

I also decided that rather than bother figuring the wemos pin compatibility and dance around the single UART on the 8266 I'd just mount an ESP32-C3-WROOM-02 direct on the board.

Schematics are a bit of a mess still but if you want to see them send me an email (it's in my profile) and I'll share a pdf or something.

Re the onboard current / voltage sensing - I hadn't seen that, seem promising although mine reports some wacky voltage values, eg

"\n,R2,0,313,46,99,1,19,39,32,18,1,2022,368,9999,1,0,261,198,28,6000,3779,291,231,0,0,0,0,12,217,220,197,:\r"

@jbergler Have a look at page 20 of SV-Series-OEM-Install-Manual for calibration process for inbuild voltage & current meters.

https://spanet.com.au/support

That's neat, turns out the SV Mini (which I have) only has voltage sensing. It does it's load shedding by guesswork :P

Wow @jbergler that looks amazing, i was coming on tonight to share my update for code and board i have ordered but its nothing as flash as that one.

Once the board arrives i will test it all works and share a link so you can order them direct from the PCB maker, mine is simply a nodemcu D1 Mini, a voltage regulator from Ali, and a couple of resistors and should fit into a little case from Ali also.

I have completely rewritten my code for the nodemcu now if anyone in interested it includes MQTT connection and a web interface.
You can query and send commands via both WEB Gui and MQTT.

Anyone feel free to make better.

https://github.com/shanekuz/SPANETMCU

@shanekuz keen to give your code a go as I have a nodemcu and a D1 mini here. I probably googled the wrong thing but do you know if I could just cut up a cat5 cable and solder it directly to the D1 mini as don't have a Rj45 breakout board? Edit: seems thats not a good idea due to magnetics and other complexities. Instead I'll grab a breakout board or connector would this work https://nz.rs-online.com/web/p/ethernet-connectors/3316443? Any issue taking power directly from the spa controller? Anything else to note?

@wayne-love

The controller has inbuilt voltage & amp measurements. Have a look here https://github.com/wayne-love/spanet-api/blob/main/spanet.md, I've forked @BlaT2512's document and am adding to it as I discover stuff. I have a pile of additions (such as power consumption, etc) to add to this but real life is getting in the way. I'll do a pull once it is up to date to merge back to the original.

Love your work, thanks for putting in the time to add to this.

I've been using your code sn2ha and it works great, have changed the connection to talk to the Spanet API so I can continue to use the app.

I've ran into an error that keeps coming up after a random amount of time, wondering if you have seen it before?

"
,R2,256,133,45,341,4,20,54,53,26,1,2022,371,9999,1,0,126,416,0,0,118443,2278,2664,0,0,46592,0,12909,74,6685,241,:
,R3,32,1,4,4,4,SW V6 19 11 12,SV3,19503329,20000357,1,0,0,0,0,0,NA,7,0,437,W.CLN,33,0,10,10,0,0,-1,:
,R4,NORM,0,0,0,4,0,946,4,4,34048,403300,834,645,0,0,0,262144,6,5,99,0,0,5,80,50,0,0,5,:
,R5,0,0,0,6,0,0,0,0,0,0,0,1,0,0,366,1,1507,1,1,0,0,0,0,1,2,6,:
,R6,1,5,30,2,5,5,2,380,1,0,3584,5120,127,128,5888,5785,2304,1792,0,30,0,0,1,0,2,3,0,410,:
,R7,2590,0,1,4,1,0,1,24,12,2020,245,126,140,130,485,207,211,1,0,0,0,23,200,1,1,1,31,50,50,100,5,:
,R9,F1,255,2592,3,0,242,9999,190,17,0,255,50044,:
,RA,F2,188,562,3,13,239,9999,61439,19,0,255,300,:
,RB,F3,76782,32,3,65045,140,9999,187,21,0,255,382,:
,RC,0,1,0,1,0,0,0,0,0,2,0,0,0,0,:
,RE,1,10,4,2,1,1,200,200,200,23,18,1,1,0,0,3,1,0,315,0,0,240,0,0,-4,13,30,8,5,-21,:*
,RG,1,1,1,1,1,1,1-1-014,1-1-01,1-1-01,0-,0-,0,0,0,2353,:*

2022-02-25 20:57:36,459 - root - INFO - Successful read
2022-02-25 20:58:41,661 - root - DEBUG - Processsing 0 commands
2022-02-25 20:58:41,662 - root - DEBUG - Requesting status
2022-02-25 20:58:41,662 - connection - DEBUG - Sending RF
2022-02-25 20:58:42,163 - connection - DEBUG - Response - show rssi
set comm idle 300 set wlan linkmon 30
exit

2022-02-25 20:58:42,164 - root - DEBUG - Response - show rssi
set comm idle 300 set wlan linkmon 30
exit

Traceback (most recent call last):
File "sn2ha.py", line 380, in
if spa.sync_status():
File "sn2ha.py", line 146, in sync_status
self.set_temp = int(response[128])/10
IndexError: list index out of range
"

edit

Ok I think I see what's going on, API is injecting these commands, the the bridge doesn't recognise the output and it rejecting it.
Any quick tips how I can add to the code to ignore these input\outputs?

Anyone see their spa controller reporting weird volts? Mine is showing 134v when supply would be 240-250v

@kylev12 - The volt and ammeters can both be calibrated. Instructions are in the OEM manual on the SpaNet website

@kylev12

Ok I think I see what's going on, API is injecting these commands, the the bridge doesn't recognise the output and it rejecting it.
Any quick tips how I can add to the code to ignore these input\outputs?

You are not going to get a perfect fix for this as both the app and my python script are assuming exclusive access to the serial interface.

By removing the serial interface you've bypassed some of the error checking that occurs in my script. As a hack, you could try wrapping lines 127 to 142 in a try / exception block where on exception you return false.

@wayne-love

The volt and ammeters can both be calibrated. Instructions are in the OEM manual on the SpaNet website

Thanks! Weird it wasn't factory calibrated, will have to invest in a multi-meter to get it cal'd correctly .. close enough for now.

I kept your connection code pretty much as is with adjusting blow.

    while not(_connected):
        logger.debug("Connecting to socket")
        try:
            self._socket = socket.socket()
            **self._socket.connect(("xx.xx.xx.xx", 9090))**
            logger.info("Socket connected")
            **self._send("<connect--xxxx--xxxx\n")**
            return True

I'll try your hack, thanks for the tips. I have no coding skills so will be a good task to learn a bit more. Cheers!

@shanekuz keen to give your code a go as I have a nodemcu and a D1 mini here. I probably googled the wrong thing but do you know if I could just cut up a cat5 cable and solder it directly to the D1 mini as don't have a Rj45 breakout board? Edit: seems thats not a good idea due to magnetics and other complexities. Instead I'll grab a breakout board or connector would this work https://nz.rs-online.com/web/p/ethernet-connectors/3316443? Any issue taking power directly from the spa controller? Anything else to note?

Matt-NZ if you PM me and are in NZ i will post you one of my boards as i had 5 printed. You shouldnt run the power from the SPA to the nodemcu no they are not made to run on that voltage.

I have completed and testing my unit now, it took two orders due to an issue with the first but here is the final unit and it works well. for more pictures and code check the link https://github.com/shanekuz/SPANETMCU it includes the gerber files so you can just order on line.

Matt-NZ if you PM me and are in NZ i will post you one of my boards as i had 5 printed. You shouldn't run the power from the SPA to the nodemcu no they are not made to run on that voltage.

@shanekuz that looks very snazzy, very generous of you. I can arrange a courier pickup if thats easier. Will contact you via linkedin.

I have managed to get it all working after a false start, currently powering on battery until my buck converter arrives I posted on wayne-love's page here wayne-love/ESPySpa#1 (reply in thread) might help other noobs.

This is extremely interesting! I have a new Alpine spa here in New Zealand and I do a lot of playing with NodeMCU. I would love to integrate my spa into OpenHAB at my place. @shanekuz you are doing great work! If you have any more of your PCBs, I would gladly take one to accelerate my ability to contribute back to the project.

I can't find a way to PM you @shanekuz - I'm based in Palmerston North and very keen to get involved. My email is [email protected] - please reach out! Thanks.

Sorry for the spam messages - I've been digesting everything I can find on this topic for the last while, and working out how I will proceed. I have another question - is it time for some of these projects to join forces, so that we are not independently developing multiple implementations of the same base code? In my day job as a hand-waving software architect, bringing together distinct teams is what I do, and I feel like there are at least two very similar projects here (belonging to @shanekuz here https://github.com/shanekuz/SPANETMCU and @wayne-love here https://github.com/wayne-love/sn_esp32).

I'm happy to help facilitate however I can, e.g. work on getting started docs, helping to unify and improve code, introducing a central discussion system (discord, GitHub discussions, etc).

@JonathanGiles welcome to the party! Agree, it would be better if we could merge the 2 projects. The only reason that I started deving on the esp32 is that I had one lying around doing nothing. To migrate to something like the NodeMCU would be largely a cut and paste process, with some minor changes along the way. I'm going to be the first to say that my code is not pretty and is in dire need of refactoring.

I'm not a big discord user, but I think it is what all the cool kids are using? I'm happy to set one up, but I'm also not going to be the guy that arrives late and forces my will onto a project. If it'll help I can look into setting it up today. Then we can arrange further what we want to do...

I've taken the liberty of creating a discord here: https://discord.gg/faK8Ag4wHn

I'm happy to grant permissions as appropriate.... And I selfishly want to get help so I can get parts ordered from @shanekuz

@JonathanGiles I ordered 5 PCBs of @shanekuz's design, I can mail you one. Also have the power bucks in stock too if needed. Will join your discord to get an address

Hi Blake, can you please advise how to obtain the API key? I didn't see anything obvious, assume I may need to inspect the traffic.
Not as smart as you guys, so really just thinking of a basic Python script to change the spa into away mode when Solar generation is low.
Just had a massive power bill, after someone (myself) left the temp set way to high during winter...:)
I am now better using the "sleep mode" to avoid heating at night.

Hi This is an embarrassing question but how do you program this into an esp?

I use the arduino application

Excuse my ignorance but I have it but don't really know how to do it as it can only open .ino files and I can't find any.

I use VSS but if you google change from VSS to Arduino its pretty much just a file name change to .ino i think.

ok so you mean i can basically rename master.cpp to .ino?

Yes I think so, give it a go

Hi Tried but it's too hard for me as I get loads of errors all the time.