O-MI Node Server

Internet of Things data server. Implementation of O-MI Node as specified in Open Messaging Interface (pdf) v1.0 standard with Open Data Format (pdf) standard. It is intended to be as reference implementation that shows how these standards work in more detail. Missing features and differences to the standard are collected to this (work in progress) document. Questions or problems with the server or the standards can be posted to Issues, email or slack.

This project also includes:

• a developer webapp for building and sending O-MI/O-DF messages.
• some experimental extensions for the server which can be found in other branches:
  • omisec-omi-interface has O-MI/O-DF interface for authorization of O-MI messages in external service.
  • warp10integration has integration to Warp10 as the DB backend.

See development branch for latest progress.

Resources

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

Dependencies

• Java 1.8
• For building: sbt http://www.scala-sbt.org/ or sbt enabled IDE

Running

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

Extract the zip file and navigate to the /bin directory To 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

This will run O-MI Node with configuration in /conf/application.conf. By default it will start at url http://localhost:8080/ and has some example and demo agents. More Information in the Configuration section.

Compiling and packaging

1. Follow the instructions 1-4 in Setup development environment below
2. sbt release
3. Result can be found in ./target/universal/o-mi-Node-version.zip

See SBT Universal Plugin for more packaging methods.

Setup development environment

1. git clone
2. Install sbt
3. (windows: logout, or put sbt into PATH yourself)
4. Open a cmd or shell to the O-MI project directory
5. Then run sbt re-start to compile and run the Node
6. Visit http://localhost:8080/ to see that it's working
7. (optional step) Create an Eclipse IDE project a. Run sbt eclipse b. Open Eclipse IDE c. Select File->import Existing Projects into Workspace.

You can check the next section to learn more

Simple Build Tool cheat sheet

Native SBT commands

• sbt compile: just compile the project
• sbt clean: remove compiled and temporary files
• sbt run: run the project; We don't use this much, so sometimes it's broken and we don't even notice. We use re-start from Revolver which allows us to recompile and restart the node without exiting sbt, because restarting sbt takes unnecessary extra time.
• sbt doc: compile api documentation
• sbt test: run all tests

Extra commands from plugins and other

• We use sbt-revolver: run sbt and then write
  • re-start: compile&run the project in background
  • re-stop: close the background process
• We use sbt-native-packager:
  • sbt stage: creates file structure, used in packaged version, to the ./target/universal/stage/ directory
  • sbt debian:packageBin: create release debian package (requires dpkg program installed)
  • See native packager docs for configuring other packages. Our sbt configuration is in ./build.sbt.
• We use sbt-scoverage:
  • sbt clean coverage test coverageReport: calculate test coverage and generate reports in O-MI Node/target/scala-2.11/scoverage-report/
• We also have some extra commands for convenience:
  • sbt systemTest: run only system tests (the used requests and responses can be found in ImplementationDetails.html)
  • sbt release: create release tar and zip packages

extra info:

• automatically run any of above commands when there is a file change by adding ~ in front, like sbt ~re-start
• all commands above compiles the needed files that are not yet compiled
• run many commands in sequence faster if you open a single sbt command line with sbt

Configuration

Basic configuration

See application.conf for the defaults and configuration documentation.

Library Config

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

• Akka Actors
• Spray-can http server
• Slick forConfig docs

O-MI Extensions

This server supports the following extensions to O-MI v1.0:

1. Websockets

• Client can initiate websocket connection to O-MI Node server by connecting to the same root path as POST requests with http connection upgrade request. (url conventions: ws:// or secure wss://)
• During a websocket connection the server accepts requests as in normal http communication. Immediate responses are sent in the same order as the corresponding requests were received.
• During a websocket connection callback can be set to "0" in an O-MI message to tell O-MI Node to use current websocket connection as the callback target.
• Keep in mind that depending on client and server configuration, a websocket connection will timeout if there is long period of inactivity. (Default is usually 1 minute). No callbacks can be sent after a timeout occurs (as websockets are always initiated by a client).