heating oil tank level sensor – JSN-SR04T version

make a heating oil tank level sensor that’s more useful than anything you can buy

There is a replacement for this project – the latest project uses a DFROBOT A02YYUW Waterproof Ultrasonic sensor as described here. The sensor is a little more expensive (£16) but it may last longer.

The ultrasonic JSN-SR04T (described below) has been working reliably. However after five years the oil vapour destroyed the silicone and the sensor started falling apart and eventually failed. Silicone does protect the sensor from water damage so this would work on a water tank. A further limitation of the JSN-SR04T ultrasonic sensor is that it cannot measure at short range – it records the same level whether the tank is full or 20cm below full. When the level drops by 20cm (about 200 litres) the readings become very useful at alerting me to order more oil.

• measures oil level in any unit – litres, gallons or days until I need to refill the tank
• displays readings on a gauge or time graph (uses Home Assistant gauge & history graph).
• receive readings or alerts as an email or phone notification or flashing smart bulb in the house.
• uses an ultrasound sensor JSN-SR04T ultrasonic distance measuring sensor, waterproof (~£6 ebay). A few years later I changed to a different sensor – see the ‘time of flight sensor’ project write up
• uses an ESP32 development board – a chip with wifi (~ £6).
• if you need to use battery power an ESP8266 or other chip might be more appropriate. The battery power might be 6 x 18650 cells based on this one I made (also see Kev’s comment below)
• with a waterproof electrician’s housing this could work outdoors and on battery power.
• with a little modification this project would monitor the salt level in a water softener or the water in a water barrel (ref Dr Zzz – youtube)

Some homes use oil as a fuel to keep warm in winter. Over the course of a winter I might need to order two or three deliveries of oil but till now I’ve no way to predict the day when I’ll need to top it up. And I really don’t ever want to run out of oil. The oil is burned in a central heating boiler in the same way that many homes in the UK burn methane gas. Although we call the liquid ‘heating oil’ it’s more runny than the oil you know: it’s more like diesel or white spirits or turps or paraffin or kerosine.

This sensor had been in reliable use for a few years when I discovered that a ‘time of flight sensor’ might be even better. The ‘time of flight sensor’ project write up explains all for now and until we’ve spent more time with it. I an running both types of sensor at once just now.

I asked local firm Shelford Heating to quote a price for an oil level sensor. Their solution involved drilling the steel tank to fit an Apollo wireless kit – but £220 seemed excessive for this need. I could also have bought the kit, which sends an approximate oil level to a display but I really wanted something that could alert me better.

how to connect up an oil level sensor and wifi chip

A waterproof ultrasonic sensor, looking like a car bumper sensor, arrives with a long lead and a blue board. Female-female Dupont jumper wires will connect the four pins on the board to an ESP32. Two of the pins connect to ~ 5v power and ground. The other two, labelled TRIG and ECHO go to any suitable GPIO pin on the ESP32. I connected them to GPIO 15 and GPIO 16. Thus far we’ve four wires joining an ESP32 and a sensor board. We now need a lead (from a USB charger) to bring 5v power and GND to the ESP32.

(I initially used an ESP32-CAM instead of an ESP32 with a USB socket. This meant that I needed to hack a USB cable and make the wiring less elegant. I just happened to have a spare ESP-CAM but frankly instead I’d recommend a ESP32 with its own USB socket.

The ultrasound sensor needs to be fixed so that it points down at the surface of the oil in the tank (photo). I used a tank hole that housed the dipstick used to measure oil level for the last 40 years. A suitable cap, as shown below, was made on a 3D printer. A container cap might have worked. You might instead drill a hole for it but I’ve no advice on this. Over time the ‘oil’ has destroyed the black plastic casing of the sensor but the sensor works as it ever did.

how to program the ESP32 with code – what does ‘coding and flashing the ESP32 chip’ mean?

My oil sensor is a ‘connected’ oil sensor. It takes readings, it stores and presents them and notifies me. To gain this connectivity you need a working Home Assistant installation on a Raspberry Pi (shown in an earlier project). What you do now is best seen demonstrated to gain understanding, but the idea is that you’ll first assemble a series of instructions (a program or code) and check the code for errors. You then get the code turned into a binary file that the ESP32 can use. Next follows a process of getting this ‘bin’ file from your computer onto the ESP chip via a USB cable. The bin or binary file is otherwise called firmware. The process of getting the file into the ESP32 is called flashing the ESP32 with new firmware.

• use your browser to interact with Home Assistant on 192.168.x.x:8123
• in Home Assistant go to the Esphome add-on and add a ‘new device’ (aka new node).
• a wizard asks you for a name (eg oil) and then your wifi details and then whether you have an ESP32 or other chip.
• at this point ESPHome tries to connect to your ESP32 but you may skip this connection and do that manually later.
• choose ‘edit’ in the device box you just now created. add the code below but change the items in bold to suit your board, your wifi, your network and the GPIO pins you want to connect to.
• in the ESPhome section of Home Assistant choose INSTALL (=compile) and Manual download. This will inspect your code and compile it for the ESP32 chip and add ‘libraries’ for each feature you put in the code. After a few minutes ESPhome creates a ‘.bin’ file and saves it on your computer.
• using the ESPhome webtool, connect your ESP32 board with a USB cable. Choose the bin file, click flash and view the logs as the bin file is uploaded to the ESP32.

# SOME SECTIONS BELOW ARE CREATED BY THE ESPHOME WIZARD SO DON'T DUPLICATE THESE

esphome:
  name: "oil-tank"
  friendly_name: "oil-tank"
  area: Cottage

esp32:
  board: esp32dev
  framework:
    type: arduino
 
Enable logging
 logger:
 
Enable Home Assistant API
api:
  encryption: 
    key: "FtKhT5Sf4cwe5bhxxxxxx" 
ota:
  - platform: esphome
    password: ""
   
wifi:
  networks:
  - ssid: !secret wifiD_ssid
    password: !secret wifiD_password
  - ssid: !secret ee_ssid
    password: !secret ee_password 
  - ssid: !secret wifi_ssid
    password: !secret wifi_password

mdns:
  disabled: False

captive_portal:

 # OPTIONAL WEBSERVER - USEFUL WHEN TESTING. 
 
 web_server:
   port: 80
 
# this section defines how the sensor will work. Read on to see how I improved this.

sensor:
 platform: ultrasonic
 trigger_pin: GPIO15
 echo_pin: GPIO16
 name: "oil level"
 accuracy_decimals: 0
 update_interval: 10s


# battery powered version configuration - read more at ESPHome Deep sleep
deep_sleep:
  run_duration: 10s
  sleep_duration: 60min

add your sensor data to the Home Assistant overview

• when the flashing is done, power-up the ESP32 with an old USB charger and go to Home Assistant > Integrations > + > ESPHome. You might have to enter the IP address you chose in the code. You’ll then see the oil level device that has been added to Home Assistant. The device will have an entitity named something like sensor.oil_level
• go to the Home Assistant Overview where you stuff is normally displayed. Choose Edit dashboard in the top corner.
• add a new card called history graph. On the entity line select your sensor.oil_level
• add a new card called gauge to display your oil level. On the entity line select your sensor.oil_level

You don’t need to use YAML code, but for completeness the YAML for the card items above is shown below. You can edit any card’s YAML code to suit.

 # THIS IS FOR THE GAUGE 
entity: sensor.oil_level
 max: 1100
 min: 0
 name: heating oil used
 severity:
   green: 100
   red: 800
   yellow: 600
 theme: default
 type: gauge

 # THIS IS FOR THE SMOOTH LINE GRAPH 
entity: sensor.oil_level
 graph: line
 hours_to_show: 96
 name: of 1000 L oil used
 type: sensor
 unit: litres

# THIS IS FOR THE DETAILED HISTORY GRAPH 
entities:
 entity: sensor.oil_level
 hours_to_show: 24
 refresh_interval: 0
 type: history-graph 

*refine ‘the oil sensor code to correctly calibrate it – the mk II code

After several months use I needed to address some points. Because of these points I modified the code as shown below. Here’s why:

• the sensor doesn’t work well when the oil in the tank is less than 30 cm away. When the tank is full the sensor is 18 cm from the oil. This calculates as a level of 196 litres. Over the next ten days the level appears to remain at 197 litres but when it drops to around 36 cm the levels change and starts making sense. There isn’t a solution for this but the readings from now on are good.
• when my tank approaches empty the level seems to plateaux at 800 litres (720cm from the sensor). The tank holds 1200 litres so this ought not happen because, on paper, the sensor can measure to the bottom of my tank. The sensor is bouncing sounds off a metal strut inside the tank. I’d need to relocate the sensor somewhere else. Because of this I keep my daily eye on the history graph, looking for a plateau.
• the sensor measures in metres so I have to calculate the litres. My tank has a perfectly regular shape from top to bottom – so by measuring dipstick depths, I found that 100cm of tank depth contains 105.3 litres. In the ‘MkII’ code below the last two lines (filter and lamda) do this calibration. The two lines can be edited or entirely omitted to suit your tank.
• when the tank level was low the readings were a bit noisy. To counteract this I calculate the sliding average of an oil level reading.
• it was suggested that the ‘oil used’ graph should fall, not rise, so I made the reading negative. This also makes knowing how much oil to order easier. I should name the sensor ‘oil used’ because the number it returns is the amount of oil I need to buy to fill the tank. Next I really don’t need an oil level reading every 10 seconds so I increased the update interval.

You’re welcome to substitute the above ‘sensor:’ section with the following.

# You can add a filter to the sensor section to calibrate the sensor. Here's mine.  
# To produce a falling oil level simply add a negative sign as here!
#   filters: 
#   - lambda: return x * -1053; 
# My complete sensor section follows:

sensor:
 platform: ultrasonic
 trigger_pin: GPIO15
 echo_pin: GPIO16
 name: "oil used"
 accuracy_decimals: 0
 update_interval: 60s 
 unit_of_measurement: "litre" 
  filters: 
  - lambda: return x * 1053;
  - sliding_window_moving_average: 
    window_size: 20 
    send_every: 10
# When tank is irregular in shape calibrate the distance into the tank
# SEE THE POST FROM 'Kev' below where he improved the filter section
#  – calibrate_linear:
#  – 110 -> 0
#  – 95 -> 204
#  – 75 -> 544
#  – 55 -> 900
#  – 35 -> 1320
#  – 15 -> 1660
#  – 0 -> 1800

so when do I need to order some more oil?

The first nice consequence is that I now know how much oil I need to order and how much I use. In a cold spell two households used 30 litres a day – I’ll be posting my metrics in a future post. And I can see I would need to order an extra 80 litres as it will take say, 9 days to arrive. As I write I was thinking about a way to predict the date when I’ll need to order more oil. Initially I put the data in a spreadsheet as below and it looks like I’ll order in mid January – unless I start to use oil faster. I’ve some tips on making the spreadsheet here. I finally got Home Assistant to do the calculations and tell me when I’ll need to order oil here

notify me with an email when more oil needs to be ordered

I order 900 litres of oil and I use 100 litres of oil as I wait for it to be delivered. Therefore I need an alert when the tank has 850 – 100 or 750 litres of oil.Home Assistant offers numerous alerts including

• get Home Assistant to send you an email – the easiest approach I reckon
• show a message in the browser or pop-up a ‘toast’ message on a phone. You can set a notification message to persist so that you can’t easily swipe it away.
• set an urgent notification to wake up a phone to tell you, or set one that waits quietly until you next pick up the phone.

Here is the automation code – if you’re starting out, the easiest method to get working is the email notification:

 # TIME TO ORDER OIL AUTOMATION - HOME ASSISTANT

 alias: heating oil level alert
 trigger:
 above: '750'
 entity_id: sensor.oil_level
 platform: numeric_state
 condition:
 after: 07:00
 condition: time
 action:
 data:
   message: at {{ states ('sensor.time') }}
   title: '{{ states (''sensor.oil_level'') }} L now. 850L oil to be ordered'
 service: notify.notify_html5
 data:
   message: at {{ states ('sensor.time') }}
   title: '{{ states (''sensor.oil_level'') }} L now. 850L oil to be ordered'
 service: notify.email 

record your daily readings in a Google spreadsheet

Update March 2020

For a while it was OK to manually record the daily oil level in a spreadsheet. I soon saw that I was using 80 – 100 litres of oil a week during December. I therefore set up a connection from Home Assistant so that the daily level could be recorded in a spreadsheet. The code for the automation routine that takes the reading is below. My tutorial to link Home Assistant and Google Sheets is on this page: send sensor data from Home Assistant to a spreadsheet

# THE FOLLOWING IS A TEXT FILE CALLED oil_level.yaml in the folder AUTOMATIONS 
# that is /config/automations/oil_level.yaml
id: '12399999'
alias: oil_level_spreadsheet
description: daily readings in oil_level.yaml
trigger:
at: "23:55:00"
platform: time
condition: []
action:
data_template: { "event": "oil_level", "value1": "{{ states('sensor.oil_level')}}", "value2": "{{ states('sensor.temperature_weather')}}", "value3": "{{ states('sensor.power_today')}}" }
service: ifttt.trigger

add your oil meter to the Home Assistant energy dashboard

Update June 2022

As well as getting help with ordering more oil, it may be extra useful to have your oil readings as kWh (energy). This needs some changes to the code to add necessary entity properties. I’ve used a guess factor of 10kW from 1 litre of oil. You could adjust that to allow for boiler efficiency but I’m only interested in what I use.

IN ESPHOME - revised code for ESP32 node
# the sensor
  - platform: ultrasonic
    trigger_pin: GPIO15
    echo_pin: GPIO16
    name: "oil kW"
    accuracy_decimals: 0
    update_interval: 60s
    id: myoillevel
    unit_of_measurement: "kWh"
    filters:
    - lambda: return x * 1018 * 10;
    - sliding_window_moving_average:
        window_size: 60
        send_every: 10
    state_class: total  
    device_class: 'energy'
# change 10 to 9 for 90% efficiency however this will affect the other sensors
  - platform: template
    name: "oil_level"
    update_interval: 30s
    unit_of_measurement: "L"
    accuracy_decimals: 0
    lambda: |-
      return -0.1 * id(myoillevel).state ;
      
  - platform: total_daily_energy
    name: oil_energy_24h
    power_id: myoillevel
    device_class: "energy"
    state_class: "total"
    unit_of_measurement: kWh
    accuracy_decimals: 1
    filters:
        # Multiplication factor if needed eg convert from W to kW
    -  multiply: 1

Compile and install the code above in place of the original code above. Use File Editor to do the following and restart Home assistant.

The result of the above is to give you entities sensor.oil kWh (for the energy dashboard) and sensor.oil_energy_24h which tells how much oil is used each day.