Ζωντανά δεδομένα (WebSocket)

Με το WebSocket παίρνετε τις μετρήσεις και τις αλλαγές των συσκευών τη στιγμή που γίνονται. Η εφαρμογή HAM χρησιμοποιεί την ίδια σύνδεση. Για μία μέτρηση τη φορά, το REST API είναι πιο απλό.

Διεύθυνση

wss://DEVICE_SERVER:9001

• Το DEVICE_SERVER είναι η τιμή του πεδίου device_server κάθε συσκευής. Τη βρίσκετε με το get_user_devices.php.
• Οι συσκευές ενός λογαριασμού μπορεί να είναι σε διαφορετικούς διακομιστές. Ανοίξτε μία σύνδεση για κάθε διαφορετικό διακομιστή, όχι μία για κάθε συσκευή.
• Η θύρα 9001 πρέπει να είναι ανοιχτή για εξερχόμενες συνδέσεις. Δείτε τις απαιτήσεις δικτύου.

Μορφή μηνυμάτων

Κάθε μήνυμα που στέλνετε είναι ένας πίνακας JSON:

[command_id, payload]

Το command_id είναι ένας ακέραιος. Ξεκινήστε από το 1 και αυξήστε τον σε κάθε μήνυμα. Η απάντηση έχει το ίδιο command_id.

Το μέγιστο μέγεθος ενός μηνύματος είναι 20 KiB. Ο διακομιστής κλείνει τη σύνδεση αν στείλετε μεγαλύτερο μήνυμα.

1. Έλεγχος ταυτότητας

Το πρώτο μήνυμα μετά τη σύνδεση είναι ο έλεγχος ταυτότητας:

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

Μπορείτε να στείλετε και {"access_token": "YOUR_ACCESS_TOKEN"}. Δείτε τον έλεγχο ταυτότητας.

Απάντηση	Σημασία
[]	Επιτυχία
["Access Denied"]	Λάθος κλειδί ή token. Ο διακομιστής κλείνει τη σύνδεση.
[1,[{},"Rate limit"]]	Πάρα πολλές συνδέσεις σε σύντομο χρόνο

Όριο συνδέσεων: 15 ανά 60 δευτερόλεπτα για ένα κλειδί API. 25 ανά 60 δευτερόλεπτα για ένα access token.

2. Εγγραφή σε συσκευές (SUBSCRIBE)

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

Πεδίο	Σημασία
c	SUBSCRIBE
server	Πάντα true
serialnos	Οι σειριακοί αριθμοί των συσκευών αυτού του διακομιστή
unsubscribe-others	true: ο διακομιστής σταματά τις παλιές εγγραφές αυτής της σύνδεσης

Απάντηση: [2,[{},""]]. Ο διακομιστής παραλείπει χωρίς μήνυμα τις συσκευές στις οποίες δεν έχετε πρόσβαση.

Για να σταματήσετε όλες τις εγγραφές, στείλτε [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Ενημερώσεις κατάστασης

Αμέσως μετά την εγγραφή, ο διακομιστής στέλνει την τρέχουσα κατάσταση κάθε συσκευής. Μετά στέλνει μια ενημέρωση κάθε φορά που κάτι αλλάζει.

Οι ενημερώσεις είναι αντικείμενα JSON, όχι πίνακες:

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

Πεδίο	Περιεχόμενο
serialno	Η συσκευή
R	Οι μετρήσεις, ακατέργαστες, με κλειδί τον κωδικό μέτρησης
O	Οι τιμές των εξόδων, με τη σειρά του output_names
T	Τα χρονοδιαγράμματα της συσκευής
S	Οι ρυθμίσεις της συσκευής
previous	Οι συσσωρευμένες τιμές της προηγούμενης περιόδου, για συσκευές με μετρητές
alarms	Οι ενεργοί συναγερμοί
is_local	true αν η σύνδεσή σας και η συσκευή είναι στο ίδιο δίκτυο

• Μια ενημέρωση μπορεί να έχει μόνο τα πεδία που άλλαξαν. Ενώστε την με την κατάσταση που έχετε ήδη.
• Ο διακομιστής ομαδοποιεί τις αλλαγές για περίπου 100 ms πριν στείλει μια ενημέρωση.
• Αγνοήστε τα μηνύματα που δεν αναγνωρίζετε.

Για να μετατρέψετε τις ακατέργαστες τιμές, χρησιμοποιήστε τους ορισμούς της οικογένειας. Δείτε το REST API.

Διατήρηση της σύνδεσης

• Ο διακομιστής στέλνει ping στο επίπεδο του WebSocket. Η βιβλιοθήκη σας πρέπει να απαντά με pong. Οι περισσότερες βιβλιοθήκες το κάνουν μόνες τους.
• Αν η σύνδεση κλείσει, συνδεθείτε ξανά. Η εφαρμογή περιμένει 100 ms την πρώτη φορά και 10 δευτερόλεπτα τις επόμενες.
• Μετά από νέα σύνδεση, στείλτε ξανά τον έλεγχο ταυτότητας και την εγγραφή.

Παράδειγμα σε Node.js

Το Node.js 22 έχει ενσωματωμένο 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);
  }
};

Ένα πλήρες παράδειγμα σε Node.js είναι στο nodejs_hamapi_example.zip. Περιέχει τη βιβλιοθήκη hamapi.js και το αρχείο example.js.

1. Στο example.js, γράψτε τα server, api_key και τους σειριακούς αριθμούς.
2. Εκτελέστε npm install και μετά node example.js.

Η βιβλιοθήκη δεν συνδέεται ξανά μόνη της όταν η σύνδεση κλείσει. Προσθέστε αυτό στον κώδικά σας.

Δείτε επίσης

• REST API
• Webhooks από κανόνες