Codec Matter Protocol

Guia de uso do esquema C Struct

O modo de esquema C Struct permite definir estruturas de dados usando a sintaxe familiar de C/C++. O analisador extrai nomes de campos, tipos e tags TLV das suas definições de estrutura, e então gera um formulário visual para entrada de dados e codificação TLV.

Sintaxe suportada

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

Tipos de dados suportados

Métodos de anotação de tags

Use comentários para especificar tags de contexto TLV para cada campo. Se nenhuma tag for especificada, as tags serão atribuídas automaticamente a partir de 0.

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

Suporte a arrays

Arrays de tamanho fixo (ex: uint32_t data[4]) e arrays de tamanho variável (ex: uint8_t data[]) são suportados. O formulário fornecerá um botão «Adicionar item» para gerenciamento dinâmico de elementos do array.

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

Limitações atuais

• Diretivas de pré-processador (#define, #ifdef) não são suportadas
• Aliases typedef (ex: typedef uint8_t BYTE) não são suportados
• Enums, unions e campos de bits não são suportados
• A edição de estruturas aninhadas é limitada a um nível
• Estruturas anônimas não são suportadas

Formato de codificação TLV Matter

Matter utiliza um esquema de codificação binária TLV (Tag-Length-Value) compacto para serializar dados estruturados. O formato é usado extensivamente na pilha de protocolo, incluindo mensagens do modelo de interação, dados de atestação de dispositivos e payloads de comissionamento.

Estrutura do byte de controle

O byte de controle é o primeiro byte de cada elemento TLV. Os 5 bits inferiores especificam o tipo de elemento e os 3 bits superiores indicam a forma do tag.

Tipos de elementos TLV

O campo de tipo de elemento determina como a parte do valor é codificada. Tipos inteiros usam 1, 2, 4 ou 8 bytes. Valores booleanos são codificados diretamente no campo de tipo. Strings e arrays de bytes carregam um prefixo de comprimento seguido dos dados.

Formato do payload de integração

Ao comissionar um dispositivo Matter, as informações de configuração são codificadas em um payload compacto incorporado em um QR code ou expresso como código de emparelhamento manual numérico. O payload QR code começa com o prefixo "MT:" seguido de uma string binária codificada em Base38.

Codificação Base38

Os payloads QR code Matter usam um conjunto de caracteres Base38 (0-9, A-Z, -.) para representação alfanumérica eficiente. Cada grupo de 3 bytes é codificado em 5 caracteres Base38.

Código de emparelhamento manual

O código de emparelhamento manual de 11 dígitos fornece um método alternativo quando a leitura do QR não está disponível. Codifica o discriminador, o código de configuração e um dígito de verificação Verhoeff. A versão de 21 dígitos inclui adicionalmente o ID do fabricante e o ID do produto.

Dígito de verificação Verhoeff

O código de emparelhamento manual utiliza o algoritmo Verhoeff para detecção de erros. Este algoritmo detecta todos os erros de um dígito e a maioria dos erros de transposição adjacente.

Casos de uso em desenvolvimento

• Depuração de payloads TLV Matter capturados de interações de dispositivos
• Inspeção de mensagens de solicitação e resposta do modelo de interação
• Verificação de payloads de comissionamento incorporados em QR codes
• Validação de estruturas TLV de certificados de atestação
• Construção de payloads de teste para testes de conformidade Matter

Referências de especificação

A especificação Matter é mantida pela Connectivity Standards Alliance (CSA). O formato de codificação TLV é definido no Apêndice A da especificação principal. A codificação de payload de integração é coberta na Seção 5.1.

• Especificação Core do Matter - Baixar do CSA
• Repositório Open Source - github.com/project-chip/connectedhomeip
• Documentação do SDK - project-chip.github.io/connectedhomeip-doc
• Manual do Desenvolvedor Matter - handbook.buildwithmatter.com