Tank Utility HSPI for HS3

[XboxMeister]

Description

Tank Utility is a HomeSeer3 plug-in for anyone with a tank monitoring meter being managed by TankUtility.com. These meters periodically measure things like how fully your tank is, tank temperature, … and upload that data to their system. I built this for my own purposes as I have a propane tank monitored through TankUtility.com but thought I'd share it with the community. It is also my first HS3 plug-in so please bear with me as I make it better over time and bugs crop up. I'm a lifelong software engineer so this isn't my first rodeo but I'm still learning the ins and outs of HS3 plug-ins. Be kind.

The plug-in is designed to work with your standard TankUtility.com account that is set up when you set up your service with them. It is the same account you use with their app to monitor usage. It collects the data for each monitor device associated with your account and creates corresponding HS3 devices that you can use to keep an eye on things. This includes information about your account (name, location of the monitor device, …) as well as last tank level reading, tank temperature and when the last reading was taken. I've also added some value added features such as keeping a rolling 7 day list of the previous tank level readings so you can track, graph, … usage. In my case, the monitor device is on a large propane tank but I assume TankUtility.com supports other kinds of tanks or will in the future beyond propane. If you don't have a monitoring device on your tank at the moment, I suggest talking to a local propane supplier as they can probably install the monitor for you and get you all set up. That's what occurred for me when I was upgrading my propane supply on my property. The local supplier offered to pay for the monitor device if I paid the annual monitoring service fee. It is a win-win as I get to monitor my home's usage as I want (through HS3) and it helps the supplier as now they know exactly when to fill the tank vs. driving to my rural property based on a rough guess of when the tank will be low. They get notifications directly from TankUtility.com so that they know exactly when to refill without me doing anything.

NOTE:If your tank is NOT being monitored through the TankUtility.com site, this plug-in will not do anything for you. It does not have any way of talking to a local monitoring device you may have on your tank that is on a network, …

NOTE:I was made aware by bsobel (thank you!) that Generac uses TankUtility meters branded for Generac and sends their data through the same data service. I contacted TankUtility.com and they confirmed that the data, format, ... is the same so if you have a Generac meter on your tank that works with a phone app, this plug-in should work just fine with it as well. If anyone out there tries this, please drop me a note to confirm all is working.

How It Works

The plug-in uses the account username and password you provide in its Config screen to connect into your TankUtility.com account to retrieve your monitoring data. As this data is stored on the TankUtility.com site, where the plug-in runs is unimportant. You don't have to have an HS3 instance running where the tank(s) being monitored are located as the readings aren't being collected by the plug-in locally. This is super convenient if you are monitoring usage at a vacation rental property or other location where you aren't present all the time.

Note, the plug-in can only get the data available through TankUtility.com at the frequency they collect it. Per TankUtility.com, they take four readings per day but only send an update to their servers once per day. There is no way to force their system to pull a live fresh reading from the meter so don't expect the value to change more than this, whether you have an LTE (cell phone network) or Wi-Fi meter. I believe they do this to conserve the battery on the meter as mine has no power source nearby and is totally battery-dependent. I have left the option to change the polling frequency in the plug-in configuration page for now in case this ever changes but I don't recommend changing it from the default as it won't give you more data.

Main Features

• Reads account and tank status from TankUtility.com data interface (including meters branded for Generac)
• Creates HS3 device structure for each tank monitored
• Reports last reading time, tank level percentage, temperature, capacity, ...
• Tracks last 7 days of tank level percentage readings for convenient reporting
• Option to report temperature either as Fahrenheit or Celsius units
• Configuration page to enter username and password for your account, set temperature reading units, set frequency to read data from TankUtility.com and turn on debugging data.
• Runs under either Windows or Linux HS3. I have both and have used it on both successfully.

Example Usage

• Use the plug-in to read your tank level and temperature every day and end out an email to yourself, a property manager, … to keep them updated.
• Monitor tank level and flag when unusually high usage from reading to reading is noticed (e.g., your vacation rental guests are leaving your gas firepit on all night).
• Use HS3 events to alert you when the tank level is low and needs to be filled soon.
• Snapshot the tank level when someone checks in and out of your vacation rental so that you can accurately charge them for above normal usage.

Downloads

• The plug-in is available through the standard HS3 updater.
• My site for my plug-ins (this is the first and only but I have several underway) is: https://wooddragonsolutions.wordpres...ility-plug-in/

Initial setup and Getting started

• The plug-in is available through the standard HS3 updater. Just download it and install it.
• The plug-in will start automatically but will not create any HS3 devices until you enter your username/password info into the Config screen under the Plugins->TankUtility->Config page in the HS3 UI.
• There are default username/password values in the fields that you need to replace with your real credentials. If the plug-in sees either of these default values, it will not try to connect to TankUtility.com or create any devices.
  • NOTE: You get your username/password by creating an account with TankUtility.com. The company that set you up with your tank monitor device can help you get this set up. I have no way of helping with this other than telling you to ask your provider so please don't ask.
• Once you enter your valid TankUtility.com credentials, the plug-in is designed to automatically go try to connect and get your data. No restart of the plug-in should be required (but it won't hurt either). If it is able to successfully log in, it will initially create all the needed devices in HS3 and then populate them with your data.
• Optionally you can choose whether you want Celsius or Fahrenheit temperatures reported (TankUtility.com only sends Fahrenheit so I do the conversion in the plug-in for Celsius). The default is Fahrenheit.
• Optionally you can set the refresh rate of the data from the TankUtility.com data feed. The default is 4 hours. My feed only updates once a day so not much point in faster than 4 hours but I set it this way in case TankUtility.com has other cases where they update more regularly than daily.
• Optionally you can turn on debug info but this is only useful if you need some help from me on a bug. Default is off.
• Note in the screenshot below I create a device called "Device ID x" where x is a sequential integer starting at 0. If you just have one meter associated to your account, you will see something very similar to what's in the image. This is the unique ID of the meter device and I use it as the root device for all the rest. Everything below it in the list is a child of that device. If you have two meters on your account, I will automatically create a second root (e.g., "Device ID 1") for that meter and again there will be child objects for it. And of course if you have more than two meters, the plug-in will create more in the same fashion. I have checked that the plug-in will handle multiple meters correctly but as I don't have this in my account, the testing isn't what I'd call exhaustive or extensive. I also want to improve how it handles odd cases like meters being removed from your account, … although I don't think that is a common case.

Requirements

• Recent build of HS3. I haven't gone back to see if it breaks anywhere back in old builds but I think what I'm doing is pretty straightforward so it shouldn't have too much sensitivity on the version.
• You need the .NET runtime 4.x+ on Windows or the equivalent Mono on Linux. I haven't extensively tested what versions it will/won't work with but pick something fairly recent and you should be good.
• I use the NewtonSoft JSON DLL but install it in my own bin directory under the HS3 installation per the guidance from HS so it should be good to go.

Support

• Please drop me a note here if you have questions or run into problems. This isn't my full-time job but I will be happy to try to help and address bugs as fast as possible. And feature requests are always appreciated.

Version 3.0.0.1- Released Feb 20, 2019

• Initial release to the HS3 updater.

Version 3.0.0.2- Released Mar 15, 2019

• Fixed bug that caused the plug-in's private copy of Newtonsoft JSON DLL not to be found on some Windows systems after install
• Added graphical status icons to all devices
• Converted all purely numerical devices to store their values vs. a string to make any user computations easier.
• Added new device "Last Reading Quantity" that reflects the approximate amount of fuel in the tank (percent full multiplied by the capacity of the tank)
• Made the plug-in name a link to the Config page on the Plug-ins->Manage page in HS3.
• Added units to the Last Reading Temperature device to reflect F/C scale.

Version 3.0.0.3- Released April 27, 2019

• Fixed bug that allowed plug-in to take ownership of manually created HS devices that didn't belong to the plugin
• Added ability to restore HS devices that were found missing (e.g., accidentally deleted) when the plug-in is restarted.
• Added ability to choose gallons or liters as units of measure for the fuel in the tank
• Added HS device that indicates when the tank has been recently filled up (or at least had fuel added to it)
• Added fuel type HS device to reflect what kind of fuel is being stored
• Added supporting graphics for the new HS devices
• General performance improvements

Version 3.0.0.4 - July 5, 2019

• Fixed minor install bug
• Added several useful links to Config page

Example images of the config screen and what the HS3 devices look like:

[bsobel]

Awesome. Had been on my list to write, great to see it available (I have 2 units, adding 2 more)

[XboxMeister]

Excellent! Let me know how it works for you. I've done some testing with two monitors under one account but as I only have one real monitor device, I had to simulate the 2nd one. It should work with multiple monitors but you never know until you try. ;-)

[bsobel]

Up and running, no issues, found both tanks no problem. A couple small suggestions:

a) When you register your config link, mark it as such so it becomes clickable from the interfaces screen (that allows you to jump right from the list to your config page, bypassing the menu)
b) Status icons on the devices, perhaps the battery indicator icons for the readings and an alert or ok icon on the last date if the last read date is more than X days (to quickly catch if things aren't updating)

Thank you again!

[XboxMeister]

Up and running, no issues, found both tanks no problem. A couple small suggestions:

a) When you register your config link, mark it as such so it becomes clickable from the interfaces screen (that allows you to jump right from the list to your config page, bypassing the menu)
b) Status icons on the devices, perhaps the battery indicator icons for the readings and an alert or ok icon on the last date if the last read date is more than X days (to quickly catch if things aren't updating)

Thank you again!

Great ideas! I will put them on my list of improvements.

Glad it's working for you so far. If you have other ideas or run into issues, drop me a note please. :-)

[bsobel]

Great ideas! I will put them on my list of improvements.

Glad it's working for you so far. If you have other ideas or run into issues, drop me a note please. :-)

Will do, and thank you again! Great to see another developer building for the platform. Oh FYI you probably know this but the Generac version is just a branded version from TankUtility and it uses their same backend. So might want to update the description on the plugin so people know it works with Generac as well...

[XboxMeister]

OK, good to know about Generac. I don't have a way to test it though so I'm a bit hesitant to say it works with it without having a way to verify that they send the same data, use the same JSON structure, … Do you happen to know if they have a test account to play with for developers? Some companies do (Tank Utility didn't).

[jbbtex]

Glad to see this plug-in. I've been using scripts to get readings from my Tank Utility monitor for more than a year. This plug-in gets much more info than I currently do.

A suggestion. Putting the numerical data into HS as VALUE would be better, I think. You could then easily display the level in HS Touch with a "meter," etc. Having it as a value would also let you do some math. I have a script that takes the percentage level and calculates current gallons and the maximum number of gallons that could be delivered taking into account the 90% rule plus a little cushion.

[XboxMeister]

Glad to see this plug-in. I've been using scripts to get readings from my Tank Utility monitor for more than a year. This plug-in gets much more info than I currently do.

A suggestion. Putting the numerical data into HS as VALUE would be better, I think. You could then easily display the level in HS Touch with a "meter," etc. Having it as a value would also let you do some math. I have a script that takes the percentage level and calculates current gallons and the maximum number of gallons that could be delivered taking into account the 90% rule plus a little cushion.

I started with scripts too but one day just said "I need to create a plug-in just to see how hard that really is". The scripts are a good way to get going fast but man the built in editor is terrible for debugging problems. Working in Visual Studio is so much easier to track down issues and most of my script code just works without much change.

Great point on using the values. I'm actually working on an update that does just that and tying in graphics status as well. Should have a new version out fairly soon with those improvements as well as a few others. I'm using this plug-in a bit to learn the nuances of HS3 development before I start pushing out several more that I have underway for a bunch of different things. Already have learned a lot just in the past few days as people are starting to use this one.

Appreciate the feedback!

[XboxMeister]

v3.0.0.2 has been released to the HS3 Updater. Please take the update and let me know how it is working. Details of what is in it are in the sticky at the top.

[FastFreddi]

Had to delete the old version to avoid error despite having disabled the plugin and rebooting the system. Not sure if its related to my previous manual install. Also, in you upcoming versions, would it be possible to add the ability to display the tank capacity and last reading quantity in litres? A 120 gallon tank is a 454 L. Also, NewtonSoft error is back. You have your <probing privatePath="bin"/> instead of bin/TankUtility

Mar-16 10:59:29

Updater Error

Installation of package Tank Utility failed. Try disabling the plugin first, then re-try the update.

Mar-16 10:59:29

Updater Error

Copying source to C:\Program Files (x86)\HomeSeer HS3\HSPI_TankUtil.exe, detailed error: The process cannot access the file 'C:\Program Files (x86)\HomeSeer HS3\HSPI_TankUtil.exe' because it is being used by another process.

[XboxMeister]

Had to delete the old version to avoid error despite having disabled the plugin and rebooting the system. Not sure if its related to my previous manual install. Also, in you upcoming versions, would it be possible to add the ability to display the tank capacity and last reading quantity in litres? A 120 gallon tank is a 454 L. Also, NewtonSoft error is back. You have your <probing privatePath="bin"/> instead of bin/TankUtility

Mar-16 10:59:29

Updater Error

Installation of package Tank Utility failed. Try disabling the plugin first, then re-try the update.

Mar-16 10:59:29

Updater Error

Copying source to C:\Program Files (x86)\HomeSeer HS3\HSPI_TankUtil.exe, detailed error: The process cannot access the file 'C:\Program Files (x86)\HomeSeer HS3\HSPI_TankUtil.exe' because it is being used by another process.

I think something went wrong with the install somehow for you as the exe.config file that is in the 3.0.0.2 zip file released to HS3 looks like the following:

<configuration>
  <runtime>
    <loadFromRemoteSources enabled="true" />
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <probing privatePath="bin/TankUtil" />
    </assemblyBinding>
  </runtime>

….

I just looked at the zip I submitted and extracted that specific file to get the code above so not sure why you are only seeing "bin". The source file that is used to generate that exe.config file also has the correct path in it. Given you had to run as Administrator last time to install, I'm thinking there may be a permissions issue overwriting that file for some reason. Also given it is saying that it couldn't access the TankUtil plug-in because another process is using it makes me think HS3 wasn't entirely shut down or something went wrong in the update as nothing should be using it. I successfully updated it both using the updater_override method and via the updater on my Windows box.

As for the litres, that should be pretty easy to add. I was actually thinking about it the other day given I had the Fahrenheit/Celsius option. Consider it a 3.0.0.3 addition. Appreciate the suggestion!

[FastFreddi]

My apologies, I was looking at another exe.config file. As for the NewtonSoft error, it occurred on first startup and restarting the plugin since has not resulted in the error.

[XboxMeister]

No worries man. Glad you got it sorted out. 👍

[wpiman]

Oh good. I had a script doing this but glad it was made into a plugin....