Gerätemanagementprotokoll

Lebenszyklus im Gerätemanagement

1. Eine Einheit und der zugehörige Einheitentyp werden erstellt.
2. Ein Gerät verbindet sich mit dem IoT Tool und sendet eine Anfrage zum Verwalten des Geräts, um zu einem verwalteten Gerät zu werden.
3. Sie können die Metadaten für ein Gerät mithilfe der IoT Tool-REST-API anzeigen und bearbeiten. Diese API-Operationen – beispielsweise Firmware-Aktualisierung und Neustart des Geräts – werden im Abschnitt „Geräteverwaltungsanfragen“ beschrieben.
4. Ein Gerät kann Aktualisierungen zu seiner Position, zu Diagnoseinformationen und Fehlercodes mithilfe des Gerätemanagementprotokolls kommunizieren.
5. Wenn ein Gerät außer Betrieb genommen wird, können Sie es über die Benutzeroberfläche oder die REST-API aus dem IoT Tool entfernen.

Anforderungen des Typs 'Gerät verwalten'

Ein Gerät verwendet die Anforderung 'Gerät verwalten', um ein verwaltetes Gerät zu werden. Ein Gerätemanagementagent muss eine Anforderung 'Gerät verwalten' senden, bevor er Anforderungen vom Server empfangen kann. Ein Gerätemanagementagent sendet diesen Anforderungstyp in der Regel bei jedem Start oder Neustart.

Topic für eine Anforderung des Typs 'Gerät verwalten'

Ein Gerät publiziert eine Anforderung des Typs 'Gerät verwalten' im folgenden Topic:

iotdevice-1/mgmt/manage

Der Server antwortet auf eine Anforderung des Typs 'Gerät verwalten' im folgenden Topic:

iotdm-1/response

Nachrichtenformat für eine Anforderung des Typs 'Gerät verwalten'

In einer Anfrage des Typs 'Gerät verwalten' sind das Feld d und alle zugehörigen Unterfelder optional. Die Werte der Felder metadata und deviceInfo ersetzen die entsprechenden Attribute für das sendende Gerät, falls sie gesendet werden.

Das optionale Feld lifetime gibt den Zeitraum in Sekunden an, in dem das Gerät eine weitere Anforderung zur Geräteverwaltung senden muss, um zu verhindern, dass es als ruhend klassifiziert wird und zu einem nicht verwalteten Gerät wird. Wenn das Feld lifetime weggelassen oder auf 0gesetzt wird, wird das verwaltete Gerät nicht zu einem ruhenden Gerät. Der Mindestwert, der für das Feld lifetime unterstützt wird, beträgt 3600 Sekunden (1 Stunde).

Die optionalen Felder supports.deviceActions und supports.firmwareActions geben die Funktionalitäten des Gerätemanagementagenten an. Wird supports.deviceActions festgelegt, unterstützt der Agent sowohl die Aktionen Neustart als auch Zurücksetzen. Für ein Gerät, das nicht zwischen einem Neustart und dem Zurücksetzen auf Werkseinstellungen unterscheidet, ist es akzeptabel, dass für beide Aktionen dasselbe Verhalten verwendet wird. Ist supports.firmwareActions gesetzt, unterstützt der Agent sowohl Die Aktionen Firmware-Download als auch Firmware-Update.

Das folgende Beispiel zeigt das Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/mgmt/manage
{
    "d": {
        "metadata":{},
        "lifetime": number,
        "supports": {
            "deviceActions": boolean,
            "firmwareActions": boolean
        },
        "deviceInfo": {
            "serialNumber": "string",
            "manufacturer": "string",
            "model": "string",
            "deviceClass": "string",
            "description" :"string",
            "fwVersion": "string",
            "hwVersion": "string",
            "descriptiveLocation": "string"
        }
    },
    "reqId": "string"
}

Das folgende Beispiel zeigt das Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Gerät verwalten'

Anforderungen des Typs 'Gerät nicht verwalten'

Ein Gerät verwendet eine Anforderung des Typs 'Gerät nicht verwalten', wenn eine Verwaltung nicht mehr erforderlich ist. Wenn ein Gerät nicht mehr verwaltet wird, sendet das IoT Tool keine neuen Geräteverwaltungsanforderungen mehr an das Gerät. Nicht verwaltete Geräte können weiterhin Fehlercodes, Protokollnachrichten und Positionsnachrichten publizieren.

Topic für die Anforderung 'Gerät nicht verwalten'

Ein Gerät publiziert eine Anforderung des Typs 'Gerät nicht verwalten' im folgenden Topic:

iotdevice-1/mgmt/unmanage

Der Server antwortet auf eine Anforderung des Typs 'Gerät nicht verwalten' im folgenden Topic:

iotdm-1/response

Nachrichtenformat für eine Anforderung des Typs 'Gerät nicht verwalten'

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/mgmt/unmanage
{
    "reqId": "string"
}

Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Nicht verwaltetes Gerät'

Anforderung 'Position aktualisieren'

Die Standort-Metadaten für ein Gerät können im IoT Tool auf folgende Weise aktualisiert werden:

Automatische Aktualisierungen der Geräteposition

• Geräte, die ihren Standort bestimmen können, können den IoT Tool-Geräteverwaltungsserver über Standortänderungen benachrichtigen. Das Gerät benachrichtigt das IoT Tool über die Standortaktualisierung. Das Gerät ruft seinen Standort beispielsweise über einen GPS-Empfänger ab und sendet eine Geräteverwaltungsnachricht an die IoT Tool-Instanz, um seinen Standort zu aktualisieren. Anhand einer Zeitmarke wird der Zeitpunkt erfasst, an dem die Position vom GPS-Empfänger abgerufen wurde. Die Zeitmarke ist gültig, auch wenn beim Senden der Nachricht zur Aktualisierung der Position eine Verzögerung auftritt. Der Server zeichnet das Datum und die Uhrzeit des Nachrichtenempfangs auf und verwendet diese Informationen, um die Metadaten zur Position zu aktualisieren, wenn keine Zeitmarke verwendet wurde.

Manuelle Aktualisierungen der Geräteposition mithilfe der REST-API

• Sie können die Standort-Metadaten für ein statisches Gerät manuell festlegen, indem Sie die IoT Tool-REST-API verwenden, wenn das Gerät registriert ist. Sie können die Position auch später ändern. Die Einstellung der Zeitmarke ist optional; wird sie jedoch ausgelassen, werden das aktuelle Datum und die Uhrzeit in den Metadaten zur Position des Geräts festgelegt.

Topic für eine Anforderung des Typs 'Position aktualisieren', die durch ein Gerät ausgelöst wird:

Ein Gerät publiziert eine Anforderung des Typs 'Position aktualisieren' im folgenden Topic:

iotdevice-1/device/update/location

Der Server antwortet auf eine Anforderung des Typs 'Position aktualisieren' im folgenden Topic:

iotdm-1/response

Positionsaktualisierung, die von Benutzern oder Apps ausgelöst wird

Wenn ein Benutzer oder eine Aktualisierung die Position eines aktiven verwalteten Geräts aktualisiert, empfängt das Gerät eine Aktualisierungsnachricht.

Topic für eine Anforderung des Typs 'Position aktualisieren', die von Benutzern oder Apps ausgelöst wird

Der Server publiziert eine Anforderung des Typs 'Position aktualisieren' im folgenden Topic:

iotdm-1/device/update

Nachrichtenformat für eine Anforderung des Typs 'Position aktualisieren'

Das Feld measuredDateTime ist das Datum und die Uhrzeit der Standortmessung.

Bei jeder Aktualisierung der Position werden die für den Breiten- und den Längengrad, die Höhe und die Genauigkeit angegebenen Werte als einzige mehrwertige Aktualisierung betrachtet. Der Breiten- und der Längengrad sind obligatorisch und sie müssen bei jeder Aktualisierung angegeben werden. Der Breitengrad und der Längengrad muss anhand des World Geodetic System 1984 (WGS84) in Dezimalgraden angegeben werden. Höhe und Genauigkeit werden in Meter gemessen und sind optional.

Wenn bei einer Aktualisierung ein optionaler Wert angegeben und bei einer späteren Aktualisierung ausgelassen wird, wird der frühere Wert durch die spätere Aktualisierung gelöscht. Jede Aktualisierung wird als vollständige mehrwertige Aktualisierung betrachtet.

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/device/update/location
{
    "d": {
        "longitude": number,
        "latitude": number,

        "elevation": number,
        "measuredDateTime": "string in ISO8601 format",
        "updatedDateTime": "string in ISO8601 format",
        "accuracy": number
    },
    "reqId": "string"
}

Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Position aktualisieren'

Positionsaktualisierungen, die von Benutzern oder Apps ausgelöst werden

Das folgende Beispiel umreißt das Nutzdatenformat:

Incoming message from the server:

Topic: iotdm-1/device/update
{
    "d": {
        "fields": [
            {
                "field": "location",
                "value": {
                    "latitude": number,
                    "longitude": number,
                    "elevation": number,
                    "accuracy": number,
                    "measuredDateTime": "string in ISO8601 format"
                    "updatedDateTime": "string in ISO8601 format",

                }
            }
        ]
    }
}

Anforderungen des Typs 'Geräteattribute aktualisieren'

Durch die Verwendung der REST-API kann das IoT Tool eine Anfrage an ein Gerät senden, um den Wert eines oder mehrerer der folgenden Geräteattribute zu aktualisieren:

Topic für eine Anforderung des Typs 'Geräteattribute aktualisieren'

Der Server publiziert eine Anforderung des Typs 'Geräteattribute aktualisieren' im folgenden Topic:

iotdm-1/device/update

Nachrichtenformat für eine Anforderung des Typs 'Geräteattribute aktualisieren'

Das folgende Beispiel umreißt das Nutzdatenformat für die Anforderung:

Incoming message from the server:

Topic: iotdm-1/device/update
{
    "d": {
        "fields": [
            {
                "field": "location",
                "value": ""
            }
        ]
    }
}

Anforderungen des Typs 'Fehlercode hinzufügen'

Geräte können den IoT Tool-Geräteverwaltungsserver über Änderungen ihres Fehlerstatus benachrichtigen, indem sie den Anforderungstyp „Fehlercodes hinzufügen” verwenden.

Topic für eine Anforderung des Typs 'Fehlercode hinzufügen'

Ein Gerät publiziert eine Anforderung des Typs 'Fehlercode hinzufügen' im folgenden Topic:

iotdevice-1/add/diag/errorCodes

Nachrichtenformat für eine Anforderung des Typs 'Fehlercode hinzufügen'

Der mit verbundene errorCode Wert ist der aktuelle Gerätefehlercode und muss zum IoT Tool hinzugefügt werden.

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/add/diag/errorCodes
{
    "d": {
        "errorCode": number
    },
    "reqId": "string"
}

Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Fehlercode hinzufügen'

Anforderungen des Typs 'Fehlercodes löschen'

Geräte können mithilfe des Anforderungstyps „Fehlercodes löschen“ anfordern, dass das IoT Tool alle Fehlercodes für das Gerät löscht.

Topic für eine Anforderung des Typs 'Fehlercodes löschen'

Ein Gerät publiziert diese Anforderung im folgenden Topic:

iotdevice-1/clear/diag/errorCodes

Nachrichtenformat für eine Anforderung des Typs 'Fehlercodes löschen'

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/clear/diag/errorCodes
{
    "reqId": "string"
}

Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": 200,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Fehlercodes löschen'

Anforderungen des Typs 'Protokoll hinzufügen'

Geräte können wählen, ob sie die IoT Tool-Geräteverwaltung über Änderungen informieren möchten, indem sie einen neuen Protokolleintrag hinzufügen. Protokolleinträge enthalten eine Protokollnachricht, eine Zeitmarke, den Schweregrad und optional die mit Base64 codierten binären Diagnosedaten.

Topic für eine Anforderung des Typs 'Protokoll hinzufügen'

Ein Gerät publiziert diese Anforderung im folgenden Topic:

iotdevice-1/add/diag/log

Nachrichtenformat für eine Anforderung des Typs 'Protokoll hinzufügen'

In der folgenden Tabelle wird das Format der Attribute der ausgehenden Nachricht beschrieben:

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/add/diag/log
{
    "d": {
        "message": "string",
        "timestamp": "string",
        "data": "string",
        "severity": number
    },
    "reqId": "string"
}

Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Protokoll hinzufügen'

Anforderungen des Typs 'Protokolle löschen'

Geräte können mithilfe des Anforderungstyps „Protokolle löschen“ das IoT Löschen aller Protokolleinträge für das Gerät anfordern.

Topic für eine Anforderung des Typs 'Protokolle löschen'

Ein Gerät publiziert die Anforderung 'Protokolle löschen' im folgenden Topic:

iotdevice-1/clear/diag/log

Nachrichtenformat für eine Anforderung des Typs 'Protokolle löschen'

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/clear/diag/log
{
    "reqId": "string"
}

Antwortformat:

Incoming message from the device:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Protokolle löschen'

Anforderungen des Typs 'Attributänderungen beobachten'

IoT kann eine Anfrage zum Beobachten von Attributänderungen an ein Gerät senden, um Änderungen eines oder mehrerer Geräteattribute zu beobachten, indem er den Anfragetyp „Beobachten von Attributänderungen“ verwendet. Wenn das Gerät die Anfrage erhält, muss es eine Benachrichtigungsanfrage an das IoT Tool senden, sobald sich die Werte der beobachteten Attribute ändern.

Topic für eine Anforderung des Typs 'Attributänderungen beobachten'

Der Server publiziert eine Anforderung des Typs 'Attributänderungen beobachten' im folgenden Topic:

iotdm-1/observe

Nachrichtenformat für eine Anforderung des Typs 'Attributänderungen beobachten'

Das Array fields ist ein Array der Einheitenattribute aus dem Einheitenmodell. Wird ein komplexes Feld, wie z. B. mgmt.firmware, angegeben, wird erwartet, dass die zugrunde liegenden Felder gleichzeitig aktualisiert werden, sodass nur eine einzige Benachrichtigung generiert wird.

Der in der Antwort verwendete Parameter message kann angegeben sein, wenn der Wert des Parameters rc nicht 200ist. Kann ein angegebener Parameterwert nicht abgerufen werden, muss der Wert des Parameters rc auf 404 gesetzt werden, wenn das Attribut nicht gefunden wird, oder auf 500 aus einem anderen Grund. Wenn Werte für Parameter nicht gefunden werden können, sollte das Array fields Elemente enthalten, für die field auf den Namen jedes Parameters gesetzt ist, der nicht gelesen werden konnte. Der Parameter value sollte weggelassen werden. Damit der Antwortcodeparameter auf 200gesetzt wird, müssen sowohl field als auch value angegeben werden, wobei value der aktuelle Wert eines Attributs ist, das durch den Wert des Parameters field angegeben wird.

Anforderungsformat:

Incoming message from the server:

Topic: iotdm-1/observe
{
    "d": {
        "fields": [
            {
                "field": "field_name"
            }
        ]
    },
    "reqId": "string"
}

Antwortformat:

Outgoing message from the device:

Topic: iotdevice-1/response
{
    "rc": number,
    "message": "string",
    "d": {
        "fields": [
            {
                "field": "field_name",
                "value": "field_value"
            }
        ]
    },
    "reqId": "string"
}

Anforderungen des Typs 'Attributbeobachtung abbrechen'

IoT kann eine Anfrage an ein Gerät senden, um die aktuelle Beobachtung eines oder mehrerer Geräteattribute zu beenden, indem er den Anfragetyp „Beobachtung von Attributen beenden“ verwendet. Der fields Teil der Anfrage ist ein Array der Geräteattributnamen aus dem Gerätemodell, zum Beispiel, location mgmt.firmware, oder mgmt.firmware.state Parameter.

Der Parameter message kann angegeben werden, wenn der Wert des Parameters rc nicht 200ist.

Topic für eine Anforderung des Typs 'Attributbeobachtung abbrechen'

Der Server publiziert eine Anforderung des Typs 'Attributbeobachtung abbrechen' im folgenden Topic:

iotdm-1/cancel

Nachrichtenformat für eine Anforderung des Typs 'Attributbeobachtung abbrechen'

Anforderungsformat:

Incoming message from the server:

Topic: iotdm-1/cancel
{
    "d": {
        "fields": [
            {
                "field": "field_name"
            }
        ]
    },
    "reqId": "string"
}

Antwortformat:

Outgoing message from the device:

Topic: iotdevice-1/response
{
    "rc": number,
    "message": "string",
    "reqId": "string"
}

Anforderungen des Typs 'Über Attributänderungen benachrichtigen'

Das IoT Tool kann mithilfe des Anforderungstyps „Notify Attribute Changes“ (Änderungen an Attributen melden) eine Beobachtungsanforderung für ein bestimmtes Attribut oder eine Reihe von Werten stellen. Wenn der Wert des Attribut bzw. der Attribute geändert wird, muss das Gerät eine Benachrichtigung senden, die den zuletzt aktuellen Wert enthält.

Der Wert des Parameters field ist der Name des geänderten Attributs und value ist der aktuelle Wert des Attributs. Das Attribut kann ein komplexes Feld sein. Wenn als Ergebnis einer einzigen Operation mehrere Werte in einem komplexen Feld aktualisiert werden, wird nur eine einzige Benachrichtigungsnachricht gesendet.

Topic für eine Anforderung des Typs 'Über Attributänderungen benachrichtigen'

Ein Gerät publiziert eine Anforderung des Typs 'Über Attributänderungen benachrichtigen' im folgenden Topic:

iotdevice-1/notify

Nachrichtenformat für eine Anforderung des Typs 'Über Attributänderungen benachrichtigen'

Anforderungsformat:

Outgoing message from the device:

Topic: iotdevice-1/notify
{
    "d": {
        "fields": [
            {
                "field": "field_name",
                "value": "field_value"
            }
        ]
    }
    "reqId": "string"
}

Antwortformat:

Incoming message from the server:

Topic: iotdm-1/response
{
    "rc": number,
    "reqId": "string"
}

Antwortcodes für eine Anforderung des Typs 'Über Attributänderungen benachrichtigen'