# Howto use Balboa Worldwide App (APP) with local spa control **URL:** \ **Category:** Devices\ **Tags:** homey-pro\ **Created:** [March 29, 2024, 4:35pm UTC](https://community.homey.app/t/howto-use-balboa-worldwide-app-app-with-local-spa-control/107326 "2024-03-29T16:35:05Z")\ **Posts on this page:** 5\ **Page:** 1
**Author:** ![OH2TH](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/oh2th/32/111414_2.png) [@OH2TH](https://community.homey.app/u/OH2TH)\ **Post date:** [March 29, 2024, 4:35pm UTC](https://community.homey.app/t/howto-use-balboa-worldwide-app-app-with-local-spa-control/107326/1 "2024-03-29T16:35:05Z")
While the [[APP][Pro] Balboa](https://community.homey.app/t/57870) handles very well the cloud based ControlMySpa (CMS) and Balboa BWA cloud connected devices. I do prefer local connectivity and control of devices. For quite some time I have had CMS for automating the spa heating and other routines. But lately Balboa has been making changes on their API and of course the community app will break. In addition the CMS service has been occasionally unreliable. So, I bought a BWA Wifi adapter also and plugged it in the spa. The spa has a RS-485 bus which allows nicely multiple controllers on it. Now the normal control panel, CMS and BWA are happily controlling the spa. BWA has local TCP port open and there is a Ruby app that can bridge the device to MQTT with Homie Convention compliant topic structure. [GitHub - ccutrer/balboa\_worldwide\_app: Ruby library for communication with Balboa Water Group's WiFi module or RS-485](https://github.com/ccutrer/balboa_worldwide_app) First I tried to use [https://homey.app/a/nl.hdg.mqtt](https://homey.app/a/nl.hdg.mqtt) and it’s Homie Discovery device, but that has it’s limitations on device capabilities as it allows only the standard Homey capabilities. # Here is how I set it up ## Install Balboa Worldwide App gem First install Balboa Worldwide App gem as described [MQTT/Homie Bridge](https://github.com/ccutrer/balboa_worldwide_app?tab=readme-ov-file#mqtthomie-bridge) on a spare Raspberry Pi ```auto > sudo apt install ruby > sudo apt install ruby-dev > sudo gem install balboa_worldwide_app > sudo curl https://github.com/ccutrer/balboa_worldwide_app/raw/main/contrib/bwa_mqtt_bridge.service -L -o /etc/systemd/system/bwa_mqtt_bridge.service ``` Modify the `/etc/systemd/system/bwa_mqtt_bridge.service` fot the MQTT server and the target BWA device: ```auto [Unit] Description=Balboa Spa MQTT Bridge [Service] ExecStart=/usr/local/bin/bwa_mqtt_bridge mqtt://localhost/ tcp://bwa_spa_hostname_or_ip:4257/ Environment="LOG_LEVEL=WARN" "LOG_VERBOSITY=0" Restart=always RestartSec=3s Type=notify NotifyAccess=main WatchdogSec=60 [Install] WantedBy=multi-user.target ``` In the above the mosquito mqtt server happens to run already on the localhost, you will need to allow anonymous connections from localhost. Replace `bwa_spa_hostname_or_ip` with your spa’s hostname or IP-address. Used fixed IP for the bwa wifi adapter. There is also a `user=cody` in the file for the service’s run as user, remove that. Finally enable and start the bridge service: ```auto > sudo systemctl enable bwa_mqtt_bridge > sudo systemctl start bwa_mqtt_bridge ``` ## Configure a new advanced virtual device with Device Capabilities Configure [[APP][Pro] Device Capabilities - Enhance the capabilities of devices](https://community.homey.app/t/43287) to add an advanced virtual device for the various capabilities published by the BWA Bridge to MQTT: ![Screenshot 2024-03-29 at 19.21.34](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/f/c/fcccd0499cfe56c87af62a35bf608846dccd0c1c.png) I mapped the `homie/bwa/spa/` topics as Virtual Device capabilities: | Topic | Data type | Settable | Format | Device Capability Type | Show as Capability | Name | | --- | --- | --- | --- | --- | --- | --- | | heating-mode | enum | x | ready,rest,ready\_in\_rest | Button | On/Off (Button tab) | Heating Ready Mode | | heating | boolean | | true,false | Button | On/Off (Button tab) | Heating | | temperature-range | enum | x | high,low | Button | On/Off (Button tab) | High Range | | current-temperature | float | | 0 - 42 | Numberfield | Temperature (Measure) | Temperature | | target-temperature | float | x | 10 - 40 | Numberfield | Temperature (Target) | Target Temperature | | circulation-pump | boolean | | true,false | Button | On/Off (Button tab) | Circulation | | pump1 | boolean | x | true,false | Button | On/Off (Button tab) | Pump 1 | | pump2 | boolean | x | true,false | Button | On/Off (Button tab) | Pump 2 | | pump3 | boolean | x | true,false | Button | On/Off (Button tab) | Pump 3 | | light1 | boolean | x | true,false | Button | On/Off (Button tab) | Light | For the buttons that have unsettable topics, use also the `Non-Clickable` option. ## Using MQTT Client to connect the topics the the device capabilities To talk with the MQTT server you will need the [MQTT Client | Homey](https://homey.app/a/nl.scanno.mqtt) app configured for your environment. Then using advanced flows setup a number of topic triggers and actions from the device capabilities. ### Read-only status information The state of heating and the circulation pump are read only values, so no need to catch a trigger. Don’t forget to set those as `Non-Clickable` in the AVD. ![Screenshot 2024-03-29 at 19.58.44](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/4/6/46f4cb3e22b84473173e058bad1dce9b51986855.png) ### Water temperature I have a ESP32 with DS1820 sensor to measure the exact water temperature and report it a bit more often than CMS nor BWA will do. CMS reports at 1 degree resolution and BWA 0.5 degrees. So I have a special flow to update information from that. ![Screenshot 2024-03-29 at 19.54.10](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/3/a/3aff4ea8439a3e2e0874e1f184da4a1cdc213383.png) ### Target temperature Values from BWA to AVD ![Screenshot 2024-03-29 at 20.00.46](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/8/9/89ddce99a025f2a27f81713e6423a8ebec8c6e6b.png) Values from AVD to BWA ![Screenshot 2024-03-29 at 20.01.48](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/b/e/be386c645ca331045807bc3f5214ddd2727913c8.png) ### Heating mode and Temperature Range Values from BWA to AVD ![Screenshot 2024-03-29 at 20.02.48](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/4/4/44dda73b1129b601805f3455f938af34ddfd1367.jpeg) Values from AVD to BWA ![Screenshot 2024-03-29 at 20.04.05](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/a/1/a144a634ebd9df1641ff2ecf571edd68b9766059.jpeg) ### Pumps 1 - 3 Number of pump controls varies on your spa, mine has three some may have less. Values from BWA to AVD ![Screenshot 2024-03-29 at 20.05.40](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/e/f/ef0089ae21cd67bc05b093797d806af25b496adf.png) Values from AVD to BWA ![Screenshot 2024-03-29 at 20.06.11](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/f/4/f4010f34b56d7946eb260c521ce98950157ed1ef.png) Repeat for the number of pumps you have. ### Light Values from BWA to AVD ![Screenshot 2024-03-29 at 20.07.56](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/b/3/b39076226dc41016d5d8de1e084f4fbbe1c31e5a.png) Values from AVD to BWA ![Screenshot 2024-03-29 at 20.07.27](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/5/6/5675a171de838d565a67e8068728d6a65e4c8d2b.png) ---
**Author:** ![OH2TH](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/oh2th/32/111414_2.png) [@OH2TH](https://community.homey.app/u/OH2TH)\ **Post date:** [March 30, 2024, 4:58am UTC](https://community.homey.app/t/howto-use-balboa-worldwide-app-app-with-local-spa-control/107326/2 "2024-03-30T04:58:50Z")
# Some Thoughts ## Booleans Handling in Homey For some really strange reason, Athom has decided that `true` or `false` value is presented as special `✓` or `⨯` characters with value is transformed to a text value. That is the reason you can’t use the boolean value from the `When Capability is changed` trigger card but have to use a logic card to decide of a true or false string is sent to the MQTT topic. Even a simple logic comparison has to be done as a string comparison with Better Logic Library! ## Avoiding Bouncing - Setup Debounce When a MQTT topic is received, there should be check to see, if the value is already set on the related AVD capability. This would stop unnecessary update from AVD to MQTT. For example: ![Screenshot 2024-03-30 at 7.54.13](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/6/6/664f8dcc21f31a76f4bf933120169d27ce4eafe2.jpeg) ---
**Author:** ![jozefnad](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/jozefnad/32/79469_2.png) [@jozefnad](https://community.homey.app/u/jozefnad)\ **Post date:** [September 20, 2024, 6:31am UTC](https://community.homey.app/t/howto-use-balboa-worldwide-app-app-with-local-spa-control/107326/3 "2024-09-20T06:31:39Z")
Hi, I am developing a custom web interface and wifi module. I have all working but I saw that with ControlMySpa there is option to change colour of leds. As I can see that you have this CMS device, can you please check the buffer for changing these colours when the API call is made? ---
**Author:** ![OH2TH](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/oh2th/32/111414_2.png) [@OH2TH](https://community.homey.app/u/OH2TH)\ **Post date:** [September 20, 2024, 6:55am UTC](https://community.homey.app/t/howto-use-balboa-worldwide-app-app-with-local-spa-control/107326/4 "2024-09-20T06:55:49Z")
Yes, I have CMS also, but this topic is about using BWA and local API. I am not aware of controlling the color of leds by CMS nor BWA. ---
**Author:** ![Maarten\_Kok](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/maarten_kok/32/113290_2.png) [@Maarten\_Kok](https://community.homey.app/u/Maarten_Kok)\ **Post date:** [April 13, 2025, 7:49pm UTC](https://community.homey.app/t/howto-use-balboa-worldwide-app-app-with-local-spa-control/107326/5 "2025-04-13T19:49:50Z")
this is what i am trying to achieve last weekend but not succesfull unfortunately: I’ve been trying to integrate my Balboa spa (with the BWA™ WiFi module) into my smart home setup so I can automate heating based on solar energy. The idea is to heat the water during sunny moments and lower the temperature at night when I’m not using the spa. I use a Homey, but unfortunately, the Balboa Homey app isn’t stable for me — it loses connection often and requires me to log in again each time. ### What I’ve tried: - The spa’s WiFi module is working and reachable at IP `192.168.2.65` - I run Mosquitto MQTT broker on a Raspberry Pi (`192.168.2.43`) — it connects fine via MQTT Explorer - I use a Python script (`balboa_mqtt_v2.py`) to send discovery/status packets over UDP port `4257` - Using `tcpdump`, I’ve confirmed that the UDP packets are sent correctly to the spa - Unfortunately, the spa never responds to these packets — even when the BWA mobile app is completely closed ### What I suspect: - The WiFi module might only allow one active client (the BWA app) - Or it blocks non-official communication (e.g., by filtering MAC addresses or through firmware restrictions)