Data i sanntid (WebSocket)

Med WebSocket får du avlesningene og endringene for enhetene i det øyeblikket de skjer. HAM-appen bruker den samme forbindelsen. For én avlesning om gangen er REST API enklere.

Adresse

wss://DEVICE_SERVER:9001

DEVICE_SERVER er verdien i feltet device_server for hver enhet. Du finner den med get_user_devices.php.
Enhetene på én konto kan være på forskjellige servere. Åpne én forbindelse for hver server, ikke én for hver enhet.
Port 9001 må være åpen for utgående forbindelser. Se Nettverkskrav (for IT).

Format på meldingene

Hver melding som du sender, er en JSON-liste:

[command_id, payload]

command_id er et heltall. Start på 1 og øk det med hver melding. Svaret har den samme command_id.

Den største størrelsen på en melding er 20 KiB. Serveren lukker forbindelsen hvis du sender en større melding.

1. Autentisering

Den første meldingen etter tilkoblingen er autentiseringen:

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

Du kan også sende {"access_token": "YOUR_ACCESS_TOKEN"}. Se autentisering.

Svar	Betydning
`[]`	Vellykket
`["Access Denied"]`	Feil nøkkel eller token. Serveren lukker forbindelsen.
`[1,[{},"Rate limit"]]`	For mange forbindelser på kort tid

Grense for forbindelser: 15 per 60 sekunder for én API-nøkkel. 25 per 60 sekunder for ett tilgangstoken.

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

Felt	Betydning
`c`	`SUBSCRIBE`
`server`	Alltid `true`
`serialnos`	Serienumrene til enhetene på denne serveren
`unsubscribe-others`	`true`: serveren stopper de tidligere abonnementene for denne forbindelsen

Svar: [2,[{},""]]. Serveren hopper over enhetene som du ikke har tilgang til. Den sender ikke en feil for dem.

For å stoppe alle abonnementene, send [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Oppdateringer av tilstanden

Rett etter abonnementet sender serveren den aktuelle tilstanden for hver enhet. Så sender den en oppdatering hver gang noe endres.

Oppdateringene er JSON-objekter, ikke lister:

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

Felt	Innhold
`serialno`	Enheten
`R`	Avlesningene, rå, med koden for avlesningen som nøkkel
`O`	Verdiene for utgangene, i rekkefølgen til `output_names`
`T`	Tidsplanene for enheten
`S`	Innstillingene for enheten
`previous`	De akkumulerte verdiene for den forrige perioden, for enheter med tellere
`alarms`	De aktive alarmene
`is_local`	`true` hvis forbindelsen din og enheten er på det samme nettverket

En oppdatering kan ha bare feltene som er endret. Slå den sammen med tilstanden som du allerede har.
Serveren samler endringer i omtrent 100 ms før den sender en oppdatering.
Ignorer meldinger som du ikke kjenner.

For å konvertere de rå verdiene, bruk definisjonene for familien. Se REST API.

Hold forbindelsen åpen

Serveren sender WebSocket-ping. Biblioteket ditt må svare med pong. De fleste biblioteker gjør dette automatisk.
Hvis forbindelsen lukkes, koble til igjen. Appen venter 100 ms den første gangen og 10 sekunder etter det.
Etter en ny forbindelse, send autentiseringen og abonnementet på nytt.

Eksempel for Node.js

Node.js 22 har en innebygd 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);
  }
};

Et fullstendig eksempel for Node.js er i nodejs_hamapi_example.zip. Det inneholder biblioteket hamapi.js og filen example.js.

I example.js, still inn server, api_key og serienumrene.
Kjør npm install, så node example.js.

Biblioteket kobler ikke til igjen når forbindelsen lukkes. Legg til dette i koden din.

Se også

Chat med support