ESPHome Home Assitant

Salt level sensor for water softener in Home Assistant with ESPHome


In this article I will explain how I quickly created a salt level sensor for my water softener using an HC-SR04 Ultrasonic Distance Sensor and a Wemos D1 mini . The inspiration was provided by DrZzs during one of his live streams. Since I wanted a smart device and upgrading mine would cost me around 150€ I decided I would try to do it myself. I will illustrate two examples on how to display the data. One in the actual height of salt left in the container and another in percentage.

Material list

So what do you actually need? 
First of all, a water softener, a Wemos D1 mini, a HC-SR04 and a 4 wire cable to connect the HC-SR04 to the D1 and a mini USB power supply

Main Components

HC-SR04 Ultrasonic Distance Sensor

The ultrasonic sensor determines distance by using sonar, which means no direct contact is required for measurements

Additionally you will need

  • a 4 wire cable (as long as required)
  • A 5V power supply for the D1 mini. (A mini usb phone charger is more than enough)
  • a mini USB cable (for flashing)

Additional tools and hardware

For this project soldering is required, here is a list of some additional tools you could find handy

Soldering iron

A soldering iron is a must for every DIYer


(optional) shrink-tube

Shrink tubes aren’t required but they will help you to avoid short-circuits and will make your project look a lot tidier … bonus: they will hide soldering defects.


Wire stripper & Wire cutters

Depending where you will place your D1 a case might come in handy. I’ve hidden mine in the garage motor. If you would like to place it somewhere else this is the way to make it look tidy


I’ve used the following software to complete the project:

Flashing the firmware on the D1 mini

As mentioned above I used ESPhome. If you do not know ESPHome and have no clue what I’m talking about, well, head up to their website. They have it well explained. So please do take the time to read the guide.

For the rest of this guide, I’m going to assume you are running However, the ESPHome getting started guide for users is extremely detailed, and you should be able to adapt easily.

Preparing the firmware

This part is pretty straightforward I have prepared the code you will only have to adapt the value we will subtract from ( it is the height from the salt container from where the sensor will be placed to the bottom )

Things to take into account:

Since we are going to measure from the top down the measured value will increase as the salt drops. In order to have a decreasing value we will take the distance from the sensor to the bottom, of the salt container and subtract the (by the sensor) measured distance from the previously measured container height.

Another thing I have done, and that is up to you, is to convert the measured distance in meters to centimeters since my salt container is only 46 cm high.
You can also convert from metric to imperial.

As some people prefer to have percentage values, I also added an example for percentages where you take the total distance(t), subtract the measured distance(x), multiply it by 100 and divide it by the total

((Measured) * 100) / (Total Dsitance)
in my case: ((0.42-x)*100)* (100 / (0.42 * 100)) = 24.28%
(0.42 -x) * (100/0.42) = 24.28%

The actual code

DO NOT USE PIN D4 !!! the D1 mini won’t boot!

Create a file called salt_level_sensor.yaml; for users, create the file in the /config/esphomefolder, so you end up with the file: /config/esphome/ salt_level_sensor.yaml.

Next, add the following contents to the file:

The above snippet shows an ESPHome project file in the YAML format.

On lines 9 & 10, make sure to set your WiFi details or else you might end up with failure. Save the file and open up the ESPHome web interface; The Car_position_sensor project should appear!

Save the file and open up the ESPHome web interface; The Car_position_sensor project should appear!
Now validate and Downlaod the bin as shownin the example below.

Uploading the firmware to the D1 mini

I won’t explain how to flash the firmware to the D1 mini since you can find all you need in the following article:

Wiring up the D1 mini and the sensor

Make sure your D1 mini is disconnected from any power source during this step! 

The wiring is pretty straight Forward we’ll use D1 and D2 for trigger and echo. The HC-SR04 needs to be power so we’ll give it 5V (VCC) and GND

Soldering done? Good let’s carry on

Now that you have soldered all the sensors and have verified there is no short-circuit, it’s time to test if all is working right and you have wired the pin-outs correctly.

Connect your D1 mini to a power source and verify it is online in ESPHome.

Installing the sensor in the salt/brine tank.

This part is totally up to you. I chose to place my sensor inside the thank and hold it in place with some hot glue the D1 mini is in my rack since I’ve added temperature sensors as well (which i haven’t explained here). DrZzs drilled a hole into the lid and placed it atop. You can then place the D1 mini on top of the lid and cover it so that it’s protected from outside factors like dust etc.

Integrating the sensor in Home Assistant

Now this is really easy thank to the efforts the Home Assistant dev team has done. In Home Assistant, go to: Configuration > Integrations > the sensor should appear at the top. Follow the steps below to integrate it in Home Assistant

This is a simple example on how to add the sensor and not the actual sensor


In order to have this view you will need the gauge card

copy the following code in your view

And you are done

Useful Information

In case of any question, find me on Discord or on Twitter.
You can find a dedicated Discord Server for any ESPHome related question or if you have questions about the drivers for the D1 mini
If you have issues with the community add-ons, you might find help on their discord server.

If you liked this article, do not hesitate to share it

I run mostly on coffee so, if you enjoy my work, and if you would like to support me you can buy me a coffee

Buy Me A Coffee

Leave a Reply

Your email address will not be published. Required fields are marked *