.. Wattsworth documentation master file, created by sphinx-quickstart on Tue Aug 1 11:55:55 2017. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. highlight:: bash The Wattsworth Project ====================== Collect, process, and visualize IoT sensor data. .. NOTE:: * See `joule `_ for information on the backend interface (CLI) * See `web `_ for information on the frontend interface (user facing) Unlike traditional IoT solutions, Wattsworth is a confederation of self sufficient nodes. Each node collects, processes and stores its own data and provides a web interface to visualize the data. For many situations a single node can solve your problem. For more complex sensor networks multiple nodes can be combined into a mesh or a client-server architecture. 1. **Data Collection** Collect and store time series data 2. **Data Processing** Build flexible signal processing pipelines. 3. **Data Visualization** View data using an intuitive web interface Follow the instructions below to set up a node and start using Wattsworth. Step 0: Install +++++++ On a fresh Ubuntu installation (>= 16.04) run the following to install the Wattsworth software stack:: $> sudo apt-get update $> sudo apt-get install puppet git $> git clone https://git.wattsworth.net/wattsworth/puppet.git $> cd puppet $> sudo puppet apply --modulepath=./modules --verbose site.pp Step 1: Generate Data +++++++++++++++++++++ Wattsworth's data processing engine is called Joule. Joule works with Streams and Modules. Streams are sets of time series data (eg temperatures, voltages, accelerations, etc). Modules are executable programs that read and write to streams. There are two types of modules: readers and filters. Readers collect external data (eg sensor readings) and write it to a stream. Let's start by creating a reader that produces a stream of random data. Copy the following to ``/etc/joule/module_configs/random_reader.conf``:: [Main] exec_cmd = joule reader random 2 10 name = Demo Reader [Source] # a reader has no inputs [Destination] output = /demo/random This file tells Joule to create a new module called **Demo Reader** that is started by the command ``joule reader random 2 10``. The random reader is a built-in reader provided by Joule. It takes two command line arguments, the number of elements to "read" and the range of random numbers. In this case we are producing a two element stream of random numbers ranging from [0, 10]. Try running the module from the command line:: # output columns: timestamp (us), element1, element2 $> joule reader random 2 10 Starting random stream: 2 elements @ 10.0Hz 1504275719114302 0.52250357475642772 0.27410492447391688 1504275719214302 0.3504811731191021 0.60611860137921958 1504275719314302 0.16871102294606499 0.26205382675613365 #... output continues, type Ctrl-C to stop When Joule runs this program as a module this output is written to a stream. The configuration file specifies this output stream is ``/demo/random``. Before we can start writing data to this stream we have to create it. To do this copy the following to ``/etc/joule/stream_configs/random.conf`` .. code-block:: ini [Main] name = Random Data path = /demo/random datatype = float32 keep = 1w [Element1] name = rand1 [Element2] name = rand2 Every stream must have a unique ``path`` similar to a file on a filesystem. The ``keep`` parameter tells Joule to save only the most recent week of data. This prevents our disk from filling up. Next we list the elements in this stream. This stream has two elements named *rand1* and *rand2*. Now we are ready to start collecting data. From the terminal restart the Joule process to activate our new module:: $> sudo service jouled restart $> joule modules # show the active modules View the Data +++++++++++++ Open a browser and navigate to http://wattsworth.local. Log in as **admin@wattsworth.local** with password **password**. From the main window click the gear icon next to the local installation. This opens the administration view (see ``admin help`` for more details). Click ``[Refresh]`` and the new data stream should appear in the file tree on the left. Navigate back to the main page (click the header logo or use the browser back button) and expand the file tree until you see the new stream. Click ``[Plot]`` and it should display in the main window. See ``web help`` for information on plotting data. Add a Filter Module +++++++++++++++++++ Modules can be connected together to build flexible data acquisition and signal processing pipelines. There are two types of modules, readers and filters. Reader modules collect data. This data can come from local sensors, remote IoT nodes, third party API's or any other source. Let's start simple and create a reader module that produces random data. Filter modules process data generated by readers or by other filters. Filters store their results into one or more output streams. Copy the following to ``/etc/joule/stream_configs/averaged.conf`` to allocate a new stream:: .. code-block:: ini [Main] name = Averaged Data path = /demo/filtered datatype = float32 keep = 1w [Element1] name = filtered1 [Element2] name = filtered2 From the terminal restart the Joule process to activate the filter:: $> sudo service jouled restart $> joule modules # show active modules View the Data +++++++++++++ From the web browser, go back to the administration view and refresh the database. You should now see two streams. Back in the data view plot both streams. The filtered stream should be the average of the random stream. Contributing ------------ .. toctree:: :maxdepth: 2 :caption: Contents: installation configuration plugins