Data live (WebSocket)

Bil-WebSocket tieħdu l-qari u l-bidliet tal-apparati fil-mument li jiġru. L-app HAM tuża l-istess konnessjoni. Għal qari wieħed kull darba, ir-REST API hija aktar sempliċi.

Indirizz

wss://DEVICE_SERVER:9001

• DEVICE_SERVER huwa l-valur tal-qasam device_server ta’ kull apparat. Issibuh b’get_user_devices.php.
• L-apparati ta’ kont wieħed jistgħu jkunu fuq servers differenti. Iftħu konnessjoni waħda għal kull server differenti, mhux waħda għal kull apparat.
• Il-port 9001 irid ikun miftuħ għall-konnessjonijiet outbound. Araw ir-rekwiżiti tan-network.

Il-format tal-messaġġi

Kull messaġġ li tibagħtu huwa array JSON:

[command_id, payload]

Il-command_id huwa numru sħiħ. Ibdew minn 1 u żiduh ma’ kull messaġġ. It-tweġiba għandha l-istess command_id.

Id-daqs massimu ta’ messaġġ huwa 20 KiB. Is-server jagħlaq il-konnessjoni jekk tibagħtu messaġġ akbar.

1. Awtentikazzjoni

L-ewwel messaġġ wara l-konnessjoni huwa l-awtentikazzjoni:

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

Tistgħu tibagħtu wkoll {"access_token": "YOUR_ACCESS_TOKEN"}. Araw l-awtentikazzjoni.

Tweġiba	Tifsira
[]	Suċċess
["Access Denied"]	Ċavetta jew token ħażin. Is-server jagħlaq il-konnessjoni.
[1,[{},"Rate limit"]]	Wisq konnessjonijiet f’ħin qasir

Limitu tal-konnessjonijiet: 15 kull 60 sekonda għal ċavetta API waħda. 25 kull 60 sekonda għal access token wieħed.

2. Abbonaw għall-apparati (SUBSCRIBE)

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

Qasam	Tifsira
c	SUBSCRIBE
server	Dejjem true
serialnos	In-numri tas-serje tal-apparati fuq dan is-server
unsubscribe-others	true: is-server iwaqqaf l-abbonamenti ta’ qabel ta’ din il-konnessjoni

Tweġiba: [2,[{},""]]. Is-server jaqbeż l-apparati li m’għandkomx aċċess għalihom. Ma jibgħatx żball għalihom.

Biex twaqqfu l-abbonamenti kollha, ibagħtu [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Aġġornamenti tal-istat

Minnufih wara l-abbonament, is-server jibgħat l-istat attwali ta’ kull apparat. Imbagħad jibgħat aġġornament kull darba li xi ħaġa tinbidel.

L-aġġornamenti huma oġġetti JSON, mhux arrays:

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

Qasam	Kontenut
serialno	L-apparat
R	Il-qari, mhux ipproċessat, skont il-kodiċi tal-qari
O	Il-valuri tal-outputs, fl-ordni ta’ output_names
T	L-iskedi tal-apparat
S	Is-settings tal-apparat
previous	Il-valuri akkumulati tal-perjodu ta’ qabel, għall-apparati b’kontaturi
alarms	L-alarms attivi
is_local	true jekk il-konnessjoni tagħkom u l-apparat huma fl-istess network

• Aġġornament jista’ jkollu biss l-oqsma li nbidlu. Għaqqduh mal-istat li diġà għandkom.
• Is-server jiġbor il-bidliet għal madwar 100 ms qabel ma jibgħat aġġornament.
• Injoraw il-messaġġi li ma tagħrfuhomx.

Biex tikkonvertu l-valuri mhux ipproċessati, użaw id-definizzjonijiet tal-familji. Araw ir-REST API.

Żommu l-konnessjoni miftuħa

• Is-server jibgħat pings tal-WebSocket. Il-librerija tagħkom trid twieġeb b’pong. Ħafna libreriji jagħmlu dan awtomatikament.
• Jekk il-konnessjoni tingħalaq, erġgħu ikkonnettjaw. L-app tistenna 100 ms l-ewwel darba u 10 sekondi wara dan.
• Wara konnessjoni ġdida, ibagħtu l-awtentikazzjoni u l-abbonament mill-ġdid.

Eżempju Node.js

Node.js 22 għandu WebSocket integrat.

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);
  }
};

Eżempju sħiħ ta’ Node.js jinsab f’nodejs_hamapi_example.zip. Fih il-librerija hamapi.js u l-fajl example.js.

1. F’example.js, issettjaw server, api_key u n-numri tas-serje.
2. Ħaddmu npm install, imbagħad node example.js.

Il-librerija ma terġax tikkonnettja meta l-konnessjoni tingħalaq. Żidu dan fil-kodiċi tagħkom.

Araw ukoll

• REST API
• Webhooks mir-regoli