Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

1.

...

Inhaltsverzeichnis

Table of Contents
minLevel1
maxLevel7

...

2.

...

Allgemein

2.1

...

Geräte

Die Darstellung der Geräte wird durch ihre eindeutigen Seriennummern identifiziert. Diese Datenobjekte enthalten eine Untergruppe von Informationen sowie eine Liste von SensorIds für Datensenken, die Messdaten enthalten. Mit dem angegebenen API-Schlüssel werden der Benutzer und die verknüpften Geräte identifiziert.

2.2

...

Sensors represent a data sink holding the data of a run. Each sensor has a start and end date. Its sensor id is unique and links to measurements, geolocation and occurrence data.

...

Sensoren

Sensoren stellen eine Datensenke dar, in der die Daten eines Laufs gespeichert werden. Jeder Sensor hat ein Start- und Enddatum. Seine Sensor-ID ist eindeutig und mit Messungen, Geolocation und Ereignisdaten verknüpft.

Sobald das Gerät neu gestartet wird, wird eine neue Sensordatensenke mit einer neuen ID erstellt.

2.3

...

Wortlaut

...

Physical device

A physical device is identified by a serial number and has 1 to n channels.
Each channel can be configured independently (e.g. own measurement interval) and has one or more sensors, which can provide 1 to m different sensor values.
For example;

...

one value: temperature (for a Temperature-Sensor)

...

two-tuples of: relative humidity and temperature (for a rH-sensor)

...

Physikalisches Gerät

Ein physisches Gerät wird durch eine Seriennummer identifiziert und hat 1 bis n Kanäle.
Jeder Kanal kann unabhängig konfiguriert werden (z.B. eigenes Messintervall) und hat einen oder mehrere Sensoren, die 1 bis m verschiedene Sensorwerte liefern können.
Zum Beispiel;

  • ein Wert: Temperatur (für einen Temperatursensor)

  • zwei Tupel von: relative Feuchte und Temperatur (für einen rH-Sensor)

  • Drei-Tupel von: status, #changes, relative on (for a für einen DI-sensorSensor)

 

Virtual representation with alarming

In elproCLOUD we have a one to one mapping of device and channel.
For the values of a sensor we have an one to n mapping to virtual sensors.

A virtual sensor is created for every configuration of a real sensor and is used to attach different type of alarms to the same sensor valueVirtuelle Darstellung mit alarmierender

In elproCLOUD haben wir eine Eins-zu-Eins-Zuordnung von Gerät und Kanal.
Für die Werte eines Sensors haben wir eine eins-zu-n-Zuordnung zu virtuellen Sensoren.

Ein virtueller Sensor wird für jede Konfiguration eines realen Sensors erstellt und dient dazu, verschiedene Arten von Alarmen mit demselben Sensorwert zu verbinden.

2.4

...

Note that any JSON accepted and returned by the API must follow the JSON standard as defined in the ECMA-404 standard with the following amendments.

...

JSON property names are case invariant and no guarantee can be made regarding the casing of names, which are returned by the API. This means that no difference is made between uppercase and lowercase letters in property names.

...

Datenformat

Beachten Sie, dass jedes von der API akzeptierte und zurückgegebene JSON dem JSON-Standard entsprechen muss, wie er in der ECMA-404 Standard mit den folgenden Änderungen.

  1. JSON-Eigenschaftsnamen sind unabhängig von der Groß-/Kleinschreibung und es kann keine Garantie für die Groß-/Kleinschreibung von Namen gegeben werden, die von der API zurückgegeben werden. Das bedeutet, dass kein Unterschied zwischen Groß- und Kleinbuchstaben in Eigenschaftsnamen gemacht wird.

  2. Die relative Reihenfolge der JSON-Namen in Antworten kann nicht garantiert werden. Das bedeutet, dass Sie sich beim Parsen und Verarbeiten von Antworten nicht auf die Reihenfolge der Eigenschaften in den Antworten verlassen sollten.

...

3. REST-API

...

The client can request information from elproCLOUD via Der Client kann über die REST-API . The communication runs typically in the following sequence:

The device will send its data and occurences in defined fix inteval to the elproCLOUD.
There are mechanisms, where the device will send its data directly to the elproCLOUD and will not wait for the next communication interval.

The customer app requests the data from elproCLOUD via the REST-API on demand or in a self defined intervall. This interval should be defined based on a risk-assesment.

Info

Please be aware that some query results are limited

Specification:

...

Informationen von elproCLOUD anfordern. Die Kommunikation läuft typischerweise in der folgenden Reihenfolge ab:

Das Gerät sendet seine Daten und Vorkommnisse in einem festgelegten Zeitintervall an die elproCLOUD.
Es gibt Mechanismen, bei denen das Gerät seine Daten direkt an die elproCLOUD sendet und nicht auf das nächste Kommunikationsintervall wartet.

Die Kunden-App fordert die Daten von elproCLOUD über die REST-API bei Bedarf oder in einem selbst definierten Intervall an. Dieses Intervall sollte auf der Grundlage einer Risikoeinschätzung festgelegt werden.

Info

Bitte beachten Sie, dass einige Abfrageergebnisse eingeschränkt sind

Spezifikation:

3.1

...

The client can request different data sets, including

...

Measurements

...

Geodata

...

Occurences

...

Datensätze und allgemeines Abfrageschema

Der Kunde kann verschiedene Datensätze anfordern, darunter

  • Messungen

  • Geodaten

  • Vorkommen

  • Abweichung

3.1.1

...

Initially, ELPRO sets up an API key for a dedicated user of an organization.

...

Art des Sicherheitssystems

Zunächst richtet ELPRO einen API-Schlüssel für einen bestimmten Benutzer einer Organisation ein.

Geben Sie Ihren API-Autorisierungscode im Anfrage-Header als Schlüssel und Wert an

EAPI-ELCLV2

123a45b67_SAMPLE_f12345ab6c789d0         

...

f12345ab6c789d0 

Im Falle eines Fehlens oder einer Nichtübereinstimmung wird eine Fehlermeldung mit dem HTTP-Status 401 "Nicht autorisiert" zurückgegeben.

3.1.2

...

Benutzerumfang

Die abgerufenen Daten fallen in den Bereich der Organisation des authentifizierten API-Benutzers. Sie werden mit dem HTTP-Statuscode 200 (SuccessErfolg) zurückgegeben.

3.1.3 Http

...

-Fehler-Codes

400 Bad RequestSchlechte Anfrage

ez.g. missing mandatory parameterB. fehlender obligatorischer Parameter

401 Unauthorized

Invalid or missing API Key

404 Resource not found

Invalid serial number or id

406 Not Acceptable

Accept Header should be only application/json

410 License exhausted

Number of queries or datatransfer used up

500 Server Error

Unexpected internal exception

503 Service Temporarily Unavailable

Service down due to maintenance or updateNicht autorisiert

Ungültiger oder fehlender API-Schlüssel

404 Ressource nicht gefunden

Ungültige Seriennummer oder ID

406 Nicht akzeptabel

Accept Header sollte nur application/json lauten

410 Lizenz erschöpft

Anzahl der verbrauchten Abfragen oder Datentransfers

500 Server-Fehler

Unerwartete interne Ausnahme

503 Dienst vorübergehend nicht verfügbar

Dienst aufgrund von Wartung oder Update nicht verfügbar

3.2 Version

...

der REST-API

For the Für die REST-API a versioning mechanism is implemented.

The versioning includes a Major and a Minor number.

Major numbers will provide an interface to the elproCLOUD and will be increased, if the functionality of the interface is dramatically changed. Minor numbers will be increased, if information is added to the returned data structure. 

Major REST-API Versions will be still available via the URList ein Versionierungsmechanismus implementiert.

Die Versionierung umfasst eine Major- und eine Minor-Nummer.

Major-Nummern stellen eine Schnittstelle zur elproCLOUD zur Verfügung und werden erhöht, wenn die Funktionalität der Schnittstelle drastisch verändert wird. Minor-Nummern werden erhöht, wenn der zurückgegebenen Datenstruktur Informationen hinzugefügt werden. 

Die wichtigsten REST-API-Versionen werden weiterhin über die URL verfügbar sein.

  • elprocloud_request_url/api/v1/…    ... (for für v1 of the der REST-API)

  • elprocloud_request_url/api/v2/…    ... (for für v2 of the der REST-API)

 Major Major.Minor Versioning will be included in the returned JSON responseVersionierung wird in der zurückgegebenen JSON-Antwort enthalten sein.

Code Block
languagejson
{

"version": "<Major.Minor>",

}

...

4.

...

Nachrichten-Warteschlange (AMQP)

...

  • A “Customer-Queue” is provided using AMQ protocol which is reachable under Es wird eine "Kunden-Warteschlange" mit dem AMQ-Protokoll bereitgestellt, die erreichbar ist unter amqp.elpro.cloud.

  • The Queue-Name is the name of the explicitly provisioned RabbitMQ Queue. Queue and Users are managed by ELPRO.

  • Furthermore a unique username and password for every customer is provided. See below in this document for an example implementation.

  •  Every customer can use his AMQP client of choice to read and acknowledge on the list of message types.

  • The connection is TLS only Die Warteschlangen-Name ist der Name der explizit bereitgestellten RabbitMQ-Warteschlange. Warteschlange und Benutzer werden von ELPRO verwaltet.

  • Außerdem eine einzigartige Benutzername und Passwort für jeden Kunden bereitgestellt wird. Unten in diesem Dokument finden Sie ein Beispiel für eine Implementierung.

  • Jeder Kunde kann einen AMQP-Client seiner Wahl zum Lesen und Bestätigen auf dem Liste der Nachrichtentypen.

  • Die Verbindung ist TLS nur (Port 443)

  • In Production the Time to live (TTL) of queue data is set to three daysProduktion die Zeit zu leben (TTL) der Warteschlangendaten wird auf drei Tage festgelegt.

4.1

...

The Queue Messages will have following basic payload as JSON:

...

Fieldname

...

Type

...

Description

...

type

...

String

...

Nachrichtenmodelle

Die Warteschlangen-Nachrichten haben folgende grundlegende Nutzdaten im JSON-Format:

Feldname

Typ

Beschreibung

Typ

String

Mögliche Nachrichtentypen:

  • eapi_measurement_new

  • eapi_geodata_new

  • eapi_occurrenceEreignis_newneu

  • eapi_deviation_enter

  • eapi_deviation_leave

dataDaten

JSON object-ObjektInner JSON

representation of an info message, see info data models later in this documentInnere JSON-Darstellung einer Info-Nachricht, siehe Info-Datenmodelle weiter unten in diesem Dokument

4.2

...

Nachrichtentyp

Jeder Typ repräsentiert eine spezielle JSON-Nutzlast innerhalb des Data JSON-Objekts. So weiß ein Verbraucher, welches Datenmodell verwendet wird.

  • eapi_measurement_new

  • eapi_geodata_new

  • eapi_occurrenceEreignis_newneu

  • eapi_deviation_enter

  • eapi_deviation_leave

4.3

...

Datenmodelle

Die Daten-Nutzdaten sind für jeden Typ unterschiedlich.

4.3.1

...

Messung

FieldnameFeldname

TypeTyp

DescriptionBeschreibung

sensorId

Int64

Id for the sensor data representing a data sinkfür die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Identifier of the device

value

Decimal

Numeric value of the measure

 

timeStampKennung des Geräts

Wert

Dezimal

Numerischer Wert der Maßnahme

Zeitstempel

DateTimeOffset

DateTime of measure as timezone der Messung als Zeitzone utc

unitEinheit

String

Unit Einheit Token

Possible ValuesMögliche Werte:

K,°C,°F, %

unitType

StringType

of unit as textTyp der Einheit als Text:

  • temperatureTemperatur

  • relative_humidityLuftfeuchtigkeit

4.3.1.1

...

Beispiel-Messungen

Daten mit Typ: "eapi_measurement_new”new"

Code Block
languagejson
{
    "type": "eapi_measurement_new",
    "data": {
        "timeStamp": "2022-10-11T16:21:27+00:00",
        "value": 24.6,
        "unit": "°C",
        "unitType": “temperature",
        "deviceId": "951FF00000340",
        "sensorId": "5368"  
    }
}

4.3.2

...

GeoDaten

FieldnameFeldname

TypeTyp

DescriptionBeschreibung

sensorId

Int64

Id for the sensor data representing a data sinkfür die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Identifier of the device

latitude

Double

Latitude with 8 digits precision

longitude

Double

Longitude with 8 digits precision

timestampKennung des Geräts

Breitengrad

Doppelter

Breitengrad mit 8 Ziffern Genauigkeit

Längengrad

Doppelter

Längengrad mit 8 Ziffern Genauigkeit

Zeitstempel

DateTimeOffset

datetime in timezone der Zeitzone utc

accuracyGenauigkeit

DecimalDezimal

Accuracy Genauigkeit in metersMetern

4.3.2.1

...

Beispiel GeoDaten

Daten mit Typ: "eapi_geodata_new” new" 

Code Block
{
    "type": "eapi_geodata_new",
    "data": {
        "timeStamp": "2022-10-11T15:21:24+00:00",
        "latitude": 47.19999075,
        "longitude": 9.50875282,
        "accuracy": 2316,
        "deviceId": "951FF00000340",
        "sensorId": "5369"
    }
}

4.3.3

...

Vorkommen

FieldnameFeldname

TypeTyp

DescriptionBeschreibung

sensorId

Int64

Id for the sensor data representing a data sinkfür die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Identifier of the device

timeStampKennung des Geräts

Zeitstempel

DateTimeDateTime of occurrence as timezone

DatumZeitpunkt des Auftretens als Zeitzone utc

typeName

String

"LoggerStatusÄnderung"LoggerStatusChange”

previousState

String

Possible valuesMögliche Werte:

"Undefined", "Init", "Shelflife", "Pairing", "Start", "LogDelayed", "LogTransit", LogPaused", "LogArrived", "StopStopped", "StopSleep", "Calibration", "EmergencyReadOut", "FatalError", "ProductionCalibration"

newStateneuerStatus

String

4.3.3.1

...

Beispielvorkommen

Daten mit dem Typ "eapi_occurrence_new” new" 

Code Block
languagejson
{
    "type": "eapi_occurrence_new",
    "data": {
        "timeStamp": "2022-10-11T15:21:24+00:00",
        "typeName": "LoggerStatusChange",
        "previousState": "Start",
        "newState": "LogDelayed",
        "deviceId": "951FF00000340",
        "sensorId": "5369"
    }
}

4.3.4

...

Abweichung

FieldnameFeldname

TypeTyp

DescriptionBeschreibung

sensorId

Int64

Id for the sensor data representing a data sinkfür die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Identifier of the device

timestampKennung des Geräts

Zeitstempel

DateTimeOffset

DateTime of deviation as timezone der Abweichung als Zeitzone utc

historyType

String

Type of Deviation describring begin or end of deviation.

Possible values:

“enter”
“leave”Typ der Abweichung beschreibt den Beginn oder das Ende der Abweichung.

Mögliche Werte:

"eingeben"
"verlassen"

deviationType

String

Deviation type, possible valuesAbweichungstyp, mögliche Werte:

"batteryBatterie",
"failureAusfall",
"missingfehlt",
"radioRadio",
"limitLimit"

reasonGrund

StringDeviation explanation code

Abweichung Erklärung Code

limitzone

String (opt.)

Limit Zone code for a limit deviation

Possible valuesGrenzwert Zonencode für eine Grenzwertabweichung

Mögliche Werte:

L1,L2,L3, H1,H2,H3…H3...

4.3.4.1

...

Beispiel Abweichung eingeben

Daten mit dem Typ "eapi_deviation_enter” enter" 

Code Block
{
    "type": "eapi_deviation_enter",
    "data": {
        "deviceId": "951FF00000340",
        "sensorId": 5763,
        "timeStamp": "2022-10-26T17:00:22+00:00",
        "historyType": "enter",
        "deviationType": "limit",
        "reason": "upper_limit_alarm"
    }
}

4.3.4.

...

2 Beispiel Abweichung Urlaub

Daten mit dem Typ "eapi_deviation_leave”leave"

Code Block
languagejson
{
    "type": "eapi_deviation_leave",
    "data": {
        "deviceId": "951FF00000340",
        "sensorId": 5763,
        "timeStamp": "2022-10-26T18:00:22+00:00",
        "historyType": "leave",
        "deviationType": "limit",
        "reason": "upper_limit_alarm"
    }
}

4.4

...

AMQP-Nachrichten verbrauchen

4.4.1

...

Beispiel-Client-Code

...

mit RabbitMQ in C#

 Example Code how to connect to a Queue with .NET and RabbitMQ nuget library Beispielcode für die Verbindung zu einer Warteschlange mit .NET und der Nuget-Bibliothek RabbitMQ:

Code Block
public ObservableCollection<MessageModel> Messages { get; private set; }

public static IConnection connection;
public static IModel channel;
public static EventingBasicConsumer consumer;

public void Read()
{        
    var serverName = "amqp.elpro.cloud"
    var queueName = "398ab9ae90efce88dcf623cc49e302e1";
    bool autoACK = true;

    try
    {
        // Prepare 
        var factory = new ConnectionFactory()
        {
            HostName = serverName,
            UserName = "user",
            Password = "password",
            Port = 443,
            Ssl = new SslOption() 
            { 
              Enabled = true, 
              ServerName = serverName
            }
        };

        connection = factory.CreateConnection();
        channel = connection.CreateModel();
      
        var routingKey = $"*.eapi_*"; //*.eapi_measurement_new e.g.                        
        Console.WriteLine(" [*] Waiting for msgs.");

        // Consumer
        consumer = new EventingBasicConsumer(channel);
        consumer.Received += (model, ea) =>
        {
            var body = ea.Body.ToArray();
            var messageText = Encoding.UTF8.GetString(body);

            var message = new MessageModel(ea.RoutingKey, messageText);

            Dispatcher.Dispatch(() => Messages.Add(message));
        };

        // Subscribe
        channel.BasicConsume(queue: queueName,
                    autoAck: autoACK,
                    consumer: consumer);

    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error at RabbitMQ.Test: {ex.Message}");
    }
}

...

5.

...

Anschlussdetails und technische Spezifikation

...