Howto use Balboa Worldwide App (APP) with local spa control

While the [APP][Pro] Balboa 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

First I tried to use MQTT Hub App for Homey | Homey 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 on a spare Raspberry Pi

> sudo apt install ruby
> sudo apt install ruby-dev
> sudo gem install balboa_worldwide_app
> sudo curl -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:

Description=Balboa Spa MQTT Bridge

ExecStart=/usr/local/bin/bwa_mqtt_bridge mqtt://localhost/ tcp://bwa_spa_hostname_or_ip:4257/


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:

> 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 to add an advanced virtual device for the various capabilities published by the BWA Bridge to MQTT:

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 App for Homey | Homey 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.

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.

Target temperature

Values from BWA to AVD

Values from AVD to BWA

Heating mode and Temperature Range

Values from BWA to AVD

Values from AVD to BWA

Pumps 1 - 3

Number of pump controls varies on your spa, mine has three some may have less.

Values from BWA to AVD

Values from AVD to BWA

Repeat for the number of pumps you have.


Values from BWA to AVD

Values from AVD to BWA


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: