MQTT Benutzerhandbuch

Voraussetzungen

Der Zugriff auf die MQTT-Schnittstelle ist von bestimmten Rahmenbedingungen und Libraries abhängig.

• HTTP-fähiges Mobilfunkmodem
• TLS 1.1/1.2
• MQTT 3.1 client library (https://github.com/mqtt/mqtt.github.io/wiki/libraries)
• Cryptographie Library mit Unterstützung von
  • TLS
  • AES128
  • CBC
  • SHA256
  • DHE
  • “Extended Tiny Encryption Algorithm”
  • optional: PresharedKeys

MQTT mit dem Telekom Broker

MQTT ( MQ Telemetry Transport oder Message Queue Telemetry Transport ) ist ein offenes Nachrichtenprotokoll für Machine-to-Machine-Kommunikation (M2M), das trotz hoher Verzögerungen oder beschränkten Netzwerken die Übertragung von Telemetriedaten in Form von Nachrichten zwischen Geräten ermöglicht. Entsprechende Geräte reichen von Sensoren und Aktoren, Mobiltelefonen, embedded Systemen in Fahrzeugen oder Laptops bis zu voll entwickelten Rechnern. Das Protokoll wurde von „Andy Stanford-Clark“ von „IBM“ und „Arlen Nipper“ von „Cirrus Link Solutions“ entwickelt.

Seit 2013 wird MQTT über die Organization for the Advancement of Structured Information Standards (OASIS) als Protokoll des Internet der Dinge standardisiert. Das MQTT-Protokoll ist auch bekannt unter älteren Namen wie „WebSphere MQTT“ (WMQTT), „SCADA-Protokoll“ oder „MQ Integrator SCADA Device Protocol“ (MQIsdp). Die Internet Assigned Numbers Authority (IANA) reserviert für MQTT die Ports 1883 und 8883. MQTT-Nachrichten können mit dem TLS-Protokoll verschlüsselt werden.

MQTT ist ein Client-Server-Protokoll. Clients senden dem Server (“Broker”) nach Verbindungsaufbau Nachrichten mit einem Topic, welches die Nachricht hierarchisch einstuft; zum Beispiel „Wohnzimmer/Kühlschrank/Temperatur“ oder „Auto/Rad/3/Luftdruck“. Die Elterntopics sind in diesem Fall „Wohnzimmer“ und „Auto“.

Clients können sich auf Topics abonnieren, wobei der Server dann die empfangenen Nachrichten an die entsprechenden Abonnenten weiterleitet.

Hinweis: Nachrichten bestehen immer aus einem Topic und dem Nachrichteninhalt.

Nachrichten werden mit einem definierbaren Quality of Service versendet:

• at most once (die Nachricht wird einmal gesendet und kommt bei Verbindungsunterbruch möglicherweise nicht an)
• at least once (die Nachricht wird so lange gesendet, bis der Empfang bestätigt wird, und kann beim Empfänger mehrfach ankommen)
• exactly once (hierbei wird sichergestellt, dass die Nachricht auch bei Verbindungsunterbruch genau einmal ankommt).

Außerdem kann mit dem Retain-Flag der Server angewiesen werden, die Nachricht zu diesem Topic zwischenzuspeichern. Clients, die neu auf dieses Thema abonnieren, bekommen als erstes die zwischengespeicherte Nachricht zugestellt.

Beim Verbindungsaufbau können Clients einen “letzten Willen” in Form einer Nachricht definieren. Falls die Verbindung zum Client verloren geht, wird diese Nachricht publiziert und dabei an die entsprechenden Abonnenten gesendet.

MQTT wird üblicherweise über TCP benutzt und hat einen 2-Byte-Header. Das erste Byte enthält den Nachrichtentyp (4 Bit), den Quality of Service (2 Bit) und ein Retain-Flag.

Es gibt folgende Nachrichten-Typen:

• CONNECT
• CONNACK
• PUBLISH
• PUBACK
• PUBREC
• PUBREL
• PUBCOMP
• SUBSCRIBE
• SUBACK
• UNSUBSCRIBE
• UNSUBACK
• PINGREQ
• PINGRESP
• DISCONNECT

Das zweite Byte enthält die Länge des restlichen MQTT-Pakets. Daran schließt sich ein variabler Teil an, der das MQTT-Topic, also das Thema, enthält. Abschließend kommt der Payload, also der Dateninhalt, der unter dem Thema veröffentlicht wird.

Detaillierte Informationen zum Aufbau von MQTT-Messages finden Sie u.a. hier: http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html.

MQTT mit dem Telekom Broker

Tenant für MQTT vorbereiten

Ihr Tenant muss für die Benutzung von MQTT vorbereitet werden. Falls Sie einen Tenant mit MQTT verwenden wollen, muss dieser zunächst für MQTT eingerichtet werden. Dies betrifft sowohl bereits existierende sowie auch neu angelegte Tenants.

Wenden Sie sich dazu an den Telekom Support: cloudofthings@telekom.de

Broker URL und Varianten der Geräteregistierung

Der MQTT Client - das Gerät - muss eine Verbindung zum Telekom MQTT-Broker herstellen. Es gibt eine URL, die dazu zur Verfügung steht: nb-iot.ram.m2m.telekom.com.

Es stehen zwei unterschiedliche Varianten zur Verfügung um ein Gerät am Telekom MQTT-Broker zu registrieren:

• Geräte-Selbstregistrierung und Geräte-Selbsterstellung
• Massenregistrierung von Geräten

Geräte-Selbstregistrierung und Geräte-Selbsterstellung besteht aus zwei Phasen:

• Geräte-Selbstregistrierungs-Phase
• Geräte-Selbsterstellungs-Phase

In der ersten Phase - Geräte-Selbstregistrierungs-Phase - das Gerät registriert sich selbst in der Cloud of Things. In dieser Phase verbindet sich das Gerät mit der CoD und erhält seine Geräte individuellen Anmeldedaten. Der Ablauf einer Geräte-Selbstregistrierung wird im Abschnitt “Geräte-Selbstregistrierung” beschrieben. Die Benutzeranmeldedaten für den Connect auf normaler Ebene werden dem Gerät im Zuge des durchzuführenden Selbstregistrierungsprozesses mitgeteilt.

In der zweiten Phase - **Geräte-Selbsterstellungs-Phase ** - erstellt sich das Gerät in der Cloud of Things. In dieser Phase erstellt das Gerät verschiedene Objekte in CoT, die ein Gerät darstellen. Die Phase der Selbsterstellung wird im Abschnitt “[Selbsterstellung des Gerätes] (#device-self-creation)” beschrieben.

Bei einer Massenregistrierung wird eine Liste von Geräten an der Cloud of Things registriert. Die Geräte individuellen Anmeldeinformationen müssen bei der Produktion der Geräte auf diesen gespeichert werden. Weitere Informationen zur Massenregistrierung sind im Abschnitt zu finden “Massenregistrierung von Geräten” zu finden.

MQTT Topics

Ein MQTT-Gerät kommuniziert mit der Cloud of Things über zwei vorgeschriebene Topics, ein Topic zum Senden (ms/ICCID) und ein Topic zum Empfangen von Daten (mr/ICCID).

Zum Empfangen von Daten macht das Gerät nach erfolgreichem Connect zum Broker hinter der Broker-URL einen Subscribe auf den Topic: **mr/ICCID.

ICCID ist ein Platzhalter für die eigene ICCID, welche entweder mit einem Zugriff auf die SIM-Karte von der Software ermittelt werden oder der Software beispielsweise per Konfigurationsdatei mitgeteilt wurde.

Bei Geräten ohne SIM-Karte muss hier die MAC-Adresse des sendenden Netzwerkgerätes verwendet werden!

Das Gerät sendet Daten zur CdD mittels Publish-Kommandos gegen den Topic: ms/ICCID

Bitte beachten Sie, dass Operations verloren gehen können, wenn Sie QoS 1 nicht verwenden.

Bitte beachten Sie, dass die Verwendung von „CleanSession=TRUE“ dazu führen kann, dass Operations an das Gerät verloren gehen.

Grundlegende MQTT Sicherheitseinstellungen

Folgende MQTT Sicherheitseinstellungen werden bei der Kommunikation mit dem Telekom MQTT-Broker vorgeschrieben bzw. umgesetzt:

• MQTT über TCP
• TLS v1.1/1.2 (Port 8883) auf den Broker (HiveMQ)
• QoS 0, 1 und 2
• CleanSession true und false
• LastWill nicht unterstützt
• Retained Flag nicht unterstützt
• Wildcard-Subscribes nicht erlaubt
• Subscriptions auf die Publish-Topics nicht erlaubt (“write-only”)

Andere Topics als die beiden zuvor genannten sind aus Sicherheitsgründen nicht verfügbar und können auch vom Gerät nicht angelegt oder subscribed werden.

Geräte-Selbstregistrierung

Jedes Gerät muss zunächst eine Selbstregistrierung (Bootstrap) durchführen. Im Zuge dieser Selbstregistrierung erhält es seine Geräte-Credentials und seine Geräte-ID.

Das Gerät generiert zunächst ein ausreichend zufälliges, temporäres Passwort mit 128Bit/16 Byte Länge. Beispiel: es initialisiert mit dem aktuellen TIME (Sekunden seit 1970) den Randomizer. Dann wird über eine Random-Funktion ein Passwort mit 128 Bits (16 Byte) erzeugt. Danach wird per Randomizer eine Sleeptime von 0 bis 60 Sekunden erzeugt und ausgeführt (damit der Zeitpunkt TIME nicht aus der CONNECT-Zeit ermittelt werden kann).

Das Gerät verbindet sich mit den Bootstrap-Benutzerdaten gegen die Bootstrap-URL. Die Bootstrap-Benutzerdaten für die Erst-Anmeldung zum Bootstrapping können unter folgender E-Mail-Adresse erfragt werden: registrierung.cloud-der-dinge@telekom.de.

Nach erfolgreichem Connect macht es einen Subscribe auf den Topic sr/ICCID. ICCID ist ein Platzhalter für die eigene ICCID, welche entweder mit einem Zugriff auf die SIM-Karte von der Software ermittelt werden oder der Software beispielsweise per Konfigurationsdatei mitgeteilt wurde.

Achtung: Das Gerät subscribed sich auf dem Topic sr/ und nicht mr/, wie für die normale Kommunikation vorgegeben!

Das Gerät published das Random Password auf Topic ss/ICCID: tempPassword

Achtung: Das Gerät published das Random Passwort auf dem Topic ss/ und nicht ms/, wie für die normale Kommunikation vorgegeben!

Hier einige Informationen, wie der Bootstrap-Prozess intern abläuft, um ein besseres Verständnis zu geben: der Bootstrap-Prozess fragt die Credentials zum User ICCID bei der CdD an und holt sie ab:

POST /devicecontrol/deviceCredentials
Content-Type : application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
Authorization: Basic ...
{
"id" : "ICCID"
}

Solange die ICCID im UI der Plattform nicht unter Devicemanagement/Geräteregistrierung eingegeben und mittels Accept-Button akzeptiert wurde, werden dem Bootstrap-Prozess auch keine Credentials mitgeteilt.

Sobald die ICCID im Userinterface akzeptiert wurde, erhält der Bootstrap-Prozess die Credentials und sendet sie mittels “Extended Tiny Encryption Algorithm” verschlüsselt an das Gerät: 3rasfst4swfa

Dieses verschlüsselte Ergebnis wird unter dem Topic sr/ICCID gepublished. Da das Gerät auf diesen Topic subscribed ist, erhält es den verschlüsselten Payload. Mit Hilfe des Random-Passwortes kann das Gerät nun den Payload entschlüsseln.

Bitte beachten Sie, dass der verschlüsselte String (Zeichenkette) um das nächste Vielfache von Acht gepadded wird. Mehrere entschlüsselte Blöcke müssen aneinandergehängt und dann die Padding-Bytes am Ende entfernt werden.

Das Gerät speichert das Passwort an geeigneter Stelle. Sein Username hat folgendes Format: ICCID

Alle weiteren Verbindungen erfolgen ab diesem Zeitpunkt mittels dieser Credentials über die Broker-URL.

Der Bootstrapvorgang kann jederzeit wiederholt werden, zum Beispiel beim Umzug auf einen anderen Tenant oder nach Verlust der Zugangsdaten. Credentials in der CoT müssen manuell gelöscht werden.

Massenregistrierung von Geräten

Die Massenregistrierung von Geräten dient der vereinfachten Registrierung großer Stückzahlen von Geräten. Die Geräte werden dazu im Rahmen der Herstellung bzw. Initialisierung beim Hersteller mit einem Usernamen und einem Passwort zur Anmeldung an der Broker-URL provisioniert. Es wird zwischen der Registrierung von MQTT und NBIOT Geräten unterschieden:

Zur Registrierung der Geräte auf der Plattform muss der Hersteller eine CSV-Datei mit folgendem Inhalt und Struktur erstellen und in der Geräteverwaltung der CoD hochladen:

MQTT Die Spaltenüberschriften für eine Datei mit MQTT Geräten lautet: ID;CREDENTIALS;TYPE;NAME;ICCID;SHELL

Die Spalten werden die folgt verwendet:

• ID: externe Geräte ID
• CREDENTIALS: Passwort, das vom Gerät für die Registrierung in der Cloud of Things verwendet wird.
• TYPE: Typ des Geräts: Wenn das Gerät über MQTT verwendet werden soll, muss der Typ “mqtt” verwendet werden.
• NAME: Name des Geräts für die Anzeige in der Geräteverwaltung.
• ICCID: wird als Registrierungsname des Geräts in der Cloud of Things verwendet.
• SHELL: Ist ein Flag (0 oder 1) gibt an, ob Operations an ein Gerät gesendet werden sollen oder nicht. (1=Ja).

Ein entsprechendes Beispiel:

ID;CREDENTIALS;TYPE;NAME;ICCID;SHELL
89490200001305737267;LF2PWJoLG1Fz;mqtt;Device1;89490200001305737267;1

NB-IoT Die Spaltenüberschriften für eine Datei mit NB-IoT Geräten lautet: ID;CREDENTIALS;TYPE;NAME;ICCID;SHELL;c8y_Mobile.imsi;c8y_Mobile.imei

Die Spalten werden die folgt verwendet:

• ID: externe Geräte ID
• CREDENTIALS: Passwort, das vom Gerät für die Registrierung in der Cloud of Things verwendet wird.
• TYPE: Typ des Geräts: Wenn das Gerät über MQTT verwendet werden soll, muss der Typ “nbiot” verwendet werden.
• NAME: Name des Geräts für die Anzeige in der Geräteverwaltung.
• ICCID: wird als Registrierungsname des Geräts in der Cloud of Things verwendet.
• SHELL: Ist ein Flag (0 oder 1) gibt an, ob Operations an ein Gerät gesendet werden sollen oder nicht. (1=Ja).
• c8y_Mobile.imsi: IMSI, die Ihrer SIM-Karte zugewiesen ist. Sie erhalten die Informationen mit Ihren SIM-Karten.
• c8y_Mobile.imei: IMEI des Geräts.

Ein entsprechendes Beispiel:

ID;CREDENTIALS;TYPE;NAME;ICCID;SHELL;c8y_Mobile.imsi;c8y_Mobile.imei
89490200001305737266;LF2PWJoLG1F;nbiot;Device1;89490200001305737266;1;123456789123456;987654321098765

Für jedes neu zu registrierende Gerät muss eine Zeile in der Datei vorhanden sein.

Hinweis: Die vorregistrierten Geräte führen keine Selbstregistrierung durch, sondern melden sich gleich mit den vorprovisionierten Credentials bei der Broker-URL an.

Löschen eines Gerätes

Im Rahmen des Life-Cycles eines Gerätes kann es notwendig sein, seine Credentials und sein ManagedObject im Tenant zu löschen. Das Gerät kann dies feststellen, indem es keinen Connect mit den ihm mitgeteilten Geräte-Credentials zur Broker-URL mehr herstellen kann, dies aber zuvor noch möglich war.

Der Broker weist den Connect in diesem Fall mit „unauthorized“ zurück.

Es ist nun Aufgabe des Gerätes, erneut eine Selbstregistrierung durchzuführen. Der genaue Vorgang der Selbstregistrierung ist weiter oben beschrieben.

Die Löschung kann über das Devicemanagement der CoT erfolgen. Vor einer Neuregistrierung müssen auch die Device Credentials in der CoT gelöscht werden.

SmartRest

Allgemeines

Normalerweise bedient ein Gerät die Cloud of Things über eine REST-Schnittstelle und sendet dort per HTTP POST-, GET- und PUT-Befehle mit JSON-Strukturen im Body (Payload) hin. Dieses Verfahren ist bewährt und sicher, hat jedoch den „Nachteil”, dass sehr viele Daten hin- und hergeschickt werden müssen und somit das Transfervolumen des Gerätes auf der SIM-Karte stark ansteigt. MQTT wurde als schmalbandiges Protokoll für die Anforderungen von Geräten im Umfeld Industrie 4.0 entwickelt, soll also das zu übertragende Datenvolumen möglichst gering halten.

Da dieser Anspruch nicht mit „gesprächigem” REST/JSON vereinbar ist, wurde SmartRest entwickelt. SmartRest ist ein Verfahren, um REST/JSON-Inhalte auf ihren wesentlichen Datenteil zu reduzieren und Overhead bei der Übertragung einzusparen. Dies geschieht durch die Vereinbarung von sogenannten SmartRest Templates. Ein SmartRest Template ist eine Schablone, die beschreibt, wie gesendete Daten zu interpretieren und in JSON/REST umzusetzen sind.

Weiter muss das Gerät auch sogenannte Response-Templates definieren. Diese Templates passen zu einer erwarteten Antwort der CdD im JSON/REST-Format. Hier werden von der Plattform dann die eigentlichen Nettodaten aus dem JSON anhand der Vorgabe des Response-Templates extrahiert und formatiert.

Ein Gerät definiert seinen eigenen Satz von Templates einmalig und spricht diesen Template-Satz über eine eindeutige ID an. Die Definition eines Template-Satzes nennt man Registrierung. Die Registrierung wird entweder vom Gerät selber durchgeführt oder vom Admin-Benutzer einmalig für alle Geräte eines bestimmten Typs.

Der Geräte-Hersteller muss diesen Satz von Templates individuell für das Gerät entwickeln und zusammenstellen. Er muss entscheiden, ob das Gerät nach der Selbstregistrierung zuerst die Template-Registrierung durchführt oder ob der Admin-Benutzer im Vorfeld auf der CdD die gelieferte Template-Sammlung registrieren muss.

Ein Gerät sendet Daten, indem es angibt, welches Template (eindeutige Template-ID) es verwenden möchte und daran anschließend die zugehörigen Nettodaten als CSV mitschickt. Es erhält von der CdD eine Antwort in Form einer Response-Template-ID und den dazugehörigen Antwort-Nettodaten.

Anlegen von SmartRest Templates

Zur Kommunikation mittels SmartRest muss immer eine Sammlung von vorab registrierten Templates existieren. Es gibt sowohl Request- als auch Response-Templates.

Eine Template-Sammlung muss in der Plattform registriert werden. Die Registrierung kann auch das Gerät selber über MQTT durchführen. Allerdings wird hier die direkte REST-Schnittstelle des jeweiligen Tenants empfohlen, da eine Template-Sammlung zur Registrierung immer komplett in einem Kommando geschickt werden muss. Dies würde zu einem sehr großen MQTT-Payload führen.

Alternativ kann natürlich auch der Tenant-Administrator die Template-Sammlung(en) für die Geräte auf der Plattform registrieren.

Request-Templates

Request-Templates haben folgenden Aufbau:

10,<ID>,<METHOD>,<URI>,<CONTENT>,<ACCEPT>,<PLACEHOLDER>,<PARAMS>,<TEMPLATE>

Erläuterungen:

Hier ein Beispiel einer Templatebeschreibung, die den Status einer Operation ändert:

10,211,PUT,/devicecontrol/operations/%%,application/vnd.com.nsn.cumulocity.operation+json,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED STRING,"{""status"": ""%%""}"

Und ein weiteres Beispiel, welches ein Measurement in der Plattform erzeugt:

10,410,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,STRING STRING NUMBER STRING STRING STRING STRING,"{ ""&&"": {""&&"": { ""value"": &&, ""unit"": ""&&"" } }, ""time"": ""&&"", ""source"": { ""id"": ""&&"" }, ""type"": ""&&"" }"

Response-Templates

Response-Templates haben folgenden Aufbau:

11,<ID>,<BASE>,<COND>,<VALUE>[,<VALUE>]

Erläuterungen:

Hier ein Beispiel, welches von der Plattform ausgelesene Measurements formatiert:

11,401,$.measurements,"$.Spannung","$.time","$.Spannung.0.unit","$.Spannung.0.value"

Ein weiteres Beispiel, welches pending Operations eines bestimmten ManagedObjects formatiert:

11,201,$.operations,"$.c8y_Command","$.id","$.c8y_Command.text"

Template Sammlungen

Alle zu verwendenden Templates eines Gerätetyps werden in einer Template-Sammlung unterhalb einer sogenannten X-ID zusammengefasst und gebündelt registriert. Die X-ID dient im weiteren Gebrauch der Angabe, welche registrierte Template-Sammlung verwendet werden soll.

Eine X-ID besteht aus Ziffern und Buchstaben, wobei mindestens 1 Buchstabe verwendet werden muss. Rein numerische X-IDs sind nicht zulässig.

Template-Sammlungen zu einer X-ID können nicht geändert werden, sondern nur gelöscht und neu angelegt werden.

Die Registrierung einer Template-Sammlung führt ein Gerät über MQTT Payload selber durch oder der Tenant-Admin erledigt dies mittels eines REST POST auf:

POST https://tenant.platform/s

Die Basic-Auth wird in einem HTTP-Header-Feld übergeben. Die Template-Sammlung mit der zugehörigen X-ID im Body des REST-Calls. Die X-ID muss in der ersten Zeile zusammen mit der fixen ID 15 angegeben werden. Danach folgen alle zu registrierenden Templates zeilenweise.

Hier ein Beispiel:

15,X-ID
10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""TestDevice"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
10,101,POST,/inventory/managedObject
.
.
.

Wenn das Gerät die Template Registrierung mittels MQTT selber durchführt, muss die gesamte Template-Sammlung in einem MQTT Payload übergeben werden. Dabei muss zwingend zuerst die fixe ID 15 und die Angabe der X-ID erfolgen. Danach folgen die einzelnen Templateregistrierungen jeweils getrennt durch ein Zeilentrenner-Zeichen:

15,X-ID\n10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"\n
10,101,POST,/inventory/managedObject\n
.
.
.

Das positive Ergebnis der Plattform nach einer Templateregistrierung lautet:

20,Templatesammlung-MO-ID

Unter der Templatesammlung-MO-ID ist die Template-Sammlung in der Plattform angelegt worden.

Änderungen an einer registrierten Template-Sammlung sind nicht möglich. Die Template-Sammlung kann aber mittels Delete auf die Templatesammlung-MO-ID in den ManagedObjects gelöscht und dann neu angelegt werden.

Für diesen Zweck sollte jede Template-Sammlung ein Template zum Löschen der Sammlung enthalten:

10,TID,DELETE,/inventory/managedObjects/&&,,,&&,UNSIGNED,

Der MQTT Payload zum Aufrufen dieses Templates lautet:

15,X-ID\nTID,Templatesammlung-MO-ID

Anschließend kann die korrigierte oder ergänzte Template-Sammlung wie oben beschrieben neu registriert werden.

Selbsterstellen des Gerätes

Ein Gerät muss sich nach Erhalt seiner Credentials einmalig in der Plattform selber anlegen. Dazu meldet es sich zunächst bei der Broker-URL mit seinem Benutzernamen und Password an.

Alle weiteren Schritte erfolgen über Publish von MQTT-Payload auf den Topic ms/ICCID. Im Payload erfolgt zu Beginn immer die fixe ID 15 und die Angabe, welche X-ID angesprochen werden soll. Danach folgt ein Zeilentrennerzeichen \n und die Angabe der anzusprechenden Template-ID.

Abschließend werden die Übergabeparameter durch Kommata getrennt aufgelistet.

Zuerst prüft das Gerät, ob zu seiner ICCID (bzw. seiner eindeutigen Seriennummer) bereits eine Registrierung vorliegt (Hardwaretausch). Dazu verwendet es z.B. folgendes Template:

10,TID,GET,/identity/externalIds/c8y_Serial/%%,,application/vnd.com.nsn.cumulocity.externalId+json,%%,STRING,

Um eine passende Antwort von der Plattform zu erhalten muss dazu ein Response Template existieren:

11,RTID,,"$.externalId","$.externalId","$.managedObject.id"

Das Gerät sendet folgende Nachricht als Payload über MQTT:

15,X-ID\nTID,ICCID

Hierbei ist die eigene ICCID anzugeben. Falls bereits eine Registrierung zu dieser ICCID vorhanden ist, kommt eine Antwort - als MQTT Publish auf den Topic mr/ICCID - mit folgendem Content:

87,1,X-ID\nRTID,2,ICCID,MO-ID

Das Gerät sollte nun diese ManagedObject-ID als eigene MO-ID für alle weiteren Aktionen verwenden.

Falls noch keine Registrierung vorhanden ist, kommt eine Fehlermeldung

50,2,404,Not Found

über mr/ICCID zurück. Das bedeutet für das Gerät, dass es sich nun zunächst selber als ManagedObject anlegen muss.

Dazu existiert eine Template-Registrierung, die das MO und seine grundlegenden Eigenschaften beschreibt:

10,TID,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity. managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json, &&,STRING STRING,"{""name"":""&&"",""type"":""&&"",""c8y_IsDevice"":{}"":{},""com_cumulocity_model_Agent"":{}}"

Um die ID des MO als Antwort zu erhalten, muss ein passendes Response Template existieren:

11,RTID,,"$.c8y_IsDevice","$.id"

Das Gerät sendet zum Selbsterstellen eine MQTT-Message mit folgendem Payload:

15,X-ID\nTID,ICCID,DeviceName

Die Plattform meldet einen RC und die ManagedObjectId, wenn das Anlegen des MO verarbeitet wurde:

87,1,X-ID\nRTID,2,MO-ID

Das Gerät registriert nun seine ICCID - oder eine andere, eindeutige Seriennummer wie z.B. seine MAC-Id - in globalIds als externalId . Dazu existiert ein Template:

10,TID,POST,/identity/globalIds/%%/externalIds,application/vnd.com.nsn.cumulocity.externalId+json,application/vnd.com.nsn.cumulocity.externalId+json,%%,STRING STRING,"{ ""type"" : ""c8y_Serial"", ""externalId"" : ""%%""}"

Das Gerät sendet zum Selbsterstellen in den ExternalIds eine MQTT-Message mit folgendem Payload:

15,X-ID\nTID,MO-ID,ICCID

Achtung: ohne die Registrierung der ICCID/Seriennummer in den globalIds kann das Gerät nicht automatisiert Operations empfangen!

Anschließend macht das Gerät ein Update auf sein ManagedObject und trägt gerätespezifische Info-Daten, wie ICCID, IMSI, Soft- und Firmware-Releasestände, seinen Typ und seine Hardware-Seriennummer (siehe externalIds) ein:

10,TID,PUT,/inventory/managedObjects/&&,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,UNSIGNED STRING STRING STRING STRING STRING STRING STRING STRING STRING STRING,"{""c8y_Hardware"":{""model"":""&&"",""revision"":""&&"",""serialNumber"":""&&""},""c8y_SoftwareList"":[{""name"":""Application"",""version"":""&&"",""url"":""none""},{""name"":""Bootloader"",""version"":""&&"",""url"":""none""},{""name"":""Bluetooth"",""version"":""&&"",""url"":""none""},{""name"":""Modem"",""version"":""&&"",""url"":""none""}],""c8y_Mobile"":{""imei"":""&&"",""iccid"":""&&"",""imsi"":""&&""}}"

Das Gerät sendet zum Update des ManagedObjects eine MQTT-Message mit folgendem Payload:

15,X-ID\nTID,MO-Id,Model,RevNr,HardwareSerialNumber,AppVersion,BLVersion,BTVersion,ModVersion,IMEI,ICCID,IMSI

Abschließend sollte das Gerät ein weiteres Update auf sein ManagedObject machen und seine Supported Operations eintragen. Diese sind natürlich gerätespezifisch:

10,TID,PUT,/inventory/managedObjects/&&,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,UNSIGNED,"{""c8y_SupportedOperations"": [ ""c8y_Configuration"",""c8y_SendConfiguration"",""c8y_DownloadConfigFile"",""c8y_UploadConfigFile"",""c8y_Software"",""c8y_SoftwareList"",""c8y_Firmware"",""c8y_FirmwareList"",""c8y_SystemCommand"",""c8y_Command"",""c8y_Restart"" ] }"

Das Gerät sendet zum Update des MO eine MQTT-Message mit folgendem Payload:

15,X-ID\nTID,MO-Id

Nun existiert das Gerät korrekt angelegt auf der Plattform und kann jetzt Measurements, Alarme usw. senden.

Senden von Messwerten

Wenn ein Gerät vollständig auf der Plattform angelegt ist, kann es beginnen, Messwerte, Ereignisse und Alarme zu senden.

Für diese Sendevorgänge sind ebenfalls Templates in der Template-Sammlung zu registrieren. Nachfolgend ein Beispiel für ein Template zum Senden eines Messwertes und seine Verwendung im MQTT-Payload.

Angenommen es existiert eine Template-Registrierung:

10,TID,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,STRING STRING NUMBER STRING STRING STRING STRING,"{ ""&&"": {""&&"": { ""value"": &&, ""unit"": ""&&"" } }, ""time"": ""&&"", ""source"": { ""id"": ""&&"" }, ""type"": ""&&"" }"

Nun erhält das Gerät einen Messwert von einem Temperatursensor und published diesen als Payload mit MQTT auf ms/ICCID:

15,X-ID\nTID,Temperatur,0,395.3,°C,2017-09-14T12:37:00.000,MO_ID,c8y_TemperatureMeasurement

Wichtig ist hierbei der Timestamp, welcher den exakten Zeitpunkt der Messung mitteilt. Der erste Parameter bezeichnet den gesamten Messwert, wie er dann im User Interface der Plattform aufgelistet wird.

Der zweite Parameter “0” ist die Bezeichnung für die Messwert-Serie oder der Kurvenbezeichner. Damit könnte man beispielsweise Temperaturmesswerte von unterschiedlichen Sensoren in einer Messwertgrafik zusammenfassen und ihre einzelnen Kurven eindeutig kennzeichnen.

Danach folgt der eigentliche Messwert, hier 395.3. Dann die Einheit, hier °C. Nach dem Timestamp der Messung folgt die Angabe zum eigenen ManagedObject, damit der Messwert in der Plattform zum korrekten Gerät referenziert. Abschließend noch der Typ des Messwertes. Hier können fest vorgegebene Plattform-Konstanten oder eigene Konstanten verwendet werden.

Das Ergebnis der Messwertübertragung wird dem Gerät als MQTT Nachricht auf den Topic mr/ICCID gepublished.

Senden von Ereignissen

Für das Senden von Ereignissen sind ebenfalls Templates in der Template-Sammlung zu registrieren. Nachfolgend ein Beispiel für ein Template zum Senden der aktuellen Geoposition des Gerätes und seine Verwendung im MQTT-Payload.

10,TID,POST,/event/events,application/vnd.com.nsn.cumulocity.event+json,application/vnd.com.nsn.cumulocity.event+json,&&,STRING STRING NUMBER NUMBER NUMBER,"{ ""time"": ""&&"", ""type"": ""c8y_LocationUpdate"", ""text"": ""Position changed."", ""source"": { ""id"": ""&&"" }, ""c8y_Position"": { ""lng"": ""&&"", ""alt"": ""&&"", ""lat"": ""&&"" } }"

Das Gerät published seine aktuelle Geoposition als PositionUpdateEvent über den Payload einer MQTT-Nachricht auf ms/ICCID:

15,X-ID\nTID,2017-09-14T12:37:00.000,MO-ID,7.1424255,77,50.746994

Hier wird als erster Parameter wieder die X-ID der Template-Sammlung übergeben. Dann folgt ein Zeilentrenner und danach die Template-ID gefolgt von einem Timestamp mit dem Zeitpunkt des Ereignisses.

Nach der Referenz auf das eigene ManagedObject folgen abschließend die drei Parameter Longitude, Altitude und Latitude.

Auf gleiche Art kann jede Art von Ereignis gesendet werden. Ereignisse sind in der Plattform frei konfigurierbar. Es sind jedoch einige minimale Parameter anzugeben:

Senden von Alarmen

Alarme sind Ereignisse, die vom Anwender besondere Aufmerksamkeit erfordern oder sogar zusätzliche Alarmierungmechanismen wie SMS-Versand auslösen.

Der Versand von Alarmen erfordert ebenfalls eine vorherige Registrierung entsprechender Templates:

10,TID,POST,/alarm/alarms,application/vnd.com.nsn.cumulocity.alarm+json,application/vnd.com.nsn.cumulocity.alarm+json,&&,STRING STRING STRING STRING STRING STRING,"{ ""type"": ""&&"", ""time"": ""&&"", ""text"": ""&&"", ""status"": ""&&"", ""severity"": ""&&"", ""source"": { ""id"": ""&&"" } }"

Das Gerät sendet einen Alarm durch das Publishen einer MQTT-Nachricht mit entsprechendem Payload auf ms/ICCID:

15,X-ID\nTID,Kesseltemperatur,2017-09-14T12:37:00.000,"Kesseltemperatur stark erhoeht",ACTIVE,MAJOR,MO-ID

Auch hier erfolgt nach Angabe der fixen ID 15 die Angabe der X-ID gefolgt von einem Zeilentrennerzeichen. Nach Angabe der Template-ID steht die Angabe zum Alarm-Typ (Kesseltemperatur), danach der Timestamp des Alarmzeitpunkts und ein Alarmtext.

Anschließend der Alarm-Status (ACTIVE, ACKNOWLEDGED oder CLEARED) und seine Wichtigkeit (CRITICAL, MAJOR, MINOR oder WARNING), jeweils immer in Großbuchstaben.

Den Abschluss bildet die eigene ManagedObject-ID, damit das referenzierende Gerät gefunden werden kann.

Anlegen und Verknüpfen eines Child-Devices

Geräte - insbesondere Gateway-Geräte - können über Kind-Geräte (Child-Devices) verfügen. Ein Gerät muss seine Child-Devices auf der Plattform selber anlegen und mit seinem ManagedObject verknüpfen.

Zu diesem Zweck sollten zwei Templates in der Template-Sammlung des Gerätes vorhanden sein.

Template A legt ein Child-Device als ManagedObject auf der Plattform an. Hier ist zu beachten, dass das Fragment “c8y_IsDevice:{}" nicht gesetzt wird, damit das Child-Device nicht in der Geräteliste sichtbar ist:

10,TID1,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,STRING,"{""name"":""&&"",""com_IsChildDevice"":""{}""}"

Passend dazu gibt es ein Response Template, um die neue MO-ID des Child-Devices als Antwort von der Plattform zu erhalten:

11,RTID,,"$.com_IsChildDevice","$.id"

Template B erzeugt den Link vom ManagedObject des Gerätes zum ManagedObject des Child-Devices:

10,TID2,POST,/inventory/managedObjects/%%/childDevices,application/vnd.com.nsn.cumulocity.managedObjectReference+json,application/vnd.com.nsn.cumulocity.managedObjectReference+json,%%,STRING STRING,"{ ""managedObject"" : { ""self"" : ""https://.../inventory/managedObjects/%%"" } }"

Das Gerät erstellt per MQTT zuerst ein Child-Device:

15,X-ID\nTID1,"Child-Device-Name"

Als Antwort sendet die Plattform:

87,1,X-ID\nRTID,2,Child-MO-ID

Nun muss das Gerät mit seinem eigenen ManagedObject die MO-ID des Child-Devices verknüpfen. Dazu ruft es das Template B mit folgendem Payload auf:

15,X-ID\nTID2,MO-ID,Child-MO-ID

Das Child-Device ist jetzt mit dem Gerät verknüpft und kann im UI der Plattform unter “Kindgeräte” ausgewählt und angesehen werden. Außerdem können jetzt weitere Eigenschaften des Child-Devices an seinem ManagedObject hinterlegt und geändert werden. Es verhält sich hier genau wie ein Geräte-ManagedObject.

Operations

Operations sind Anweisungen, die über die Plattform an ein Gerät geschickt werden. Das Gerät muss die Operation interpretieren, ausführen und Ergebnisse bzw. einen Status zurückmelden.

Operations werden zum Gerät über den Topic mr/ICCID gepublished. Da das Gerät auf diesen Topic subscribed ist, erhält es neue Operations automatisch.

Sobald eine Operation für ein Gerät erstellt wurde, wird diese bei der nächsten Verbindung gesendet. Es ist nicht möglich, eine Operation nach seiner Erstellung abzubrechen. Alle erstellten Operations werden bei der nächsten Verbindung an den Broker gesendet.

Bindende Voraussetzung für jede Template-Sammlung ist, dass unter der Template-ID 500 ein GET Template registriert ist, welches neue Operations von der Plattform abholt. Das Gerät verwendet dieses Template nicht, die komplette Steuerung übernimmt hier der MQTT Connector.

Weiter ist zu beachten, dass bei mehreren vorhandenen Template-Sammlungen das Template mit der ID 500 in genau der Template-Sammlung existieren muss, welche das Gerät bei seiner ersten Aktion verwendet, beispielsweise das Überprüfen der eigenen ICCID/Serial in den ExternalIds (s.o.). Dies gilt auch für alle Response-Templates zu den Operations.

10,500,GET,/devicecontrol/operations/%%,,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED,

Bitte beachten Sie, dass ohne die Registrierung dieses Templates mit der ID 500 das Gerät nicht automatisiert Operations empfangen kann. Außerdem muss zwingend der erste Request an den Broker mit einem Template aus der Template-Sammlung geschickt werden, in der dieses 500er Template registriert ist.

Das Gerät legt außerdem anhand von Response-Templates in seiner Template-Sammlung fest, in welchem Format es Informationen zu bestimmten Operations erwartet:

11,TID,,"@.,$.operations,"$.c8y_Command","@.id","@.c8y_Command.text"

Dieses Response Template kann beispielsweise folgenden Content als Antwort erzeugen:

87,1,X-ID\nTID,2,OP-ID,ls -l

Auf der Plattform wird eine Operation mit folgendem JSON erstellt:

{
    "creationTime": "2017-09-14T13:01:27.740+02:00",
    "deviceId": MO-ID,
    "deviceName": "DeviceName",
    "id": OP-ID,
    "status": "PENDING"
    "c8y_Command": {
        "result": " ",
        "syntax": null,
        "text": "ls -l"
        },
    "description": "Execute shell command"
}

Das Gerät muss nun die Operation - in diesem Fall das Shell-Kommando “ls -l” - ausführen und eventuelle Ergebnisse sowie den Ergebnisstatus (SUCCESSFUL oder FAILED) zurückmelden.

Auch dazu müssen Template Registrierungen in der Template Sammlung definiert sein. Das nachfolgende Beispiel zeigt ein Template, mit dem das Ergebnis der vorstehenden Operation und der aktualisierte Status zurückgemeldet werden kann:

10,TID,PUT,/devicecontrol/operations/%%,application/vnd.com.nsn.cumulocity.operation+json,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED STRING STRING STRING,"{""status"": ""%%"", ""c8y_Command"": {""result"": ""%%"",""syntax"": """",""text"": ""%%""}}"

Das Gerät published dazu eine MQTT Nachricht mit folgendem Payload auf den Topic ms/ICCID:

15,X-Id\nTID,OP-ID,"SUCCESSFUL","total 28496 -rw-r--r-- 1 user staff 474559 10 Mai 10:08 D-Route5.gpx drwxr-xr-x 6 user staff 192 18 Sep 10:11 Distribute -rw-r--r-- 1 user staff 6959276 8 Aug 11:59 GTEClient.jar","ls -l"

Wichtigstes Merkmal ist bei allen Aktionen die OperationID (OP-ID), die zusammen mit der Operation übermittelt wurde. Mit der OP-ID werden Operations auf der Plattform eindeutig referenziert.

Handhabung von Operationen für Child-Devices

Operations, die für ein zugewiesenes untergeordnetes Gerät (Child-Device) auf der Plattform konfiguriert sind, werden ebenfalls mit dem Topic mr/ICCID auf dem Gerät veröffentlicht.

Die MO-ID in der Antwort entspricht der MO-ID des untergeordneten Geräts.

Daher muss das übergeordnete Gerät (Parent-Device) (Gateway) die MO-IDs seiner zugewiesenen untergeordneten Geräte kennen, um die Vorgänge an seine untergeordneten Geräte weiterleiten zu können. Die Antworten und Statusaktualisierungen der Vorgänge müssen vom übergeordneten Gerät an die Plattform für seine untergeordneten Geräte gesendet oder verarbeitet werden.

Eigenen Tenant abfragen

Falls der verbundene Tenant von einem selbstregistrierten Gerät benötigt wird beispielsweise um per HTTPS-Verbindung einen Firmware-Download durchzuführen - kann dies mit Hilfe von zwei Templates erreicht werden:

10,800,GET,/user/currentUser,,,,,
11,801,,"$.userName","$.self"

Wenn das Gerät dann den SR-Request 800 abschickt, erhält es folgende Antwort:

801,1,http://<yoururl>.ram.m2m.telekom.com/currentUser

Der aktuelle Tenant kann dann aus dieser Antwort ermittelt werden.

Hardware austauchen

Im Laufe der Zeit wird es aufgrund von Defekten zu Hardwareänderungen kommen. Trotzdem sollten die bereits gesammelten Daten erhalten bleiben und sollte wie gewohnt ablaufen.

Dies wird durch die Selbstregistrierung des Ersatzgeräts oder eine Neuregistrierung einer sogenannten „Identität“ in CoT garantiert.

Die Erstellung einer Identität muss in der Geräteverwaltungsanwendung in CoT erfolgen. Wählen Sie “Alle Geräte” und wählen Sie das entsprechende Gerät aus. Wählen Sie im Gerätemenü die Registerkarte “Identität” und “Identität hinzufügen”. (z.B. Seriennummer)

Achtung: Es muss der derselbe Typ wie bei der alten Identität verwendet werden muss. Es muss nur eine neue “external_ID” erstellt werden. Der nächste Schritt besteht darin, die alten Anmeldeinformationen des Geräts auf der Registerkarte “Anmeldeinformationen des Geräts” zu löschen. Jetzt startet das neue Gerät eine Selbstregistrierung und muss den Gerätebenutzer/ die ICCID des geänderten Geräts verwenden.

Neue Anmeldeinformationen für diesen Nutzer können mit der Selbstregistrierung erstellt werden, und das alte MO kann diese neuen Anmeldeinformationen verwenden. Es ist nur wichtig, dass der Gerätebenutzer denselben Namen hat.

SMARTREST binary payload

SmartRest-Nachrichten können auch binär codiert werden, um das Datenvolumen zu reduzieren.

Hierzu stehen folgende MQTT-Topics zur Verfügung:

Eine binäre request MQTT-Nachricht hat die folgende Struktur:

<XID><TID><Payload>

wobei:

Die Rohdaten bestehen aus Werten, die gemäß den SmartRest-Templates die folgenden Datentypen haben können:

Eine MQTT-Nachricht kann aus mehreren binären MQTT-Nutzdaten bestehen:

<XID><TID><Payload><XID><TID><Payload><XID><TID><Payload>...

Eine auf diese Weise definierte binär codierte Nachricht kann wie folgt geparsed werden:

• Zu Beginn wird die 0-terminierte Zeichenfolge extrahiert und als <XID> interpretiert
• Die Template-ID <TID> wird aus den nächsten zwei Bytes ermittelt
  • Hinweis: Im Gegensatz zum normalen SmartRest, bei dem die TID bis zu 4 Byte lang sein kann, können binäre Anfragen nur auf TIDs bis zu 65535 zugreifen.
• Die Template-Sammlung mit <XID> wird verwendet, um die SmartRest-Templates mit der <TID> zu ermitteln und bereitzustellen. Basierend auf der in der SmartRest-Templates definierten Reihenfolge der Datentypen werden die nächsten Bytes der Nachricht in die entsprechenden Datentypen konvertiert. Diese Daten werden verwendet, um eine herkömmliche SmartRest MQTT-Nachricht zu generieren.
• Die generierte Nachricht wird dann an die Cloud of Things gesendet.
• Wenn das Byte-Array nach dem Parsen der ersten Nachricht weitere Bytes enthält, werden diese als eine andere Nachricht interpretiert und auf die gleiche Weise verarbeitet.

Um den MQTT-Standard für binäre Nutzdaten effizient zu verwenden, sollten Sie sicherstellen, dass der Datentyp STRING nach Möglichkeit vermieden wird.

Dementsprechend sollten die SmartRest-Templates so angepasst werden, dass Daten wie Zahlen und Daten geeigneten Datentypen zugeordnet werden und Werte wie Status, Messdatenbeschreibung und Typ nicht mehr als variable Daten übertragen werden müssen, sondern im Template vordefiniert sind. Sie können beispielsweise auf die Übertragung des Status eines Vorgangs verzichten, indem Sie für jeden Status ein eigenes Template definieren.

1. Optimiertes Template zum Senden des Ergebnisses einer erfolgreich ausgeführten Operation:

   10,410,PUT,/devicecontrol/operations/%%,application/vnd.com.nsn.cumulocity.operation+json,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED STRING STRING,"{""status"": ""SUCCESSFUL"", ""c8y_Command"": {""result"": ""%%"",""syntax"": """",""text"": ""%%""}}"
   

2. Optimiertes Template zum Senden des Ergebnisses einer fehlgeschlagenen Operation:

   10,411,PUT,/devicecontrol/operations/%%,application/vnd.com.nsn.cumulocity.operation+json,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED STRING STRING,"{""status"": ""FAILED"", ""c8y_Command"": {""result"": ""%%"",""syntax"": """",""text"": ""%%""}}"
   

Zur besseren Lesbarkeit sind die Werte in den folgenden Nachrichtenbeispielen durch ein Leerzeichen getrennt. Werte vom Datentyp STRING werden in Anführungszeichen gesetzt, die nicht in der Payload erscheinen. Ein Datumswert vom Typ DATE wird als “” (= Unix Timestamp in Sekunden) dargestellt.

Eine MQTT-Nachricht im Binärformat, die das Ergebnis einer Operation unter Verwendung des Templates ‘(1)’ sendet und den Status auf “SUCCESSFUL” setzt, sieht dann folgendermaßen aus:

"myXID" 410 11203 "README.md Device93707.properties" "ls"

In hexadezimalen Format:

6D 79 58 49 44 00
01 9A
00 00 2B C3
52 45 41 44 4D 45 2E 6D 64 20 44 65 76 69 63 65 39 33 37 30 37 2E 70 72 6F 70 65 72 74 69 65 73 00
6C 73 00

Beachten Sie, dass die Nachricht natürlich wirklich die entsprechenden Bytewerte enthalten muss. Dies bedeutet: 109, 121, 88, 73, 68, 0 usw. und nicht die Zeichen “6”, “D”, “7” usw. im hexadezimalen Format. Dies wird hier nur ausgewählt, um auch nicht druckbare Bytes anzuzeigen.

Binäre Nutzdaten können beispielsweise für mosquitto_pub mit dem Parameter –stdin-file / -s gesendet werden:

cat getOperation.bin | mosquitto_pub -t "bs/ICCID" -h BROKER_HOST -u ICCID
-P PASSWORD -p 8883 --cafile CERTIFICATE_FILE -s

Ein optimiertes Template zum Senden von elektrischen Messwerten im Binärformat:

10,300,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,NUMBER DATE UNSIGNED,"{ ""Spannung"": {""U"": { ""value"": &&, ""unit"": ""Volt"" } }, ""time"": ""&&"", ""source"": { ""id"": ""&&"" },""type"": ""c8y_VoltageMeasurement"" }"

"myXID" 300 11.3583 <TS> 42503

Ein optimiertes Template zum Senden von Temperatur Messwerten im Binärformat:

10,305,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,NUMBER DATE UNSIGNED,"{ ""Temperatur"": {""T"": { ""value"": &&, ""unit"": ""°Celsius"" } }, ""time"": ""&&"", ""source"": { ""id"": ""&&"" },""type"": ""c8y_TemperatureMeasurement"" }"

"myXID" 305 22.5 <TS> 42503

Fehlerbehandlung

Zusätzlich zu den im Anhang aufgeführten SmartRest-Fehlercodes können bei der Verarbeitung von binären MQTT-Nachrichten die folgenden Fehlermeldungen auftreten.

Die Fehlermeldungen haben dasselbe Format wie die Cloud of Things SmartREST-Fehlermeldungen und werden über das Topic br/ICCID an das Gerät gesendet.

Platzhalter in Fehlermeldungen

Die folgenden Fehlermeldungen werden mit Platzhaltern in spitzen Klammern (< und >) angezeigt. Wenn die Fehlermeldung übermittelt wird, werden diese Platzhalter mit konkreten Werten gefüllt. Die folgenden Platzhalter werden in Fehlermeldungen verwendet:

Fehlende X-ID

Wenn die X-ID in der Nachricht nicht vorhanden ist oder nicht mit 0-terminiert ist:

42 Malformed Request: no X-Id found in binary message '<Binary-MessageIndex>' around byte '<Byte-Position>'

Fehlende Template ID

Wenn die Template-ID einer Nachricht nicht ermittelt werden kann:

42 Malformed Request: no Template ID found in binary message '<BinaryMessage-Index>' around byte '<Byte-Position>'

SmartRequest Template nicht gefunden

Wenn die ermittelte Template-ID oder X-ID nicht im Cache gefunden werden kann:

43 Invalid template identifier: template with X-ID '<X-ID>' and Template ID '<Template-ID>' not found in cache

Die Ursache kann das sein

• Das Template, auf das referenziert wird, wurde im Tenant der “Cloud of Things” nicht definiert.
• Das Template wurde noch nicht vom Tenant geladen. In diesem Fall sollte das Problem nach einigen Minuten verschwinden.

Invalid parameters

Wenn einer der angegebenen Parameter nicht korrekt geparsed werden kann:

45 Invalid parameter at position '<Parameter-Position>': Expected type '<Parameter-Type>' in binary message '<Binary-Message-Index>' around byte '<Byte-Position>'

SmartRest Codes

Smartrest Response Codes

Auf jevon Cloud of Things SmartRest Command sendet die Plattform ein Ergebnis als MQTT Payload auf den Topic mr/ICCID . Nachfolgend sind die Codes erklärt.

SmartRest Fehlercodes

Beispiel einer Template-Sammlung

15,TestTemplates-01
10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""TestDevice"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
10,101,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,STRING,"{""name"":""&&"",""com_IsChildDevice"":""{}""}"
10,102,POST,/inventory/managedObjects/%%/childDevices,application/vnd.com.nsn.cumulocity.managedObjectReference+json,application/vnd.com.nsn.cumulocity.managedObjectReference+json,%%,STRING STRING,"{ ""managedObject"" : { ""self"": ""https://.../inventory/managedObjects/%%"" } }"
10,103,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Modbus Test Device"",""type"":""POSIXAgent"",""c8y_IsDevice"":{},""com_cumulocity_model_Agent"":{},""c8y_ModbusConfiguration"": {""protocol"": ""TCP"",""transmitRate"": 10,""pollingRate"": 10},""c8y_SerialConfiguration"": { ""baudRate"": 19200,""stopBits"": 1,""parity"": ""E"",""dataBits"": 8} }"
10,110,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,STRING STRING,"{""name"":""&&"",""type"":""&&"",""c8y_IsDevice"":{},""com_cumulocity_model_Agent"":{}}"
11,111,,"$.c8y_IsDevice","$.id"
11,112,,"$.com_IsChildDevice","$.id"
10,120,POST,/identity/globalIds/%%/externalIds,application/vnd.com.nsn.cumulocity.externalId+json,application/vnd.com.nsn.cumulocity.externalId+json,%%,STRING STRING,"{ ""type"" : ""c8y_Serial"", ""externalId"" : ""%%"" }"
10,130,GET,/identity/externalIds/c8y_Serial/%%,,application/vnd.com.nsn.cumulocity.externalId+json,%%,STRING,
11,135,,"$.externalId","$.externalId","$.managedObject.id"
10,200,GET,/devicecontrol/operations?deviceId=%%&nocache=true&status=PENDING,,application/vnd.com.nsn.cumulocity.operationCollection+json,%%,UNSIGNED,
11,201,$.operations,"$.c8y_Command","$.id","$.c8y_Command.text"
11,202,$.operations,"$.c8y_Restart","$.id","$.description"
11,203,$.operations,"$.c8y_Firmware","$.id","$.c8y_Firmware.url"
11,205,,"@.c8y_Command","@.id","@.c8y_Command.text"
11,206,,"@.c8y_Restart","@.id","@.description"
11,207,,"@.c8y_Firmware","@.id","@.c8y_Firmware.url"
10,211,PUT,/devicecontrol/operations/%%,application/vnd.com.nsn.cumulocity.operation+json,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED STRING,"{""status"": ""%%""}"
10,212,PUT,/devicecontrol/operations/%%,application/vnd.com.nsn.cumulocity.operation+json,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED STRING STRING STRING,"{""status"": ""%%"", ""c8y_Command"": {""result"": ""%%"",""syntax"": """",""text"": ""%%""}}"
10,300,PUT,/inventory/managedObjects/&&,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,UNSIGNED STRING STRING STRING STRING STRING STRING STRING STRING STRING STRING,"{""c8y_Hardware"":{""model"":""&&"",""revision"":""&&"",""serialNumber"":""&&""},""c8y_SoftwareList"":[{""name"":""Application"",""version"":""&&"",""url"":""none""},{""name"":""Bootloader"",""version"":""&&"",""url"":""none""},{""name"":""Bluetooth"",""version"":""&&"",""url"":""none""},{""name"":""Modem"",""version"":""&&"",""url"":""none""}],""c8y_Mobile"":{""imei"":""&&"",""iccid"":""&&"",""imsi"":""&&""}}"
10,310,PUT,/inventory/managedObjects/&&,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,UNSIGNED,"{""c8y_SupportedOperations"": [ ""c8y_Configuration"",""c8y_SendConfiguration"",""c8y_DownloadConfigFile"",""c8y_UploadConfigFile"",""c8y_Software"",""c8y_SoftwareList"",""c8y_Firmware"",""c8y_FirmwareList"",""c8y_SystemCommand"",""c8y_Command"",""c8y_Restart"" ] }"
10,320,PUT,/inventory/managedObjects/&&,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,&&,UNSIGNED STRING STRING STRING,"{""c8y_Firmware"": {""name"": ""&&"", ""version"": ""&&"", ""url"": ""&&""} }"
10,350,DELETE,/inventory/managedObjects/&&,,,&&,UNSIGNED,
10,400,GET,/measurement/measurements?source=%%&pageSize=1000,,,%%,UNSIGNED,
11,401,$.measurements,"$.Spannung","$.time","$.Spannung.0.unit","$.Spannung.0.value"
11,402,$.measurements,"$.Kesseltemperatur","$.time","$.Kesseltemperatur.0.unit","$.Kesseltemperatur.0.value"
10,410,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,STRING STRING NUMBER STRING STRING STRING STRING,"{ ""&&"": {""&&"": { ""value"": &&, ""unit"": ""&&"" } }, ""time"": ""&&"", ""source"": { ""id"": ""&&"" }, ""type"": ""&&"" }"
10,450,GET,/measurement/measurements?source=%%&dateFrom=%%&dateTo=%%&pageSize=1000,,,%%,UNSIGNED STRING STRING,
10,500,GET,/devicecontrol/operations/%%?nocache=true,,application/vnd.com.nsn.cumulocity.operation+json,%%,UNSIGNED,
10,550,GET,/alarm/alarms?source=%%&pageSize=1000,,,%%,UNSIGNED,
11,551,$.alarms,"$.severity","$.time","$.status","$.text","$.type"
10,560,POST,/alarm/alarms,application/vnd.com.nsn.cumulocity.alarm+json,application/vnd.com.nsn.cumulocity.alarm+json,&&,STRING STRING STRING STRING STRING STRING,"{""type"": ""&&"", ""time"": ""&&"", ""text"": ""&&"", ""status"": ""&&"",""severity"": ""&&"", ""source"": { ""id"": ""&&"" } }"
10,600,GET,/event/events?source=%%&pageSize=1000,,,%%,UNSIGNED,
11,601,$.events,"$.c8y_Position","$.time","$.c8y_Position.lng","$.c8y_Position.alt","$.c8y_Position.lat"
10,610,POST,/event/events,application/vnd.com.nsn.cumulocity.event+json,application/vnd.com.nsn.cumulocity.event+json,&&,STRING STRING NUMBER NUMBER NUMBER,"{""time"": ""&&"", ""type"": ""c8y_LocationUpdate"", ""text"": ""Position changed."", ""source"": { ""id"": ""&&"" }, ""c8y_Position"": { ""lng"": ""&&"", ""alt"": ""&&"", ""lat"": ""&&"" } }"
10,900,GET,/measurement/measurements?source=%%&dateFrom=%%&dateTo=%%&pageSize=1000,,,%%,UNSIGNED STRING STRING,