API

Εισαγωγή

Κάθε συσκευή μας έχει έναν αύξοντα αριθμό της μορφής F:S (π.χ. 12:34). Το μέρος F του σειριακού αριθμού είναι η οικογένεια προϊόντος και είναι κοινό σε παρόμοιες συσκευές. Για παράδειγμα, όλες οι συσκευές DinSwitch έχουν σειριακό αριθμό με τη μορφή 12:S, ενώ όλες οι συσκευές Plug έχουν 14:S κ.ο.κ. Το S είναι ένας αύξων αριθμός, μοναδικός για κάθε συσκευή εντός της ίδιας οικογένειας. Ο σειριακός αριθμός μιας συσκευής είναι το αναγνωριστικό που χρησιμοποιείται από τον διακομιστή, το UI και τα τελικά σημεία API. Παραδείγματα σειριακών αριθμών είναι τα εξής: 12:4, 12:7, 14:20, 8:4.

Για κάθε συσκευή δημιουργούνται δύο τυχαία κλειδιά. Το ένα είναι το device_key και είναι ο κωδικός πρόσβασης WPA του σημείου πρόσβασης (AP) και χρησιμοποιείται επίσης για την καταχώρηση μιας συσκευής. Το δεύτερο κλειδί είναι μια μακρά ακολουθία που χρησιμοποιεί ο διακομιστής για να πιστοποιήσει τη σύνδεση μιας συσκευής και η συσκευή για να πιστοποιήσει τον διακομιστή.

Όλες οι επικοινωνίες και οι αλληλεπιδράσεις με τις συσκευές πραγματοποιούνται μέσω του διακομιστή από προεπιλογή. Υπάρχει η δυνατότητα αποστολής αιτημάτων HTTP με εντολές συσκευής απευθείας στις συσκευές στη διεύθυνση IP τους, μόλις συνδεθούν σε ένα τοπικό δίκτυο, αλλά είναι απενεργοποιημένη από προεπιλογή για λόγους ασφαλείας. Ο διακομιστής πιστοποιεί τις συσκευές, πιστοποιεί τους πελάτες και διαβιβάζει εντολές και δεδομένα μεταξύ των δύο. Ο διακομιστής χειρίζεται, μεταξύ άλλων, την καταγραφή δεδομένων και την αξιολόγηση κανόνων.

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

Ο συνδεδεμένος χρήστης καθορίζεται από τον διακομιστή, χρησιμοποιώντας ένα παρεχόμενο api_key ή ένα access_token μέσω των παραμέτρων COOKIE, POST ή GET. Σε περίπτωση που το access_token ή το api_key παρέχονται πολλές φορές, το api_key έχει προτεραιότητα έναντι του access_token και στη συνέχεια, οι παράμετροι GET έχουν την υψηλότερη προτεραιότητα, οι παράμετροι POST είναι οι επόμενες και τελευταίες είναι οι παράμετροι COOKIE.

Ένα διακριτικό πρόσβασης (access token) δημιουργείται με τον τρόπο OAuth2 όταν ένας χρήστης συνδέεται χρησιμοποιώντας το email και τον κωδικό πρόσβασής του. Πολλαπλά access_tokens μπορούν να είναι ενεργά μέχρι ένα ορισμένο όριο. Όταν ξεπεραστεί αυτό το όριο, τα παλαιότερα access_tokens αντικαθίστανται και ακυρώνονται. Τα access tokens έχουν επίσης ημερομηνία λήξης. Αυτό σημαίνει ότι τα access tokens είναι προσωρινά.

Από την άλλη πλευρά, ένα api_key δεν λήγει ποτέ, αλλά κάθε λογαριασμός χρήστη περιορίζεται σε ένα μόνο. Μπορείτε να δημιουργήσετε ένα κλειδί api_key (το οποίο θα αντικαταστήσει το ήδη υπάρχον), επισκεπτόμενοι την ενότητα λογαριασμού χρήστη στον ιστότοπο της HAM και χρησιμοποιώντας την επιλογή "generate API key".

/get_user_devices.php

URL: https://hamsystems.eu/get_user_devices.php

Επιστρέφει πληροφορίες για τη συσκευή του χρήστη, συμπεριλαμβανομένων των κατόψεων, των ομάδων και των δικαιωμάτων.

Παράμετροι [GET/POST]

• access_token ή api_key

Απόκριση:

/device_command.php

URL: https://hamsystems.eu/device_command.php

Παράμετροι: [GET/POST]

• "access_token ή api_key" - Για έλεγχο ταυτότητας
• "serialno" - Σειριακός αριθμός της συσκευής
• "command" - η εντολή που πρέπει να σταλεί στη συσκευή

Αποκρίσεις:

Παράδειγμα για "serialno = 12:0, command = READ"

Εικονικές συσκευές

Είναι δυνατή η δημιουργία και η ενημέρωση της κατάστασης συσκευών που δεν ανήκουν στο σύστημα HAM για σκοπούς όπως η καταγραφή δεδομένων, η ενσωμάτωση συστημάτων που δεν ανήκουν στο σύστημα HAM και άλλα. Αυτού του είδους οι συσκευές αναφέρονται ως "εικονικές συσκευές" και μπορείτε να αποκτήσετε πρόσβαση και να ενημερώσετε την κατάστασή τους αφού επικοινωνήσετε με την εταιρεία μας. Οι σειριακοί αριθμοί τους αρχίζουν με v:.

Κάθε εικονική συσκευή έχει έναν καθορισμένο αριθμό μετρήσεων που μπορούν να ενημερωθούν και να καταγραφούν, και αυτές μπορούν να διαμορφωθούν από τις ρυθμίσεις της εικονικής συσκευής, όπως φαίνεται παρακάτω.

Υπάρχει μια συμμετοχή ανά ανάγνωση/εγγραφή. Για κάθε εγγραφή:

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

Αφού είστε ικανοποιημένοι με τις ρυθμίσεις σας, μπορείτε να κάνετε κλικ στο κουμπί Υποβολή.

Για να ενημερώσετε την κατάσταση της εικονικής συσκευής πρέπει να χρησιμοποιήσετε το api όπως περιγράφεται παρακάτω:

/virtual_device_update.php

URL: https://hamsystems.eu/virtual_device_update.php

Παράμετροι [JSON]

• "access_token ή api_key" - Για έλεγχο ταυτότητας
• "serialno" - Σειριακός αριθμός της συσκευής
•  "R¨- Οι μετρήσεις σε μορφή κατάστασης της συσκευής, ανατρέξτε στην εντολή για λεπτομέρειες

Είναι σημαντικό να χρησιμοποιείτε "u#" για τις ενδείξεις, όπου # είναι ο δείκτης της ανάγνωσης με τη σειρά που έχει ρυθμιστεί στις ρυθμίσεις της εικονικής συσκευής.

Παράδειγμα αίτησης: "(v:x)" είναι ο αύξων αριθμός :

Η απόκριση περιλαμβάνει την "τρέχουσα" κατάσταση της συσκευής.

Παράδειγμα απόκρισης για το παραπάνω αίτημα: