Balboa Spa Control Protocol

gistfile1.md

I've graduate from a gist to a full repo. See https://github.com/ccutrer/balboa_worldwide_app, especially https://github.com/ccutrer/balboa_worldwide_app/blob/master/doc/protocol.md

+1 watching this topic...have Wi-Fi balboa spa controller....much home automation...just no way of tying the hot tub into the home system...

Hey guy! A Perfect Solution!! Worked like a charm and i translated it to php. I have just one question perhaps you know and would be great! If i want to toggle pump3 i dont know which hex to use for it. I tryed 0600 and 95 CB as Logical sequence but that is not working.

Found the crc:

python2.7 ./pycrc.py --width 8 --poly 0x07 --reflect-in false --reflect-out false --xor-out 0x02 --xor-in 0x02 --algo=bbb --generate=c -o crc.c

Output from reveng:
width=8 poly=0x07 init=0x02 refin=false refout=false xorout=0x02 check=0x04 residue=0x0e name=(none)

The data for the CRC is the full message, including the length param, without the header/footer 0x7e.

python2.7 ./pycrc.py --width 8 --poly 0x07 --reflect-in false --reflect-out false --xor-out 0x02 --xor-in 0x02 --check-hexstring=1DFFAF13000064070700000100000400000000000000000064000000
0xc2

Which matches: 7E1DFFAF13000064070700000100000400000000000000000064000000C27E

If you use pycrc with the parameters I gave above, it will generate C code that correctly computes the checksum. (I have one of these too, and am writing home automation code that talks to one. https://sourceforge.net/p/gnhast/

Your page was incredibly helpful in getting me going. Thanks!

What can you tell me about your spa? I'm trying to figure out the config response. Mine has 2 pumps, no circ pump, no blower. Config type 4. The first 3 (seem to be the significant ones) of the config response are 02 14 80
Yours appeared to be 02 02 80

Mine is a BP2000G1 with a TP800 Display.

Oh awesome! I didn't even notice your message, just happened to be searching through my gists for something else.

I have a Bullfrog A7L. Two two-speed pumps, separate circ pump, and lights. The wifi module and everything all came pre-installed.

ok, my main controller is a BFBP20 (looks like a Bullfrog specific model number, but has the Balboa logo on it), and the wifi module is a BWGWIFI1.

I've also graduated my code from the gist to an actual repo, and updated it with the CRC info. Thanks again for that! When I next find some time to work on it, I plan to pretend to be a hot tub and see what other configurations I can guess by feeding different info back to the iOS app.

I own a balboa spa with wifi module.
I would like to monitoring it otherwise than with the ios or android app.
So I found this thread wich is fully interesting, but i am unable to run the ruby application.
May you help me ? I would like to use ubuntu script
How to logon the correct module, mac address ?
Is there a security layer, with SSID and key?
thanks a lot

Hrmm.. is this the best place for me to get ahold of you? I found a bunch more information on mine, and would like you to run some specific commands on yours.

Hey garbled or ccutrer.. is there any chance to contact you :-) i still dont know how to activate for example pump3 or the blower :-( everything else work like a charm

I'm leaving this note here since I used the info from this project to start my own. I have created a proof-of-concept Windows program to communicate with my SPA. If you would be interested in how that project develops, I have a GitHub repository:
https://github.com/MHotchin/BalboaSpaComms
NOTE - just proof of concept right now, but I would like to get it working and usable.

Hey I'm looking into controlling a Balboa spa over the same connection that the wifi module and topside panels connect to. It looks like it is an rs458 connection. I am thinking of connecting it to a raspberry pi and controlling it that way, something similar to this project: https://github.com/sfeakes/AqualinkD I'm trying to figure out the pinout of that port. Has anyone opened up their wifi module or button panel? If anyone has any info on this, I would love to know. Thanks

@GreenZapdos > Hey I'm looking into controlling a Balboa spa over the same connection that the wifi module and topside panels connect to. It looks like it is an rs458 connection. I am thinking of connecting it to a raspberry pi and controlling it that way, something similar to this project: https://github.com/sfeakes/AqualinkD I'm trying to figure out the pinout of that port. Has anyone opened up their wifi module or button panel? If anyone has any info on this, I would love to know. Thanks

Have you been able to analyse a little more how the panels work? I have a VL801D that I have disassembled. Chips are etched. I can start by finding out how to power this baby, then do some serial analyser but if you have more info already, please share with me.

Hey guy! A Perfect Solution!! Worked like a charm and i translated it to php. I have just one question perhaps you know and would be great! If i want to toggle pump3 i dont know which hex to use for it. I tryed 0600 and 95 CB as Logical sequence but that is not working.

Hey swissboy22, can you send me or publish your php success? This would help me a lot. :)

@kgerlich Did you get anywhere with this? I’m about doing the same.

Any sucess ?

Wondering if anything developed on the direct wired connection bypassing the wifi module - any success?

I managed to interface a Pi directly to the controller : you need a RS-485 module and a Micro Fit ATX cable for the connection. My code and research (see README) is here : https://github.com/rsrawley/spaControl. I use Node.js as a backend server. Took me a while to figure it all out, so hopefully this helps someone out !

Thank you @rsrawley. Will look into the details of your project when I have the time.

As I just got my Spa with a Balboa BP2100G0 with a TP600 UI, I'll order the components to build a mqtt bridge with esp8266 + RS485 Transceiver.

Be prepared for me to ask questions ;-)
I'll then link my repo here.

As I just got my Spa with a Balboa BP2100G0 with a TP600 UI, I'll order the components to build a mqtt bridge with esp8266 + RS485 Transceiver.

Be prepared for me to ask questions ;-)
I'll then link my repo here.

Any update on this? I have mine down right now to replace motor, so very interested in getting it added to my Home Assistant.

Yep, working really fine ;-)
https://github.com/cribskip/esp8266_spa

Hey guy! A Perfect Solution!! Worked like a charm and i translated it to php. I have just one question perhaps you know and would be great! If i want to toggle pump3 i dont know which hex to use for it. I tryed 0600 and 95 CB as Logical sequence but that is not working.

Hi swissboy - would you mind sharing your php solution?

This is great. Im having a little trouble understanding the messaging format. My goal is to (using the wifi module) use a macro on my watch to toggle the pumps so I do not have to use my phone. the main control panel on my tub no longer works and I really just need to have a way to turn the pumps on while im in the tub. If someone could give me an example hex string that would tell the pump2 to turn on, that would be great. or is the crc thing critical to that? Thanks in advance.
JB

It's 0x05 for toggle item as described here: https://github.com/ccutrer/balboa_worldwide_app/blob/main/doc/protocol.md#toggle-item You need to wrap this in StartOfFrame and EndOfFrame. CRC is important and your ID needs to be registered. Please see for additional messages https://github.com/cribskip/esp8266_spa/blob/master/src/balboa_helper.ino BearProtocol ***@***.***> schrieb am Mo., 14. Apr. 2025, 14:51:

…

***@***.**** commented on this gist. ------------------------------ This is great. Im having a little trouble understanding the messaging format. My goal is to (using the wifi module) use a macro on my watch to toggle the pumps so I do not have to use my phone. the main control panel on my tub no longer works and I really just need to have a way to turn the pumps on while im in the tub. If someone could give me an example hex string that would tell the pump2 to turn on, that would be great. or is the crc thing critical to that? Thanks in advance. JB — Reply to this email directly, view it on GitHub <https://gist.github.com/ccutrer/ba945ac2ff9508d9e151556b572f2503#gistcomment-5540036> or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK476RDHNSO5WTJWZXMOI32ZOVNNBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDUOJ2WLJDOMFWWLO3UNBZGKYLEL5YGC4TUNFRWS4DBNZ2F6YLDORUXM2LUPGBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVA2DEMZTGU3DQNNHORZGSZ3HMVZKMY3SMVQXIZI> . You are receiving this email because you commented on the thread. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub> .