Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Geräte hinzufügen und beanspruchen

Fügen Sie Geräte von Hand hinzu, lassen Sie sie sich mit einem Provisionierungsschlüssel selbst registrieren oder beanspruchen Sie ein lizenziertes Gerät über seine Seriennummer und seinen Claim-Code; geben Sie es zurück in den Pool.

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 von Hand anlegen, Geräte sich mit dem Provisioning-Schlüssel des Profils selbst registrieren lassen und ein lizenziertes Gerät beanspruchen. Für Dateien mit vielen Geräten siehe Geräte im Massenimport importieren; für LoRaWAN-Sensoren siehe OTAA-Gerät hinzufügen.

WegVerwendung fürVoraussetzungen
Von Hand hinzufügenEinige Geräte, die Sie selbst einrichtenGeräte anlegen (Admin)
SelbstprovisionierungViele Geräte einer Art, die sich selbst registrierenProvisionierung verwalten (Admin)
BeanspruchenLizenzierte Geräte mit werksseitiger IdentitätGeräte beanspruchen (Admin)

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?:

AuswahlFügt hinzu
Die Auswahl für lizenzierte Geräte („Mit dem Code auf seiner Cloud-Seite: scannen oder eingeben.“)Einen lizenzierten Router, Gateway oder Controller durch Beanspruchen
Kamera oder RecorderEine IP-Kamera oder ein Recorder. Siehe Kamera oder Recorder hinzufügen.
NetzwerkgerätEin SNMP-Agent oder ein anderes Gerät, das die Plattform abfragt. Siehe Protokoll-Endpunkte.
LoRaWAN-GatewayEin Basics-Station-Gateway. Siehe LoRaWAN-Gateway hinzufügen.
LoRaWAN-GerätEin LoRaWAN-Sensor. Siehe OTAA-Gerät hinzufügen.
Anderes GerätJedes Gerät, das selbst über MQTT oder HTTP verbindet

Eine Auswahl erscheint nur, wenn ihr Modul eingeschaltet ist und Sie deren Berechtigungen besitzen. Anderen Weg wählen kehrt zur Liste zurück.

Ein Gerät von Hand hinzufügen

  1. Wählen Sie im Panel Anderes Gerät.
  2. Geben Sie einen Namen ein (eindeutig in Ihrer Organisation, 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 danach Ich habe es gespeichert 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). Wenn Ihre Geräte MQTT basic oder X.509 nutzen, schalten Sie es aus: Das Gerät wird dann ohne Zugangsdaten angelegt, und Sie setzen diese über die API. Siehe Gerätezugangsdaten.

Selbstprovisionierung mit einem Provisioning-Schlüssel

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

Profil einrichten

  1. Öffnen Sie das Profil und dessen Reiter Provisioning.
  2. Wählen Sie die Provisioning-Strategie:
StrategieVerhalten
DeaktiviertJede Anfrage schlägt fehl (strategy_disabled).
Neue Geräte anlegen erlaubenHermetry legt ein Gerät mit dem Namen an, den das Gerät sendet, und gibt dessen Zugangsdaten zurück. Das Gerät startet im Status Quarantäne.
Nur vorab provisionierte GeräteNur Geräte, die Sie zuvor (nach Name) angelegt haben, dürfen sich provisionieren. Empfohlen für in großer Menge verkaufte Geräte, weil ein Schlüssel in der Firmware ausgelesen werden kann.
  1. Speichern, dann Schlüssel erstellen unter Provisioning-Schlüssel wählen. Kopieren Sie das Geheimnis: „Kopieren Sie das Geheimnis jetzt. Sie werden es nicht wieder sehen.“ Wählen Sie Ich habe es kopiert.

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

Hinweis

Ein Gerät, das mit Allow creating new devices angelegt wurde, wartet in der Quarantäne: Es darf sich verbinden, aber seine Daten werden verworfen, bis ein Administrator es aktiviert. Gerate in Quarantäne zählen zu Ihrem Gerätelimit. Siehe Quarantine for self-registered devices.

Was das Gerät sendet

Verbinden Sie sich über TLS mit dem Benutzernamen provision und leerem 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 dann mit seinen neuen Zugangsdaten an. Über HTTPS senden Sie denselben Inhalt an POST /api/v1/provision ohne Bearer-Header; eine Ablehnung wird ebenfalls mit 200 beantwortet, mit "status": "FAILURE".

AblehnungBedeutung
device_existsEin Gerät mit diesem Namen existiert. Hermetry stellt Zugangsdaten für einen vorhandenen Namen niemals neu aus.
provision_key_invalidUnbekannter Schlüssel oder falsches Geheimnis.
provision_key_revokedDer Schlüssel wurde widerrufen oder seine Schonfrist ist abgelaufen.
strategy_disabledDie Strategie des Profils ist Deaktiviert.
rate_limitedZu viele Anfragen (siehe Grenzwerte unten).

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, die der alte Schlüssel weiter funktioniert akzeptiert (standardmäßig 30, 0 bis 365; 0 stoppt ihn sofort), danach wird er automatisch widerrufen. Ab jetzt eingerichtete Geräte benötigen den neuen Schlüssel.
  • Widerrufen stoppt einen Schlüssel sofort und endgültig. Sie geben die Schlüssel-ID ein und einen Grund („Zum Beispiel: Das Geheimnis wurde versehentlich geteilt.“). Bereits registrierte Geräte funktionieren weiter.

Ein lizenziertes Gerät beanspruchen

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

Gerät beanspruchen

  1. Melden Sie sich am lokalen Bedienfeld des Geräts an und öffnen Sie dessen Seite Cloud. Schalten Sie die Cloud-Verbindung ein, 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 geöffnet.
  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 Display 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 Beanspruchungscode (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 seinem X.509-Zertifikat als Zugangsdaten hinzugefügt. Seine Verbindung wird innerhalb Ihrer Organisation neu gestartet.

Hinweis

Es gibt kein gedrucktes Beanspruchungsetikett. Der QR-Code und der Beanspruchungscode werden nur auf dem lokalen Bedienfeld des Geräts angezeigt, hinter dessen Anmeldung.

Wenn eine Beanspruchung fehlschlägt

MeldungBedeutung
„Das Beanspruchungsfenster am Gerät ist geschlossen. …“Drücken Sie auf der Seite Cloud Beanspruchungsfenster öffnen und versuchen Sie es dann innerhalb von 15 Minuten erneut.
„Dieses Gerät gehört einem anderen Konto. …“Bitten Sie den Verkäufer oder den früheren Besitzer, es freizugeben, und versuchen Sie es dann erneut.
„Die Seriennummer oder der Beanspruchungscode ist nicht korrekt. …“Prüfen Sie beides auf der Seite Cloud des Geräts.
„Vorerst zu viele Versuche. Warten Sie eine Stunde und versuchen Sie es dann erneut.“Fehlgeschlagene Beanspruchungen sind auf 5 pro Seriennummer, 20 pro Benutzer und 30 pro Adresse und Stunde begrenzt.
„Das Geräte-Limit Ihres Tarifs ist erreicht. …“Entfernen Sie zuerst ein Gerät oder erhöhen Sie den Tarif.
„Dieses Gerät wird gerade hinzugefügt. …“Warten Sie einen Moment und prüfen Sie die Geräteliste.
„Dieses Gerät ist bereits in diesem Konto.“Nichts zu tun.

Beanspruchung per API

POST/tenant/{tenantId}/api/iot/claim

Beanspruchen Sie ein lizenziertes Gerät über seine Seriennummer und seinen Claim-Code. Optional: name für das neue Gerät, iotAssetId, um es sofort zuzuordnen, und dryRun, um zu prüfen, was beansprucht würde, ohne es zu beanspruchen (ein Probelauf zählt wie ein echter Lauf zum Versuchslimit). Der Claim-Code wird nie zurückgegeben. Eine Ablehnung enthält in details.reason einen der Werte not_claimable, bad_secret, press_claim_button, device_limit oder rate_limited.

Anfragetext application/json

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

Beispiel curl

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"}'

Antworten

201Created
{
    "status": "claimed",
    "serial": "RT420-2610-000123",
    "deviceId": "…",
    "model": "…",
    "profileId": "…"
}
200OK
{
    "status": "claimable",
    "serial": "RT420-2610-000123",
    "model": "…",
    "type": "…",
    "hw": "…"
}
400Bad Request
{
    "message": "The serial or claim code is not correct.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "bad_secret"
    }
}
403Forbidden
{
    "message": "…",
    "code": "FEATURE_NOT_AVAILABLE",
    "details": {
        "reason": "device_limit"
    }
}
409Conflict
{
    "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"
    }
}
429Too Many Requests
{
    "message": "…",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "rate_limited"
    }
}

Die Antwort 200 mit "status": "claimable" kennzeichnet einen Probelauf. Eine Beanspruchung eines Geräts, das Ihre Organisation bereits besitzt, liefert 200 mit "status": "claimed" und "alreadyOwned": true. Eine noch laufende Beanspruchung liefert {"status": "in_progress", "serial": "…"}. 409 mit not_claimable bedeutet, dass die Seriennummer unbekannt, außer Betrieb 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 wurde. Ein im Konto erstelltes und nicht beanspruchtes Gerät trägt den Hinweis Not a factory device.

Um ein lizenziertes Gerät an einen anderen Eigentümer zu übergeben, wählen Sie auf dem Reiter Ownership die Option 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 veranlasst, wenden Sie sich an den Support.

Siehe auch