Walter vl: Categories

2021-08-24T08:20:10Z

Categories

New page

=Purpose=

The purpose of this script is to allow monitoring of a heating oil tank, by use of an ultrasonic sensor which measures the distance ''(of air)'' from the top of the fuel to the top of the tank.

The script is configured with the dimensions of the tank, and calculates the fuel level both as a percentage and as a volume in litres. It can also adjust to compensate for fuel expansion/contraction with temperature, to give a stable reading.

=Dependencies=

You will require a distance sensor which measures the air gap at the top of the tank. This is outside the scope of this example, but there are plenty of such devices on the market and many of them actually seem to be the ''same'' design, just rehoused and rebranded.

The Beckett Rocket, Watchman Sonic, and Apollo Ultrasonic oil tank monitors, and probably others, should all work with [https://github.com/merbanan/rtl_433 rtl_433] using a cheap USB DVB receiver. With a little more work, it should also be possible to [http://www.susa.net/wordpress/2012/08/raspberry-pi-reading-wh1081-weather-sensors-using-an-rfm01-and-rfm12b/ use an RFM01 or RFM12B FSK receiver module] on a Raspberry Pi, which should require less CPU.

Note that the RFXtrx433 modules are not suitable for this, as the modulation of the 433MHz signal is FSK. See [https://hackaday.io/project/1548-rocket-receiver-teardown here] for the full details.

Others have [http://www.domoticz.com/forum/viewtopic.php?f=38&t=8647&p=59737&hilit=oil+tank#p59737 made their own sensors].

Most sensors will also provide a temperature reading, since the speed of sound varies significantly across the temperature range that they need to operate within. However, is this is not required — the compensation for expansion of the fuel can be disabled if no temperature sensor is available.

=Domoticz Setup=

==Input sensors==

In my case, the input sensors are virtual; I haven't yet hooked up the [https://github.com/merbanan/rtl_433 rtl_433] receiver software to Domoticz directly, so I'm feeding values in externally. They were created as follows:

Temperature sensor (type 80):
curl 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=80'
Depth sensor (type 13):
curl 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=13'

==Output sensors==

Percentage sensor (type 2):
curl 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=2'

Volume sensor (RFXMeter type 113, subtype 2):
curl 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=113'
curl 'http://localhost:8080/json.htm?type=setused&idx=5&name=Oil&switchtype=2&used=true'

The <tt>idx=5</tt> in the above will need to be replaced with the index of the created device in your own system.

''(In fact, it's not clear that this is the correct device type to use. It's the only one I could find that has a unit of litres ''(or m³ in some cases)'', but it's designed for measuring water ''flow''' not an amount. So the graphs aren't useful. We might need to add a new sensor type of plain ''volume'' to Domoticz.)''

=Installation instructions for the dzVents version=

Having configured the devices as described above, all that remains is to edit the configuration in the script below, and place it into your <tt>scripts/dzVents/scripts</tt> directory.

=dzVents Script with comments=
<source lang="lua">--
-- dzVents script to calculate oil tank levels
-- Based on https://www.domoticz.com/wiki/Lua_-_Oil_Tank_Monitor
-- David Woodhouse <dwmw2@infradead.org>
--

-- Input devices: Temperature and air gap above fluid in tank
--local tank_temp_sensor = 'Oil tank temperature'
local tank_temp_sensor = 'Gas Temperature (left)'
local depth_sensor = 'Oil level sensor'

-- Output devices: Percentage full, volume.
local pct_sensor = 'Oil level'
local volume_sensor = 'Oil'

-- To adjust for fluid expansion
-- Report volume/percentage as they would be at 10°C
local canon_temp = 10
-- Kerosene
local expansion_coeff = 1.00099

-- Tank dimensions
local tank_height = 120
local tank_area = 60 * 181

return {
on = {
devices = {
depth_sensor
}
},
execute = function(domoticz, device)
local depthdev = domoticz.devices(depth_sensor)
local tempdev = domoticz.devices(tank_temp_sensor)
local pctdev = domoticz.devices(pct_sensor)
local volumedev = domoticz.devices(volume_sensor)

local depth = depthdev.state
-- Calculate percentage and volume
local pct = (tank_height - depth) / tank_height * 100
local volume = (tank_height - depth) * tank_area / 1000

-- Adjust for fluid expansion
if tempdev ~= nil then
local temp = tempdev.state
local temp_delta = canon_temp - temp
local scale = expansion_coeff ^ temp_delta

-- temp_delta is how much colder the tank is than the canonical temperature
-- When the tank is colder, we scale *up* the reported volume to report it what it would be at 10°C
-- When the tank is warmer, we scale down.
-- domoticz.log('Scale factor ' .. scale .. ' for ' .. temp .. '°C delta ' .. temp_delta .. '°C', domoticz.LOG_INFO)
pct = pct * scale
volume = volume * scale
end
domoticz.log('Tank update to ' .. pct.. '% ' .. volume .. 'l', domoticz.LOG_INFO)
pctdev.updatePercentage(pct)

local prev_volume = volumedev.state + 0
volume = -volume
domoticz.log('Volume ' .. volume .. ' was ' .. prev_volume, domoticz.LOG_INFO)
-- Don't allow fluctuations to screw up the usage calculations. Only go up if it's been refilled.
if volume >= prev_volume or (volume < (prev_volume - 100)) then
-- domoticz.log('Raising volume from ' .. prev_volume .. ' to ' .. volume, domoticz.LOG_INFO)
volumedev.update(0, volume)
else
-- domoticz.log('Not reducing volume from ' .. prev_volume .. ' to ' .. volume, domoticz.LOG_INFO)
end
end
}

</source>

=Installation instructions for the Lua version=

Having configured the devices as described above, all that remains is to edit the configuration in the script below, and place it into your <tt>scripts/lua</tt> directory.

=Lua Script with comments=
<syntaxhighlight lang="lua">
------------------------------------------------------------------------------
--
-- Copyright © 2015 David Woodhouse <dwmw2@infradead.org> and released under
-- the GNU General Public License, v2 or later.
--
--
-- Domoticz lua script to convert ultrasonic tank monitor readings into
-- percentage and volume virtual sensors for fuel tanks.
--
-- Takes input from distance sensor measuring the air above the fluid, and
-- converts to percentage and volume using the dimensions of the tank as
-- configured below.
--
-- Optionally, to prevent fluctuation as the fluid expands/contracts with
-- temperature, can convert the output values to report what the percentage
-- and volume *would* be at a fixed temperature.
--
------------------------------------------------------------------------------
--
-- Input sensors don't *have* to be virtual; mine are because they're filled in
-- by an external script running rtl_433 and receiving Watchman Sonic transmissions
--
-- Add tank temperature sensor:
-- 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=80'
-- Add depth sensor:
-- 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=13'
--
------------------------------------------------------------------------------
-- Output sensors are virtual, fed solely by this script
--
-- Add percentage sensor:
-- 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=2'
--
-- Add tank volume:
-- 'http://localhost:8080/json.htm?type=createvirtualsensor&idx=1&sensortype=113'
-- 'http://localhost:8080/json.htm?type=setused&idx=5&name=Oil&switchtype=2&used=true'
--
------------------------------------------------------------------------------
--
-- Update depth:
-- 'http://localhost:8080/json.htm?type=command&param=udevice&idx=3&nvalue=0&svalue=59'
--
------------------------------------------------------------------------------

-- Input devices: Temperature and air gap above fluid in tank
tank_temp_sensor = 'Oil tank temp'
depth_sensor = 'Oil tank sensor'

-- Output devices: Percentage full, volume.
pct_sensor = 'Oil tank'
pct_sensor_id = 4
volume_sensor = 'Oil'
volume_sensor_id = 5

-- To adjust for fluid expansion
-- Report volume/percentage as they would be at 10°C
canon_temp = -10
-- Kerosene
expansion_coeff = 1.00099

-- Tank dimensions
tank_height = 120
tank_area = 60 * 181

-----------------------------------------------------------------------------------
commandArray = {}

if (devicechanged[depth_sensor] or devicechanged[tank_temp_sensor]) then
-- Use otherdevices_svalues[] because devicechanged[foo_Utility] is not
-- present when the value is zero
depth = otherdevices_svalues[depth_sensor]

-- Calculate percentage and volume
pct = (tank_height - depth) / tank_height * 100
volume = (tank_height - depth) * tank_area / 1000

-- Adjust for fluid expansion
tank_temp = otherdevices_svalues[tank_temp_sensor]
if (tank_temp ~= nil) then
temp_delta = tank_temp - canon_temp
scale = expansion_coeff ^ temp_delta
pct = pct * scale
volume = volume * scale
end

-- print(string.format("depth now %f; percentage %f %% volume %f l", depth, pct, volume))

commandArray[1] = {['UpdateDevice'] = pct_sensor_id .. "|0|" .. pct}
commandArray[2] = {['UpdateDevice'] = volume_sensor_id .. "|0|" .. volume}
end

return commandArray
</syntaxhighlight>

=Example of use (if relevant) i.e. output files / screen displays=

[[File:Oil.png||Domoticz displaying oil tank levels]]
[[Category:Lua]]
[[Category:DzVents]]
[[Category:Scripting]]

Lua / dzVents - Oil Tank Monitor - Revision history

Walter vl: Categories