IoT-Zähler: Registrierung eines Geräts und wie es seine Messwerte signiert

IoT-Geräte: Registrieren Sie ein AMI oder einen IoT-Endpunkt, kopieren Sie dessen Geheimnis (wird einmal angezeigt), wechseln Sie es mit dem neuen Geheimnis und sehen Sie, wie das Gerät jede Anfrage an /api/public/utilities/iot/reads signiert – mit einer Beispielanfrage, den Grenzwerten und jeder Antwort, die es erhalten kann.

Ein AMI- oder IoT-Zähler übermittelt seine Messwerte über HTTPS an TRANXACT. Jedes Gerät verfügt über einen vom Server generierten Schlüssel (utd_ gefolgt von 24 Buchstaben und Ziffern) und ein geheimes Passwort. Das Gerät authentifiziert sich bei jeder Anfrage, sodass niemand anderes Messwerte für diesen Zähler übermitteln kann.

Registrieren eines Geräts

1. Öffnen Sie CRM › Utilities › Utility Meters & Reads › IoT Devices und klicken Sie auf New.
2. Geben Sie eine Bezeichnung ein, wählen Sie den Messwert aus und wählen Sie die Signatur: hmac (eine HMAC-SHA256-Signatur jeder Anfrage – empfohlen), bearer (Schlüssel und Geheimnis werden als Token gesendet) oder beides.
3. Stellen Sie für dieses Gerät und die Firmware (falls bekannt) die maximale Anzahl an Lesevorgängen pro Minute ein.
4. Speichern. Die Antwort zeigt den Schlüssel und das Geheimnis: „Kopieren Sie das Geheimnis jetzt – es wird nicht erneut angezeigt.“ Geben Sie beides in die Gerätekonfiguration ein.

Das Geheimnis drehen

Drücken Sie in der Gerätezeile auf „Neues Geheimnis“ und bestätigen Sie. Das neue Geheimnis wird einmal angezeigt, das alte ist danach nicht mehr gültig. Geben Sie dem Gerät daher sofort das neue Geheimnis. Stellen Sie den Status auf „Deaktiviert“, um ein Gerät ohne Rotation zu stoppen, oder auf „Außer Betrieb“, wenn es außer Dienst gestellt wird.

Wie ein Gerät eine Messung signalisiert

1. Erstellen Sie den JSON-Body: eine Liste von Lesevorgängen, jeweils mit read_at (ISO-8601-Zeit) und dem Messwert. Batterie-, Signal-, Firmware- und Alarminformationen sind optional.
2. Die aktuelle Unix-Zeit in Sekunden als Zeitstempel verwenden.
3. Berechnen Sie unter dem Gerätegeheimnis den HMAC-SHA256-Hash des Zeitstempels, eines Punktes und der exakten Bytes des Nachrichtentextes: „<Zeitstempel>.<Nachrichtentext>“. Schreiben Sie das Ergebnis als 64-stellige Hexadezimalzeichen in Kleinbuchstaben.
4. Senden Sie den Body per POST an /api/public/utilities/iot/reads mit den Headern X-Utility-Device (der Schlüssel), X-Utility-Timestamp und X-Utility-Signature (die Hexadezimaldarstellung, optional mit dem Präfix sha256=).

POST https://<your-tranxact-host>/api/public/utilities/iot/reads
Content-Type: application/json
X-Utility-Device: <utd_DEVICE_KEY>
X-Utility-Timestamp: <1792252800>
X-Utility-Signature: sha256=<64 hex characters>

{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}],
 "battery_pct":<87>,"signal_dbm":<-71>,"firmware":"<2.4.1>",
 "alarms":[{"type":"<leak>","detail":"<continuous flow 6 h>"}]}

Dieselbe Signatur funktionierte auch in einer Shell, um ein Gerät vor der Installation zu testen:

BODY='{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "<DEVICE_SECRET>" | sed 's/^.* //')
curl -X POST "https://<your-tranxact-host>/api/public/utilities/iot/reads" \
  -H "Content-Type: application/json" \
  -H "X-Utility-Device: <utd_DEVICE_KEY>" \
  -H "X-Utility-Timestamp: $TS" \
  -H "X-Utility-Signature: sha256=$SIG" \
  --data-binary "$BODY"

Ein Gerät, das auf Bearer (oder beides) eingestellt ist, sendet stattdessen möglicherweise Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> ohne Signatur-Header. HMAC ist die sicherere Wahl: Das Geheimnis wird niemals übertragen, und eine abgefangene Anfrage kann nicht wiederholt werden.

Grenzen

• Der Zeitstempel muss innerhalb von 5 Minuten von der Serveruhr abweichen: Stellen Sie sicher, dass die Geräteuhr über NTP synchronisiert ist.
• Dieselbe signierte Anfrage wird zweimal als Wiederholungsanfrage abgelehnt. Ein bereits vorhandener Lesevorgang wird als Duplikat gezählt und einmal gespeichert.
• Maximal 64 KB und 500 Lesevorgänge pro Anfrage, die maximale Anzahl an Lesevorgängen pro Minute des Geräts und 600 Anfragen pro Minute von einer Adresse.
• Das Gerät muss eingeschaltet und an einen Zähler angeschlossen sein.

Was das Gerät zurückerhält

Gesundheit und Alarme

• Jede Anfrage aktualisiert den Status „Zuletzt gesehen“, den Akkustand in Prozent und die Signalstärke in dBm des Geräts. Bei einem Akkustand unter 15 % wird ein Alarm ausgelöst.
• Alarmtypen, die ein Gerät senden kann: niedriger Batteriestand, Manipulation, Leckage, Rückfluss, kein Durchfluss, Offline und Sonstige. Pro Gerät ist jeweils ein Alarm pro Typ aktiv.
• Die Gerätealarme werden aufgelistet; „Löschen“ schließt einen Alarm mit einem Hinweis. Ein Leck löst automatisch einen Serviceauftrag zur Leckageuntersuchung mit hoher Priorität aus; ein Manipulations- oder Rückflussalarm löst ebenfalls einen Serviceauftrag aus.
• Die im Dashboard angezeigte Zahl für IoT-Zähler (24h) gibt die Anzahl der aktiven Geräte an, von denen am Vortag Daten empfangen wurden.