Matter Protocol Codec

C Struct Schema Usage Guide

The C Struct Schema mode allows you to define data structures using familiar C/C++ syntax. The parser extracts field names, types, and TLV tags from your struct definitions, then generates a visual form for easy data entry and TLV encoding.

Supported Syntax

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

Supported Data Types

Tag Annotation Methods

Use comments to specify TLV context tags for each field. If no tag is specified, tags are auto-assigned starting from 0.

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

Array Support

Fixed-size arrays (e.g., uint32_t data[4]) and variable-size arrays (e.g., uint8_t data[]) are supported. The form will provide an "Add Item" button for dynamic array element management.

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

Current Limitations

• Preprocessor directives (#define, #ifdef) are not supported
• typedef aliases (e.g., typedef uint8_t BYTE) are not supported
• Enums, unions, and bit-fields are not supported
• Nested struct editing is limited to one level
• Anonymous structs are not supported

Matter TLV Encoding Format

Matter uses a compact Tag-Length-Value (TLV) binary encoding scheme to serialize structured data. The format is used extensively across the protocol stack, including in Interaction Model messages, device attestation data, and commissioning payloads. Each TLV element consists of a control byte that encodes both the element type and tag form, followed by tag bytes (if any), length (for variable-length types), and the value payload.

Control Byte Structure

The control byte is the first byte of every TLV element. The lower 5 bits specify the element type, and the upper 3 bits indicate the tag form. This compact encoding allows single-byte representation for small values and tags.

TLV Element Types

The element type field determines how the value portion is encoded. Integer types use 1, 2, 4, or 8 bytes. Boolean values are encoded directly in the type field with no value bytes. Strings and byte arrays carry a length prefix followed by the data.

Onboarding Payload Format

When commissioning a new Matter device, the setup information is encoded in a compact payload embedded within a QR code or expressed as a numeric manual pairing code. The QR code payload begins with the prefix "MT:" followed by a Base38 encoded binary string containing the version, vendor ID, product ID, commissioning flow, discovery capabilities, discriminator, and setup passcode.

Base38 Encoding

Matter QR code payloads use a Base38 character set (0-9, A-Z, -.) for efficient alphanumeric representation. This encoding was chosen to fit within the constraints of QR code alphanumeric mode while maximizing data density. Every group of 3 bytes is encoded into 5 Base38 characters.

Manual Pairing Code

The 11-digit manual pairing code provides a fallback commissioning method when QR code scanning is unavailable. It encodes the discriminator (short form), setup passcode, and a Verhoeff check digit. The 21-digit version additionally includes the vendor ID and product ID for custom commissioning flows.

Verhoeff Check Digit

The manual pairing code uses the Verhoeff algorithm for error detection. This algorithm detects all single-digit errors and most adjacent transposition errors, making it well-suited for human-entered numeric codes.

Development Use Cases

• Debugging Matter TLV payloads captured from device interactions
• Inspecting Interaction Model request and response messages
• Verifying commissioning payloads embedded in QR codes
• Validating device attestation certificate TLV structures
• Building test payloads for Matter protocol conformance testing

Specification References

The Matter specification is maintained by the Connectivity Standards Alliance (CSA). The TLV encoding format is defined in the Core Specification Appendix A. Onboarding payload encoding is covered in Section 5.1.

• Matter Core Specification - Download from CSA
• Open Source Repository - github.com/project-chip/connectedhomeip
• SDK Documentation - project-chip.github.io/connectedhomeip-doc
• Matter Developer Handbook - handbook.buildwithmatter.com