Matter

Referência do driver Matter: as redes Wi-Fi e Thread em que os dispositivos entram, comissionamento por Bluetooth na Fabric local, o fluxo do Parear dispositivo, identidade do nó, as tags que vêm do dispositivo e o que escrever em cada uma faz.

O driver Matter lê equipamento Matter: sensores inteligentes, tomadas, luzes e dispositivos semelhantes certificados para o padrão Matter, entrem eles na rede por Wi-Fi ou por Thread. É um driver só para os dois. A rede é só o caminho de entrada: depois que o dispositivo está nela, o Ganter Lab o lê do mesmo jeito, pela rede local.

O Ganter Lab age como controlador Matter com Fabric local própria: ele comissiona cada dispositivo uma vez por Bluetooth Low Energy neste computador, entrega a ele as credenciais de uma rede cadastrada no cartão Redes do driver e, dali em diante, conversa com ele pela rede local: pelo seu roteador, no caso de um dispositivo Wi-Fi, e pelo seu Thread Border Router, no caso de um dispositivo Thread.

Você nunca diz ao Ganter Lab se um dispositivo é Wi-Fi ou Thread: o próprio dispositivo diz. Aberta a sessão pelo Bluetooth, o Ganter Lab lê do dispositivo em que tipo de rede ele entra, antes de escrever qualquer coisa nele, e para com uma mensagem própria quando a rede escolhida é do outro tipo.

Isso inverte a ordem usual de configuração. Um dispositivo Matter não começa por um host e uma porta: ele começa por uma cerimônia de pareamento, e só a identidade estável do nó comissionado é guardada depois.

O que você precisa ter antes de parear:

• Um adaptador Bluetooth Low Energy neste computador, ligado, com o Windows permitindo que o Ganter Lab o use.
• A rede em que o dispositivo vai entrar, cadastrada no cartão Redes: para um dispositivo Wi-Fi, o nome do Wi-Fi e a senha dele; para um dispositivo Thread, uma rede Thread existente com um Border Router, e o Active Operational Dataset completo dela. O Ganter Lab junta dispositivos à sua rede; ele não consegue inventar credenciais para ela.
• O código de configuração do dispositivo, impresso no dispositivo ou na embalagem, e o dispositivo em modo de pareamento.

Redes

O painel do driver Matter traz um cartão chamado Redes: as redes Wi-Fi e Thread em que os dispositivos entram, uma por linha. Uma rede é cadastrada uma vez, antes do primeiro dispositivo, e serve a todos os dispositivos pareados nela, então parear uma segunda lâmpada no mesmo Wi-Fi não pede nada de novo. O cartão só é desenhado para um papel que pode configurar o Connector, porque ele guarda os segredos das redes e não serve a nada além do pareamento.

A cabeça do cartão traz os comandos dele, nesta ordem:

A tabela mostra, de cada rede, o Nome, o Tipo de rede (Rede Wi-Fi ou Rede Thread) e o Estado: Pronta para parear, ou o que ainda falta à rede. Uma rede cujo nome ainda não foi escrito aparece como Rede sem nome.

Os campos da rede selecionada são editados ali mesmo, embaixo da tabela, e se salvam sozinhos. Um valor que as regras abaixo recusam não é gravado, e o campo diz por quê.

Duas coisas decidem se um dispositivo Wi-Fi pode ser pareado, e o cartão diz as duas ao lado dos campos:

• A maioria dos dispositivos só entra em redes de 2,4 GHz. Um roteador que anuncia o mesmo nome em 2,4 GHz e em 5 GHz serve; uma rede que só existe em 5 GHz não serve.
• Este computador e os dispositivos precisam estar na mesma rede local. Uma rede de visitantes, ou o isolamento de clientes ligado no roteador, impede o computador de achar os dispositivos depois que eles entram.

Uma rede só serve ao pareamento enquanto o segredo dela passa por essas regras: uma rede Wi-Fi com nome e senha válidos (vazia incluída), uma rede Thread com dataset válido.

Editar uma rede muda o que o próximo pareamento entrega, nunca o que um dispositivo já recebeu. Um dispositivo que precisa mudar de rede, ou cujo roteador ganhou senha nova, é resetado e pareado de novo.

O fluxo do Parear dispositivo

No driver Matter, a barra de ferramentas oferece Parear dispositivo onde os outros drivers oferecem Acrescentar dispositivo, e a entrada Matter do menu Novo… da coluna também. Enquanto nenhuma rede serve ao pareamento, ele continua desenhado e esmaecido, com a dica "Acrescente primeiro a rede em que o dispositivo vai entrar." Senão, ele abre um formulário:

Uma pasta do driver Matter oferece Novo dispositivo (na tabela Dispositivos dela, no menu de contexto dela e em Novo… > Matter > <Pasta>). Ele abre este mesmo formulário, esmaecido do mesmo jeito enquanto nenhuma rede serve, e o dispositivo pareado é arquivado naquela pasta.

O Parear dispositivo do formulário fica desabilitado até o nome e o código de configuração estarem preenchidos e alguma rede servir. Enquanto o pareamento roda, o formulário relata o estágio dele: Validar (conferindo o código e o segredo da rede), Encontrar (procurando o dispositivo por Bluetooth), Parear (autenticando com o código de configuração e lendo em que tipo de rede o dispositivo entra), Entrar na rede (enviando a rede ao dispositivo e depois perguntando por ele na rede local até ele responder; a linha de status diz se essa rede é Wi-Fi ou Thread), Salvar (abrindo a sessão segura com o dispositivo na rede local, concluindo o comissionamento dele e registrando o nó na Fabric local).

O Cancelar fica disponível enquanto o dispositivo físico ainda não foi alterado; assim que o comissionamento alterou o dispositivo, o botão passa a dizer que o Ganter Lab está finalizando com segurança, e o fluxo completa o registro em vez de abandonar um nó comissionado pela metade. Um pareamento roda por vez; uma segunda tentativa enquanto um está em andamento é recusada.

O dispositivo novo registra o nome da rede em que entrou, mostrado no campo Rede dele. Parear o próximo dispositivo na mesma rede pede só o nome e o código de configuração.

Quando o pareamento falha

Se o pareamento falha, a mensagem declara a causa e o que fazer:

Sempre que uma falha chega depois de o equipamento já ter sido comissionado, a mensagem diz isso e mostra o Node ID: o nó continua na Fabric e pode ser adicionado mais tarde com o Descobrir, assim que ele alcançar a rede. Não reinicie o dispositivo nesse caso; só uma mensagem que diz que nada foi salvo significa que o equipamento ficou intocado.

Um dispositivo que responde que não conseguiu entrar na rede é a exceção: ele não guarda nada que valha manter. O Ganter Lab encerra o pareamento no dispositivo, que descarta o que recebeu e volta na hora ao modo de pareamento, e tira o nó dele da Fabric, então a mensagem não traz Node ID e o Descobrir nunca lista um nó que não consegue responder. Corrija a rede e pareie de novo. Só um dispositivo que não deu resposta nenhuma mantém o nó, porque só se sabe se ele entrou quando ele aparece na rede local.

O que é guardado

A senha do Wi-Fi e o dataset nunca aparecem no diário, no endereço de um dispositivo nem na Thing Description dele. Redes e pareamento não são oferecidos a agentes pelo servidor MCP: o pareamento precisa de alguém junto do dispositivo, e as redes guardam segredos.

Identidade do nó

Um dispositivo pareado fica preso ao Node ID estável de 64 bits do equipamento, mostrado somente leitura no cartão Conexão dele como 16 dígitos hexadecimais, ao lado do estado do dispositivo. O nome de exibição editável é seu para mudar; o Node ID não é. Um dispositivo cuja identidade guardada não pode mais ser lida mostra Precisa de novo pareamento no lugar dele.

O painel do dispositivo também mostra um campo Rede somente leitura: o nome da rede em que o dispositivo entrou quando foi pareado. Um dispositivo pareado por uma versão que não o registrava diz que nada foi registrado. O campo é um registro, não uma configuração: editar ou remover essa rede no cartão Redes não muda nada no dispositivo.

Como a identidade é o Node ID, dispositivos Matter mantêm estado de conexão independente: desabilitar, excluir ou perder um nó não deixa outro indisponível, e excluir um dispositivo libera apenas o uso que ele fazia da sessão segura, e não remove o equipamento da Fabric local.

Descoberta

O Descobrir no driver Matter lista os nós já comissionados na Fabric local desta aplicação e lê, de cada um, os valores que ele publica. Para lê-los, abre uma sessão segura com cada nó, então um nó que está fora da rede continua listado, sem valores, depois que a sessão dele não consegue abrir. Os candidatos da descoberta carregam a identidade do nó e nenhum segredo de configuração. O fluxo geral de descoberta está descrito em Descoberta.

Os valores de um dispositivo configurado são comparados com as tags dele pela saída, pelo cluster e pelo atributo, nunca pelo nome: uma tag que você renomeou continua contando, e um valor nunca é acrescentado duas vezes.

A própria página do dispositivo oferece o mesmo sem sair dela: Descobrir tags, no cabeçalho do cartão Tags dele, lê só aquele nó e lista, marcados, os valores para os quais ele ainda não tem tag, com Acrescentar tags (veja Descobrir as tags de um dispositivo).

Tags

As tags de um dispositivo Matter vêm do próprio dispositivo: ninguém digita cluster nem número de atributo para elas. Um pareamento que dá certo segue direto para elas. O feed mostra "Dispositivo Matter 'Luz da cozinha' pareado.", a página abre no driver Matter, com o dispositivo novo destacado na tabela Dispositivos dele, e uma varredura só desse dispositivo roda na hora. O dispositivo que o pareamento criou aparece em Dispositivos descobertos com os valores que publica, todos marcados, e a varredura termina com "Marque os valores de 'Luz da cozinha' que vão virar tags e clique em Acrescentar tags." Desmarque o que você não quer e clique em Acrescentar tags; o feed então mostra "5 tags acrescentadas a 'Luz da cozinha'." Um dispositivo que ainda não respondeu não informa nada: "'Luz da cozinha' ainda não informou nenhum valor. Rode Descobrir de novo quando ele estiver online." O mesmo cartão volta a cada Descobrir seguinte, com os valores que o dispositivo ainda não tem como tag.

O Acrescentar tags só é desenhado para um papel com Configurar Connector. Ele fica acinzentado, com o motivo na dica, enquanto roda uma varredura ou um pareamento, enquanto a estação recusa mudanças e enquanto nada está marcado ("Marque ao menos um valor para acrescentar."). Um valor cuja saída, cluster e atributo o dispositivo já lê nunca é acrescentado de novo; quando todo valor marcado já está lá, nada é salvo: "'Luz da cozinha' já tem uma tag para cada valor marcado, então nada foi acrescentado." Um nome que outra tag do dispositivo já usa ganha um número depois dele, como em Brilho (2).

A varredura lê o que o dispositivo publica, do jeito que a especificação Matter organiza:

O que a varredura oferece, e com qual nome:

Uma tag oferecida como gravável chega com o acesso Leitura e escrita; todas as outras chegam Somente leitura.

Os valores que o driver conhece

O driver carrega uma tabela, tirada da especificação Matter, dos valores que ele conhece pelo nome e de como cada um muda. Um valor muda de um de três jeitos: um comando que o driver envia, que o dispositivo precisa listar entre os comandos que aceita; uma escrita do próprio atributo, quando a especificação o torna gravável e o dispositivo o lista; ou de jeito nenhum, para um valor que o dispositivo só informa.

A especificação envia temperaturas, umidade e pressão em unidades fixas: centésimos de grau Celsius, centésimos de por cento e décimos de quilopascal. A descoberta oferece esses valores já em °C, % e kPa: a tag chega com o fator no estágio Escala dela (0,01 para uma temperatura e uma umidade, 0,1 para uma pressão) e com a unidade, então um dispositivo que envia 2150 lê 21,5 °C. Uma escrita desfaz esse estágio antes de o valor sair, então um setpoint escrito como 21,5 chega ao dispositivo como 2150. A luminosidade é logarítmica (10000 × log10(lux) + 1), então nenhum fator a converte: ela lê o número que o dispositivo envia. Todo outro valor também lê como o dispositivo envia.

Fechaduras, cor por coordenadas X e Y, cenas, grupos e o comando Toggle não estão na tabela. Um dispositivo Matter também não tem comandos próprios: toda mudança é uma escrita numa das tags dele.

Escrever um valor

Uma tag Matter com acesso Leitura e escrita muda o dispositivo quando é escrita: pelo cartão Valor ao vivo dela, por um controle de dashboard, pela Logic ou por um agente. A escrita entra na fila do dispositivo como a de qualquer driver, na vez dela junto com as leituras do dispositivo, e a resposta é a do próprio dispositivo. O driver escolhe o comando Matter ou a escrita do atributo a partir da tabela; ninguém escolhe comando. Só o SUCCESS do dispositivo conta como escrito. Todo o resto é recusado, com um motivo:

Uma escrita recusada nunca é informada como escrita, nem como equipamento fora de alcance. Na página da tag, a linha de status mostra "Escrita recusada pelo equipamento: CONSTRAINT_ERROR, 0x87." quando o dispositivo recusou, com o motivo no lugar do status para uma recusa resolvida antes de qualquer envio, e "Escrita não confirmada: o equipamento não respondeu a tempo." quando nenhuma resposta veio; "A escrita falhou: não foi possível alcançar o equipamento." fica para um dispositivo que não está conectado. O motivo também viaja com a escrita: a linha do diário da escrita o nomeia, com o que o status quer dizer, e o tag_write de um agente o devolve.

Uma tag feita à mão

Para o valor raro que o dispositivo não publica de um jeito que a varredura ofereça, o Acrescentar tag num dispositivo Matter cria uma tag para preencher à mão. O cartão Origem dela mostra três campos numa linha, e a prévia do endereço embaixo deles os monta como <endpoint>/<cluster>/<attribute>, em decimal (1/8/0 é o brilho da primeira saída). Enquanto nenhum cluster é escolhido, a tag não é salva, e o painel diz: "Escolha o cluster que esta tag lê. Sem ele, nada é pedido ao dispositivo."

O nome da tag é livre: ele nomeia a tag e não seleciona nada no dispositivo. O tipo de dado é escolhido entre Boolean, Int32, UInt32, Float, Double e String; uma leitura que o tipo declarado não consegue representar lê como erro, e não como número de substituição. O valor chega como o dispositivo envia: uma temperatura, uma umidade ou uma pressão feita à mão lê em centésimos ou décimos até você dar a ela, no estágio Escala, o fator e a unidade da tabela acima.

O campo de acesso oferece escrita só onde a tabela do driver muda o valor; senão, oferece Somente leitura e diz embaixo por quê:

Quando uma edição da saída, do cluster ou do atributo aponta a tag para um valor que o driver não consegue escrever, o acesso dela volta a Somente leitura. Uma tag que a descoberta ofereceu mantém o acesso que a descoberta deu, porque só a descoberta pergunta ao dispositivo quais comandos ele aceita: um valor que o dispositivo não listou continua Somente leitura, e o campo continua oferecendo escrita.

Tags salvas por versões anteriores

Uma versão anterior nomeava o cluster de uma tag Matter só pelo nome da tag, com o endereço <endpoint>/<attribute>. Quando esta versão inicia pela primeira vez, toda tag de um dispositivo Matter cujo nome é um cluster do catálogo Matter (a parte depois dos últimos dois-pontos, sem os espaços em volta, maiúsculas ignoradas) recebe esse cluster, então continua lendo exatamente o valor que lia. O nome dela fica como estava, e a prévia do endereço passa a mostrar <endpoint>/<cluster>/<attribute>. Uma tag cujo nome não batia com nenhum cluster nunca leu nada: ela fica sem cluster, as leituras dela são recusadas com um motivo que diz isso, e a página dela pede o cluster. Uma tag convertida mantém o acesso que tinha, Somente leitura, o único que aquelas versões ofereciam; para escrevê-la, escolha Leitura e escrita, que funciona para os valores da tabela acima.