innoveahubs/o-mi

Internet of Things data server implementing Open Messaging Interface and Open Data Format

O-MI Node Server

Table of Contents

1. Introduction
2. Development status
3. Resources
4. Dependencies
5. Running
6. Compiling and Packaging
7. Setting up a development environment
   1. Setting up IDE
8. Configuration
9. FAQ
10. Optional Components
11. Directory structure

Other

1. sbt help

Introduction

Internet of Things data server. Implementation of O-MI Node as specified in Open Messaging Interface (O-MI) v1.0 standard with Open Data Format (O-DF) v1.0 standard. It is intended to be as reference implementation that shows how these standards work in more detail. See Features.md for more details.

O-MI can be used to query or update data, but also to set up data streams with subscriptions. It means that the standard can be used to make peer-to-peer like connections, but it can also be used in traditional client-server setup. O-MI standardizes the requests with XML, and they can be sent with almost any text based protocol. This implementation supports http, https and websocket.

O-DF is a simple object hierarchy format defined in XML. O-DF is used as data payload in O-MI. Simply put, O-DF can be thought as a file structure with directories which are Objects and files which are InfoItems. O-MI also supports use of any text based data format, but request semantics might be more ambigious. Payloads other than O-DF are not yet supported in this implementation.

Questions or problems with the server or the standards can be posted to Issues, email or gitter chat.

Development status

All important features are working, but the project is in beta phase where things are not yet very optimized and malicious requests might cause crashing. However, the project can be used in production if the server has low risk profile or authentication.

For large amounts of data, it is not recommended to use the default value history database. Instead, it can be disabled or changed to e.g. InfluxDB, see FAQ for instructions.

O-MI Node can be extended with special request logic which can be implemented with "agents". Different authentication and authorization mechanisms can be implemented via auth apis. New databases can be implemented with DB interface. Other payloads than O-DF cannot yet be implemented.

See development branch for latest progress.

Resources

• O-MI Specification (html) (pdf)
• O-DF Specification (html) (pdf)
• API Documentation ScalaDoc
• API Documentation JavaDoc
• Examples of requests and responses, as handled by this server
• Technical Documentation (outdated)

Dependencies

• For running:
  • Java 8 JRE (JDK on Mac)
• For building:
  • Java 8 JDK
  • SBT (Simple Build Tool) or SBT enabled IDE

Running

Download the pre-compiled zip, tgz or debian package from latest git releases here.

File to choose:

• o-mi-node-x.y.z.zip for Windows
• o-mi-node-x.y.z.deb for Ubuntu, Debian or other linux with dpkg
• o-mi-node-x.y.z.rpm for Red Hat linux
• o-mi-node-x.y.z.tgz for Mac or other Unix

For zip or tgz file:

1. Download and extract the file
2. Navigate to the bin directory
3. Run O-MI Node run the corresponding startup script from the bin directory for your OS:

• bin/o-mi-node.bat for Windows
• bin/o-mi-node for Unix and Mac

By default it will start at url http://localhost:8080/ and has some example and demo agents.

This will run O-MI Node with configuration in /conf/application.conf.

More Information in the Configuration section.

For linux packages

1. dpkg -i o-mi-node-x.y.z.deb or rpm -i o-mi-node-x.y.z.rpm
2. sudo systemctl start o-mi-node
3. If it needs to start after a reboot: sudo systemctl enable o-mi-node

With docker

1. docker pull aaltoasia/o-mi
2. docker run -p 8080:8080 aaltoasia/o-mi

Setting up a development environment

1. git clone
2. Install sbt
3. (on windows: logout, or put sbt into PATH yourself)
4. Open a cmd or shell to the O-MI project directory
5. Then run sbt and in opened the ">" prompt run reStart to compile and run the O-MI Node
6. Visit http://localhost:8080/ to see that it's working

You can check our Simple Build Tool cheat sheet section to learn more

If you would like to use an IDE, check how to set up Eclipse or IntelliJ IDEA

Compiling and packaging

1. Follow the instructions 1-4 in Setting up a development environment above
2. run sbt universal:packageBin (For other package types, use sbt release)
3. Result can be found in ./target/universal/o-mi-Node-version.zip

See SBT Universal Plugin for more packaging methods.

Configuration

Basic configuration

See reference.conf for the defaults and configuration documentation in the comments.

Configuration Location

• In package releases: /etc/o-mi-node/application.conf
• In tar and zip releases: ./conf/application.conf
• In development environment: ./O-MI-Node/src/main/resources/application.conf (create a new file if not found)
  • Default values are stored in ./O-MI-Node/src/main/resources/reference.conf

Syntax

Configuration file allows json-like syntax but it is not very strict about the object syntax. See here.

Library Config

application.conf can also have a lot of Akka (threading framework and HTTP server) and Slick (database) specific settings:

• HTTP server settings (Akka HTTP)
• Threading system etc. (Akka)
• SQL value history database (Slick forConfig)
  • see also guide on how to use a different db

Optional components

• Authentication and/or Authorization module
• InfluxDB as value history db. Install it separately and see this guide
• Warp10 as value history db. Branch warp10integration has experimental integration to Warp10 as the DB backend. Download -warp10 version from releases.

Directory structure

• O-MI-Node/ - Main directory for the o-mi-node server
  • src/main - Server source code
  • src/test - Source code of automatic tests
  • html/ - Developer web app source
• Agents/ - Sources for all internal agent examples
• tools/ - Some scripts and examples for working with O-DF/O-MI
• database/ - Database location when running
• project/dependencies.scala - Library dependencies list and versions
• build.sbt - Build system settings and instructions
• src/ - Only some specific files for releases, see O-MI-Node/src for real sources

Acknowledgements

Sections of this project has been developed as part of the bIoTope Project, which has received funding from the European Union’s Horizon 2020 Research and Innovation Programme under grant agreement No. 688203.