Getting Started

Joule is part of the Wattsworth software stack. See http://wattsworth.net/install.html for installation details. Before continuing make sure Joule is installed and the database is accessible:

Command Line:
$> joule --version joule 0.1.5 $> nilmtool info Client version: 1.10.3 Server version: 1.10.3 #... more output

This guide will step through the implementation of the two stage pipeline shown below:

_images/getting_started_pipeline.png

The Reader Module

The first module is a data reader. Reader modules “read” data into the Joule pipeline. This data can come from embedded sensors, HTTP API’s, system logs, or any other timeseries data source.

Our reader will simply produce random values. Joule provides a built-in module specifically for this purpose. Stubbing pipeline inputs with a random data source can simplify unit testing and expose logic errors. See the Module Documentation page for more details on this and other Joule modules.

Try out random on the command line:

Command Line:
$> joule-random-reader -h # ... module documentation (available at http://docs.wattsworth.net/modules) $> joule-random-reader --width 2 --rate 10 1485188853650944 0.32359053067687582 0.70028608966895545 1485188853750944 0.72139550945715136 0.39218791387411422 1485188853850944 0.40728044378612194 0.26446072057019654 1485188853950944 0.61021957330250398 0.27359526775709841 # output continues, hit ctrl-c to stop

Now let’s add this module to our pipeline. We need to create a module configuration file to tell Joule how to execute the module and where to connect its output. To do this create the following file:

/etc/joule/module_configs/demo_reader.conf
[Main] exec_cmd = joule-random-reader name = Demo Reader [Arguments] width = 2 rate = 10 [Inputs] # a reader has no input streams [Outputs] output = /demo/random

This connects the module to a stream called /demo/random. For more details on the configuration format see Modules. Joule will generate an error if a module is connected to an unconfigured stream. Configure the stream by creating the following file:

/etc/joule/stream_configs/random.conf
[Main] name = Random Data path = /demo/random datatype = float32 keep = 1w [Element1] name = rand1 [Element2] name = rand2

The stream configuration file specifies what kind of data the stream holds and how long to store it in the database. For more details on the configuration format see Streams.

Now the pipeline is ready to execute. Restart joule and check that the new module is running:

Command Line:
$> sudo service jouled restart # check status using the joule CLI $> joule modules +-------------+---------+--------------+---------+-----+ | Module | Inputs | Outputs | Status | CPU | +-------------+---------+--------------+---------+-----+ | Demo Reader | | /demo/random | running | 0% | +-------------+---------+--------------+---------+-----+ $> joule logs "Demo Reader" [27 Jan 2017 18:05:41] ---starting module--- [27 Jan 2017 18:05:41] Starting random stream: 2 elements @ 10.0Hz # confirm data is entering NilmDB $> nilmtool list -E /demo/random /demo/random interval extents: Fri, 27 Jan 2017 # ... total data: 1559 rows, 155.700002 seconds

The Filter Module

Now let’s add a filter to smooth out the random data produced by the reader. Joule provides a built-in moving average filter, mean, that does exactly this. See the Module Documentation page for more details on this and other Joule modules.

Joule filters can execute as standalone programs but require extra configuration to do so because they can have multiple inputs and outputs. For now let’s just run it in the Joule environment. To add the module to the pipeline create the following file:

/etc/joule/module_configs/demo_filter.conf
[Main] exec_cmd = joule-mean-filter name = Demo Filter [Arguments] window = 11 [Inputs] input = /demo/random [Outputs] output = /demo/smoothed

The input stream is already configured. The output will have the same datatype and number of elements. To configure this stream create the following file:

/etc/joule/stream_configs/smoothed.conf
[Main] name = Filtered Data path = /demo/smoothed datatype = float32 keep = 1w [Element1] name = filtered1 [Element2] name = filtered2

Now the pipeline is fully configured. Restart joule and check that both modules are running:

Command Line:
$> sudo service jouled restart # wait a few seconds then check status using joule CLI $> joule modules +-------------+--------------+----------------+---------+-----+ | Module | Inputs | Outputs | Status | CPU | +-------------+--------------+----------------+---------+-----+ | Demo Reader | | /demo/random | running | 0% | | Demo Filter | /demo/random | /demo/smoothed | running | 0% | +-------------+--------------+----------------+---------+-----+ $> joule logs "Demo Reader" [27 Jan 2017 18:22:48] ---starting module--- $> joule logs "Demo Filter" [27 Jan 2017 18:22:48] ---starting module--- # confirm data is entering NilmDB $> nilmtool list -E -n /demo/* /demo/filtered interval extents: Fri, 27 Jan 2017 # ... total data: 132 rows, 13.100001 seconds /demo/smoothed interval extents: Fri, 27 Jan 2017 # ... total data: 147 rows, 14.600001 seconds

Next Steps

For more details on modules and streams read Using Joule or visit the Lumen Documentation to start visualizing your data.