Skip to content

Latest commit

 

History

History
145 lines (89 loc) · 7.91 KB

README.md

File metadata and controls

145 lines (89 loc) · 7.91 KB
Raw

OORI - An O-MI/O-DF RDF Integration Server

OORI is server that is able to monitor the values of O-DF objects on multiple O-MI nodes. To do this, it makes use of O-MI's subscription functionality. The O-DF structure is converted into RDF format using the O-DF ontology and stored to a SPARQL endpoint. As a result, the current values of a subscribed object are at any time available for querying in the SPARQL endpoint.

Project Status

The project is currently in early alpha state. It has not yet been extensively tested and automated tests are missing. However, the core functionality, i.e., subscribing for changes of O-MI/O-DF IoT data and converting it to RDF as well as providing a public SPARQL query interface of this data is implemented and working.

Contributions

The project has two main contributions:

  1. A server exposing HTTP methods that allow to register O-DF structures that should be constantly converted and stored to an RDF triple store.
  2. An RDF ontology that defines classes and properties to describe O-DF structures. It is used by the server to perform O-DF conversion into RDF.

Building the project

Go to a command prompt and move to the ~/oori directory and run the command

mvn clean package

This will give you an executable jar file in the directory ~/oori/target. If you have docker installed on your machine, you can also create a docker image from the source code by issuing the command

mvn clean package docker:build

We recommend to use Docker, as it is also required for working through the next section of this document, 'Getting started locally with demo data'.

Getting started locally with demo data

To start using the server, first obtain the source code by either cloning or downloading the git repository somewhere to your local system. In these instructions we assume you have the source code available under your home directory in the path ~/oori.

Get things up and running using Docker

Make sure you have the docker-compose utility installed on your system. Go to a command prompt and move to the ~/oori/src/main/docker directory and run the command

docker-compose up

This will locally bring up a preconfigured OORI server, a fuseki server and an O-MI node. If everything worked well, you will be able to point your browser to:

  • http://localhost:8080/html/webclient/index.html, which is the local O-MI node, and
  • http://localhost:3030/, which is the local Fuseki server for holding the RDF representation of the O-MI/O-DF data. The default credentials are admin/b1oT0pe.

In the next step you will populate the O-MI node with some demo O-MI/O-DF data and issue a subscription to OORI so that the demo data gets converted into RDF format and stored in Fuseki. To do this, move to the directory ~/oori/src/main/docker/demo_init using another terminal and execute the data initialization script:

./demo_init.sh

After clicking the 'Read All' button in the local O-MI node, you can notice that now you have an object BrusselsBikesParkingSpot containing data about available bike stands in Brussels. Furthermore, the script sent a subscription on this dataset to the OORI server running in the Docker container. An initial baseline synchronization has been performed wich resulted into conversion of the bike stands data into RDF and storage into Fuseki. You can check the RDF data by going to Fuseki's data query frontend.

Creating custom setups

For easy configuration and deployment we highly recommend to adopt the file docker-compose.yml (in the directory ~oori/src/main/docker/) which is intended for a local demo deployment and adjust it to your needs. You may want to remove the O-MI node which would not be necessary if your goal is to set up a public OORI server that should be used by 'third-party' O-MI nodes on the Web.

Running the Server without Docker

OORI is packaged as a .jar file. To run it, simply execute the generated jar file using the following command:

java -jar oori-0.0.1-SNAPSHOT.jar

The filename varies depending on the current version of the project. The command will start the OORI server at the default port 9090.

Configuration

Currently you can customize the following properties:

  1. The port the server runs on,
  2. The SPARQL endpoint that should be used for storing the generated RDF data,
  3. Callback parameters to specify the URL where data changes should be posted by the O-MI node

If you start OORI using java, you can set the properties (1) and (2) in the following form:

java -Dserver.port=SERVER_PORT -Dendpoint.url=ENDPOINT_URL -jar oori-0.0.1-SNAPSHOT.jar

When using Docker, these properties can also be set as environment variables named SERVER_PORT and ENDPOINT_URL in the Dockerfile. The properties for the callback parameters (2) can only be set as environment variables:

  • CB_PROTOCOL: protocol used in the callback URL (default: http),
  • CB_PORT: port used in the callback URL (default: 9090, should be the same as SERVER_PORT and will be removed in future versions),
  • CB_HOSTNAME: hostname used in the callback URL. MUST be set for productive installations as the default value localhost will not be resolvable.

In future versions of OORI, we plan to further consolidate and simplify these configuration parameters.

Usage

OORI provides the REST endpoint

/nodes

which, when called using the HTTP GET method, returns a list of all registered O-MI nodes and O-DF structures.

To register a new O-DF structure that is available at an O-MI node at OORI, send an HTTP POST request to the /nodes method with the body being a JSON structure holding two values:

  1. url specifies the O-MI node URL which serves the O-DF structure, and
  2. subscriptionXMLRequest which is a one-time read O-MI request that specifies the object(s) and infoitem(s) that should be monitored.

An exempary JSON body of such a POST request may look like the following:

{
 "url": "http://biotope.sntiotlab.lu:8080/",
 "subscriptionXMLRequest": "<?xml version='1.0' encoding='UTF-8'?><omi:omiEnvelope xmlns:xs='http://www.w3.org/2001/XMLSchema-instance' xmlns:omi='omi.xsd' version='1.0' ttl='0'><omi:read msgformat='odf'><omi:msg><Objects xmlns='odf.xsd'><Object><id>SnT</id><Object><id>IoTlab</id><Object><id>Netatmo</id><InfoItem name='Location'/></Object></Object></Object></Objects></omi:msg></omi:read></omi:omiEnvelope>"
}

Built With

Future Work

Our immediate next steps will be to

  • Implement automated JUnit tests
  • Provide a docker-compose.yml file involving Fuseki as a preconfigured RDF storage backend
  • Implement support for unsubscribing O-DF structures
  • Implement generation of O-MI write requests at SPARQL CONSTRUCT of a new RDF value

The final goal will be to use the RDF data generated by OORI as a basis for integrating multiple O-MI/O-DF capable devices by orchestrate them using graphical tools like existing RDF visualization/exploration tools (e.g., VOWL) and graphical SPARQL query authoring solutions (e.g., SparqlFilterFlow).

Authors

  • Christian Mader - Initial design and implementation
  • Sylvain Kubler - Integration approach with bIoTope ecosystem (O-MI nodes and IoTBnB)

License

This project is licensed under the GPLv3 License - see the LICENSE file for details.

Acknowledgments

This work was funded by the bIoTope project.