Home

Please see http://docs.sense.sics.se

This page contains introductory documentation on running your own instance of the SicsthSense Engine.

For users of the SicsthSense system there is a tutorial.

This Github repository contains the code for the SicsthSense web interface and the backend engine. The Engine is the code for running a server to store IoT sensor data. Here you can find details on how to install, interact with and modify the code of SicsthSense. The code is all released under the Modified BSD License, so feel free to fork and modify. If you would simply like to use our publicly available instance of SicsthSense at http://sense.sics.se or http://presense.sics.se, then please look at the examples of interactions.

Running your own instance

Download the code:

$ git clone https://github.com/sics-iot/sicsthsense.git

In the downloaded sicsthsense directory, you should run the INSTALL script to initialise the database and place config files in the correct place:

$ sh INSTALL.sh

To build the SicsthSense Engine, change into the sicsthsense/engine directory, use Maven (allowing automatic dependency management for the 3rd party libraries) to build it:

$ ./build.sh

There must be an SQL server for storage, we recommend MySQL, the database initialisation can be easily performed by applying the buildDB.sql file: cat buildDB.sql | mysql -u root -p.

Run the packaged .jar file in the engine directory:

$ ./run.sh

Now you have the SicsthSense up and running! There should be an HTTP server running on port 8080. Visiting this with a web browser should confirm it. From here you may authenticate using OpenID or a username/password combination. To interact with the server please see our examples page. This Wiki also contains a breakdown of the codebase

Technology

The Engine is a Java implementation of a RESTful HTTP server representing the SicsthSense cloud presence.

It uses DropWizard, which is a distribution of popular Java frameworks (Jetty,Jersey, Jackson, JDBI, slf4j, etc.). Other external libraries used include: Atmosphere (for websockets). And a MySQL server for the data storage.

Interacting with the engine

All entities in the SicsthSense system follow a RESTful resource orientated architecture. For example user 1 may be accessed from the URL: http://HOSTNAME:8080/users/1 The engine will then return a JSON representation of the user.

This wiki also contains a full description of the Data representation.

Similarly, that user's resources can be listed via GETing the URL: http://HOSTNAME:8080/users/1/resources or individual resources by appending their resource ID: http://HOSTNAME:8080/users/1/resources/999

A new resource can be added by POSTing a JSON representation of a resource to the URL: http://HOSTNAME:8080/users/1/resources, whereas they can be deleted by performing an HTTP DELETE request to their relevant URL: http://HOSTNAME:8080/users/1/resources/999 It is possible to modify the representation stored on the server by PUTing a new JSON representation of that resource. Alternatively a new resource may be created by POSTing a JSON representation of the new resource. We have a page of explicit Examples.

Resources contain Parsers that make sense of data and output Streams of data points. The parsers can simply be a JSON field path, allowing a given JSON field to be parsed as a datapoint from the incoming data and then stored in SicsthSense. Details of the parsing behaviour can be found at Parsing data.

Data enters the system via SicsthSense receiving a POST or by it performing a Poll. Poll events can be scheduled by configuring the Resource. Simply specify the fields polling_url and polling_period, SicsthSense will then perform an HTTP GET on that url every period seconds.

Data is not public by default, so users must provide credentials when accessing non-public data. Any configuration requires people to provide their user key http://URL?key=XXXXX. Accessing or posting data to the system requires the key of that resource/stream http://URL?key=XXXXX. Further details can be found in the Examples page.