Live gegevens (WebSocket)

Met de WebSocket ontvangt u de metingen en de wijzigingen van de apparaten op het moment dat ze gebeuren. De HAM-app gebruikt dezelfde verbinding. Voor één meting tegelijk is de REST API eenvoudiger.

Adres

wss://DEVICE_SERVER:9001

DEVICE_SERVER is de waarde van het veld device_server van elk apparaat. U vindt het met get_user_devices.php.
De apparaten van één account kunnen op verschillende servers staan. Open één verbinding voor elke andere server, niet één voor elk apparaat.
Poort 9001 moet open zijn voor uitgaande verbindingen. Zie de netwerkvereisten.

Berichtindeling

Elk bericht dat u verstuurt, is een JSON-array:

[command_id, payload]

De command_id is een geheel getal. Begin bij 1 en verhoog het bij elk bericht. Het antwoord heeft dezelfde command_id.

De maximale grootte van een bericht is 20 KiB. De server sluit de verbinding als u een groter bericht verstuurt.

1. Authenticatie

Het eerste bericht na de verbinding is de authenticatie:

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

U kunt ook {"access_token": "YOUR_ACCESS_TOKEN"} sturen. Zie authenticatie.

Antwoord	Betekenis
`[]`	Gelukt
`["Access Denied"]`	Onjuiste sleutel of token. De server sluit de verbinding.
`[1,[{},"Rate limit"]]`	Te veel verbindingen in korte tijd

Verbindingslimiet: 15 per 60 seconden voor één API-sleutel. 25 per 60 seconden voor één toegangstoken.

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

Veld	Betekenis
`c`	`SUBSCRIBE`
`server`	Altijd `true`
`serialnos`	De serienummers van de apparaten op deze server
`unsubscribe-others`	`true`: de server stopt de eerdere abonnementen van deze verbinding

Antwoord: [2,[{},""]]. De server slaat de apparaten over waartoe u geen toegang hebt. Hij stuurt er geen fout voor.

Om alle abonnementen te stoppen, stuurt u [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Statusupdates

Direct na het abonnement stuurt de server de huidige status van elk apparaat. Daarna stuurt hij een update telkens wanneer er iets verandert.

De updates zijn JSON-objecten, geen arrays:

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

Veld	Inhoud
`serialno`	Het apparaat
`R`	De metingen, ruw, met de metingcode als sleutel
`O`	De uitgangswaarden, in de volgorde van `output_names`
`T`	De schema’s van het apparaat
`S`	De apparaatinstellingen
`previous`	De opgetelde waarden van de vorige periode, voor apparaten met tellers
`alarms`	De actieve alarmen
`is_local`	`true` als uw verbinding en het apparaat op hetzelfde netwerk zitten

Een update kan alleen de velden hebben die zijn veranderd. Voeg hem samen met de status die u al hebt.
De server groepeert wijzigingen ongeveer 100 ms voordat hij een update stuurt.
Negeer berichten die u niet herkent.

Gebruik de familiedefinities om de ruwe waarden om te zetten. Zie de REST API.

De verbinding open houden

De server stuurt WebSocket-pings. Uw bibliotheek moet met een pong antwoorden. De meeste bibliotheken doen dit automatisch.
Sluit de verbinding? Maak dan opnieuw verbinding. De app wacht de eerste keer 100 ms en daarna 10 seconden.
Stuur na een nieuwe verbinding de authenticatie en het abonnement opnieuw.

Voorbeeld met Node.js

Node.js 22 heeft een ingebouwde 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);
  }
};

Een volledig voorbeeld met Node.js staat in nodejs_hamapi_example.zip. Het bevat de bibliotheek hamapi.js en het bestand example.js.

Vul in example.js server, api_key en de serienummers in.
Voer npm install uit en daarna node example.js.

De bibliotheek maakt niet opnieuw verbinding als de verbinding sluit. Voeg dit toe aan uw code.

Zie ook

Chat met support