Aktuelle data (WebSocket)

Med WebSocket får du enhedernes målinger og ændringer i det øjeblik, de sker. HAM-appen bruger den samme forbindelse. Til én måling ad gangen er REST API nemmere.

Adresse

wss://DEVICE_SERVER:9001

• DEVICE_SERVER er værdien i feltet device_server for hver enhed. Du finder den med get_user_devices.php.
• Enhederne på én konto kan være på forskellige servere. Åbn én forbindelse for hver forskellig server, ikke én for hver enhed.
• Port 9001 skal være åben for udgående forbindelser. Se Krav til netværket (for IT).

Format for meddelelser

Hver meddelelse, du sender, er et JSON-array:

[command_id, payload]

command_id er et heltal. Start ved 1, og forøg det med hver meddelelse. Svaret har det samme command_id.

Den største størrelse for en meddelelse er 20 KiB. Serveren lukker forbindelsen, hvis du sender en større meddelelse.

1. Godkendelse

Den første meddelelse efter forbindelsen er godkendelsen:

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

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

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

Grænse for forbindelser: 15 for hver 60 sekunder for én API-nøgle. 25 for hver 60 sekunder for ét adgangstoken.

2. Abonnér på enheder (SUBSCRIBE)

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

Felt	Betydning
c	SUBSCRIBE
server	Altid true
serialnos	Serienumrene på enhederne på denne server
unsubscribe-others	true: serveren stopper denne forbindelses tidligere abonnementer

Svar: [2,[{},""]]. Serveren springer de enheder over, som du ikke har adgang til. Den sender ingen fejl for dem.

Send [3, {"c": "UNSUBSCRIBE", "server": true}] for at stoppe alle abonnementer.

3. Opdateringer af tilstanden

Lige efter abonnementet sender serveren den aktuelle tilstand for hver enhed. Derefter sender den en opdatering, hver gang noget ændrer sig.

Opdateringerne er JSON-objekter, ikke arrays:

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

Felt	Indhold
serialno	Enheden
R	Målingerne, rå, med målingens kode som nøgle
O	Udgangenes værdier i rækkefølgen fra output_names
T	Enhedens tidsplaner
S	Enhedens indstillinger
previous	De akkumulerede værdier for den forrige periode for enheder med tællere
alarms	De aktive alarmer
is_local	true, hvis din forbindelse og enheden er på det samme netværk

• En opdatering kan kun have de felter, der ændrede sig. Flet den ind i den tilstand, du allerede har.
• Serveren samler ændringer i cirka 100 ms, før den sender en opdatering.
• Ignorer meddelelser, som du ikke genkender.

Brug familiernes definitioner til at omregne de rå værdier. Se REST API.

Hold forbindelsen åben

• Serveren sender WebSocket-pings. Dit bibliotek skal svare med en pong. De fleste biblioteker gør det automatisk.
• Hvis forbindelsen lukker, skal du forbinde igen. App’en venter 100 ms første gang og 10 sekunder derefter.
• Send godkendelsen og abonnementet igen efter en ny forbindelse.

Eksempel til Node.js

Node.js 22 har en indbygget 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 komplet eksempel til Node.js er i nodejs_hamapi_example.zip. Det indeholder biblioteket hamapi.js og filen example.js.

1. Indstil server, api_key og serienumrene i example.js.
2. Kør npm install og derefter node example.js.

Biblioteket forbinder ikke igen, når forbindelsen lukker. Tilføj det til din kode.

Se også

• REST API
• Webhooks fra regler