Live-Daten (WebSocket)

Mit dem WebSocket erhalten Sie die Messwerte und die Änderungen der Geräte im Moment des Geschehens. Die HAM App verwendet dieselbe Verbindung. Für jeweils einen Messwert ist die REST-API einfacher.

Adresse

wss://DEVICE_SERVER:9001

DEVICE_SERVER ist der Wert des Felds device_server jedes Geräts. Sie finden ihn mit get_user_devices.php.
Die Geräte eines Kontos können auf verschiedenen Servern sein. Öffnen Sie eine Verbindung für jeden verschiedenen Server, nicht eine für jedes Gerät.
Port 9001 muss für ausgehende Verbindungen offen sein. Siehe die Netzwerkanforderungen.

Nachrichtenformat

Jede Nachricht, die Sie senden, ist ein JSON-Array:

[command_id, payload]

Die command_id ist eine ganze Zahl. Beginnen Sie bei 1 und erhöhen Sie sie mit jeder Nachricht. Die Antwort hat dieselbe command_id.

Die maximale Größe einer Nachricht ist 20 KiB. Der Server schließt die Verbindung, wenn Sie eine größere Nachricht senden.

1. Authentifizierung

Die erste Nachricht nach der Verbindung ist die Authentifizierung:

[1, {"api_key": "YOUR_API_KEY"}]

Sie können auch {"access_token": "YOUR_ACCESS_TOKEN"} senden. Siehe Authentifizierung.

Antwort	Bedeutung
`[]`	Erfolg
`["Access Denied"]`	Falscher Schlüssel oder Token. Der Server schließt die Verbindung.
`[1,[{},"Rate limit"]]`	Zu viele Verbindungen in kurzer Zeit

Verbindungslimit: 15 pro 60 Sekunden für einen API-Schlüssel. 25 pro 60 Sekunden für einen Access-Token.

[2, {"c": "SUBSCRIBE", "server": true, "serialnos": ["e11:123", "e9:456"], "unsubscribe-others": true}]

Feld	Bedeutung
`c`	`SUBSCRIBE`
`server`	Immer `true`
`serialnos`	Die Seriennummern der Geräte auf diesem Server
`unsubscribe-others`	`true`: Der Server beendet die früheren Abonnements dieser Verbindung

Antwort: [2,[{},""]]. Der Server überspringt die Geräte, auf die Sie keinen Zugriff haben. Er sendet dafür keinen Fehler.

Um alle Abonnements zu beenden, senden Sie [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Zustandsaktualisierungen

Direkt nach dem Abonnement sendet der Server den aktuellen Zustand jedes Geräts. Danach sendet er bei jeder Änderung eine Aktualisierung.

Die Aktualisierungen sind JSON-Objekte, keine Arrays:

{
  "serialno": "e11:123",
  "R": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
  "O": [],
  "alarms": [],
  "is_local": false
}

Feld	Inhalt
`serialno`	Das Gerät
`R`	Die Messwerte, roh, nach Messwertcode geordnet
`O`	Die Ausgangswerte, in der Reihenfolge von `output_names`
`T`	Die Zeitpläne des Geräts
`S`	Die Geräteeinstellungen
`previous`	Die akkumulierten Werte des vorherigen Zeitraums, für Geräte mit Zählern
`alarms`	Die aktiven Alarme
`is_local`	`true`, wenn Ihre Verbindung und das Gerät im selben Netzwerk sind

Eine Aktualisierung kann nur die geänderten Felder enthalten. Führen Sie sie mit dem Zustand zusammen, den Sie schon haben.
Der Server fasst Änderungen etwa 100 ms lang zusammen, bevor er eine Aktualisierung sendet.
Ignorieren Sie Nachrichten, die Sie nicht kennen.

Um die Rohwerte umzurechnen, verwenden Sie die Familiendefinitionen. Siehe die REST-API.

Die Verbindung offen halten

Der Server sendet WebSocket-Pings. Ihre Bibliothek muss mit einem Pong antworten. Die meisten Bibliotheken tun das automatisch.
Wenn die Verbindung schließt, verbinden Sie sich erneut. Die App wartet beim ersten Mal 100 ms und danach 10 Sekunden.
Senden Sie nach einer neuen Verbindung die Authentifizierung und das Abonnement erneut.

Beispiel mit Node.js

Node.js 22 hat einen eingebauten WebSocket.

const ws = new WebSocket('wss://DEVICE_SERVER:9001');
let id = 1;

ws.onopen = () => {
  ws.send(JSON.stringify([id++, { api_key: 'YOUR_API_KEY' }]));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (Array.isArray(msg) && msg.length === 0) {
    ws.send(JSON.stringify([id++, {
      c: 'SUBSCRIBE', server: true,
      serialnos: ['e11:123'], 'unsubscribe-others': true
    }]));
  } else if (!Array.isArray(msg) && msg.serialno) {
    console.log(msg.serialno, msg.R);
  }
};

Ein vollständiges Beispiel mit Node.js ist in nodejs_hamapi_example.zip. Es enthält die Bibliothek hamapi.js und die Datei example.js.

Tragen Sie in example.js server, api_key und die Seriennummern ein.
Führen Sie npm install und danach node example.js aus.

Die Bibliothek verbindet sich nicht neu, wenn die Verbindung schließt. Ergänzen Sie dies in Ihrem Code.

Siehe auch

Chat mit dem Support