Reaaliaikaiset tiedot (WebSocket)

WebSocketilla saat laitteiden mittaukset ja muutokset sillä hetkellä, kun ne tapahtuvat. HAM-sovellus käyttää samaa yhteyttä. Yhden mittauksen kerrallaan saat helpommin REST API:lla.

Osoite

wss://DEVICE_SERVER:9001

• DEVICE_SERVER on kunkin laitteen kentän device_server arvo. Löydät sen päätepisteellä get_user_devices.php.
• Yhden tilin laitteet voivat olla eri palvelimilla. Avaa yksi yhteys jokaista eri palvelinta kohti, ei jokaista laitetta kohti.
• Portin 9001 on oltava auki lähteville yhteyksille. Katso verkkovaatimukset.

Viestin muoto

Jokainen lähettämäsi viesti on JSON-taulukko:

[command_id, payload]

command_id on kokonaisluku. Aloita luvusta 1 ja kasvata sitä jokaisella viestillä. Vastauksessa on sama command_id.

Viestin enimmäiskoko on 20 KiB. Palvelin sulkee yhteyden, jos lähetät suuremman viestin.

1. Todennus

Ensimmäinen viesti yhteyden jälkeen on todennus:

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

Voit myös lähettää {"access_token": "YOUR_ACCESS_TOKEN"}. Katso todennus.

Vastaus	Merkitys
[]	Onnistui
["Access Denied"]	Väärä avain tai tunnus. Palvelin sulkee yhteyden.
[1,[{},"Rate limit"]]	Liian monta yhteyttä lyhyessä ajassa

Yhteysraja: 15 per 60 sekuntia yhdelle API-avaimelle. 25 per 60 sekuntia yhdelle pääsytunnukselle.

2. Tilaa laitteet (SUBSCRIBE)

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

Kenttä	Merkitys
c	SUBSCRIBE
server	Aina true
serialnos	Tämän palvelimen laitteiden sarjanumerot
unsubscribe-others	true: palvelin lopettaa tämän yhteyden aiemmat tilaukset

Vastaus: [2,[{},""]]. Palvelin ohittaa laitteet, joihin sinulla ei ole käyttöoikeutta. Se ei lähetä niistä virhettä.

Kun haluat lopettaa kaikki tilaukset, lähetä [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Tilapäivitykset

Heti tilauksen jälkeen palvelin lähettää kunkin laitteen nykyisen tilan. Sen jälkeen se lähettää päivityksen aina, kun jokin muuttuu.

Päivitykset ovat JSON-objekteja, eivät taulukoita:

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

Kenttä	Sisältö
serialno	Laite
R	Mittaukset raakoina, avaimena mittauskoodi
O	Lähtöjen arvot output_names-järjestyksessä
T	Laitteen aikataulut
S	Laitteen asetukset
previous	Edellisen jakson kertyneet arvot laitteille, joissa on laskureita
alarms	Aktiiviset hälytykset
is_local	true, jos yhteytesi ja laite ovat samassa verkossa

• Päivityksessä voivat olla vain muuttuneet kentät. Yhdistä se tilaan, joka sinulla jo on.
• Palvelin kerää muutoksia noin 100 ms ennen kuin se lähettää päivityksen.
• Ohita viestit, joita et tunnista.

Raaka-arvojen muuntamiseen käytä perheiden määrityksiä. Katso REST API.

Pidä yhteys auki

• Palvelin lähettää WebSocket-pingejä. Kirjastosi on vastattava pongilla. Useimmat kirjastot tekevät tämän automaattisesti.
• Jos yhteys sulkeutuu, yhdistä uudelleen. Sovellus odottaa 100 ms ensimmäisellä kerralla ja sen jälkeen 10 sekuntia.
• Uuden yhteyden jälkeen lähetä todennus ja tilaus uudelleen.

Node.js-esimerkki

Node.js 22:ssa on sisäänrakennettu 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);
  }
};

Täydellinen Node.js-esimerkki on tiedostossa nodejs_hamapi_example.zip. Siinä on kirjasto hamapi.js ja tiedosto example.js.

1. Aseta tiedostossa example.js arvot server, api_key ja sarjanumerot.
2. Suorita npm install ja sitten node example.js.

Kirjasto ei yhdistä uudelleen, kun yhteys sulkeutuu. Lisää tämä koodiisi.

Katso myös

• REST API
• Webhookit säännöistä