Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Graphs with RRD4J
RRD4J is a high performance data logging and graphing system for time series data, implementing RRDTool's functionality in Java. It follows much of the same logic and uses the same data sources, archive types and definitions as RRDTool does.
OpenRemote is now integrating this logging and graphing system and your sensors information can now be stored and graphically displayed on your panels.
A RRD4J Tutorial can be found here
Only Sensor data can be stored in the RRD4J Database.
OpenRemote is using the WebElements to display the graphics. Make sure your device can display the WebElement
This tutorial is splitted in 3 steps:
- Creating and configuring the RRD4J Database
- Displaying graphics
- Advanced feature: dynamically changing the graphic timeframe
Creating and configuring the RRD4J Database
In order to display graph, you need to have some data to be displayed. RRD4J is storing the data on Round Robin Database (RRD) files. This RRD file is automatically created by OpenRemote following your RRD4J configuration.
The configuration file is located within your controller in the folder "rrd/rrd4j-config.xml".
This configuration file is composed of two main section:
- The data definition
- The graph definition
Here is a example of such a config file with 2 sensors:
<?xml version="1.0" encoding="UTF-8"?> <rrd4j xmlns="http://www.openremote.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openremote.org http://www.openremote.org/schemas/rrd4j.xsd"> <rrdDB fileName="test.rrd" step="60"> <datasource name="Temp SDB" type="GAUGE" heartbeat="120" /> <datasource name="Temp CH7" type="GAUGE" heartbeat="120" /> <archive function="AVERAGE" xff="0.5" steps="1" rows="300" /> <archive function="AVERAGE" xff="0.5" steps="10" rows="144" /> <archive function="AVERAGE" xff="0.5" steps="15" rows="672" /> <archive function="AVERAGE" xff="0.5" steps="60" rows="744" /> <archive function="AVERAGE" xff="0.5" steps="120" rows="4380" /> </rrdDB> <rrd_graph_def name="graph2"> <options> <vertical_label>Temp (°c)</vertical_label> <title>YPH RRD4J Example</title> </options> <datasources> <def> <name>Temp_SDB</name> <rrd>test.rrd</rrd> <source>Temp SDB</source> <cf>AVERAGE</cf> </def> <def> <name>Temp_CH7</name> <rrd>test.rrd</rrd> <source>Temp CH7</source> <cf>AVERAGE</cf> </def> </datasources> <graph> <line> <datasource>Temp_SDB</datasource> <color>#FF0000</color> <legend>Temp Salle de Bain\r</legend> <width>2</width> </line> <line> <datasource>Temp_CH7</datasource> <color>#0000FF</color> <legend>Chambre Astrid\r</legend> <width>2</width> </line> <comment>This chart displays OR sensor values.</comment> </graph> </rrd_graph_def> </rrd4j>
Here is the resulting graph that RRD4J will generate :
The data Definition
This section of the RRD4J configuration file describes which data to store in the RRD file and how to store them.
The RRD file creation parameters:
- 'filename': the name of the RRD file that will be created by OpenRemote within your controller in the folder "rrd"
- 'step' : The RRD Time step in seconds
The Data source parameters:
- 'name' : This value must be the exact name of the OpenRemote sensor you'd like to log. The name is limited to 20 characters!
- 'type': This is the type of the datasource values. ABSOLUTE Is for counters which get reset upon reading. COUNTER Is for continuous incrementing counters like the ifInOctets counter in a router. DERIVE Will store the derivative of the line going from the last to the current value of the data source. GAUGE Is for things like temperatures or number of people in a room or the value of a RedHat share.
- 'heartbeat' : This is usually twice the value of the RRDDB step.
The archive parameters :
ToDO ....(see RRDTool original author Tobias Oetiker's documentation)
NOTE: If you change/add data sources, you must stop the controller and remove the RRD files (test.rrd)
##The graph definition
This section of the RRD4J configuration file describes what data will be part of the graph and this graph will look like.
<rrd_graph_def name="graph2"> <options> <vertical_label>Temp (°c)</vertical_label> <title>YPH RRD4J Example</title> </options> <datasources> <def> <name>Temp_SDB</name> <rrd>test.rrd</rrd> <source>Temp SDB</source> <cf>AVERAGE</cf> </def> ... </datasources> <graph> <line> <datasource>Temp_SDB</datasource> <color>#FF0000</color> <legend>Temp Salle de Bain\r</legend> <width>2</width> </line> ... <comment>This chart displays OR sensor values.</comment> </graph>
The RRD graph definitions parameters are:
- 'name': The name of the graph. This is the graph name that you're going to call from your OpenRemote panel
The graph definition is compound of 3 main parts:
graph definition - options
The "options" section lets you defined some optional information on your graph like axis labels, title, units, color, grid, log scale, fonts, ...
graph definition - datasources
This section create the link between the datesource you've stored in your RRD4J database and the ones to display in the graph. There are several ways to create a graph datasource definition. You could create a datasource by evaluating a mathematical expression, ...
In our tutorial, for each datasource you'd like to display, its definition parameters are:
- 'name': the id of your graph datasource definition within this graph definition. It can be different from the name of that datasource stored into your RRD DB or from your OpenRemote Sensor
- 'rrd': from which RRD Database the data source come from?
- 'source': one of the datasource you've created in your RRD Database
- 'cf': one of the available consolidation function:
- AVERAGE The average of the data points is stored.
- FIRST The fist data point is used.
- LAST The last data point is used.
- MAX The largest of the data points is stored.
- MIN The smallest of the data points is stored.
- TOTAL The total of the data points is stored.
graph definition - graph
What needs to be part of main graph area like lines, areas, stack, hrule, vrule, ... a sample definition of those is provided here In this tutorial, we're displaying the datasource using a line representation. In that case, the parameters are:
- 'datasource': the graph datasource definition to be used
- 'width' of the line
- 'color' of the line (see here for color map)
- 'legend' of the line
The graph could be seen at the URL generated by OpenRemote:
IP= is the IP address or DNS name of your controller followed by the port number. For testing you can quickly see your results by entering the following shorter URL in your browser
This shows your collected data since 2014-01-31 13:01h.
In order to view it in the OpenRemote panel, we're going to use the Web View element of OpenRemote. There are two ways to use the Web View element:
- either you enter directly the URL as parameter or
- you link the Web View element to a sensor and the sensor will provide to URL to the Web View element. We're going to create such a sensor for the RRD4J Graph. The benefit of this approach is that web view will be refreshed if your sensor changes.
Creating the RRD4J Commands
Optional: Create a new device to group all RRD4j commands
Create a new command to call the controller in order to get the URL of RRD4J graph. Named it i.e.'GetRRDGraphURL' and select the 'RRD4J Graph URL' protocol. Fill-in the following parameters:
- graph name as defined in your RRD4J configuration file
- start / end date with format yyyymmdd-hh-mm
- width / height of the graph to display
- command: 'getURL'
Now that the command exists, defined a sensor linked to that command
That's it for the building modeler side, now go the panel design part of the online designer.
Designing the panel
To display the graph, we're going to use Web View element from the widget list. Note however if you are using the Android Console and this does not work, please try using an Image connected to the RRD4J sensor instead.
Select it and drop it into your panel. You can set some properties like width, height, ... the URL can be empty but don't forget to link the Web View element to the RRD4J sensor.
That's it! you can now display your graph within your prefered panel.
##Advanced feature: dynamically changing the graphic timeframe
One nice feature of the RRD4J implementation within Openremote is that you can dynamically change the time period of the graph your displaying. you can increase/decrease the start/end date of the graph and it will be refreshed in your web view element.
To do so, the RRD4J protocol supports several commands:
startPlus1Year: this command will increase the start date by 1 year
startPlus1Month: this command will increase the start date by 1 month
startPlus1Day: this command will increase the start date by 1 day
startPlus1Hour: this command will increase the start date by 1 hour
startMinus1Year: this command will decrease the start date by 1 year
startMinus1Month: this command will decrease the start date by 1 month
startMinus1Day: this command will decrease the start date by 1 day
startMinus1Hour: this command will decrease the start date by 1 hour
You've got also the same 8 command for the end date, so:
endPlus1Year: this command will increase the end date by 1 year
endPlus1Month: this command will increase the end date by 1 month
endPlus1Day: this command will increase the end date by 1 day
endPlus1Hour: this command will increase the end date by 1 hour
endMinus1Year: this command will decrease the end date by 1 year
endMinus1Month: this command will decrease the end date by 1 month
endMinus1Day: this command will decrease the end date by 1 day
endMinus1Hour: this command will decrease the end date by 1 hour
The following commands can be used to reset the time axis:
Commands below are only available in version Pro 1.2.0 and above
- resetStart: Reset start time
- resetEnd: Reset end time
- resetStartEnd: - Reset both start and end times
Create a new Command and setup the properties
- Name: the name of the OpenRemote command within the Online Designed protocol
- graph name: need to be the one defined in your RRD4J configuration file
- command: one of the RRD4J command to change the start-end date
In example for the "StartPlus1Month" command:
You can of course create a command for each of those 16 RRD4J commands
Now, let's have a look at one basic way to use them on the design side. The target of this tutorial is to achieve the following design result:
First of all, if you'd like to control that the command are working, you could add a new label on your panel and link it to RRD4J sensor. Like this your RRD4J URL will be displayed and refreshed each time it's changing.
Now you can create a button to trigger one RRD4J command. Drop a button on your panel, setup some properties, width, heigth, give it a label and link the button command property to one of the created RRD4J command by selecting it from the selection tree.
You can repeat that command button creation for each of the RRD4J command.
Here is a screenshot of the achieve results on iPAD:
A public template has been created with that panel
name: RRD4J Graph keywords: RRD4J Graph