Pellet Level Monitor WITH HC-SR04, ESP8266 and Tasmota

This project is a wireless pellet stove level sensor that uses an HC-SR04 ultrasonic distance sensor connected to a NodeMCU ESP8266 running Tasmota firmware. The sensor measures the distance from the lid of the pellet tank down to the fuel surface, and that reading can be mapped to a percentage to show how much fuel is left. Because Tasmota supports MQTT, HTTP, and a built-in web UI, you can connect it to almost any smart home platform or custom application. Everything is housed in two small 3D printed enclosures with magnetic mounts, so installation is as simple as sticking them to the metal tank lid.

For hardware you will need a NodeMCU ESP8266 board, an HC-SR04 ultrasonic distance sensor, a 1k ohm resistor, a 2.2k ohm resistor, a thin flat cable (roughly 4mm wide and 2mm thick), two 10mm ring magnets for the NodeMCU enclosure, one 10mm ring magnet for the sensor enclosure, a USB cable for flashing, super glue, and hot glue.

For software you will need VS Code with the PlatformIO extension installed, the Tasmota firmware source code, and the ESP flasher tool. You will also want access to the Tasmota documentation for the HC-SR04 sensor, which covers pin configuration in detail.

For tools you will need a soldering iron and solder, wire strippers, flush-cut pliers, and a 3D printer to print the two enclosures. The enclosure files are designed for the standard NodeMCU v3 module and the HC-SR04 sensor.

Tools and Materials

HC-SR04 Ultrasonic Distance Sensor: https://s.click.aliexpress.com/e/_c3z3YhjX

NodeMCU ESP8266: https://s.click.aliexpress.com/e/_c3Ej0BfX

ESP32 Wroom Module: https://s.click.aliexpress.com/e/_c4mpKqyH

Soldering Station: https://s.click.aliexpress.com/e/_c3khswC9

Soldering Helping Hand: https://s.click.aliexpress.com/e/_c4noQXSl

Bench Power Supply: https://s.click.aliexpress.com/e/_c45PTV6N

Other Rersources

Tasmota Firmware: https://tasmota.github.io/docs/

PlatformIO: https://platformio.org/

ESP Flasher: https://github.com/esphome/esphome-flasher

Ding Platform: https://ding.mk/en

The HC-SR04 works by sending a short ultrasonic pulse from the trigger pin and waiting for that pulse to bounce back and be detected by the echo pin. The time between sending and receiving corresponds to the distance to whatever is in front of the sensor. The NodeMCU controls the trigger pulse through pin D6 and reads the echo response through pin D5.

There is one important detail: the HC-SR04 runs at 5 volts, which means the echo pin also outputs a 5V signal. The ESP8266's GPIO pins are only rated for 3.3V, so connecting the echo pin directly would damage the board over time. A simple voltage divider using a 1k ohm and a 2.2k ohm resistor solves this. When these two resistors are connected in series between 5V and ground, the junction between them sits at approximately 3.3V, which is safe for the NodeMCU GPIO.

Open VS Code with PlatformIO and clone or download the Tasmota source code. Create a new build environment for the ESP8266 and name it something descriptive, like distance-sensor. In the firmware configuration file you need to enable the HC-SR04 sensor driver by uncommenting or adding the relevant define for the sensor. Then set the pin assignments: D5 for echo and D6 for trigger, matching the hardware wiring you will do in the next step. The Tasmota documentation explains exactly which configuration defines to set.

Once the configuration is set, run the build. PlatformIO will compile the firmware and produce a binary file in the build output folder. Note the path to that binary because you will need it in the next step.

Connect the NodeMCU to your computer via USB. Open the ESP flasher tool and select the COM port that the board is detected on. Browse to the compiled Tasmota binary from the previous step and select it. Click flash and wait for the process to complete. A serial monitor will show the boot output and confirm the device is running.

Once flashed, the NodeMCU will create its own Wi-Fi access point. Connect to it from your phone or computer, enter your home Wi-Fi credentials in the Tasmota setup page, and the device will reboot and join your network. You can then access the Tasmota web UI by entering the board's IP address in a browser.

The HC-SR04 sensor comes with header pins soldered on, but the 3D printed enclosure does not have room for a connector. You need to remove these pins first. Add a small amount of leaded solder to each pin to lower its melting point, then apply heat and pull each pin free. You do not need to clean the pads because you will be soldering directly to them.

Thread the flat cable through the slot in the sensor enclosure lid before soldering, since you cannot pass it through afterwards. Strip a short length of insulation from each of the four wires and tin them lightly. Solder each wire to the correct pad on the sensor board: the darkest wire to ground, the yellow wire to VCC, and the remaining two to the echo and trigger pads. The exact order depends on the cable you use, so keep track of which wire goes where as you solder.

After soldering, add a small amount of hot glue over the solder joints to hold the wires in place, and add another blob at the cable exit point on the enclosure lid to act as a strain relief. Fit the sensor into the enclosure body and press the lid on. The lid has two small pins that push the sensor board flush against the front face. Glue a 10mm ring magnet into the recess on the back of the enclosure with a drop of super glue.

Pull a longer length of the flat cable through the opening in the NodeMCU enclosure so you have room to solder outside the case. Strip and tin the four wires. On the NodeMCU, you will solder directly to the pins rather than using the header sockets.

Solder the ground wire to a ground pin and the VCC wire to the Vin pin on the NodeMCU, which supplies 5V from USB to power the sensor. For the trigger wire, solder it to D6. For the echo wire, do not connect it directly to D5. Instead, solder the 1k and 2.2k resistors together at one end to form the midpoint of the voltage divider. Connect the 2.2k resistor's free end to ground, connect the 1k resistor's free end to D6 (which sits at 3.3V logic), and connect the echo wire from the sensor to the midpoint junction. Then connect a short wire from that midpoint to D5.

Pull the cable back through the enclosure so the slack sits inside. Secure the NodeMCU board and the resistors with a small amount of hot glue to prevent movement, then fit the enclosure lid. Glue two 10mm ring magnets into the recesses on the bottom of the case with super glue.

Power the NodeMCU via USB and open the Tasmota web UI at the board's IP address. You should see a distance value updating at a regular interval. Hold your hand a few centimetres in front of the sensor and the value should drop to match. Move your hand further away and the reading should increase. Point it at a wall or ceiling to confirm it measures longer distances accurately.

If the reading is zero or does not change, double-check the pin assignments in the firmware and verify the voltage divider wiring on the echo line. If the reading is erratic, make sure the VCC and ground connections are solid.

The build gives you a wireless ultrasonic distance sensor that reports readings through Tasmota's web UI and can publish data via MQTT to any platform you choose. The 3D printed magnetic enclosures make it easy to mount the sensor on the inside of a metal tank lid and the controller on the outside, keeping the Wi-Fi antenna clear of the metal walls. From here, the next step is to calibrate the distance range for your specific tank and write a conversion that turns the raw centimetre reading into a fuel percentage.

If you want to follow the rest of the build, including how I connect this to a live data platform and add low-level alerts, subscribe to the Taste The Code YouTube channel where I continue this project in upcoming videos.