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, …
How It Works
Main Features
Example Usage
Downloads
Requirements
Version 3.0.0.1- Released Feb 20, 2019
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.
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/
- 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.
- 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.
- 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.
- 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
- Fixed minor install bug
- Added several useful links to Config page
Comment