Geräte hinzufügen und beanspruchen

Es gibt mehrere Wege, ein Gerät in Ihre Organisation aufzunehmen. Diese Seite behandelt die drei, die Sie am häufigsten nutzen: ein Gerät manuell hinzufügen, Geräte sich mit dem Provisionierungsschlüssel des Profils selbst registrieren lassen und ein lizenziertes Gerät beanspruchen. Für Dateien mit vielen Geräten siehe Geräte in großer Zahl importieren; für LoRaWAN-Sensoren siehe OTAA-Gerät hinzufügen.

Das Panel „Neues Gerät“

Öffnen Sie Geräte und wählen Sie Neues Gerät. Wenn Ihre Organisation mehrere Wege bietet, fragt das Panel Was fügen Sie hinzu?:

Eine Auswahl erscheint nur, wenn das zugehörige Modul aktiv ist und Sie dessen Berechtigungen besitzen. Anderen Weg wählen kehrt zur Liste zurück.

Ein Gerät manuell hinzufügen

1. Wählen Sie im Panel Anderes Gerät.
2. Geben Sie einen Namen ein (innerhalb Ihrer Organisation eindeutig, bis zu 128 Zeichen), optional ein Label, und wählen Sie das Geräteprofil (Das Standardprofil, wenn Sie keines wählen).
3. Aktivieren Sie Dieses Gerät ist ein Gateway nur für ein Gerät, das für andere Geräte meldet.
4. Wählen Sie Gerät anlegen.
5. Kopieren Sie jetzt das Zugriffstoken: Es wird nur einmal angezeigt. Wählen Sie Ich habe es gespeichert, wenn Sie fertig sind, oder Gerät öffnen.

Die Geräteeinstellungen Ihrer Organisation legen fest, ob ein neues Gerät sofort ein Zugriffstoken erhält: Zugriffstoken für neue Geräte ausstellen (standardmäßig aktiv; Geräte > ⋯ > Einstellungen). Verwenden Ihre Geräte MQTT basic oder X.509, schalten Sie es aus: Das Gerät wird dann ohne Anmeldeinformation angelegt, und Sie setzen eine über die API. Siehe Geräte-Anmeldeinformationen.

Selbstprovisionierung mit einem Provisionierungsschlüssel

Das Gerät kennt den Provisionierungsschlüssel und das Geheimnis seines Profils. Beim ersten Start fordert es bei Hermetry seine eigene Anmeldeinformation an, sodass Sie nicht jedes Gerät vorab anlegen müssen.

Profil einrichten

1. Öffnen Sie das Profil und dessen Reiter Provisionierung.
2. Wählen Sie die Provisionierungsstrategie:

1. Speichern Sie, und wählen Sie dann Schlüssel erstellen unter Provisionierungsschlüssel. Kopieren Sie das Geheimnis: „Kopieren Sie das Geheimnis jetzt. Sie werden es nicht wiedersehen.“ Wählen Sie Ich habe es kopiert.

Die Schlüsseltabelle zeigt jede Schlüssel-ID, deren Status (In Verwendung, Alt, noch akzeptiert, Widerrufen), Erstellt, Akzeptiert bis und Zuletzt verwendet. Die Schlüsselschaltflächen wirken sofort; sie gehören nicht zu Änderungen speichern.

Was das Gerät sendet

Verbinden Sie sich über TLS mit dem Benutzernamen provision und einem leeren Passwort, abonnieren Sie v1/provision/res und veröffentlichen Sie dann auf v1/provision/req:

{"deviceName": "boiler-07", "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60", "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"}

Die Antwort auf v1/provision/res:

{"status": "SUCCESS", "credentialsType": "ACCESS_TOKEN", "credentialsValue": "aZ3…"}

Das Gerät meldet sich danach mit seiner neuen Anmeldeinformation an. Über HTTPS senden Sie denselben Inhalt an POST /api/v1/provision ohne Bearer-Header; eine Ablehnung antwortet ebenfalls mit 200, mit "status": "FAILURE".

Grenzwerte: erfolgreiche Provisionierungen pro Schlüssel und Stunde (standardmäßig 60), 5 Anfragen pro Gerätename und Stunde sowie 10 Anfragen pro Quelladresse und Minute.

Schlüssel ersetzen oder widerrufen

• Schlüssel ersetzen erstellt einen neuen Schlüssel und ein neues Geheimnis. Der alte Schlüssel bleibt für Tage, an denen der alte Schlüssel weiter funktioniert akzeptiert (standardmäßig 30, 0 bis 365; 0 beendet ihn sofort) und wird danach automatisch widerrufen. Geräte, die Sie ab jetzt einrichten, benötigen den neuen Schlüssel.
• Widerrufen beendet einen Schlüssel sofort und endgültig. Sie geben die Schlüssel-ID ein und einen Grund („Zum Beispiel: Das Geheimnis wurde versehentlich weitergegeben.“). Bereits registrierte Geräte funktionieren weiter.

Ein lizenziertes Gerät beanspruchen

Lizenzierte Router, Gateways und Steuerungen verlassen das Werk mit einer eigenen Identität: einer Seriennummer, einem Zertifikat und einem Claim-Geheimnis. Bevor Sie eines beanspruchen, gehört es keiner Organisation an, und Hermetry verwirft seine Daten.

Beanspruchen

1. Melden Sie sich am lokalen Bedienfeld des Geräts an und öffnen Sie dessen Seite Cloud. Aktivieren Sie die Cloud-Verbindung, falls sie aus ist; das Gerät verbindet sich dann selbstständig mit Hermetry.
2. Drücken Sie auf derselben Seite Beanspruchungsfenster öffnen. Das Fenster bleibt 15 Minuten lang offen.
3. Öffnen Sie in Hermetry Geräte > Neues Gerät und wählen Sie die Auswahl für lizenzierte Geräte.
4. Wählen Sie, wie Sie den Code eingeben:
   • Den Code auf dem Bildschirm des Geräts scannen: Richten Sie die Kamera Ihres Telefons auf den QR-Code auf der Seite Cloud und kopieren Sie den angezeigten Text in das Feld.
   • Seriennummer und Code eingeben: Geben Sie die Seriennummer (6 bis 32 Buchstaben, Ziffern und Bindestriche, zum Beispiel RT420-2610-000123) und den Claim-Code (20 Zeichen, zum Beispiel 7KQ2-M9XH-D4TB-6WRA-1NZC) ein.
5. Wählen Sie Prüfen. Geben Sie bei Bereit zum Hinzufügen einen Gerätenamen ein (leer = die Seriennummer).
6. Wählen Sie Gerät hinzufügen. „Das Gerät wurde hinzugefügt. Es verbindet sich innerhalb weniger Sekunden, wenn es online ist.“

Das Gerät wird mit einer Kopie des Profils seines Modells und seiner X.509-Zertifikat-Anmeldeinformation hinzugefügt. Seine Verbindung wird innerhalb Ihrer Organisation neu gestartet.

Wenn ein Beanspruchen fehlschlägt

Beanspruchung per API

{
    "serial": "RT420-2610-000123",
    "secret": "7KQ2M9XHD4TB6WRA1NZC",
    "name": "Pump house router"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
  -H 'Content-Type: application/json' \
  -d '{"serial":"RT420-2610-000123","secret":"7KQ2M9XHD4TB6WRA1NZC","name":"Pump house router"}'

{
    "status": "claimed",
    "serial": "RT420-2610-000123",
    "deviceId": "…",
    "model": "…",
    "profileId": "…"
}

{
    "status": "claimable",
    "serial": "RT420-2610-000123",
    "model": "…",
    "type": "…",
    "hw": "…"
}

{
    "message": "The serial or claim code is not correct.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "bad_secret"
    }
}

{
    "message": "…",
    "code": "FEATURE_NOT_AVAILABLE",
    "details": {
        "reason": "device_limit"
    }
}

{
    "message": "Open the claim window on the device's Cloud page (it stays open for 15 minutes), then try again.",
    "code": "CONFLICT",
    "details": {
        "reason": "press_claim_button"
    }
}

{
    "message": "…",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "rate_limited"
    }
}

Die Antwort 200 mit "status": "claimable" kennzeichnet einen Probelauf. Die Beanspruchung eines Geräts, das Ihre Organisation bereits besitzt, liefert 200 mit "status": "claimed" und "alreadyOwned": true. Eine laufende Beanspruchung liefert {"status": "in_progress", "serial": "…"}. 409 mit not_claimable bedeutet, dass die Seriennummer unbekannt, außer Betrieb genommen oder einem anderen Konto zugeordnet ist.

Der Reiter Eigentum und das Freigeben eines Geräts

Der Reiter Ownership eines beanspruchten Geräts zeigt seine Serial, das Model, das Certificate (gültig bis) und wann es Added to this account hinzugefügt wurde. Ein in Ihrem Konto erstelltes statt beanspruchtes Gerät trägt den Hinweis Not a factory device.

Um ein lizenziertes Gerät an einen anderen Eigentümer weiterzugeben, wählen Sie auf dem Reiter Ownership Release device. Der Dialog Release this device? erklärt:

• Das Gerät verlässt dieses Konto und seine Verbindung wird geschlossen.
• Seine Daten bleiben im Verlauf dieses Kontos erhalten.
• Der nächste Eigentümer benötigt physischen Zugriff auf das Gerät, um es hinzuzufügen.
• Ein Werksreset des Geräts gibt es nicht frei: Nur diese Aktion tut das.

Geben Sie zur Bestätigung die Seriennummer ein und optional einen Grund an. Das Gerät kehrt in den Werkspool zurück.

Ein Gerät kann auch über die Schaltfläche Release auf seiner eigenen Cloud-Seite freigegeben werden. Sie erhalten dann eine Meldung „A device released itself from your account“. Hat niemand in Ihrem Team dies getan, wenden Sie sich an den Support.

Verwandte Themen

• Lizenzierte Geräte
• Gerätidentität und Sicherheit der Beanspruchung
• Die Geräteliste und die Geräteseite