Home Assistant: Configuring "Salt Sentry" using MQTT protocol

Background

About a week ago I had never heard of Home Assistant, Salt Sentry, nor MQTT. If you're here, maybe this is true for you too.

Just before that, I replaced a water softener. This reminded me that you also have to add salt to said water softener. I never remember to do this and thought it would be keen if something could tell me when to do so by measuring the physical salt level.

A bit of googling revealed a few home dev style solutions (buy some parts, solder some things) but the most complete of these appeared to be a product called "Salt Sentry"

It works by using a small software development board which contains a VL53L0X sensor which is some magical device that can measure distance with accuracy of 2mm when just pointing it into the ether. 🤷 cool.

To use this, you need to integrate it with something else, there are a few options, but the most popular one seemed to be called "Home Assistant". While I was waiting for the Salt Sentry to arrive, i thought I'd get ahead of things and install Home Assistant.

Home Assistant

Home Assistant (wikipedia) is something one can run on a Raspberry Pi or other similar hardware. I happened to have a few Pi's laying around unused so i thought I'd give it a shot:

"Home Assistant is free and open-source software for home automation designed to be a central control system for smart home devices with a focus on local control and privacy."

I ended up installing this by downloading and using `dd` to image it to an SD card.

 dd if=haos_rpi3-64-9.4.img of=/dev/sdb bs=4M && sync

Plug it in, boot it up, and i highly recommend creating a local DNS record for 'homeassistant.local' as most of the docs use that and may even link to it. Configuring it is outside of the scope of this page but it's pretty simple.

On its own with no config it auto discovered some Devices, which it calls "Integrations" on its own:

• Ecobee thermostat + remote sensor
• Roku
• Onkyo A/V receiver
• Mobile phone (once app installed)
• Outdoor Weather
• The literal Sun

All of this was super easy, didn't require any CLI changes, it just was clicky clicky from a quick web UI. Cool, that'll be the same with MQTT too? no.

MQTT

MQTT (wikipedia) stands for "MQ Telemetry Transport". What does MQ stand for? Apparently it came from IBM thing called "MQSeries" where it stood for Message Queing, wikipedia says it stands for nothing. We're off to a great start.

If you go to Settings -> Devices and Services -> Integrations and choose to add MQTT, it just asks for your broker and you're just kinda stuck.

To use MQTT with Home Assitant, you must use something called "Mosquitto Broker". Why? I don't know, but you need it. Install it from Settings -> Add-Ons -> Add-on store. It will take several minutes to install. I would recommend rebooting after as well.

Once it's installed.. this is where you hit question marks. What's next? The docs just say that it should show up as a discovered integraiton, but it didn't for me. So I rebooted Home Assistant, and then MQTT appeared as discovered after a bit.

Before going further, go and add a new user to Home assistant itsself, and configure Mosquitto to use it. This made it a lot easier to get the device to talk to it. I used "mosquitto" as username, use what you want. Record the password

• Settings -> People -> Users -> Add user
  • Display name / Username: mosquitto
  • Password: <redacted>
  • Create

Now go in to the MQTT settings and tell it

• Settings -> Devices and Services -> MQTT Configure
  • Re-Configure MQTT
  • Username: mosquitto
  • Password: <redacted>
  • Next (until finished).
  • It may ask you to reboot

Salt Sentry

Configure the device per the manual. On its settings page set:

• mqtt server: <ip of your home assistant server>
• mqtt username: mosquitto
• mqtt password: <redacted, same as MQTT>
• mqtt topic: saltsentry

Once you have this in, the Salt Sentry should finally show as connected.

Do a sanity check.

• Settings -> Devices and Services -> MQTT Configure
  • Listen to a topic: saltsentry
  • Start Listening

You should see a message received at the current timestamp. This is percentage full. You may also listen to the topic `saltsentry_distance` as another check, which is the distance in centimeters.

Sensors

Finally, things are talking. But none of these things you just 'listened' for anywhere appear anywhere. This is where you have to manually edit a YAML file. I did this by going installing the File Editor add-on. (Settings -> Add-Ons -> Add-on store). Once installed I'd suggest toggling 'show in sidebar' to find it easier.

In the File Editor, Browse to /config/configuration.yaml by clicking the "Folder" icon in top left. Then paste this in at the bottom. Note the Salt Sentry manual suggests something here but it's wrong as of the time of writing (upper case S in sensor, the wrong quotes, multiple of the same lines)

mqtt:
 sensor:
 - name: "Salt Sentry percent"
   state_topic: "saltsentry"
   unit_of_measurement: "%"
 - name: "Salt Sentry distance"
   state_topic: "saltsentry_distance"
   unit_of_measurement: "cm"

This gives you two new sensors that will be visible to pull data from in your dashboard. They'll use the names above, but ONLY after you restart the MQTT service..

• Settings -> Devices and Services -> MQTT -> ⋮ -> Reload.

If the reload fails, it generally means there was an issue with the configuration.yaml file. It will download logs which hopefully help.

You may now add these to a dashboard. I went to edit mode of dashboard, chose Add Card, then By entity tab, then typed 'sentry' and added all based on its suggestion.

Finally, you may do what you originally wanted to do, which is notify when the salt level is low. This is done via "Automations".. which I'm too burned out to figure out at the moment.