Τεκμηρίωση Matter Cluster

Τι είναι το Matter;

Το Matter είναι ένα πρότυπο διαλειτουργικότητας έξυπνων συσκευών. Αντί κάθε κατασκευαστής να επινοεί ένα εντελώς διαφορετικό μοντέλο δεδομένων συσκευής, το Matter ορίζει μια κοινή δομή ώστε controllers, εφαρμογές, hubs και cloud συστήματα να μπορούν να κατανοούν τις συσκευές με προβλέψιμο τρόπο.

Τα σημαντικότερα δομικά στοιχεία είναι:

• Node: ολόκληρη η φυσική συσκευή στο δίκτυο.
• Endpoint: ένα λειτουργικό τμήμα της συσκευής. Ένα φυσικό προϊόν μπορεί να εκθέτει πολλαπλά endpoints.
• Cluster: μια ομάδα σχετικών λειτουργιών ή ιδιοτήτων. Σκεφτείτε ένα cluster ως μια θεματική περιοχή, όπως Door Lock, Battery ή Temperature Measurement.
• Attribute: μία συγκεκριμένη τιμή μέσα σε ένα cluster, όπως LockState ή BatVoltage.
• Command: μια ενέργεια που μπορείτε να στείλετε σε ένα cluster, όπως lock/unlock για μια συσκευή κλειδαριάς.

Πώς να διαβάσετε τον πίνακα

• Το Endpoint σας λέει σε ποιο λειτουργικό τμήμα της συσκευής ανήκει η γραμμή.
• Το Cluster δίνει το ανθρώπινα αναγνώσιμο όνομα του cluster ακολουθούμενο από το αριθμητικό του ID σε παρενθέσεις, για παράδειγμα Basic Information (40).
• Το Attribute είναι η ακριβής ιδιότητα που εκθέτει το cluster.
• Το Path χρησιμοποιεί τη μορφή endpoint/cluster/attribute και εμφανίζεται ως inline code.

Λεπτομερής σημασία, σημασιολογία τιμών και παραδείγματα για κάθε attribute υπάρχουν στις αναπτυσσόμενες κάρτες κάτω από κάθε πίνακα.

Σημαντική σημείωση για αρχάριους

Ένα cluster δεν είναι το ίδιο πράγμα με έναν τύπο συσκευής.

Για παράδειγμα, το cluster Boolean State δίνει μόνο μια τιμή true/false. Αυτή η τιμή μπορεί να σημαίνει πολύ διαφορετικά πράγματα ανάλογα με τον τύπο συσκευής του endpoint:

• για έναν αισθητήρα επαφής (contact sensor), μπορεί να σημαίνει ανοιχτό/κλειστό
• για έναν αισθητήρα διαρροής (leak sensor), μπορεί να σημαίνει διαρροή/χωρίς διαρροή

Έτσι τα δεδομένα Matter πρέπει πάντα να ερμηνεύονται χρησιμοποιώντας και τα δύο:

1. το cluster και το attribute
2. το πλαίσιο του ρόλου / τύπου συσκευής του endpoint

Δεδομένα πληροφοριών συσκευής

Αυτή η ενότητα τεκμηριώνει τιμές που αναφέρονται από τα clusters συσκευών Matter. Αυτά τα πεδία είναι attributes δεδομένων που χρησιμοποιούνται για inventory, state shadows, διαγνωστικά, κατάσταση τροφοδοσίας και μετρήσεις αισθητήρων. Δεν είναι εντολές.

Πληροφορίες root συσκευής / συστήματος

Αυτές οι γραμμές περιγράφουν τη συνολική ταυτότητα της συσκευής και πληροφορίες διαγνωστικών/διαχείρισης δικτύου. Είναι σημαντικές για inventory, troubleshooting και υποστήριξη, αλλά δεν ελέγχουν άμεσα την κύρια λειτουργία κλειδαριάς που βλέπει ο χρήστης.

Λεπτομέρειες πεδίων

VendorName — Ανθρώπινα αναγνώσιμο όνομα κατασκευαστή. Παράδειγμα: "SmartphoneKey Systems Inc". Τιμή string. Δεν είναι enum. Είναι το όνομα εμφάνισης του κατασκευαστή που αναφέρει η συσκευή, οπότε διαφορετικοί κατασκευαστές επιστρέφουν διαφορετικό κείμενο.

ProductName — Ανθρώπινα αναγνώσιμο όνομα προϊόντος. Παράδειγμα: "SmartphoneKey Reader". Τιμή string. Είναι το όνομα εμφάνισης προϊόντος/μοντέλου που εκθέτει το node, όχι enum τύπου συσκευής.

HardwareVersionString — String έκδοσης hardware. Παράδειγμα: "release". Τιμή string. Συνήθως μια ανθρώπινα αναγνώσιμη αναθεώρηση hardware, αναθεώρηση πλακέτας ή ετικέτα έκδοσης. Αντιμετωπίστε το ως κείμενο που ορίζεται από τον κατασκευαστή.

SoftwareVersionString — String έκδοσης λογισμικού/firmware. Παράδειγμα: "1.26.1+1". Τιμή string. Συνήθως έκδοση firmware/λογισμικού. Χρησιμοποιήστε το ως κείμενο, επειδή οι κατασκευαστές μπορεί να περιλαμβάνουν semantic versions, build metadata ή προσαρμοσμένες ετικέτες.

ManufacturingDate/DateCode — Ημερομηνία κατασκευής ή date code που παρέχει η συσκευή. Παράδειγμα: "20250903". Τιμή string/date-code. Η μορφή παρέχεται από τον κατασκευαστή. Σε αυτό το export μοιάζει με YYYYMMDD, αλλά μην υποθέσετε ότι όλες οι συσκευές χρησιμοποιούν την ίδια μορφή.

SerialNumber — String σειριακού αριθμού. Παράδειγμα: "11064672519639222187". Τιμή string. Φυσικός σειριακός αριθμός. Μπορεί να φαίνεται αριθμητικός αλλά θα πρέπει να αποθηκεύεται ως κείμενο για να μη χαθούν αρχικά μηδενικά ή η μορφοποίηση.

VendorID — Αναγνωριστικό κατασκευαστή. Παράδειγμα: 4619. Αριθμητικό αναγνωριστικό κατασκευαστή που αποδίδεται μέσω της διαδικασίας vendor ID του Matter/CSA. Αποθηκεύστε το ως αριθμό, αλλά η εμφάνιση σε δεκαεξαδική μορφή (hex) μπορεί επίσης να είναι χρήσιμη για engineering logs.

ProductURL — URL προϊόντος αν υλοποιείται. Παράδειγμα: "". Τιμή URL (string) όταν υλοποιείται. Το κενό string σημαίνει ότι η συσκευή δεν παρείχε URL προϊόντος/υποστήριξης.

UpTime — Τρέχον uptime. Παράδειγμα: 588758. Αριθμητική διάρκεια σε δευτερόλεπτα. Σημαίνει ότι η συσκευή είναι σε λειτουργία για 588.758 δευτερόλεπτα από την τελευταία εκκίνηση. Μια ξαφνική χαμηλή τιμή συνήθως σημαίνει ότι το node επανεκκινήθηκε πρόσφατα.

TotalOperationalHours — Συνολικές ώρες λειτουργίας. Παράδειγμα: 163. Αριθμητική διάρκεια σε ώρες. Σημαίνει ότι η συσκευή αναφέρει 163 συνολικές ώρες λειτουργίας. Αυτή η τιμή είναι αθροιστική αν η συσκευή τη διατηρεί (persists).

BootReason — Λόγος της πιο πρόσφατης εκκίνησης. Παράδειγμα: 6. Τιμή enum. Συνηθισμένες σημασίες Matter περιλαμβάνουν 0 = Unspecified, 1 = PowerOnReboot, 2 = BrownOutReset, 3 = SoftwareWatchdogReset, 4 = HardwareWatchdogReset, 5 = SoftwareUpdateCompleted, 6 = SoftwareReset. Εδώ το 6 σημαίνει reset/reboot που ενεργοποιήθηκε από λογισμικό.

NeighborTable — Καταχωρήσεις πίνακα γειτόνων (neighbor table). Παράδειγμα: [{"averageRssi": -25, ...}] ή απλοποιημένα ως [-25]. Τιμή πίνακα/λίστας. Κάθε καταχώρηση περιγράφει έναν γείτονα Thread. Οι τιμές RSSI είναι κανονικά αρνητικά dBm: όσο πιο κοντά στο 0, τόσο ισχυρότερο· γύρω στο -25 είναι πολύ ισχυρό, -50 είναι καλό, -70 είναι αδύναμο.

RoutingRole — Τρέχων ρόλος δρομολόγησης Thread. Παράδειγμα: 6. Τιμή enum που περιγράφει τον ρόλο Thread. Τυπικές τιμές είναι καταστάσεις τύπου ρόλου όπως disabled, detached, child/end device, router, leader ή ρόλος με δυνατότητα border-router, ανάλογα με την υλοποίηση/έκδοση προδιαγραφής. Χρησιμοποιήστε το κυρίως για διαγνωστικά, όχι ως business state.

NetworkName — Όνομα δικτύου Thread. Παράδειγμα: "OpenThread-952e". Τιμή string. Όνομα δικτύου Thread. Θα πρέπει να ταιριάζει με το αναμενόμενο Thread mesh αν η συσκευή συνδέθηκε στο σωστό δίκτυο.

RSSI — Δείκτης ισχύος λαμβανόμενου σήματος (Received signal strength indicator). Παράδειγμα: nan. Αριθμητικό RSSI σε dBm όταν αναφέρεται. Το RSSI του Wi-Fi είναι συνήθως αρνητικό: όσο πιο κοντά στο 0, τόσο ισχυρότερο. nan, null ή απουσία συνήθως σημαίνει ότι δεν χρησιμοποιείται Wi-Fi ή ότι η συσκευή δεν το αναφέρει.

IdleModeDuration — Διάρκεια idle mode για συμπεριφορά ICD. Παράδειγμα: 300. Αριθμητική διάρκεια σε δευτερόλεπτα. Για συσκευές ICD αυτό είναι το διάστημα idle-mode όπου η συσκευή μπορεί να κοιμάται ή να είναι λιγότερο άμεσα προσβάσιμη.

ActiveModeDuration — Διάρκεια active mode για συμπεριφορά ICD. Παράδειγμα: 300. Αριθμητική διάρκεια σε milliseconds στους ορισμούς Matter ICD. Περιγράφει για πόσο μένει η συσκευή σε active mode μετά από wake/active συμπεριφορά πριν επιστρέψει σε idle.

ActiveModeThreshold — Κατώφλι για είσοδο σε active mode. Παράδειγμα: 300. Αριθμητικό κατώφλι σε milliseconds. Χρησιμοποιείται από τη συμπεριφορά ICD για να αποφασίσει τον χρονισμό/απόκριση του active-mode. Μεγαλύτερες τιμές συνήθως κρατούν τη συσκευή responsive για περισσότερο, αλλά μπορεί να επηρεάσουν τη μπαταρία.

UserActiveModeTriggerHint — Hint που περιγράφει πώς να ενεργοποιηθεί το active mode. Παράδειγμα: 4381. Τιμή bitmap/bitmask. Κάθε bit υπαινίσσεται μια πιθανή ενέργεια χρήστη που μπορεί να ξυπνήσει ή να ενεργοποιήσει τη συσκευή. Αποκωδικοποιήστε το ως flags, όχι ως έναν απλό αριθμό. Συνδυάστε το με το UserActiveModeTriggerInstruction για ανθρώπινα αναγνώσιμες οδηγίες.

UserActiveModeTriggerInstruction — Κείμενο οδηγιών για active mode που ενεργοποιεί ο χρήστης. Παράδειγμα: "Restart the application". Τιμή string. Ανθρώπινα αναγνώσιμη οδηγία για το πώς ένας χρήστης μπορεί να ενεργοποιήσει το active mode. Είναι κείμενο άμεσα εμφανίσιμο αν χρειαστεί.

Door lock / έλεγχος πρόσβασης

Αυτές οι γραμμές περιγράφουν τη συμπεριφορά ελέγχου πρόσβασης της συσκευής. Αυτή είναι η πιο κρίσιμη για τη λειτουργία (business-critical) ομάδα για όσους εργάζονται με λογική εισόδου από πόρτα, credentials, απομακρυσμένες λειτουργίες και συμπεριφορά φυσικής ασφάλειας.

Μπαταρία / πηγή τροφοδοσίας

Αυτές οι γραμμές περιγράφουν πώς τροφοδοτείται η συσκευή και αν μπορεί να χρειάζεται συντήρηση. Αυτό είναι ιδιαίτερα σημαντικό για ομάδες υποστήριξης πεδίου και για πλατφόρμες που χρειάζεται να εμφανίζουν την υγεία της μπαταρίας.

Αισθητήρας υγρασίας

Αυτές οι γραμμές δείχνουν δεδομένα περιβαλλοντικής μέτρησης υγρασίας. Παρόλο που το κύριο προϊόν είναι μια συσκευή προσανατολισμένη σε reader/lock, αυτό το export εκθέτει επίσης πληροφορίες μέτρησης υγρασίας σε ένα endpoint.

MeasuredValue — Τρέχουσα μετρούμενη τιμή σχετικής υγρασίας. Παράδειγμα: 3011. Αριθμητική μετρούμενη υγρασία σε εκατοστά του τοις εκατό. Μετατρέψτε με value / 100, οπότε το 3011 σημαίνει 30.11% RH.

Αισθητήρας κατοίκησης / παρουσίας

Αυτές οι γραμμές δείχνουν αν το endpoint ανιχνεύει αυτή τη στιγμή κατοίκηση ή παρουσία. Αυτό χρησιμοποιείται συνήθως από συστήματα αυτοματισμού και παρακολούθησης παρά από βασικές ροές κλειδαριάς.

Occupancy — Τρέχουσα κατάσταση κατοίκησης/παρουσίας. Παράδειγμα: 0. Τιμή bitmap. Το bit 0 υποδεικνύει ότι ανιχνεύθηκε κατοίκηση/παρουσία. 0 σημαίνει ότι δεν ανιχνεύθηκε κατοίκηση· 1 σημαίνει ότι ανιχνεύθηκε. Μελλοντικά/πρόσθετα bits μπορεί να αναπαριστούν περισσότερους τρόπους ανίχνευσης.

Ερμηνεία αισθητήρα επαφής (contact sensor)

Αυτή η ενότητα απομονώνει τη γραμμή Boolean State που τεκμηριώνεται ως ερμηνεία τύπου αισθητήρα επαφής/πόρτας. Έχει διαχωριστεί σκόπιμα για να δείξει ότι το Boolean State χρειάζεται το πλαίσιο του τύπου συσκευής.

StateValue — Δυαδική τιμή κατάστασης. Για αυτόν τον αισθητήρα πόρτας αντιστοιχίζεται σε κατάσταση επαφής ανοιχτό/κλειστό. Παράδειγμα: true. Τιμή boolean. Για ένα endpoint αισθητήρα επαφής, αντιστοιχίστε με το πλαίσιο του endpoint: συνήθως true = ανοιχτό/επαφή ενεργή, false = κλειστό/ανενεργό, αλλά επαληθεύστε με τη συγκεκριμένη συμπεριφορά της συσκευής.

Ερμηνεία αισθητήρα διαρροής νερού (water leak sensor)

Αυτή η ενότητα απομονώνει τη γραμμή Boolean State που τεκμηριώνεται ως ερμηνεία διαρροής νερού. Έχει διαχωριστεί σκόπιμα για να δείξει ότι το ίδιο cluster Boolean State μπορεί να αναπαριστά μια εντελώς διαφορετική πραγματική συνθήκη.

Αισθητήρας θερμοκρασίας

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

MeasuredValue — Τρέχουσα μετρούμενη τιμή θερμοκρασίας. Παράδειγμα: 2591. Αριθμητική μετρούμενη θερμοκρασία σε εκατοστά του βαθμού Κελσίου. Μετατρέψτε με value / 100, οπότε το 2591 σημαίνει 25.91 °C.

Υποστηριζόμενες εντολές

Αυτή η ενότητα τεκμηριώνει τις δυνατότητες εντολών. Αυτά τα πεδία περιγράφουν τι μπορεί να δεχτεί η συσκευή ως ενέργειες. Στο Matter, η υποστήριξη εντολών κανονικά ανακαλύπτεται από το global attribute AcceptedCommandList, με μορφή path endpoint/cluster/65529.

Χρησιμοποιήστε αυτή την ενότητα ξεχωριστά από τα Δεδομένα πληροφοριών συσκευής:

• Δεδομένα πληροφοριών συσκευής = attributes που αναφέρει η συσκευή, για παράδειγμα 0/40/1, 1/257/0 ή 1/47/12.
• Υποστηριζόμενες εντολές = ενέργειες που δέχεται η συσκευή/cluster, για παράδειγμα LockDoor, UnlockDoor, GetUser ή γενικές εντολές commissioning.

Πεδία δυνατότητας εντολών Matter

Το Matter εκθέτει τη δυνατότητα εντολών μέσω global attributes cluster. Στη μορφή endpoint/cluster/attribute, τα σημαντικότερα paths δυνατότητας-εντολών είναι:

Παράδειγμα path: 0/49/65529 σημαίνει endpoint 0, cluster 49, attribute 65529. Αυτό σας λέει ποιες εντολές δέχεται το cluster Network Commissioning στο endpoint 0.

Γενικές εντολές endpoint 0 για όλους τους τύπους συσκευών Matter

Το endpoint 0 είναι το root/system endpoint. Αυτές οι εντολές δεν είναι ειδικές για κλειδαριές. Είναι κοινές δυνατότητες συστήματος, commissioning, διαγνωστικών, ασφάλειας και διαχείρισης fabric του Matter. Οποιοσδήποτε τύπος συσκευής μπορεί να εκθέτει ορισμένα από αυτά τα clusters ανάλογα με το τι υποστηρίζει.

Για την υλοποίηση bridge, αυτές οι λίστες εντολών του endpoint 0 θα πρέπει συνήθως να αντιμετωπίζονται ως δυνατότητες συστήματος. Είναι χρήσιμες για commissioning, διαγνωστικά, ρύθμιση δικτύου και διαχείριση fabric, αλλά δεν θα πρέπει να εκτίθενται ως κανονικές εντολές χρήστη όπως lock/unlock, ανάγνωση θερμοκρασίας ή κατάσταση διαρροής.

Υποστηριζόμενες εντολές του cluster Door Lock

Το cluster Door Lock έχει ένα σύνολο εντολών για λειτουργία κλειδαριάς, διαχείριση user/PIN/RFID, schedules, credentials, logs και ρύθμιση Aliro reader. Σημαντικό: μια πραγματική κλειδαριά μπορεί να υποστηρίζει μόνο ένα υποσύνολο αυτών των εντολών. Για να μάθετε τι υποστηρίζει μία ακριβώς συσκευή, διαβάστε το τυπικό global attribute AcceptedCommandList για το cluster 257 στο endpoint της κλειδαριάς, για παράδειγμα path 1/257/65529 όταν χρησιμοποιείτε τη μορφή endpoint/cluster/attribute.

Για χρήση python-matter-server / bridge, οι εντολές κανονικά στέλνονται στο cluster 257 στο endpoint της κλειδαριάς, συνήθως το endpoint 1. Στο payload σας AWS IoT, το bridge θα πρέπει να αναλύσει (resolve) device_uuid -> node_id, και μετά να στείλει την εντολή με node_id, endpoint_id, όνομα εντολής cluster, και ορίσματα ειδικά για την εντολή.

Έλεγχος υποστήριξης εντολών Door Lock

Η υποστήριξη εντολών Door Lock είναι ξεχωριστή από τις γενικές εντολές συστήματος του endpoint 0 παραπάνω. Μην υποθέσετε ότι κάθε κλειδαριά Matter υποστηρίζει κάθε εντολή που παρατίθεται παραπάνω. Ο πρακτικός έλεγχος υποστήριξης είναι:

Αντιστοίχιση τύπων συσκευών Matter

Πηγή αλήθειας (Source of Truth)

Οι τύποι συσκευών Matter διαβάζονται από το cluster Matter Descriptor:

<endpoint>/29/0

Όπου:

29 = Descriptor cluster
0  = DeviceTypeList attribute

Το python-matter-server επιστρέφει την τιμή σε δεκαδική μορφή:

"1/29/0": [
  {
    "0": 21,
    "1": 1
  }
]

Σημασία:

"0" = Matter Device Type ID
"1" = Device Type Revision

Το επίσημο data model του Matter SDK δημοσιεύει τον χάρτη device type ID του Matter 1.5 στο connectedhomeip/data_model/1.5/device_types/device_type_ids.json.

Πηγή:

• https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.5/device_types/device_type_ids.json

Κανόνες Bridge

Shadow device_info

Το shadow device_info αποθηκεύει τον αριθμητικό τύπο συσκευής Matter κάτω από το πραγματικό Matter path.

Παράδειγμα για Contact Sensor:

{
  "1/29/0": 21
}

Μην γράφετε αυτό το προσαρμοσμένο πεδίο στο device_info:

{
  "device_type": "contact_sensor"
}

Κανόνες σύνθετων αισθητήρων (Composite Sensor)

Ορισμένες φυσικές συσκευές εκθέτουν πολλαπλά endpoints αισθητήρων.

Παράδειγμα:

770 = Temperature Sensor
775 = Humidity Sensor

Το bridge τα συνδυάζει σε:

temperature_humidity_sensor

Το shadow device_info εξακολουθεί να αποθηκεύει μόνο ένα επιλεγμένο αριθμητικό Matter path, για παράδειγμα:

{
  "1/29/0": 770
}

Αλλά ο εσωτερικός τύπος bridge και το AWS IoT Thing Type γίνονται:

temperature_humidity_sensor

Πλήρης λίστα τύπων συσκευών Matter