Ενσωμάτωση MQTT
Το MQTT συνδέει το HyperVisu με τον κόσμο του publish/subscribe: Zigbee2MQTT, Tasmota, Shelly (λειτουργία MQTT), ESPHome, energy gateways και οποιοδήποτε προσαρμοσμένο firmware που επικοινωνεί με έναν MQTT broker. Το HyperVisu λειτουργεί ως MQTT client — εγγράφεται (subscribes) στα topics όπου οι συσκευές δημοσιεύουν την κατάστασή τους και δημοσιεύει (publishes) εντολές στα topics που ακούν οι συσκευές. Δεν υπάρχει polling: μια συσκευή που αλλάζει κατάσταση δημοσιεύει, και το widget ενημερώνεται άμεσα.
Ένας broker μεσολαβεί στη σύνδεση. Μπορεί να είναι ένας broker που εκτελείτε ήδη (Mosquitto, EMQX, αυτός που συνοδεύει μια εγκατάσταση Zigbee2MQTT, …) ή ο ενσωματωμένος broker του HyperVisu, τον οποίο μπορεί να εκτελεί ο ίδιος ο διακομιστής ώστε οι συσκευές να συνδέονται απευθείας σε αυτόν (βλ. «The Built-in MQTT Broker»). Όλα όσα περιγράφονται σε αυτό το άρθρο ισχύουν και στις δύο περιπτώσεις — ο ενσωματωμένος broker είναι ένας τυπικός broker, προσβάσιμος μέσω μιας κανονικής σύνδεσης.
Τι χρειάζεστε: τη διεύθυνση και τη θύρα του broker, τα διαπιστευτήριά του εάν απαιτούνται, καθώς και τα topics και τη μορφή payload της συσκευής — από την τεκμηρίωση της συσκευής ή απευθείας από τον broker μέσω του topic browser (παρακάτω).
Συνδέσεις. Ενεργοποιήστε πρώτα το MQTT Protocol στη σελίδα Services (βλ. «Services & Protocols»)· είναι απενεργοποιημένο σε έναν νέο server. Το MQTT υποστηρίζει πολλαπλές συνδέσεις: μία σύνδεση ανά broker (βλ. «Connections»). Στο Add connection, επιλέξτε την κάρτα MQTT: το παράθυρο διαλόγου ζητά ένα Instance Name, τη Broker address, τη Port, το Client ID και τα διαπιστευτήρια, ενώ περιλαμβάνει και κουμπί Test. Το CA certificate και οι Broker options (Keepalive, Default QoS, Availability topic, Clean session) δεν περιλαμβάνονται στο παράθυρο διαλόγου: ορίζονται στην αποθηκευμένη σύνδεση, η οποία ανοίγει στον επεξεργαστή της μόλις κάνετε κλικ στο Create connection. Ο επεξεργαστής σύνδεσης περιλαμβάνει:
| Πεδίο | Περιγραφή |
|---|---|
| Broker address | Host, ή πλήρες URL: mqtt://, mqtts://, ws://, wss:// (ένα απλό host σημαίνει mqtt://). Μια διαδρομή στη διεύθυνση διατηρείται, για παράδειγμα ws://192.168.1.30/mqtt. |
| Port | Η θύρα ακρόασης — συνήθως 1883 για απλό MQTT και 8883 για MQTT μέσω TLS. Πληκτρολογείτε την πάντα: στο παράθυρο διαλόγου Add connection, ένα κενό πεδίο θύρας αποθηκεύεται ως 1883 ανεξαρτήτως του scheme, και το πεδίο Port υπερισχύει της θύρας που αναγράφεται στη διεύθυνση. |
| Username / Password | Αφήστε τα κενά για ανώνυμο broker. |
| Client ID | Αφήστε το κενό για παραγωγή αναγνωριστικού βάσει της διεύθυνσης MAC του server. |
| Accept self-signed certificates | Εμφανίζεται μόνο για mqtts:// / wss://. Απενεργοποιημένο από προεπιλογή: το πιστοποιητικό του broker πρέπει να έχει υπογραφεί από έμπιστη αρχή. Όταν ενεργοποιηθεί, το πιστοποιητικό δεν επαληθεύεται καθόλου. |
| CA certificate | Εμφανίζεται μόνο για TLS: το πιστοποιητικό PEM της αρχής που υπέγραψε τον broker, όταν αυτή δεν είναι δημόσια. |
| Keepalive | Χρονικό διάστημα διατήρησης μιας ανενεργής σύνδεσης πριν από την αποστολή ping (προεπιλογή 60 s). |
| Default QoS | 0 · at most once, 1 · at least once ή 2 · exactly once — χρησιμοποιείται από κάθε αντικείμενο που δεν ορίζει δικό του. |
| Availability topic / Announce HyperVisu availability | Το topic όπου το HyperVisu δημοσιεύει online / offline για τον εαυτό του (προεπιλογή hypervisu/status, retained). Ο broker δημοσιεύει offline εκ μέρους του εάν διακοπεί η σύνδεση. |
| Clean session | Ενεργό (προεπιλογή): ο broker διαγράφει τις εγγραφές όταν διακοπεί η σύνδεση και το HyperVisu επανεγγράφεται κατά την επανασύνδεση. Απενεργοποιήστε το μόνο για broker που πρέπει να διατηρεί μηνύματα σε ουρά όσο το HyperVisu είναι εκτός λειτουργίας. |
Η δοκιμή (Test) σε μια σύνδεση MQTT είναι πραγματική δοκιμή: ο server συνδέεται στον broker και περιμένει την επιβεβαίωσή του (εντός 10 s). Ένα επιτυχές αποτέλεσμα εμφανίζει την ένδειξη Connection succeeded. Στο παράθυρο διαλόγου Add connection, το Test δοκιμάζει τις τιμές που πληκτρολογήσατε, πριν δημιουργήσετε τη σύνδεση. Σε μια αποθηκευμένη σύνδεση, το Test ελέγχει την αποθηκευμένη σύνδεση και όχι τα πεδία που δεν έχετε αποθηκεύσει ακόμα: κάντε πρώτα κλικ στο Save connection και στη συνέχεια στο Test. Μια επιτυχής δοκιμή αποδεικνύει ότι η διεύθυνση, η θύρα, τα διαπιστευτήρια και οι ρυθμίσεις TLS γίνονται δεκτές από τον broker· δεν αποδεικνύει ότι κάποιο topic μεταφέρει δεδομένα.
Η κατάσταση της σύνδεσης εμφανίζεται ως Connected όσο η σύνδεση με τον broker είναι ενεργή. Εάν ο broker καταστεί μη διαθέσιμος, πραγματοποιείται απόπειρα επανασύνδεσης κάθε λίγα δευτερόλεπτα, χωρίς όριο — δεν απαιτείται ποτέ επανεκκίνηση του server.
📘 Σημείωση: Αφού δημιουργήσετε ή αποθηκεύσετε μια σύνδεση, εμφανίζεται η επιλογή Apply changes στην πλευρική γραμμή με έναν μετρητή. Η σύνδεση λειτουργεί ήδη χωρίς αυτό· η εφαρμογή επαναφορτώνει τις ρυθμίσεις του server και μηδενίζει τον μετρητή.
Σύνδεση αντικειμένου (βλ. «Binding MQTT» παρακάτω). Ανά αντικείμενο εισάγετε ένα Topic· η διαχείριση το αποθηκεύει ως <connection>:<topic> ώστε δύο brokers να μπορούν να διαθέτουν το ίδιο όνομα topic. Η κατεύθυνση του αντικειμένου καθορίζει τη συμπεριφορά:
| Κατεύθυνση | Συμπεριφορά |
|---|---|
| In | Εγγράφεται στο topic (state topic). Επιτρέπονται wildcards: + για ένα επίπεδο, # για τα υπόλοιπα. |
| Out | Δημοσιεύει στο topic (command topic). Πρέπει να είναι συγκεκριμένο topic — χωρίς wildcards. |
| In/Out | Εγγράφεται και δημοσιεύει στο ίδιο topic. Ενδείκνυται μόνο για συσκευές που διατηρούν retained state σε ένα ενιαίο topic· προτιμήστε δύο αντικείμενα (ένα In, ένα Out). |
Το payload codec — ο τρόπος με τον οποίο το payload μετατρέπεται σε τιμή και αντίστροφα — είναι η συμβολοσειρά τύπου δεδομένων του αντικειμένου, η οποία δημιουργείται από τον επεξεργαστή βάσει αυτών των πεδίων:
| Πεδίο | Αποθηκεύεται ως | Σημασία |
|---|---|---|
| Payload format | — / PATH= | Raw value: ολόκληρο το payload είναι η τιμή. JSON: η τιμή διαβάζεται στο JSON path (state, sensor.temperature, values[0]). |
| ON token / OFF token | ON= / OFF= | Για δυαδικά (boolean) αντικείμενα: τι γράφει και τι αναμένει η συσκευή για true/false (π.χ. ON / OFF). Χωρίς tokens, τα true/false, 1/0, on/off αναγνωρίζονται στην είσοδο και δημοσιεύεται true/false. |
| Scale / Offset | SCALE= / OFFSET= | Ανάγνωση: τιμή = raw × scale + offset· η δημοσίευση χρησιμοποιεί το αντίστροφο, raw = (τιμή − offset) ÷ scale. Ένα αντικείμενο εντολής και το αντίστοιχο αντικείμενο ανάδρασης λαμβάνουν επομένως το ίδιο scale. |
| Payload template | PUB= | Προαιρετικό πρότυπο δημοσίευσης· το {{value}} αντικαθίσταται από την τιμή, π.χ. {"state":"{{value}}"}. Αφήστε το κενό για δημοσίευση της απλής τιμής. |
| QoS | QOS= | Broker default, 0, 1 ή 2 για αυτήν την εντολή. |
| Retain published messages | RETAIN=1 | Απενεργοποιημένο από προεπιλογή. |
| Minimum interval (ms) | THROTTLE= | Η συχνότητα αποστολής για αισθητήρες με υψηλό ρυθμό δεδομένων περιορίζεται σε αυτό το όριο (προεπιλογή 100 ms)· η τελευταία τιμή παραδίδεται πάντα. Η τιμή 0 το απενεργοποιεί. |
Η συμβολοσειρά έχει τη μορφή TYPE:param:param… — για παράδειγμα BOOL:PATH=state:ON=ON:OFF=OFF ή FLOAT:SCALE=0.3937:PUB={"brightness":{{value}}}. Μια κενή συμβολοσειρά σημαίνει «χρήση του ανεπεξέργαστου payload ως τύπος του αντικειμένου». Ο επεξεργαστής αντικειμένου δεν διαθέτει πεδίο τύπου δεδομένων: ο τύπος είναι αυτός που εμφανίζεται στο πεδίο στο οποίο κάνετε κλικ στον topic browser (παρακάτω), και το κλικ σε ένα πεδίο προσαρμόζει αυτόματα τον τύπο του αντικειμένου. Τα αντικείμενα χρώματος (RGB) δέχονται {"r","g","b"}, {"red","green","blue"}, [r,g,b], #RRGGBB και 255,128,0 στην είσοδο, και δημοσιεύουν {"r":…,"g":…,"b":…} εκτός εάν ορίζεται διαφορετικά από ένα πρότυπο.
⚠️ Προειδοποίηση: Μια εντολή με ένδειξη retained εκτελείται εκ νέου κάθε φορά που η συσκευή επανασυνδέεται στον broker. Διατηρείτε retained κατάσταση, όχι εντολές — ο επεξεργαστής εμφανίζει προειδοποίηση όταν ενεργοποιείτε το retain για ένα αντικείμενο εξόδου.
Topic browser. Το MQTT είναι το μοναδικό πρωτόκολλο του οποίου οι διευθύνσεις μπορούν να ανιχνευθούν απευθείας από το δίκτυο. Στον επεξεργαστή αντικειμένου, στην ενότητα MQTT topic configuration, κάντε κλικ στο Scan broker: ο server παρακολουθεί ολόκληρο τον broker για τέσσερα δευτερόλεπτα και αναφέρει πόσα topics εντόπισε (τα retained topics λαμβάνονται άμεσα, επομένως μια σύντομη σάρωση εμφανίζει τα περισσότερα στοιχεία προς σύνδεση· για συσκευή που δεν χρησιμοποιεί retain, προκαλέστε μια νέα αποστολή τιμής και εκτελέστε ξανά σάρωση). Η λίστα περιορίζεται στα 500 topics. Ο επεξεργαστής αντικειμένου δεν μπορεί να σαρώσει επιμέρους τμήμα του broker: ανοίξτε το Topic και πληκτρολογήστε στο Search topics… για να φιλτράρετε τα αποτελέσματα, ή πληκτρολογήστε απευθείας το πλήρες topic. Κάθε γραμμή εμφανίζει το topic και το τελευταίο payload, με ένδειξη retained. Επιλέξτε ένα topic και:
- για payload τύπου JSON, κάθε πεδίο παρατίθεται στην ενότητα Pick the value this object should follow — με ένα κλικ ορίζονται το JSON path, ο τύπος αντικειμένου και, για δυαδικές τιμές, τα tokens ON/OFF σύμφωνα με τη μορφοποίηση της συσκευής·
- για απλό payload, η επιλογή Use the raw payload as
συμπληρώνει τον τύπο.
Επιλέξτε το topic πριν κάνετε κλικ σε ένα πεδίο: η επιλογή άλλου topic επαναφέρει τη μορφή payload, το JSON path και τα tokens. Το κλικ δεν συμπληρώνει τα πεδία Scale και Offset.
Μπορείτε επίσης να πληκτρολογήσετε ένα topic που δεν εντοπίστηκε από τη σάρωση — ένα command topic ενδέχεται να μην έχει δημοσιευτεί ποτέ, ενώ ένα αντικείμενο εισόδου μπορεί να απαιτεί wildcard. Πληκτρολογήστε το στο Topic και κάντε κλικ στο Use "…" στη λίστα.
Σημαντικές λεπτομέρειες λειτουργίας
- Άμεση κατάσταση μετά από επανεκκίνηση. Τα μηνύματα με retain αναπαράγονται από τον broker σε κάθε (επαν)σύνδεση, επομένως τα widgets εμφανίζουν τιμές χωρίς να αναμένουν την επόμενη δημοσίευση της συσκευής.
- Καμία υποθετική ανάδραση. Μια εντολή επιβεβαιώνεται μόνο όταν η συσκευή δημοσιεύσει στο topic κατάστασής της (ή όταν το αναπαραγάγει ο broker) — ακριβώς όπως τα status objects στο KNX. Εάν η συσκευή είναι εκτός λειτουργίας, το widget δεν προσομοιώνει ανάδραση.
- Εντολές κατά τη διάρκεια διακοπής. Οι εντολές με QoS 1 ή 2 τοποθετούνται σε ουρά όσο ο broker δεν είναι προσβάσιμος και παραδίδονται κατά την επανασύνδεση· οι εντολές με QoS 0 προς μη προσβάσιμο broker αποτυγχάνουν και καταγράφονται στο ιστορικό.
- Προστασία. Payloads μεγαλύτερα από 64 KB απορρίπτονται με σχετική προειδοποίηση· ανοίγεται μία μόνο συνδρομή ανά διακριτό φίλτρο topic, ανεξάρτητα από το πόσα αντικείμενα το μοιράζονται.
Παράδειγμα εφαρμογής — dimmable λαμπτήρας Zigbee2MQTT
Το Zigbee2MQTT δημοσιεύει την κατάσταση του λαμπτήρα ως JSON στο zigbee2mqtt/lamp ({"state":"ON","brightness":178}) και δέχεται εντολές στο zigbee2mqtt/lamp/set. Το εύρος φωτεινότητας είναι 0–254.
- Δημιουργήστε μια σύνδεση MQTT για τον broker (βλ. «Connections»): διεύθυνση broker
192.168.1.10, θύρα1883, διαπιστευτήρια του Zigbee2MQTT broker εάν υπάρχουν. Κάντε κλικ στο Test — πρέπει να επιβεβαιώσει επιτυχή σύνδεση. - Στο Devices, προσθέστε ένα widget Dimmer με όνομα «Office lamp». Στο Protocol, επιλέξτε τη σύνδεση του broker σας, βάσει του ονόματος που ορίσατε. Η συσκευή δημιουργείται με τέσσερα αντικείμενα: Switch ON/OFF, Switch Feedback, Dimming setpoint και Dimming feedback.
- Στο Switch ON/OFF (εντολή on/off): πληκτρολογήστε
zigbee2mqtt/lamp/setστο Topic και κάντε κλικ στο Use "…" στη λίστα. Ορίστε το ON token σεON, το OFF token σεOFFκαι το Payload template σε{"state":"{{value}}"}. Πληκτρολογήστε τα tokens: οι γκρι ενδείξειςONκαιOFFαποτελούν απλώς υποδείξεις, και χωρίς tokens ο διακόπτης δημοσιεύειtrueήfalse. - Στο Switch Feedback (κατάσταση on/off): κάντε κλικ στο Scan broker, επιλέξτε
zigbee2mqtt/lamp, και μετά κάντε κλικ στο πεδίοstate— ο επεξεργαστής ορίζει το JSON pathstateκαι τα tokensON/OFF. - Στο Dimming setpoint (εντολή φωτεινότητας): topic
zigbee2mqtt/lamp/set, Payload template{"brightness":{{value}}}, Scale0.3937, Offset0. - Στο Dimming feedback (κατάσταση φωτεινότητας): topic
zigbee2mqtt/lamp, κάντε κλικ στο πεδίοbrightness, και ορίστε το ίδιο Scale0.3937. Αυτό αντιστοιχεί περίπου στο100/254: οι εισερχόμενες τιμές πολλαπλασιάζονται με αυτό (το Zigbee 0–254 μετατρέπεται σε 0–100 %), οι εξερχόμενες τιμές διαιρούνται με αυτό (το 0–100 % μετατρέπεται σε 0–254). - Κάντε κλικ στο Save object σε κάθε αντικείμενο, στη συνέχεια κάντε κλικ στο Apply changes στην πλευρική γραμμή και επιβεβαιώστε.
- Ρυθμίστε τη φωτεινότητα στο
50 %στην εφαρμογή. Ο λαμπτήρας λαμβάνει περίπου127, και η ανάδρασή του επιστρέφει περίπου50 %. Το slider επιβεβαιώνει την τιμή από το state topic, και ο χειρισμός του λαμπτήρα από το φυσικό του τηλεχειριστήριο ενημερώνει επίσης την εφαρμογή.
📘 Σημείωση: Η τιμή που αποστέλλεται δεν στρογγυλοποιείται: το
50 %δημοσιεύεται ως127.000254. Ο επεξεργαστής αντικειμένου δεν διαθέτει πεδίο τύπου δεδομένων, επομένως δεν μπορείτε να ορίσετε ένα command object να στέλνει ακέραιο αριθμό. Βεβαιωθείτε ότι ο λαμπτήρας σας δέχεται δεκαδική τιμή φωτεινότητας.
Παραμετροποίηση αντικειμένων MQTT
Τα αντικείμενα MQTT διαμορφώνονται στο παράθυρο ρυθμίσεων αντικειμένου (ανοίξτε το αντικείμενο με το Edit, βλ. «Object Settings, Logging & Notifications»). Το τμήμα που αφορά το πρωτόκολλο κατανέμεται σε τρεις κάρτες:
MQTT topic configuration
| Πεδίο | Περιγραφή |
|---|---|
| Topic | Το topic στο οποίο εγγράφεται το αντικείμενο (In: state topic — επιτρέπονται wildcards + και #) ή στο οποίο δημοσιεύει (Out: command topic — χωρίς wildcards). Επιλέξτε το από τη λίστα μετά το Scan broker, ή πληκτρολογήστε το. Η αποθηκευμένη διεύθυνση είναι <connection>:<topic>. |
| Scan broker | Παρακολουθεί τον broker για λίγα δευτερόλεπτα και παραθέτει τα topics που εντοπίστηκαν, το καθένα με το Last payload και ένδειξη retained. Με επιλεγμένο topic, ένα payload τύπου JSON εμφανίζει τα πεδία του στην ενότητα Pick the value this object should follow — με ένα κλικ συμπληρώνονται το JSON path, ο τύπος δεδομένων και τα tokens ON/OFF· ένα απλό payload προσφέρει την επιλογή Use the raw payload as |
| Payload format | Raw value (ολόκληρο το payload αποτελεί την τιμή) ή JSON με JSON path (state, sensor.temperature, values[0]). |
| ON token / OFF token | Δυαδικά αντικείμενα: τι γράφει και τι αναμένει η συσκευή για true/false (π.χ. ON / OFF). |
Publishing (αντικείμενα εξόδου)
| Πεδίο | Περιγραφή |
|---|---|
| Payload template | Προαιρετικό. Το {{value}} αντικαθίσταται από την τιμή· αφήστε το κενό για δημοσίευση της απλής τιμής. |
| QoS | Broker default, 0, 1 ή 2 — η εγγύηση παράδοσης για αυτήν την εντολή. |
| Retain published messages | Απενεργοποιημένο από προεπιλογή. Μια εντολή με retain εκτελείται εκ νέου κάθε φορά που επανασυνδέεται η συσκευή — διατηρείτε retain στην κατάσταση, όχι στις εντολές. |
Subscribing (αντικείμενα εισόδου)
| Πεδίο | Περιγραφή |
|---|---|
| Minimum interval (ms) | Η συχνότητα αποστολής για αισθητήρες με υψηλό ρυθμό δεδομένων περιορίζεται σε αυτό το όριο (προεπιλογή 100 ms)· η τελευταία τιμή παραδίδεται πάντα. Η τιμή 0 το απενεργοποιεί. |
| Scale / Offset | Αριθμητικά αντικείμενα: τιμή = raw × scale + offset στην είσοδο, το αντίστροφο κατά τη δημοσίευση. |
Τα πεδία αποθηκεύονται ως η συμβολοσειρά τύπου δεδομένων του αντικειμένου (π.χ. BOOL:PATH=state:ON=ON:OFF=OFF) — η σύνταξη, ο topic browser και ένα παράδειγμα εφαρμογής περιγράφονται στην παραπάνω ενότητα MQTT.
