Matter Protocol Codec

Anleitung zur Verwendung des C-Struct-Schemas

Der C-Struct-Schema-Modus ermöglicht es Ihnen, Datenstrukturen mit der vertrauten C/C++-Syntax zu definieren. Der Parser extrahiert Feldnamen, Typen und TLV-Tags aus Ihren Strukturdefinitionen und generiert dann ein visuelles Formular für die Dateneingabe und TLV-Kodierung.

Unterstützte Syntax

// Supported syntax forms:
typedef struct { ... } StructName;
typedef struct Tag { ... } StructName;
struct StructName { ... };

Unterstützte Datentypen

Methoden zur Tag-Annotation

Verwenden Sie Kommentare, um TLV-Kontext-Tags für jedes Feld anzugeben. Wenn kein Tag angegeben wird, werden Tags automatisch ab 0 zugewiesen.

uint8_t field1;     // tag 0
uint16_t field2;    // tag: 1
uint32_t field3;    /* tag 2 */
@tag(3) uint64_t field4;

Array-Unterstützung

Arrays mit fester Größe (z.B. uint32_t data[4]) und Arrays mit variabler Größe (z.B. uint8_t data[]) werden unterstützt. Das Formular bietet eine Schaltfläche «Element hinzufügen» für die dynamische Verwaltung von Array-Elementen.

uint32_t subjects[4];  // Fixed-size array (max 4 items)
uint8_t data[];        // Variable-size array

Aktuelle Einschränkungen

• Präprozessor-Direktiven (#define, #ifdef) werden nicht unterstützt
• typedef-Aliase (z.B. typedef uint8_t BYTE) werden nicht unterstützt
• Enums, Unions und Bitfelder werden nicht unterstützt
• Die Bearbeitung verschachtelter Strukturen ist auf eine Ebene beschränkt
• Anonyme Strukturen werden nicht unterstützt

Matter TLV-Kodierungsformat

Matter verwendet ein kompaktes TLV (Tag-Length-Value) Binärkodierungsschema zur Serialisierung strukturierter Daten. Das Format wird im gesamten Protokollstapel verwendet, einschließlich Interaction-Model-Nachrichten, Geräteattestierungsdaten und Inbetriebnahme-Payloads.

Kontrollbyte-Struktur

Das Kontrollbyte ist das erste Byte jedes TLV-Elements. Die unteren 5 Bits geben den Elementtyp an und die oberen 3 Bits kennzeichnen die Tag-Form.

TLV-Elementtypen

Das Elementtyp-Feld bestimmt die Kodierung des Werteteils. Ganzzahltypen verwenden 1, 2, 4 oder 8 Bytes. Boolesche Werte werden direkt im Typ-Feld kodiert. Strings und Byte-Arrays tragen ein Längenpräfix gefolgt von den Daten.

Onboarding-Payload-Format

Bei der Inbetriebnahme eines Matter-Geräts werden die Setup-Informationen in einem kompakten Payload kodiert, der in einen QR-Code eingebettet oder als numerischer manueller Kopplungscode dargestellt wird. Der QR-Code-Payload beginnt mit dem Präfix MT:" gefolgt von einem Base38-kodierten Binärstring.

Base38-Kodierung

Matter QR-Code-Payloads verwenden einen Base38-Zeichensatz (0-9, A-Z, -.) für effiziente alphanumerische Darstellung. Jeweils 3 Bytes werden in 5 Base38-Zeichen kodiert.

Manueller Kopplungscode

Der 11-stellige manuelle Kopplungscode bietet eine Alternative, wenn QR-Code-Scannen nicht verfügbar ist. Er kodiert den Diskriminator, den Setup-Passcode und eine Verhoeff-Prüfziffer. Die 21-stellige Version enthält zusätzlich Hersteller-ID und Produkt-ID.

Verhoeff-Prüfziffer

Der manuelle Kopplungscode verwendet den Verhoeff-Algorithmus zur Fehlererkennung. Dieser Algorithmus erkennt alle Einzelziffernfehler und die meisten benachbarten Transpositionsfehler.

Entwicklungs-Anwendungsfälle

• Debugging von Matter TLV-Payloads aus Geräteinteraktionen
• Inspektion von Interaction-Model-Anfrage- und Antwortnachrichten
• Überprüfung von in QR-Codes eingebetteten Inbetriebnahme-Payloads
• Validierung von TLV-Strukturen in Geräteattestierungszertifikaten
• Erstellung von Testpayloads für Matter-Protokoll-Konformitätstests

Spezifikationsreferenzen

Die Matter-Spezifikation wird von der Connectivity Standards Alliance (CSA) gepflegt. Das TLV-Kodierungsformat ist in Anhang A der Kernspezifikation definiert. Die Onboarding-Payload-Kodierung wird in Abschnitt 5.1 behandelt.

• Matter-Kernspezifikation - Von CSA herunterladen
• Open-Source-Repository - github.com/project-chip/connectedhomeip
• SDK-Dokumentation - project-chip.github.io/connectedhomeip-doc
• Matter-Entwicklerhandbuch - handbook.buildwithmatter.com