In addition to the "wx" and "fc" weather objects, the weather plug-in (via wxjsondata.hap) also provides "hooks" to get status for other "custom" object types. You can also provide your own custom objects via another "custom" plug-in. Here's what is needed to do so:
get_update Procedure
The "custom" plug-in should provide a public (via hvPublic) get_update procedure that creates the object's state information. If the plug-in sees an events command with the object name in it, if will call get_update. Additionally, when the plug-in starts initially, it calls get_update to quickly get the object's initial status.
get_update {object_type}
Where:
- object_type
- If called with an object_type, get_update should create the object's state information only if object_type matches one of the objects that it supports. If called without an object_type, get_update should create the state information for all objects it supports.
Note 2: get_update doesn't return anything directly. However, it should trigger a call to wsupdate for each object it supports. See below for details of wsupdate.
Note 3: There can be more than one plug-in with a public get_update procedure. Calling the procedure will actually run the procedure in each plug-in that published it (via hvPublic).
Here is a simple example, as used in the Weather plug-in:
hvPublic get_update
proc get_update {{type wx}} {
if {$type in "wx fc"} {WeatherSetVar}
}
In this case, get_update calls WeatherSetVar, another procedure within the Weather plug-in,
if the object type is "wx", "fc", or null.
WeatherSetVar will fetch weather info according to its configuration
and eventually call wsupdate for "wx" and/or "fc", accordingly.
Note that unless the object type is present and does NOT match "wx" or "fc", state data for both "wx" and "fc" will be generated if they are both enabled in the Weather plug-in, regardless of
which is requested. This is OK since the only harm is that the plug-in may track unneeded object information.
</dd></dl>
wsupdate Procedure
The "custom" plug-in should call wsupdate. This public procedure is made available in the wxjsondata.hap plug-in. (It may also be available in other plug-ins that want object state data.) The "custom" plug-in generating object state information should import (via hvImport) the wsupdate procedure. The "custom" generating plug-in may call this procedure either because it was triggered by a previous call to get_update, or because a object's state has changed and needs to be reported. The wsupdate procedure takes the generated object state information and stores it for later use.Its format should be:
wsupdate object_type state_value_list
Where:
- object_type
- The object type being reported.
- state_value_list
- This is a list of object state information. one entry for each valid ID. Entries may be as simple as a numerical state value, e.g., "0" or "1" to indicate an object's state is clear or set, or may be more complex structures like a list of key-value pairs, e.g., {"tempf": 29, "dewpointf": 27}
Full Example of a Custom Object Plug-in
Here's an example of a plug-in that uses all of the above procedures. It creates an object "dm" which has only one ID ("0"). State information consists of two key-value pairs. For demonstration purposes, the values of these two keys are incremented each time the get_update procedure is called. Once started, it will simulate periodic (5 minute) state changes.
# Sample custom object generator plug-in
hvImport debug
hvImport wsupdate
set Wx(L) 1
set Wx(T) 100
hvPublic get_update dm
proc dm {{type dm}} {
global Wx
if {$type ne "dm"} {return}
lappend list [format {{"location": "%s", "temperature": "%s"}} \
$Wx(L) $Wx(T)]
wsupdate dm $list
incr Wx(L)
incr Wx(T)
after cancel dm
after 300000 dm
}
The dm object info can be added to the example from Weather Websockets, showing how weather and "custom" objects can be integrated into one web page (as can standard HomeVision objects):
<center>
<h3>Weather</h3>
<HV:Image png WeatherGetIcon id="icon">
<br>
<span id="wind"><HV:Run WeatherGet Wind></span>
<br>
<span id="fcloc"><HV:Run WeatherGet FcLoc></span>
<br>
<span id="fcday1"><HV:Run WeatherGet FcDay1></span>
<br>
<HV:Image png WeatherGetIcon FcImg1 id="iconfc1">
<br>
<span id="FcSc1"><HV:Run WeatherGet FcSc1></span>
<br>
dm T is <span id="dmt"></span>
<br>
dm L is <span id="dml"></span>
</center>
<script src="wxwebsocket.js" type="text/javascript"></script>
<script type="text/javascript">
hvobjs["wx"] = [
{
"element": document.getElementById("icon"),
"index": 0, "function": wxf, "type": "icon"
}, {
"element": document.getElementById("wind"),
"index": 0, "function": wxf, "type": "wind"
}
]
hvobjs["fc"] = [
{
"element": document.getElementById("fcloc"),
"index": 0, "function": fcf, "type": "loc"
}, {
"element": document.getElementById("fcday1"),
"index": 1, "function": fcf, "type": "day"
}, {
"element": document.getElementById("iconfc1"),
"index": 1, "function": fcf, "type": "img"
}, {
"element": document.getElementById("FcSc1"),
"index": 1, "function": fcf, "type": "sc"
}
]
hvobjs["dm"] = [
{
"element": document.getElementById("dmt"),
"index": 0, "function": wxf, "type": "temf"
}, {
"element": document.getElementById("dml"),
"index": 0, "function": wxf, "type": "location"
}
]
</script>
Note that for simplicity, this example uses the weather helper functions from wxwebsocket.js.
If the "custom" objects need unique helper functions,
then they should be included in a separate javascript file.
</dd>
</dl>
Next:
Weather Info for NetIO
Weather with MQTT
See Also:
Introduction to the Weather Plug-in
Web-Based Weather Data
Using Weather Control Variables
Forecast Examples
HomeVision Controller Weather Variables
Local Weather Data Files
Speaking Weather Data
Triggering Weather Fetches
Weather Websockets
Disclaimer