-
Notifications
You must be signed in to change notification settings - Fork 1
Module thc_Rrd
This module implements an interface to the RRD database. It provides functions to log and plot device states.
It requires the Tcl package 'Rrd' or the standalone tool 'Rrdtool'. If both the package and the standalone tool are not available all thc_Rrd commands are simply ignored by THC.
Creates or opens an RRD database. This command is a wrapper of the RRDTool create function, using a simplified syntax. If the database doesn't exist it will be created. The round robin archives of the database are specified via the -rra option. All declared devices are automatically added to the database.
If a RRD database already exists it will be extended with eventually added new devices if the standalone RRD tools is installed.
If the standalone RRD tool is not available an existing RRD database needs fit exactly the set and order of the defined devices. To add in this situation new devices or to change the order of the defined devices the existing database needs to be deleted manually.
| Parameters | Description |
|---|---|
| -file <RrdFile> | The name of the RRD database file to open or to create |
| -step <Step> | Specifies the base interval in seconds with which data will be fed into the RRD. This argument corresponds to the --start parameter of the 'rrdcreate' RRD library command. |
| -rra {StepS NbrRow} | Specifies a round robin archive for MAX and AVERAGE values. The two provided elements of the list specify the step time (in seconds) and the number of rows. This argument can be repeated to specify multiple round robin archives. |
-
The following example opens or creates an RRD database that contains 3 MAX and AVERAGE archives :
thc::Rrd::Open -file /var/thc/thc.rrd -step 60 \
-rra [list 1 [expr 26*60]] \
-rra [list 5 [expr 33*24*12]] \
-rra [list 60 [expr 358*24]]
This example runs the following command under the hood :
thc::Rrd::create /var/thc/thc.rrd --step 60 --start 1409169540 \
DS:Surveillance_state:GAUGE:120:U:U \
DS:MotionSalon_state:GAUGE:120:U:U \
DS:LightSalon_state:GAUGE:120:U:U \
DS:TagReader1_battery:GAUGE:120:U:U \
... \
RRA:MAX:0.5:1:1560 RRA:AVERAGE:0.5:1:1560 \
RRA:MAX:0.5:5:9504 RRA:AVERAGE:0.5:5:9504 \
RRA:MAX:0.5:60:8592 RRA:AVERAGE:0.5:60:8592
thc::Rrd::Log, thc::Rrd::Graph, RrdCreate documentation on http://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html
Logs the devices states. This command calls the RRDTool update function. The states of all declared devices is written to the opened RRD database.
For devices that have a sticky state, this sticky state is written instead of the instantaneous state. The sticky states has usually to be cleared with thc::ResetStickyStates after having logged them by thc::Rrd::Log.
-
thc::Rrd::Log; thc::ResetStickyStates
thc::Rrd::Open, thc::Rrd::Graph, thc::ResetStickyStates, RrdUpdate documentation on http://oss.oetiker.ch/rrdtool/doc/rrdupdate.en.html
Generates a graph picture. This command calls the RRDTool graph function. The -type option allows specifying if the graphs have to be plotted overlaying (analog values), or if they have to be stacked (digital values).
The graph formats are controlled via the -rrd_arguments option that is directly forwarded to the underlying rrdgraph command.
Finally, the devices that have to be plotted are provided as remaining arguments. See the example below that shows how device groups can be built with the 'array names' command that is applied on the GetDeviceCommand array variable.
By specifying a dummy device the generated images can be displayed on the website (see thc::DefineDevice).
| Parameters | Description |
|---|---|
| -file <PictureFile> | The name and path of the graph file to generate. It is recommended to end this in .png, .svg or .eps. |
| -type binary|analog | Specifies the type of the plotted values. Analog values (default) are plotted overlaying. Digital values are plotted stacked. |
| -rrd_arguments <RrdGraphOptions> | The options provided in this list are directly forwarded to the rrdgraph command. For details consult the rrdgraph documentation. |
| <Device> <Device> ... | List of devices to plot. A device can be specified by a 2 element list. The first element is in this case the device name, and the second element a scale RPN expression (see references) |
-
Plot of binary device states:
thc::Rrd::Graph \
-file $::LogDir/thc.png \
-type binary \
-rrd_arguments [list \
--title "Surveillance and Alarm Activities - [clock format $Time -format {%A, %Y.%m.%d, %H:%M:%S}]" \
--x-grid MINUTE:10:HOUR:1:HOUR:3:0:%b%d,%Hh \
--alt-autoscale \
--end $Time --start end-26h --step 60 --height 300 --width 1560] \
Surveillance,state Alarm,state AllLights,state \
{*}[lsearch -all -inline $DeviceList Motion*,state] \
{*}[lsearch -all -inline $DeviceList Window*,state] \
{*}[lsearch -all -inline $DeviceList Light*,state]
Plot of analog device states :
thc::Rrd::Graph \
-file $::LogDir/thc_bat.png \
-type analog \
-rrd_arguments [list \
--title "Battery level - [clock format $Time -format {%A, %Y.%m.%d, %H:%M:%S}]" \
--vertical-label "Battery level (%)" \
--x-grid MINUTE:10:HOUR:1:HOUR:3:0:%b%d,%Hh \
--alt-autoscale \
--end $Time --start end-26h --step 60 --height 300 --width 1560] \
{*}[lsearch -all -inline $DeviceList *,battery]
Plot two analog device states with different scales :
thc::Rrd::Graph \
-file $::LogDir/thc_env.png \
-type analog \
-rrd_arguments [list \
--title "Temperature and Humidity - [clock format $Time -format {%A, %Y.%m.%d, %H:%M:%S}]" \
--vertical-label "Temperature (C)" --right-axis-label "Humidity (%)" \
--x-grid MINUTE:10:HOUR:1:HOUR:3:0:%b%d,%Hh \
--right-axis 5:-35 --alt-autoscale \
--end $Time --start end-26h --step 60 --height 300 --width 1560 \
Living,temp {Living,hum ",35,+,5,/"}
Display the generated image in the website: Use a dummy device :
thc::DefineDevice Battery,26hours \
-name Battery -group "Graphs 26 hours" \
-type image -data $::LogDir/thc_bat.png
thc::Rrd::Open, thc::Rrd::Log, RrdGraph documentation on http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html, Rrd RPN documentation on http://http://oss.oetiker.ch/rrdtool/doc/rrdgraph_rpn.en.html
THC, Tight Home Control - See THC index register - THC repository on github.com/Drolla/thc