For recent specification and news, to to Eclipse Unide project

Purpose

This REST server is part of the Eclipse Unide project. Its main purpose is to showcase how PPMP messages can be validated against the schemas defined in the PPMP protocol and processed. The REST server provides an example use case, where PPMP protocol messages are persisted to an InfluxDB. Using a monitoring tool like Grafana the persisted data can be visualized afterwards.

This document guides you through the architecture and the persistency functionality of the REST server.

Getting started

Download

You’ll find the latest builds of this server on the Eclipse repository. The ppmp-server-*.jar can easily be downloaded and started as described below.

Building and Running the Server

To build the REST server run:

mvn clean install

After configuring the server as described below you can run it using

java -jar ppmp-server-<VERSION>-fat.jar -conf ./target/application_conf.json

Configuration

After building the project a configuration file is created in ./target/application.json. Open this file and set database- and http- settings according to your needs.

The file contains the following properties which should be overridden with the corresponding properties of your environment.

{
  "http.port": 8090,
  "persistence.enable" : true,
  "persistence.system" : "sql",
  "influxDb.url": "http://localhost:8086",
  "influxDb.user": "root",
  "influxDb.password": "root",
  "sqlDriver": "org.postgresql.Driver", // optional, defaults to org.postgresql.Driver
  "sqlDb.url" : "jdbc:postgresql://localhost:5432/unide_ppmp",
  "sqlDb.user" : "postgres",
  "sqlDb.password" : "password"
}

The following table contains detailed information about the properties.

Property Required Default Description

http.port

Yes

-

The HTTP port on which the server will run.

persistence.enable

No

true

Enables persistence. If this property is set to false, only the validation endpoint can be used.

persistence.system

No

influxDb

The name of the database in which PPMP message type messages should be persisted.

influxDb.url

Yes

-

The connection URL of the InfluxDB instance.

influxDb.user

Yes

-

The username for InfluxDB.

influxDb.password

Yes

-

The password for InfluxDB.

sqlDb.url

Yes

-

The connection URL of the SQL DB instance.

sqlDb.user

Yes

-

The username for SQL DB.

sqlDb.password

Yes

-

The password for the SQL DB.

Service Overview

REST Endpoints

The server provides the following endpoints:

Route Method Description

/rest/v2

POST

Validate and save a PPMP protocol message of any type

/rest/v2/validate

POST

Validate a PPMP protocol message of any type

/rest/v2/message

POST

Validate and save a PPMP protocol message of type message

/rest/v2/measurement

POST

Validate and save a PPMP protocol message of type measurement

/rest/v2/process

POST

Validate and save a PPMP protocol message of type process

Components

The REST server is made up from these components:

Table 1. Components
Component Description

RestVerticle

Provides the REST endpoints for any interaction with the REST server

PpmpValidator

Validates JSON payloads against the PPMP protocol schema

Vert.x EventBus

The communication system to allow message passing between verticles.

ReceiverVerticle

Consumes events from the eventbus and delegates them to concrete receivers.

InfluxDbReceiver

Transforms PPMP messages to InfluxDB line protocol and sends them to InfluxDB over the REST API

InfluxDB

The database used to persist PPMP messages

The interactions between those components are shown in the figure below.

Ppmp Message processing
Ppmp Message processing

InfluxDB Schema Design

All PPMP messages are written to the InfluxDB. The schema of the database differs for each message type. Each message type is persisted in its own database. The databases are created on application startup. The databases are:

  • Messages

  • Measurements

  • Processes

InfluxDB tables are called Measurement. The Measurement s for the message types are:

  • ppmp_messages

  • ppmp_measurements

  • ppmp_processes

The schemas for each message type are described below.

PPMP Message

This type is written to the Messages database. The Measurement name is ppmp_message.

Table 2. PPMP Message
Attribute Type Name

message.ts

time

time

device.DeviceID

tag

deviceId

message.messageCode

tag

code

message.origin

field

origin

message.severity

field

severity

message.title

field

title

message.description

field

description

message.hint

field

hint

message.type

field

type

PPMP Measurement

This type is written to the Measurements database. The Measurement name is ppmp_measurements.

Table 3. PPMP Measurement Message
Attribute Type Name

ts + offset in series.$_time

time

time

device.DeviceID

tag

deviceId

series.name_of_array

tag

measurement.point

measurements.series.name_of_array.item

field

value

A PPMP Measurement message can contain one or more entries which will be persisted.

The following example shows a measurement that contains four entries.

{
	"content-spec": "urn:spec://eclipse.org/unide/measurement-message#v2",
	"device":
	{
		"deviceID": "a4927dad-58d4-4580-b460-79cefd56775b"
	},
	"measurements":
	[
		{
			"ts": "2002-05-30T09:30:10.123+02:00",
			"result": "OK",
			"series":
			{
				"$_time":
				[
				    0,
				    23
				],
				"temperature":
				[
				    52.4,
				    46.32
				],
				"pressure":
				[
				    26,
				    20
				]
			}
		}
	]
}

The resulting entries of this measurement message are:

Time Tags Fields

2002-05-30T09:30:10.123+02:00

deviceId=12341231,measurementPoint=temperature

value=52.4

2002-05-30T09:30:10.146+02:00

deviceId=12341231,measurementPoint=temperature

value=46.32

2002-05-30T09:30:10.123+02:00

deviceId=12341231,measurementPoint=pressure

value=26

2002-05-30T09:30:10.146+02:00

deviceId=12341231,measurementPoint=pressure

value=20

Basically the following schema applies:

ts + $_time[i] deviceId=device.deviceId,measurementPoint='value_array_name' value='value_array_name'[i]

PPMP Proccess

This type is written to the Processes database. The Measurement name is ppmp_processes.

Table 4. PPMP Prccess
Attribute Type Name

process.ts

time

time

device.DeviceID

tag

deviceId

process.program.id

tag

programId

process - payload as json

field

payload

PostgresDB Schema Design

Postgres provides the possibility to store time based data by using the Postgres timescale extension.

The timescale extension is required for the rest server when using postgres as DB. The easiest way to setup Postgres with the timescale extension is using docker.

The unide rest-server does only need the connection string to a running database instance. All tables and timescale specific statements are created or executed on application startup of the rest-server, when they are not exists.

All PPMP messages are written to the SQL DB. Each message is persisted in its own table. The tables are:

  • ppmp_messages

  • ppmp_measurements

  • ppmp_processes

The schemas for each message type are described below.

The raw SQL creation statements can be found in org/eclipse/iot/unide/server/receiver/sql/migrations

PPMP Message

This type is written to the ppmp_messages table.

Table 5. PPMP Message
Attribute Type Name

message.ts

timestamp

time

device.DeviceID

text

deviceid

message.messageCode

text

code

message.origin

text

origin

message.severity

text

severity

message.title

text

title

message.description

text

description

message.hint

text

hint

message.type

text

type

PPMP Measurement

This type is written to the ppmp_measurements table.

Table 6. PPMP Measurement Message
Attribute Type Name

ts + offset in series.$_time

timestamp

time

device.DeviceID

text

deviceId

series.name_of_array

text

measurement.point

measurements.series.name_of_array.item

decimal

value

A PPMP Measurement message can contain one or more entries which will be persisted.

The following example shows a measurement that contains four entries.

{
	"content-spec": "urn:spec://eclipse.org/unide/measurement-message#v2",
	"device":
	{
		"deviceID": "a4927dad-58d4-4580-b460-79cefd56775b"
	},
	"measurements":
	[
		{
			"ts": "2002-05-30T09:30:10.123+02:00",
			"result": "OK",
			"series":
			{
				"$_time":
				[
				    0,
				    23
				],
				"temperature":
				[
				    52.4,
				    46.32
				],
				"pressure":
				[
				    26,
				    20
				]
			}
		}
	]
}

The resulting entries of this measurement message are:

time deviceid measurementpoint value

2002-05-30T09:30:10.123+02:00

deviceId=12341231

measurementPoint=temperature

value=52.4

2002-05-30T09:30:10.146+02:00

deviceId=12341231

measurementPoint=temperature

value=46.32

2002-05-30T09:30:10.123+02:00

deviceId=12341231

measurementPoint=pressure

value=26

2002-05-30T09:30:10.146+02:00

deviceId=12341231

measurementPoint=pressure

value=20

PPMP Proccess

This type is written to the Processes database. The Measurement name is ppmp_processes.

Table 7. PPMP Prccess
Attribute Type Name

process.ts

timestamp

time

device.DeviceID

test

deviceId

process.program.id

text

programId

process - payload as json

json

payload