OpenCV Oil Tank Gauge Reader with Home Assistant Integration

Introduction

Welcome to the OpenCV Tank Gauge Reader project. This project aims to provide the necessary elements to build a non-invasive fuel oil tank gauge reader using standard off-the-shelf parts and some easy 3D prints. With built-in Home Assistant integration, it's easy to view the level of your tank from your smartphone, or receive notifications when your tank is low.

This project is the original work of Steve Richardson (steve.richardson@makeitlabs.com), and is released under the MIT License. It's intended to be useful, educational, and fun. However, there's no warranty and no guarantee that you won't run your oil tank dry, burn your house down, or upset your cat. If you build this project, that's all on you.

Features

• Based on Raspberry Pi Zero W and the official Raspberry Pi camera
• Computer vision detects position of the indicator relative to the scale markings to determine tank level
• NeoPixel RGB LED Display shows level readings and status at a glance, improving upon the original gauge
• Home Assistant integration allows creation of custom dashboard displays and automatic notifications when tank level is low
• HTML5/JS web app allows real-time camera preview and instant computer vision parameter tuning
• REST API allows custom integrations

Inspiration

This project uses a $5 Raspberry Pi with WiFi and a tiny video camera to "read" the oil tank gauge level, using basic computer vision techniques. It provides the level reading to Home Assistant, where the Home Assistant app can show the oil level on screen at a glance, from anywhere. Home Assistant can also be configured to generate push notifications or make voice assistant (e.g. Alexa) announcements if the oil level has fallen to a low level.

I did the project as a fun diversion, to build something cool, and to learn a bit more about OpenCV. I was also motivated by the predicted shortages of heating oil for the 2022-2023 winter, in order to keep closer watch of my tank levels.

Is this the best (or even a sensible) way to read the level of your oil tank? Not really. There are commercial gauges on the market, like the Smart Oil Gauge, which replace a classic float gauge with a distance sensor (optical or ultrasonic) to measure the distance from the top of the tank down to the oil. The downsides are usually high price ($150-$200 USD), and that they involve an invasive change to the fuel oil tank, which may be a challenge due to rental agreements or local regulations. Most of these solutions also lose the basic visual gauge functionality that a classic float gauge provides, and only provide an electronic reading via an app. They are also private cloud-based solutions, and may not provide an API to integrate with your home automation software of choice.

Background

Why would you want or need to read the level of your oil tank? You may also be wondering why anyone would even have an oil tank in their home to begin with?

Home heating oil/fuel oil is an archaic, but popular means of heating homes and making hot water in certain parts of the USA and some other parts of the world. Yet, it's nearly unheard of in other parts of the country and/or world. So, while natural gas might be the most commonly used fuel to produce heat and hot water, many people, particularly in the Northeastern part of the US, use this close cousin of diesel fuel instead.

Oil is typically delivered to the end user either by customer request, or on a seemingly haphazard "automatic" basis when under contract with an oil company. This automatic method is based on their own algorithms that attempt to determine usage based on past usage and recent local weather. These algorithms are not perfect, and sometimes homes run out of oil. Furthermore, oil tanks are typically located in basements, in crawl spaces, or outdoors, and not in places where it's easy or convenient to regularly check the visual gauge. So if the oil contract is by request, it's important to remember to check the tank level frequently and call in an order promptly when it's low. And even if it's an automatic fill contract, it's a good idea to check it often, because sometimes usage exceeds predicted amounts, and running out in the middle of the winter is not fun (ask me how I know). Running out of oil involves an emergency delivery from the company (sometimes at a premium price), and a fussy re-priming of the oil burner. It can also result in costly frozen pipes and other home damage in extreme cases if a home is unattended for a period of time.

Some oil companies have hopped on the bandwagon of electronic sensing and remote reporting of tank levels to improve this situation, but it seems to be the exception rather than the rule. Oil companies tend to be low-tech in nature - slinging dinosaur juice is their business, not troubleshooting electronic devices and IT issues in customer homes.

Requirements

Firstly, this project has been designed with indoor (basement) oil tanks in mind. The 3D-printed enclosure is not weather-tight, and is designed around materials (PLA, particularly) that quickly degrade when exposed to the elements. Also, it's powered by an AC wall adapter, which would generally be unsafe to use outdoors. If your tank is outdoors, or even in a crawlspace area, you should consider a different solution, or be prepared to step up and improve this design.

Secondly, the mechanical design is only suitable for a Scully Twis-Lok oil tank gauge. The concepts and software could easily be applied to other models, but you'll be on your own. Read more in the Gauge Requirements section to make sure you have a compatible gauge before proceeding.

Mechanical

You will need access to a 3D printer and some basic mechanical skills for this project. There are many hours of 3D printing, but the parts are designed to be easy to print and assemble.

Jump to the Mechanical Assembly page for instructions to 3D print and assemble the gauge.

Electronics

You need to do some basic soldering and wiring for this project. It's simple enough that a custom circuit board is not needed, but there are a handful of connections that must be made.

Read the Electronics Assembly page for instructions.

Software

Software is primarily written in Python, and is intended to run on Raspberry Pi OS. You won't need to know how to program in Python to use this project, but it won't hurt to have some basic Linux familiarity to get the Pi configured and the software installed.

See the Software Installation page to read about how to install the software on your Pi.

If you're interested in the technical details of the software or computer vision algorithm, read the Software Details.

Testing & Calibration

Once you've got it built and the software is installed, read the Testing & Calibration page to test and calibrate the gauge reader. The project features a web-based real-time tuner to configure the computer vis

ion parameters.

Home Assistant

Once you've got it up and running, read about how you can set up dashboards and notifications in Home Assistant.