Βασικό λογισμικό του HALO Smart Sensor API
Προς τα εμπρός
Αυτό το έγγραφο περιγράφει την ομάδα εγκαταστάσεων του έξυπνου αισθητήρα Halo που είναι γνωστά συλλογικά ως BASIC API ή Διεπαφή Προγραμματισμού Εφαρμογών. Αυτή η συζήτηση προορίζεται για χρήση από προγραμματιστές ή ολοκληρωμένους που ενδιαφέρονται να ενσωματώσουν έναν ή περισσότερους έξυπνους αισθητήρες HALO (HALO) με στοιχεία ή συστήματα λογισμικού τρίτου κατασκευαστή (μη IPVideo). Γενικά, το HALO API προορίζεται να μεταφέρει αποτελεσματικά πληροφορίες από το HALO μέσω ενός συμβατικού δικτύου Ethernet στο εξωτερικό πρόγραμμα. Για να επιτευχθεί αυτός ο στόχος, το API χωρίζεται σε τρεις ενότητες: Event Driven Socket Connection, Heartbeat Socket Connection και Event Data URL. Η διεπαφή BACnet είναι επίσης παρούσα και καλύπτεται σε ξεχωριστό έγγραφο.
Σχεδιασμός API
Το API έχει σχεδιαστεί χρησιμοποιώντας τυπικές μορφές του κλάδου όπως το TCP/IP. HTTP, HTTPS και JSON. Ο σχεδιασμός δεν απαιτεί ειδικές ή ιδιόκτητες τεχνικές ή βιβλιοθήκες που θα χρησιμοποιηθούν στην ανάπτυξη του εξωτερικού προγράμματος ή εφαρμογής. Το API είναι ευέλικτο και μπορεί να διαμορφωθεί και να προγραμματιστεί ώστε να παρέχει ακριβώς τα δεδομένα που απαιτούνται και με τον πιο αποτελεσματικό τρόπο. Οι λεπτομέρειες της λειτουργίας καθεμιάς από τις παραπάνω ενότητες καλύπτονται στις επόμενες ενότητες αυτού του οδηγού.
Εξωτερικά Μηνύματα
Αυτή η δυνατότητα χρησιμοποιείται για την παράδοση ειδοποιήσεων ή συναγερμών και δεδομένων συμβάντων σε εξωτερικό πρόγραμμα, σύστημα VMS, διακομιστή κ.λπ. όταν ενεργοποιείται (ορίζεται) ένα Συμβάν. Τα προαιρετικά μηνύματα μπορούν επίσης να ενεργοποιηθούν για να σηματοδοτούν όταν ένα συμβάν διαγράφεται (επαναφέρεται). Αυτή η παράδοση μπορεί να γίνει σε υποδοχή TCP/IP ή διακομιστή HTTP/S σε πραγματικό χρόνο. Υπάρχει μια σειρά από διαμορφώσιμα πρωτόκολλα με προσαρμόσιμο περιεχόμενο. Διατίθενται έλεγχος ταυτότητας και κρυπτογράφηση.
Καρδιοχτύπι
Τα μηνύματα καρδιακού παλμού αποστέλλονται σε ένα ρυθμιζόμενο διάστημα (αντί για την ενεργοποίηση των συμβάντων) για την παροχή απόδειξης ζωντανής/διαθεσιμότητας. Έχουν παρόμοιο εύρος δυνατοτήτων με το Εξωτερικό Μηνύματα, αλλά συνήθως διαμορφώνονται ώστε να περιέχουν πληροφορίες γενικής κατάστασης και όχι λεπτομέρειες σχετικά με ένα συγκεκριμένο συμβάν.
Δεδομένα συμβάντων URL
Αυτή η διευκόλυνση είναι διαθέσιμη μόνο σε NDA και θα πρέπει να χρησιμοποιείται μόνο όταν το εξωτερικό πρόγραμμα απαιτεί πρόσβαση σε οποιεσδήποτε και όλες τις τιμές συμβάντος, τα κατώφλια και τις σημαίες κατάστασης. Αυτά τα δεδομένα ανακτώνται γενικά κατόπιν ζήτησης από το εξωτερικό πρόγραμμα αλλά όχι σε πολύ υψηλή συχνότητα. Αυτή η μέθοδος γενικά επιφέρει κάποια καθυστέρηση όταν χρησιμοποιείται ένα μέτριο ποσοστό δημοσκοπήσεων. Τα τυπικά ποσοστά δημοσκοπήσεων κυμαίνονται από μία φορά ανά λεπτό έως μία φορά ανά 5 δευτερόλεπτα με απόλυτο μέγιστο ρυθμό μία φορά ανά δευτερόλεπτο. Αυτή η μέθοδος μπορεί επίσης να χρησιμοποιηθεί για την ανάκτηση πρόσθετων υποστηρικτικών δεδομένων όταν λαμβάνεται ένα συμβάν (ειδοποίηση).
Λεπτομέρειες Εξωτερικών Μηνυμάτων
Ένα τμήμα του HALO web Το αναδυόμενο παράθυρο ενσωμάτωσης διεπαφής παρέχει τη διαμόρφωση μιας μοναδικής σύνδεσης τρίτου μέρους όπου μπορούν να αποσταλούν διάφορες τιμές σε μια απομακρυσμένη υποδοχή TCP ή σε έναν διακομιστή HTTP/HTTPS. Οι θέσεις κατόχων (tokens) χρησιμοποιούνται για την εισαγωγή ζωντανών τιμών στο μεταδιδόμενο κείμενο. Αν και φέρει την ένδειξη "Εξωτερικά μηνύματα", αυτό το κανάλι μπορεί να χρησιμοποιηθεί για σχεδόν οποιονδήποτε σκοπό που απαιτεί ενεργοποίηση συμβάντων σε πραγματικό χρόνο, που παρέχονται ενεργά από το HALO. Αυτή η διάταξη είναι αρκετά ευέλικτη επειδή οι επιλογές στις "Ενέργειες" καθορίζουν ποια συμβάντα HALO μεταδίδονται μέσω αυτού του καναλιού.
Στη λειτουργία HTTP, οι συμβολοσειρές Set και Reset είναι οι URLs που πρέπει να εισαχθούν και να μορφοποιηθούν όπως απαιτείται από τον επιθυμητό διακομιστή προορισμού. Ένα πεδίο Χρήστης και Κωδικός πρόσβασης μπορεί να χρησιμοποιηθεί για έλεγχο ταυτότητας. Δείτε τη λειτουργία HTTP παρακάτω.
Στη λειτουργία TCP, οι συμβολοσειρές Set και Reset είναι μόνο τα δεδομένα ενός μόνο μηνύματος που αποστέλλεται στην υποδοχή TCP λήψης. Μπορούν να μορφοποιηθούν όπως απαιτείται από τον προορισμό. Ο προορισμός καθορίζεται στα πεδία Διεύθυνση και Θύρα. Δείτε τη λειτουργία TCP παρακάτω.
Για οποιαδήποτε λειτουργία, εμφανίζεται η κατάσταση από το πιο πρόσφατο μήνυμα που μπορεί να βοηθήσει στη διόρθωση της σύνδεσης ή άλλων προβλημάτων. Θα μπορούσατε να χρησιμοποιήσετε τα κουμπιά Event TEST στο αναδυόμενο παράθυρο Actions για να επιβάλετε ένα μήνυμα:
Καθολική Ενεργοποίηση/Απενεργοποίηση για Ρύθμιση ή Επαναφορά πρέπει να είναι ενεργοποιημένη για να ενεργοποιήσετε αυτούς τους τύπους μηνυμάτων. Η επαναφορά συχνά δεν χρησιμοποιείται επειδή ενδιαφέρει μόνο η έναρξη ενός συμβάντος, αλλά αυτό μπορεί να διαφέρει. Κάθε συμβάν μπορεί να καθορίσει ανεξάρτητα εάν θα χρησιμοποιεί είτε το μήνυμα Set είτε το μήνυμα Reset στο αναδυόμενο παράθυρο Actions. Τα κουμπιά του βολβού του ματιού θα εμφανίσουν μια κατά προσέγγιση αναπαράσταση του τι αποστέλλεται μετά από αντικαταστάσεις και μορφοποίηση λέξεων-κλειδιών. Το Repeat Holdoff μπορεί να χρησιμοποιηθεί για τον περιορισμό συχνών μηνυμάτων καθυστερώντας προτού σταλεί ένα άλλο. Αυτό γίνεται ανεξάρτητα ανά Συμβάν. Το HALO διαθέτει ενσωματωμένο χρόνο αναμονής για συμβάντα 15 δευτερολέπτων για να αποτρέψει την ταχεία επανενεργοποίηση συμβάντων. Εάν θέλετε να διασφαλίσετε ότι δεν αποστέλλονται περισσότερα από 1 συμβάν ενός τύπου ανά λεπτό, μπορείτε να ορίσετε το Repeat Holdoff σε 60 (δευτερόλεπτα).
Λεπτομέρειες για τους παλμούς της καρδιάς
Οι μεταδόσεις Heartbeat λειτουργούν με παρόμοιο τρόπο με τους παραπάνω, εκτός από το ότι δεν υπάρχει αλληλεπίδραση με τη σελίδα Ενέργειες. Αντίθετα, η μετάδοση Heartbeat πραγματοποιείται σε τακτική βάση, όπως έχει διαμορφωθεί με το πεδίο Interval, στη λειτουργία HTTP, οι συμβολοσειρές Set και Reset είναι οι URLs που πρέπει να εισαχθούν και να μορφοποιηθούν όπως απαιτείται από τον επιθυμητό διακομιστή προορισμού. Ένα πεδίο Χρήστης και Κωδικός πρόσβασης μπορεί να χρησιμοποιηθεί για έλεγχο ταυτότητας. Δείτε τη λειτουργία HTTP παρακάτω.
Ενώ ο πρωταρχικός σκοπός του Heartbeat είναι να παρέχει απόδειξη της ζωής ενός έξυπνου αισθητήρα HALO σε μια απομακρυσμένη εφαρμογή, αυτό το μήνυμα μπορεί επίσης να χρησιμοποιηθεί για τη μετάδοση επιλεγμένων αισθητήρων ή πληροφοριών τρέχουσας κατάστασης συμβάντος. Ο πρώηνampΤο le παραπάνω στέλνει μια παράμετρο μεγάλης συμβολοσειράς με το URL που περιλαμβάνουν το όνομα Halo, την πλειονότητα των τιμών του αισθητήρα και, τέλος, το Triggered=%ACTIVE% που θα μπορούσε να είναι κενό ή μια λίστα συμβάντων που ενεργοποιούνται αυτήν τη στιγμή.
Λειτουργία HTTP (και HTTPS).
Τα εξωτερικά μηνύματα και οι συμβολοσειρές Heartbeat μπορούν να είναι http: ή https: URLs όπως χρειάζεται. Η διαδρομή και οι παράμετροι μπορούν να εισαχθούν όπως απαιτείται από τον διακομιστή προορισμού. Λέξεις-κλειδιά όπως %NAME% (όνομα συσκευής HALO) ή %EID% (Αναγνωριστικό συμβάντος) μπορούν να εισαχθούν όπως απαιτείται και θα αντικατασταθούν με αντίστοιχα δεδομένα κατά την αποστολή του μηνύματος. Εμφανίζεται μια λίστα με λέξεις-κλειδιά που χρησιμοποιούνται συνήθως για γρήγορη αναφορά.
Ο URL διαδρομή μπορεί να περιέχει λέξεις-κλειδιά καθώς και τις παραμέτρους του URL. Οι παράμετροι μπορεί να είναι ζεύγη NAME=VALUE ή αντικείμενο JSON ή προσαρμοσμένη μορφή ανάλογα με τον διακομιστή προορισμού. ΠρώηνampΤα στοιχεία για τα εξωτερικά μηνύματα θα περιλαμβάνουν %EID% για να υποδείξουν το συμβάν που ενεργοποίησε:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampΤα les για Heartbeat ενδέχεται να προσθέσουν %ACTIVE% (συμβάντα που ενεργοποιούνται αυτήν τη στιγμή) ή μια τιμή αισθητήρα:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Οι τιμές %SENSOR:…% χρησιμοποιούν τα ονόματα που βρίσκονται στις επικεφαλίδες στηλών του δεξιού αισθητήρα στο αρχείο καταγραφής evtYYYYMMDD.csv fileμικρό. Συνήθως είναι:
Εάν ο διακομιστής προορισμού προτιμά HTTP PUT ή POST αντί για αιτήματα GET, μπορείτε να ορίσετε το πρόθεμα URL με PUT: ή POST:. Ανεξάρτητα, μπορείτε να προσθέσετε ένα ωφέλιμο φορτίο JSON που είναι δημοφιλές σε πολλούς διακομιστές προσθέτοντας τη λέξη-κλειδί [JSONBODY] ακολουθούμενη από ένα αντικείμενο με μορφή JSON. Πρώηνample:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
Ο URL υποστηρίζει τυπική διεύθυνση IP (και IPv6) και επιλογές θύρας και κωδικού πρόσβασης χρήστη ή μπορείτε να χρησιμοποιήσετε τα πεδία Χρήστης και Κωδικός πρόσβασης, εάν χρειάζεται, ως διακομιστής προορισμού για μεθόδους ελέγχου ταυτότητας, όπως το Basic ή το Digest:
https://username:password@123.321.123.321:9876/event…
Λειτουργία TCP
Τα εξωτερικά μηνύματα και οι συμβολοσειρές Heartbeat είναι μόνο για δεδομένα, καθώς τα πεδία Διεύθυνση και Θύρα καθορίζουν τον προορισμό. Η Διεύθυνση υποστηρίζει ονόματα, IPv4 και IPv6.
Η συμβολοσειρά μπορεί να μορφοποιηθεί όπως τα τμήματα δεδομένων των μηνυμάτων HTTP που περιγράφονται παραπάνω ή όπως απαιτείται από τον διακομιστή προορισμού.
ExampΤα στοιχεία για τα εξωτερικά μηνύματα θα περιλαμβάνουν %EID% για να υποδείξουν το συμβάν που ενεργοποίησε:
τοποθεσία=%NAME%,γεγονός=%EID%
{“τοποθεσία”:”:%NAME%”,”συμβάν”:”%EID%”}
ExampΤα les για Heartbeat ενδέχεται να προσθέσουν %ACTIVE% (συμβάντα που ενεργοποιούνται αυτήν τη στιγμή) ή μια τιμή αισθητήρα:
τοποθεσία=%NAME%&Triggered=%ACTIVE%
{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Τα πλαίσια ελέγχου στις στήλες "Σύνολο ενσωμάτωσης" και "Επαναφορά ενσωμάτωσης" καθορίζουν ποια Συμβάντα ενεργοποιούν την αποστολή. Περισσότερα για τη ρύθμιση των συμβάντων και των ενεργειών είναι διαθέσιμα στον Οδηγό διαχειριστή HALO.
Παράδοση μηνυμάτων συμβάντων JSON
Ορισμένοι προγραμματιστές προτιμούν να λαμβάνουν δεδομένα συμβάντων μορφοποιημένα ως JSON με το πρότυπο του κλάδου και όχι απλό κείμενο ASCII, καθώς το πρώτο αναλύεται πιο αξιόπιστα και πιο εύκολα. Στο HALO web στην καρτέλα "Μηνύματα", μπορείτε να παρέχετε μηνύματα JSON στις ρυθμίσεις "Εξωτερικά μηνύματα" "Ρύθμιση συμβολοσειράς" και "Επαναφορά συμβολοσειράς" και στο "Χτύπο καρδιάς" "Μήνυμα".
Examples:
Ορισμός συμβολοσειράς ρυθμίσεων "Εξωτερικά μηνύματα":
{ “συσκευή”:”%NAME%”, “συμβάν”:”%EID%”, “ξυπνητήρι”:”ναι” }
Αυτό θα στείλει ένα μόνο μήνυμα TCP ή UDP JSON στον καθορισμένο διακομιστή αναφέροντας το φιλικό όνομα συσκευής, το όνομα συμβάντος και ότι μόλις ξεκίνησε.
Ρυθμίσεις "Εξωτερικά μηνύματα" Επαναφορά συμβολοσειράς:
{ “συσκευή”:”%NAME%”, “συμβάν”:”%EID%”, “ξυπνητήρι”:”όχι” }
Αυτό θα στείλει ένα μόνο μήνυμα TCP ή UDP JSON στον καθορισμένο διακομιστή αναφέροντας το φιλικό όνομα συσκευής, το όνομα συμβάντος και ότι η συνθήκη έχει πλέον σταματήσει.
Μήνυμα "Χτυποκάρδια":
{ “συσκευή”:”%NAME%”, “ζωντανή”:”%DATE% %TIME%” }
Αυτό θα στέλνει περιοδικά ένα μήνυμα TCP ή UDP JSON στον καθορισμένο διακομιστή που αναφέρει ότι το HALO είναι ζωντανό την υποδεικνυόμενη ώρα.
Έγγραφα / Πόροι
 |
Βασικό λογισμικό του HALO Smart Sensor API [pdf] Οδηγός χρήστη Βασικό λογισμικό HALO Smart Sensor API |
