Description
The Virtual Rain Sensor is a device that activates or trips when it has rained or will rain. It does this by retrieving the past and future precipitation(rain, snow, sleet & hail) total for each day over a defined window of time and comparing the total to an adjustable threshold. When the threshold is exceeded the device will change state to “tripped” indicating that rain is detected. The intended application of this device is for suspending an automatic irrigation system when it has or will rain. The threshold value ensures that the irrigation will not be bypassed for instances of light rain and aims to maintain a minimum amount of moisture at the given location. For forecasted precipitation this device compares the Quantitative Precipitation Forecast(QPF) or the user may choose the Probability of Precipitation(PoP). A free account with the Weather Underground API is required for this plugin to operate. If you do not already have a key which is used for the weather plugin then follow instructions below.
Requirements\Limitations
[ul][li]Must have free developer key from Weather Underground API(see instructions below)[/li]
[li]Not all locations will have precipitation available or a weather station nearby[/li][/ul]
Version History
[ul][li]1.0 Initial Release[/li]
[li]2.0 Added settings tab to UI, combined API requests on update, and improved update scheduling.[/li]
[li]2.1 Committed correct icons[/li]
[li]2.2 Fixed stale ‘lastUpdate’ value(Fixed problem where multiple updates could be requested on the UI in 1 minute exceeding the limit)[/li]
[li]2.4 Fixed to allow personal weather stations as location. Current date synced to weather location NOT Vera system time. Dates displayed on UI are also synced with location and not local system time of web browser. (Any location can be entered in the world regardless of time zone and the UI can be displayed on a system with a different time zone and it will still show the correct dates)[/li]
[li]2.5 Fixed non-available forecast precipitation after the API changed. Corrected browser caching problem on UI. Improved error reporting so it defaults to an un-tripped state on a failed update.[/li]
[li]2.6 Corrected so negative precipitation values from personal weather stations will not create a negative total, but will show as “T” or “N/A”. Printed total precipitation on the dashboard.[/li]
[li]2.7 Added probability of precipitation device state variable for information only and not for decision making.[/li]
[li]2.8 Improved the cleanup and release of allocated memory.[/li]
[li]3.0 Added variable threshold calculated by evapotranspiration. Added option for PoP or QPF as forecasted rain trigger. Added trigger for when the current temperature is too low.[/li]
[li]3.1 Corrected problem with UI7 not displaying settings tab.[/li][/ul]
Weather Underground API Key Sign Up
You must obtain a free key for the Weather Underground API before you can use this plugin. If you already have a key setup with the Weather plugin then you may use that key for both plugins.
[ol][li]Go to Loading | Weather Underground
[li]Under “Create Your Free Account!”, enter your email and choose a password(used only during setup).[/li]
[li]Pick an arbitrary handle(not used but required) and then click “Sign Up”. A confirmation email is sent.[/li]
[li]Open the confirmation email from the email address you used to sign up.[/li]
[li]Click the link in the email.[/li]
[li]On the webpage that loads, under “Already have a wunderground.com account?”, enter your email and password you picked then click “Login”.[/li]
[li]On the webpage that loads, click “Explore My Options”.[/li]
[li]On the webpage that loads, click “Purchase Key”. Note the cost of $0 USD per month.[/li]
[li]On the webpage that loads, fill out the form and click “Purchase Key”.[/li]
[li]On the webpage that loads, your API key is located in the field “Key ID”, save this key for later.[/li][/ol]
Installation
[url=http://apps.mios.com/plugin.php?id=6366]MiOS Apps
API Requests
The Weather Underground API developer key only allows 500 calls per day and no more than 10 calls in one minute. Use these equations below to calculate the number of requests this plugin will generate. Note that it is not possible to exceed either one of these conditions with this plugin alone.
Maximum API requests in 1 min: = 1 + (daysInPast - 1)
Minimum API requests in 1 day: = ( 24 hours / hoursBetweenUpdate ) + daysInPast - 1
Icon State
Grey Raindrop: No rain detected, “Not tripped”, total precipitation below threshold
Blue Raindrop: Rain detected, “Tripped”, total precipitation above threshold
Variables
urn:upnp-org:serviceId:VRainSensor
Inputs
Key: Weather Underground API key
Location: Site to monitor precipitation, formats may be “lat,long” or 5-digit zip code
MetricUnits(0 or 1): Sets metric or english units, “1” for metric units and “0” for english units
[u]DaysInPast/u: Number of days in the past, including today, to add the accumulated precipitation in the total
[u]DaysInFuture/u: Number of days in the future, including today, to add the forecasted precipitation in the total
Threshold: Value to determine tripped state from precipitation total, in units of inches or millimeters
[u]HoursBetweenUpdate/u: Number of hours until the next update will occur
[u]LandscapeCoefficient/u: Evapotranspiration crop coefficient sets the water demand of plants in landscape (0=Use fixed threshold)
LowTempCutoff: Temperature threshold in Celsius or Fahrenheit that the “Tripped” state occurs when the current temperature falls below
[u]PoPThreshold/u: Percentage of PoP that will trigger the “Tripped” state (0=Use QPF instead of PoP)
Outputs
PrecipitationTotal: Total amount of precipitation over the defined past and future days
ForecastedPrecip: CSV(Comma Separated Value) string of the QPF(Quantitative Precipitation Forecast) for each day
PastPrecip: CSV string of the precipitation total for each day in the past
ProbabilityOfPrecip: CSV string of the probability of precipitation for each day
TodaysDate: Current date in format ‘MM/DD/YYYY’
DataSource: Weather Underground Station id used to get accumulated precipitation(past and present)
PastEvapotranspiration: CSV string of the evapotranspiration for each day in the past
FutureEvapotranspiration: CSV string of the evapotranspiration for each day in the future
urn:micasaverde-com:serviceId:SecuritySensor1
Armed: Armed state of the device, “1” for armed and “0” for bypassed
Tripped: Tripped state of the device, “1” for precip total above threshold and “0” for precip total below threshold
LastTrip: Unix epoch time when “Tripped” last transitioned from “0” to “1”
urn:micasaverde-com:serviceId:HaDevice1
LastUpdate: Unix epoch time when data and tripped state last updated
Triggers
Since version 3.0 there are 3 different trigger options. These are OR logic so it only requires one condition to be true for the sensor to trip to a “1” state and all conditions must be false for it to reset to “0” state.
-
Total Precipitation Threshold
1a. Fixed amount - A constant threshold that does not change over time
1b. Evapotranspiration - Threshold is continually set equal to the total evapotranspiration for the given period. The Evapotranspiration landscape coefficient allows for adjusting to various types of crops/plants that have different amount of water demands. - Forecast Method - There are two modes; When QPF is selected the QPF is added to the total precipitation and PoP is ignored. When a PoP threshold is selected then QPF is ignored and the forecast is triggered by only PoP.
- Low Temp Cutoff - Threshold where the sensor will trip to a “1” state when the current temperature drops below the threshold.
Settings
The following table shows the relationships between the length of the window(number of days in the past and future) and the level of the threshold.
Short Window, Low Threshold: Sensitive to small amounts of rain in one day(quick to set, quick to reset)
Short Window, High Threshold: Sensitive to large amounts of rain in one day(quick to set, quick to reset)
Long Window, Low Threshold: Sensitive to small amounts of rain in one day(quick to set, slow to reset)
Long Window, High Threshold: Sensitive to small amounts of rain over several days(slow to set, quick to reset) or a large amount of rain in one day(quick to set, slow to reset)
One caution I would add about choosing settings is the potential for the sensor to remain tripped when there is rain potential that is over the threshold reoccurring for several days, but there is actually no or little rainfall. Logic could be added to escape this condition, but for now I would just like to see if it is really necessary. Setting a high enough threshold and a shorter forecast window should minimize the condition from occurring.
Usage In Scene
Add a trigger and choose the Virtual Rain Sensor device
A sensor is tripped
Device is tripped: fired when total precipitation above threshold
Device is not tripped: fired when total precipitation below threshold
An armed sensor is tripped
Device armed is tripped: fired when armed and total precipitation above threshold
Device armed is not tripped: fired when armed and total precipitation below threshold
Usage In Luup Code
Here are some Luup code examples to display possible uses. In each example the device number is assumed to be 99 and will need to be changed to your device number. These are just examples so other parameters may need to be tweaked to fit your needs.
Input Examples
[code]–Arm
luup.call_action(“urn:micasaverde-com:serviceId:SecuritySensor1”, “SetArmed”, {newArmedValue=“1”}, 99)
–Bypass
luup.call_action(“urn:micasaverde-com:serviceId:SecuritySensor1”, “SetArmed”, {newArmedValue=“0”}, 99)
–Force an update of the forecast
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “Update”, {}, 99)
–Change to english units
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetMetric”, {newMetricValue=“0”}, 99)
–Change to metric units
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetMetric”, {newMetricValue=“1”}, 99)
–Change the weather underground API key to use “abcd1234”
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetKey”, {newKeyValue=“abcd1234”}, 99)
–Change location to use zipcode “12345”
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetLocation”, {newLocationValue=“12345”}, 99)
–Change the number of days to look in the past(including today) to 5
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetDaysInPast”, {newDaysInPastValue=“5”}, 99)
–Change the number of days to look in the future(including today) to 4
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetDaysInFuture”, {newDaysInFutureValue=“4”}, 99)
–Change the total precipitation threshold to 0.56
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetThreshold”, {newThresholdValue=“0.56”}, 99)
–Change the update interval to 6 hours
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetHoursBetweenUpdate”, {newHoursBetweenUpdateValue=“6”}, 99)
–Change the landscape coefficient to 0.6 (will also change to variable threshold)
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetLandscapeCoefficient”, {newLandscapeCoefficientValue=“0.6”}, 99)
–Change the landscape coefficient to 0 (will also change to fixed threshold)
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetLandscapeCoefficient”, {newLandscapeCoefficientValue=“0”}, 99)
–Change the Probability of precipitation threshold to 60% (will stop using QPF for forecasted rain)
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetPoPThreshold”, {newPoPThresholdValue=“60”}, 99)
–Change the Probability of precipitation threshold to 0% (will start using QPF for forecasted rain)
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetPoPThreshold”, {newPoPThresholdValue=“0”}, 99)
–Change the low temperature cutoff to -10 degrees
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “SetLowTempCutoff”, {newLowTempCutoffValue=“-10”}, 99)[/code]
Output Examples
1. Make decision based on rain or no rain detected
[code]–Force update(this step optional)
luup.call_action(“urn:upnp-org:serviceId:VRainSensor”, “Update”, {}, 99)
–Get current state
local tripped = luup.variable_get(“urn:micasaverde-com:serviceId:SecuritySensor1”,“Tripped”, 99)
if tripped == “0” then
–Do not tripped logic here
–Precipitation not detected, total precipitation below threshold
end
if tripped == “1” then
–Do tripped logic here
–Precipitation detected, total precipitation above threshold
end[/code]
2. Retrieve total precipitaion
--Get total precipitation in past and future
local precipitationTotal = luup.variable_get("urn:upnp-org:serviceId:VRainSensor","PrecipitationTotal", 99)
3. Create a lua table containing the precipitation for each day in the past
[code]–Convert CSV string to a lua table(
function csvToTable(csvString)
local t={}
local i=1
for str in string.gmatch(csvString, “([^, ]+)”) do
t[i] = str
i = i + 1
end
return t
end
–Assume device id of Virtual Rain Sensor is 99
local deviceId = 99
–Get past precipitation as CSV string
local pastPrecipCSV = luup.variable_get(“urn:upnp-org:serviceId:VRainSensor”,“PastPrecip”,deviceId)
–Convert CSV string to a lua table
local pastPrecipTable = csvToTable(pastPrecipCSV)
–Number of elements in table
local tableSize = #pastPrecipTable
for day = 1, tableSize do
–Get past precip for each day
local precipForOneDay = pastPrecipTable[day]
end[/code]