Gögn í rauntíma (WebSocket)

Með WebSocket færðu mælingar og breytingar tækjanna á sama augnabliki og þær gerast. HAM-appið notar sömu tengingu. Fyrir eina mælingu í einu er REST API einfaldara.

Vistfang

wss://DEVICE_SERVER:9001

• DEVICE_SERVER er gildi reitsins device_server fyrir hvert tæki. Þú finnur það með get_user_devices.php.
• Tæki eins reiknings geta verið á mismunandi netþjónum. Opnaðu eina tengingu fyrir hvern netþjón, ekki eina fyrir hvert tæki.
• Gátt 9001 verður að vera opin fyrir tengingar út á við. Sjá Netkröfur (fyrir upplýsingatækni).

Snið skilaboða

Hver skilaboð sem þú sendir eru JSON-fylki:

[command_id, payload]

command_id er heiltala. Byrjaðu á 1 og hækkaðu hana með hverjum skilaboðum. Svarið hefur sama command_id.

Hámarksstærð skilaboða er 20 KiB. Netþjónninn lokar tengingunni ef þú sendir stærri skilaboð.

1. Auðkenning

Fyrstu skilaboðin eftir tenginguna eru auðkenningin:

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

Þú getur líka sent {"access_token": "YOUR_ACCESS_TOKEN"}. Sjá auðkenningu.

Svar	Merking
[]	Tókst
["Access Denied"]	Rangur lykill eða tákn. Netþjónninn lokar tengingunni.
[1,[{},"Rate limit"]]	Of margar tengingar á stuttum tíma

Takmörk tenginga: 15 á hverjum 60 sekúndum fyrir einn API-lykil. 25 á hverjum 60 sekúndum fyrir eitt aðgangstákn.

2. Gerast áskrifandi að tækjum (SUBSCRIBE)

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

Reitur	Merking
c	SUBSCRIBE
server	Alltaf true
serialnos	Raðnúmer tækjanna á þessum netþjóni
unsubscribe-others	true: netþjónninn stöðvar fyrri áskriftir þessarar tengingar

Svar: [2,[{},""]]. Netþjónninn sleppir tækjunum sem þú hefur ekki aðgang að. Hann sendir enga villu fyrir þau.

Til að stöðva allar áskriftir sendirðu [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Uppfærslur á stöðu

Strax eftir áskriftina sendir netþjónninn núverandi stöðu hvers tækis. Síðan sendir hann uppfærslu í hvert sinn sem eitthvað breytist.

Uppfærslurnar eru JSON-hlutir, ekki fylki:

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

Reitur	Innihald
serialno	Tækið
R	Mælingarnar, óunnar, eftir kóða mælingar
O	Gildi úttakanna, í röð output_names
T	Tímaáætlanir tækisins
S	Stillingar tækisins
previous	Uppsöfnuð gildi fyrra tímabils, fyrir tæki með teljara
alarms	Virkar viðvaranir
is_local	true ef tengingin þín og tækið eru á sama neti

• Uppfærsla getur haft aðeins reitina sem breyttust. Sameinaðu hana við stöðuna sem þú ert þegar með.
• Netþjónninn safnar breytingum saman í um 100 ms áður en hann sendir uppfærslu.
• Hunsaðu skilaboð sem þú þekkir ekki.

Til að umreikna óunnu gildin notarðu skilgreiningar fjölskyldnanna. Sjá REST API.

Haltu tengingunni opinni

• Netþjónninn sendir WebSocket-ping. Safnið þitt verður að svara með pong. Flest söfn gera þetta sjálfkrafa.
• Ef tengingin lokast tengirðu aftur. Appið bíður 100 ms í fyrsta sinn og 10 sekúndur eftir það.
• Eftir nýja tengingu sendirðu auðkenninguna og áskriftina aftur.

Dæmi í Node.js

Node.js 22 hefur innbyggt 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);
  }
};

Heilt dæmi í Node.js er í nodejs_hamapi_example.zip. Það inniheldur safnið hamapi.js og skrána example.js.

1. Í example.js stillirðu server, api_key og raðnúmerin.
2. Keyrðu npm install, síðan node example.js.

Safnið tengist ekki aftur þegar tengingin lokast. Bættu þessu við kóðann þinn.

Sjá líka

• REST API
• Webhooks frá reglum