DIY – Monitor Heating Oil Tank Gallons with Pushbullet, SMS, and Email Alerting

NOTE: Updated code 10-27-2018

In this day and age where everything is measured, recorded, and available remotely (via a REST API most of the time!), it really bothered me that our heating oil tank measured the remaining gallons of oil by a crude plastic dip stick. It’s not accurate, there is no historical data, and there is no way to audit (for honesty, accuracy, or problems/errors).

So the problem is simple enough: Find a quick and easy way to remotely monitor the number of gallons of heating oil in a home, and alert at pre-set intervals (let’s say 75%, 50%, and 25%) of remaining oil in the tank.

After looking for commercial solutions, the cheapest one I found is $120 with a $10/year fee. In my view, that’s simply ridiculous. I decided that I could build something better for 1/3rd of the price ($40), without an yearly fee.

Hardware How-To

Start with this Instructable I created with the exact parts/steps, and with lots of pictures:
https://www.instructables.com/id/Monitor-Heating-Oil-Tank-Gallons-With-Email-SMS-an/

This should take care of the hardware side.

Firmware code and How-To Access Data

Once you have it built – flash your Photon with the code here (see bellow – large code paste).

After that, you should be able to do this from the particle CLI (replace $device-id-here$ with actual device #):

If you have not used the Particle Photon, I am going to provide some additional information on the bottom of this post that will walk you through building/flashing the code, and how to setup the web hook. I have also added a lot of pictures of this on the Instructables page to go with the steps.

Particle Photon web IDE code:

Now that you have everything you need, the last part is to web hook the “Alert” publish call into something that actually alerts you. The easiest way to do this is to create a JSON “custom” webhook, which allows you to “hook” a publish event. In this case, I will hook the “Alert” published event, and redirect it to Pushbullet. You can just as easily call a 3rd party SMS service (Twilio), Email (Sendgrid, Mailgun, etc), or some other custom notification/hook.

Here is the Pushbullet config (please replace “Access-Token” with your token):

Web Hook for Notifications (free with Pushbullet)

Or, if you are using Pushover

You will note that I have added a whole lot of pictures showing the steps around the Photon code build/flash and the Webhooks on the Instructables page. Here is some more informations/detials:

What if you have never used a Particle Photon? Detailed Help on setup/code/flashing!

I made the assumption that a most people who would be interested in a hardware project like this one would be very familiar with Particle’s photons/arduino, and I think this is a bad assumption. If you have not used these before, here is a step by step walk thru what to do from the software side in order to get this to work.

1.) Start by following this: https://docs.particle.io/guide/getting-started/start/photon/#step-1-power-on-your-device
2.) After you have initialized/”set up” your photon, go to: https://build.particle.io
3.) On the left side, under “Current Apps” (where it says “Title”) create an app called “oil-tank”.
Paste the large code from “Particle Photon web IDE code:” above, and click on the top-left “Save” (folder icon)
4.) On the left, click on “Libraries” (bookmark icon) and under “Community Libraries” search in the box for “HC_SR04”.
5.) Click on the found “HC_SR04” and click the blue “INCLUDE IN PROJECT” button. Then select from the list “oil-tank” (what you called your app in step #3), and click the blue “CONFIRM” button.
6.) At this point, make sure there is only ONE line that looks like this:

at the top of the file.
7.) Now clic on “Devices” and click on the star icon next to the device you setup in step #1 — this selects it for flashing the firmware.
8.) Go back to your “Code” for “oil-tank” and click “Verify” (check icon above “Save”) and then “Flash” (lightning bolt icon above “Verify”)
9.) That’s it — you have now flashed the firmware on your Photon.

What are these Web Hooks/Notifications – step by step instructions

1.) Go to: https://console.particle.io/devices
2.) Click on “Integrations” (star-looking icon above the Billing icon) and click on “New Integration”, and click on “Webhook”.
3.) There are TWO differentways to do this – using the “WEBHOOK BUILDER” step by step, OR pasting the whole JSON in the “CUSTOM TEMPLATE” section. No matter which you do, the only thing to really pay attention to is the “Event Name”. It always needs to be “Alert” (unless you change the Particle.publish in your firmware. This is what hooks that notifications into some “real world” notifcation – alert, SMS, Email, etc.)
4.) If you use the “CUSTOM TEMPLATE”, you can paste the “Web Hook for Notifications (free with Pushbullet)” code.
Alternative, and let’s say if you want SMS for example, you can go to the “WEBHOOK BUILDER” section, and follow something like this: https://www.twilio.com/docs/guides/sms-mms-messages-particle-photon#sign-into-or-sign-up-for-a-twilio-account, specifically following this sub-section: https://www.twilio.com/docs/guides/sms-mms-messages-particle-photon#example-1-a-simple-example-of-sending-smses-with-a-particle-photon (the “Set Up a Particle Webhook” part, and noting that the “Event Name” should be “Alert”).
5.) That’s it — you now have a method to “Alert” to external services. Generally, look for the REST POST URL, and either place it in your “WEBHOOK BUILDER” section, or into the JSON template I provided above.