search

AaltoAsia / O-MI

Internet of Things data server implementing Open Messaging Interface and Open Data Format
BSD 4-Clause "Original" or "Old" License
22 stars 13 forks source link

readme

O-MI Node Server Latest release Build Status Coverage Status Codacy Badge Join the chat at https://gitter.im/AaltoAsia/O-MI

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. Join the chat at https://gitter.im/AaltoAsia/O-MI

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

Dependencies

Running

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

File to choose:

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:

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

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:

Optional components

Directory structure

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.