Data i realtid (WebSocket)

Med WebSocket får du enheternas avläsningar och ändringar i samma ögonblick som de sker. HAM-appen använder samma anslutning. För en avläsning i taget är REST API enklare.

Adress

wss://DEVICE_SERVER:9001

DEVICE_SERVER är värdet i fältet device_server för varje enhet. Du hittar det med get_user_devices.php.
Enheterna i ett konto kan finnas på olika servrar. Öppna en anslutning för varje annan server, inte en för varje enhet.
Port 9001 måste vara öppen för utgående anslutningar. Se nätverkskraven.

Meddelandeformat

Varje meddelande som du skickar är en JSON-array:

[command_id, payload]

command_id är ett heltal. Börja på 1 och öka det med varje meddelande. Svaret har samma command_id.

Den största storleken för ett meddelande är 20 KiB. Servern stänger anslutningen om du skickar ett större meddelande.

1. Autentisering

Det första meddelandet efter anslutningen är autentiseringen:

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

Du kan också skicka {"access_token": "YOUR_ACCESS_TOKEN"}. Se autentisering.

Svar	Betydelse
`[]`	Lyckades
`["Access Denied"]`	Fel nyckel eller token. Servern stänger anslutningen.
`[1,[{},"Rate limit"]]`	För många anslutningar på kort tid

Gräns för anslutningar: 15 per 60 sekunder för en API-nyckel. 25 per 60 sekunder för en åtkomsttoken.

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

Fält	Betydelse
`c`	`SUBSCRIBE`
`server`	Alltid `true`
`serialnos`	Serienumren för enheterna på den här servern
`unsubscribe-others`	`true`: servern stoppar de tidigare prenumerationerna för den här anslutningen

Svar: [2,[{},""]]. Servern hoppar över de enheter som du inte har åtkomst till. Den skickar inget fel för dem.

För att stoppa alla prenumerationer, skicka [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Uppdateringar av tillståndet

Direkt efter prenumerationen skickar servern det aktuella tillståndet för varje enhet. Sedan skickar den en uppdatering varje gång något ändras.

Uppdateringarna är JSON-objekt, inte arrayer:

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

Fält	Innehåll
`serialno`	Enheten
`R`	Avläsningarna, som råvärden, med avläsningens kod som nyckel
`O`	Utgångarnas värden, i ordningen i `output_names`
`T`	Enhetens scheman
`S`	Enhetens inställningar
`previous`	De ackumulerade värdena för den föregående perioden, för enheter med räknare
`alarms`	De aktiva larmen
`is_local`	`true` om din anslutning och enheten finns i samma nätverk

En uppdatering kan ha bara de fält som ändrades. Slå ihop den med det tillstånd som du redan har.
Servern grupperar ändringar under ungefär 100 ms innan den skickar en uppdatering.
Ignorera meddelanden som du inte känner igen.

För att konvertera råvärdena, använd familjedefinitionerna. Se REST API.

Håll anslutningen öppen

Servern skickar WebSocket-pings. Ditt bibliotek måste svara med en pong. De flesta bibliotek gör det automatiskt.
Om anslutningen stängs, anslut igen. Appen väntar 100 ms den första gången och 10 sekunder efter det.
Efter en ny anslutning, skicka autentiseringen och prenumerationen igen.

Exempel för Node.js

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

Ett komplett exempel för Node.js finns i nodejs_hamapi_example.zip. Det innehåller biblioteket hamapi.js och filen example.js.

I example.js, ställ in server, api_key och serienumren.
Kör npm install och sedan node example.js.

Biblioteket ansluter inte igen när anslutningen stängs. Lägg till det i din kod.

Se också

Chatta med supporten