...

Virtuelle Darstellung mit alarmierenderAlarmierung

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.

...

Spezifikation:

• Der Endpunkt REST API URL https://apibridge.elpro.cloud

  • Das API-Token wird von ELPRO bereitgestellt

• Für Entwickler ist die technische Spezifikation von OpenAPI als Swagger UI verfügbar https://apibridge.elpro.cloud/swagger

3.1 Datensätze und allgemeines Abfrageschema

Der Kunde kann verschiedene Datensätze anfordern, darunter

• MessungenMesswerte

• Geodaten

• VorkommenOccurences

• AbweichungAbweichungen

3.1.1 Art des Sicherheitssystems

...

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

Im Falle eines Fehlens oder einer Nichtübereinstimmung wird eine Fehlermeldung mit dem HTTP-Status 401 "Nicht autorisiertUnauthorized" 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 (ErfolgSuccess) zurückgegeben.

3.1.3 Http-Fehler-Codes

3.2

...

Konfigurations-API

Für die REST-API ist ein Die REST-Schnittstelle bietet einen sehr einfachen Endpunkt für die Konfiguration von LIBERO Gx-Geräten.

Konfigurationsvorlage erstellen und hochladen

• Verwenden Sie den Wizard in elproCLOUD, um eine Konfigurationsvorlage für einen LIBERO Gx zu erstellen

• Wählen Sie den richtigen LIBERO Gx-Typ (die ersten drei Ziffern der Seriennummer sind wichtig)

• Füllen Sie die Formulare des Wizard aus, bis Sie die Übersichtsseite erreicht haben

  • Alt+Klick auf die Schaltfläche "Sensor kaufen und starten".

  • Ein Dateidownload wird angezeigt

  • Speichern Sie die Datei unter einem passenden Namen (z.B. LIBERO_GH_longlive_freezer.json)

• Verwenden Sie den Endpunkt POST /api/v1/Templates, um den Inhalt der gespeicherten Konfigurations-JSON-Datei hochzuladen

  • Wichtig: Die Konfiguration muss JSON-escaped sein. Tun Sie dies programmatisch oder verwenden Sie ein Online-Tool

  • Das Anfrageobjekt wird in der Swagger UI beschrieben

• Optional: Verwenden Sie den Endpunkt GET /api/v1/Templates, um alle verfügbaren Vorlagen aufzulisten

Konfigurieren Sie die Vorlagen

• Verwenden Sie den Endpunkt PUT /api/v1/Device/{deviceSerialNumber} zur Konfiguration der Geräte

  • Ein Aufruf pro Gerät, verwenden Sie ein Skript, um diesen Prozess zu automatisieren

  • Drei mögliche Nutzdaten, die durch $type angegeben werden

    • Weitere Informationen zu den spezifischen Objekten finden Sie in der Swagger UI

    • DeviceConfigurationRequestByTemplateId und DeviceConfigurationRequestByTemplateName können zur Konfiguration eines Geräts verwendet werden

      • Optional: Bereitstellung von Metadaten, siehe Swagger UI für weitere Informationen zu Platzhaltern

    • DeviceConfigurationRequestClearPending kann verwendet werden, um eine ausstehende Konfiguration für Geräte zu löschen, die noch nicht mit der Organisation gepaart worden sind

3.3 Version der REST-API

Für die REST-API ist ein Versionierungsmechanismus implementiert.

...

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

...

{

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

}

...

4. Nachrichten

...

Queue (AMQP)

...

• Es wird eine "Kunden-WarteschlangeQueue" mit dem AMQ-Protokoll bereitgestellt, die erreichbar ist unter amqp.elpro.cloud.

• Die WarteschlangenDer Queue-Name ist der Name der explizit bereitgestellten RabbitMQ-WarteschlangeQueueu. Warteschlange Queueu und Benutzer werden von ELPRO verwaltet.

• Außerdem eine einzigartige Benutzername und Passwort für jeden Kunden zur Verfügung gestellt wird. Siehe unten in diesem Dokument für eine Beispiel-Implementierung.

• Jeder Kunde kann einen AMQP-Client seiner Wahl zum Lesen (read) und Bestätigen auf dem (acknowledge) gemäss der Liste der Nachrichtentypen nutzen.

• Die Verbindung ist TLS nur (Port 443)

• In Produktion die Zeit zu leben Auf der Produktivumgebung ist die Time To Live (TTL) der Warteschlangendaten wird auf drei Tage festgelegt.

...

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

4.2 Nachrichtentyp

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

...

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

4.3.1

...

Messwerte

4.3.1.1 Beispiel-Messungen

...

{
    "type": "eapi_measurement_new",
    "data": {
	    "sensorId": "5368"
		"deviceId": "951FF00000340",
        "timeStamp": "2022-10-11T16:21:27+00:00",
		"error": "Short       "valueCircuit",
		"status": 24.60,
        "unit": "°C",
        		"unitType": “temperature",
        "deviceId		"value": "951FF00000340",
        "sensorId": "5368" 24.6,
		"tiltAngle": 2.4,
     }
}

4.3.2 GeoDaten

4.3.2.1 Beispiel GeoDaten

...

{
    "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

...

Occurence

4.3.3.1

...

Beispiel Occurence

Daten mit dem Typ "eapi_occurrence_new" 

{
    "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

4.3.4.1 Beispiel Abweichung

...

aufgetreten

Daten mit dem Typ "eapi_deviation_enter" 

{
    "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

...

verlassen

Daten mit dem Typ "eapi_deviation_leave"

{
    "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

...

verwenden

4.4.1 Beispiel-Client-Code mit RabbitMQ in C#

...

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.

...

Verbindungsdetails und technische Spezifikation

• Endpunkt REST API URL https://apibridge.elpro.cloud

• AMQP-Server: amqp.elpro.cloud

• Für Entwickler die technische Spezifikation von OpenAPI als Swagger UI https://apibridge.elpro.cloud/swagger

...