Native Device: formato da mensagem

Cada mensagem Native Device é uma linha de texto com sete partes, marcadas pelos separadores $, >, @, ?, < e #.

Formato

$6A6F>/ac/rs@0?r0=off&r1=off&_to=192.168.0.10<99999# — Dispositivo: $6A6F, Ação: >/ac/rs, Protocolo: @0, Valores: ?r0=off&r1=off, Destino: &_to=192.168.0.10, Sequência: <99999, Fim: #$6A6F>/ac/rs@0?r0=off&r1=off&_to=192.168.0.10<99999#

Parte	Descrição
$6A6F	ID do equipamento que recebe a mensagem: os 4 últimos caracteres do endereço MAC, em letras maiúsculas (está na etiqueta). O ID 0000 endereça todos os equipamentos da rede ao mesmo tempo, e cada um responde com o próprio ID.
>/ac/rs	Ação (caminho) a executar ou consultar. Veja a lista de ações.
@0	Número do protocolo: o que fazer com a ação. Veja a tabela de protocolos.
?r0=off&r1=off	Parâmetros, no formato nome=valor, separados por &. Sem parâmetros, a consulta devolve todos os valores da ação.
&_to=192.168.0.10	Opcional: IP de quem envia a mensagem, para a resposta. Coloque-o por último: ?r0=off&_to=192.168.0.10, ou ?_to=192.168.0.10 quando não há outros. Veja os parâmetros de controle.
<99999	Número de sequência. Veja número de sequência.
#	Fim da mensagem.

Os separadores são obrigatórios, mesmo com o campo vazio: uma mensagem sem parâmetros ainda leva o ?.

Parâmetros de controle

Parâmetros que começam com _ não são dados da ação: eles controlam a mensagem. Vão na parte dos valores, junto dos outros parâmetros.

Parâmetro	Para que serve
_to	IP de quem envia a mensagem. O equipamento manda a resposta para esse IP. Veja para onde vai a resposta.
_n	Índice do item, nas ações que guardam vários itens: a zona em /lb/Zona do LOUD, o botão em /lb/buttons, o item de cena em /cs/btN. Nas cenas de botão, as ações de clique usam _n = 0, 1, 2…, e as de segurar usam -1, -2, -3…
_ts	Data e hora da última alteração, em segundos desde 1º de janeiro de 1970 (UTC). Vai junto quando você grava uma configuração. O equipamento guarda o valor e o devolve quando você consulta a configuração.
_su	Nas ações /aa/*: identificador livre, de até 8 caracteres. O equipamento guarda e devolve o valor. Ele não muda o envio.

A descrição também lista parâmetros com _. Eles seguem as mesmas regras, e os aplicativos não os mostram como saídas.

Número de sequência

O número de sequência vem entre < e #. Use um número diferente em cada mensagem. O equipamento ignora uma mensagem cuja sequência ele já recebeu há pouco: assim, a mesma mensagem que chega por UDP e por TCP só é executada uma vez.

O valor 0 desliga essa verificação: o equipamento executa todas as cópias. Não use 0 em comandos.

A resposta traz um número de sequência próprio, diferente do pedido. Para saber a que pedido uma resposta corresponde, compare o ID, a ação, o protocolo e o _n.

Protocolos

Protocolo	Nome	Descrição
@0	Set Data	Consulta valores (sem parâmetros) ou grava valores (com parâmetros).
@1	Delete Data	Apaga itens de uma ação, como os itens de cena de um botão. Veja Delete Data.
@6	Get All	Lê todos os itens de uma ação de uma vez. Veja Get All.
@8	Send All	Envia a mesma mensagem a vários equipamentos ao mesmo tempo. Veja Send All.
@9	Description	Pede ao equipamento a descrição das ações e dos parâmetros que ele oferece. Veja Descrição.

@1 Delete Data

Para apagar itens de cena de um botão, envie @1 com o _n do primeiro item a apagar. Exemplo: apagar do terceiro item de clique em diante, no botão 0.

$72B0>/cs/bt0@1?_n=2&_ts=1760900000<48213# — Dispositivo: $72B0, Ação: >/cs/bt0, Protocolo: @1, Valores: ?_n=2&_ts=1760900000, Sequência: <48213, Fim: #$72B0>/cs/bt0@1?_n=2&_ts=1760900000<48213#

• Com _n igual a 0 ou maior, o equipamento apaga as ações de clique desse índice em diante.
• Com _n negativo, apaga as ações de segurar desse índice em diante (-2 apaga -2, -3…).

A resposta traz status=OK quando deu certo:

$72B0>/cs/bt0@1?code=0000&status=OK&_n=2<90311#

@6 Get All

Para ler todos os itens de uma ação que guarda vários itens, envie @6 sem parâmetros. Exemplo: ler a configuração de todos os botões.

$72B0>/lb/buttons@6?<48214# — Dispositivo: $72B0, Ação: >/lb/buttons, Protocolo: @6, Valores: ?, Sequência: <48214, Fim: #$72B0>/lb/buttons@6?<48214#

O equipamento responde com uma mensagem por item. Cada uma vem com o protocolo @0, o code e o _n do item. O campo len da descrição informa quantos itens a ação tem.

@8 Send All

O Studio SHC usa @8 para enviar a mesma rede Wi-Fi a vários equipamentos (opção Enviar para todos (rede cabeada)):

$72B0>/lb/wifi@8?ssid=MinhaRede&pass=12345678<48215#

Resposta

A resposta tem o mesmo formato da mensagem. Ela vem com o ID do equipamento que respondeu, a ação, o protocolo e os valores atuais.

O primeiro valor é o code, que diz se o pedido deu certo:

Protocolo	Deu certo quando
@0, @6, @8	code começa com 1 (ex.: code=1001, ou code=1 no LOUD). code=0001 indica erro.
@1	a resposta traz status=OK.
@9	a resposta chega (a descrição não traz code).

$72B0>/ac/rs@0?code=1001&r0=on&r1=off<77120#

Descrição (@9)

A descrição é a lista das ações que um equipamento oferece, com os parâmetros de cada uma: nome, tipo e valores aceitos. Cada equipamento guarda a própria descrição. Com ela, você sabe o que pode enviar a um equipamento sem consultar outra documentação.

O Studio SHC usa a descrição para montar as telas do equipamento: saídas, entradas e ações. Para buscar a descrição de novo, use o botão Recarregar.

Pedir a descrição

Para pedir a descrição de todas as ações, envie a ação /* com o protocolo @9:

$72B0>/*@9?<48216# — Dispositivo: $72B0, Ação: >/*, Protocolo: @9, Valores: ?, Sequência: <48216, Fim: #$72B0>/*@9?<48216#

Para pedir a descrição de uma ação só, envie o caminho dela com o protocolo @9. Exemplo: a descrição de /ac/rs.

$72B0>/ac/rs@9?<48217# — Dispositivo: $72B0, Ação: >/ac/rs, Protocolo: @9, Valores: ?, Sequência: <48217, Fim: #$72B0>/ac/rs@9?<48217#

A resposta

O equipamento responde com uma mensagem por ação: com /*, uma para cada ação; com o caminho de uma ação, uma mensagem só. Cada mensagem traz o caminho da ação, o protocolo @9 e, no lugar dos valores, um texto JSON:

$72B0>/ac/rs@9?{"name":"rs","path":"/ac/rs","params":[{"name":"r0","type":"Boolean","params":["toggle","on","off"]},{"name":"r1","type":"Boolean","params":["toggle","on","off"]}],"paramsResponse":[]}<51877#

• No pedido com /*, o número de mensagens é o valor nAC da ação /if/device. Espere até receber esse número de mensagens. No Studio SHC, o campo Ações mostra quantas chegaram, como 6/18.
• Decodifique o texto como URL antes de ler (%7B vira {). Num texto sem codificação, a decodificação não muda nada.
• O JSON termina na chave que fecha o primeiro {. O que vier depois, como &_ts=1760900000, são parâmetros de controle.

O mesmo JSON, organizado:

{
  "name": "rs",
  "path": "/ac/rs",
  "params": [
    { "name": "r0", "type": "Boolean", "params": ["toggle", "on", "off"] },
    { "name": "r1", "type": "Boolean", "params": ["toggle", "on", "off"] }
  ],
  "paramsResponse": []
}

Esse equipamento tem duas saídas de relé, r0 e r1. Cada uma aceita toggle, on ou off. Veja como usar em /ac/rs.

Campos da ação

Campo	O que traz
name	Nome curto da ação (ex.: rs).
path	Caminho da ação, para usar nas mensagens (ex.: /ac/rs).
params	Parâmetros que a ação aceita. A consulta (@0 sem parâmetros) devolve os valores atuais deles.
paramsResponse	Parâmetros que só vêm na resposta: você não os envia. Ex.: em /if/device, model, version e nAC.
len	Quantos itens a ação guarda, de _n = 0 até len − 1. Nas ações sem _n, vem 1 ou o campo não vem. Firmware anterior ao 3.1.0 usa o nome lens (ex.: "lens":1 em /lb/device).

Campos de cada parâmetro

Campo	O que traz
name	Nome do parâmetro na mensagem (ex.: r0, vl). Começa com _ quando é parâmetro de controle.
type	Tipo do valor. Veja a tabela de tipos abaixo.
params	Lista com os valores aceitos (ex.: on, off) e as restrições, que começam com $ (ex.: $max=99).
friendlyName	Opcional. Nome para mostrar ao usuário (ex.: volume).
description	Opcional. Explicação do parâmetro.

Tipo	Valor
Boolean	Um dos valores listados em params, como toggle, on e off.
Chosen	Um dos valores listados em params (ex.: as entradas AUX1, BT, OPT do LOUD).
Integer	Número inteiro, entre $min e $max.
String	Texto, com tamanho máximo $max.
Buffer	Bytes em hexadecimal, 2 caracteres por byte (ex.: 0D = Enter). $max limita os caracteres e $maxBytes, os bytes.
Array[N]:Tipo	Firmware legado: N parâmetros do mesmo tipo, numerados de 0 a N − 1. Ex.: r com Array[4]:Boolean equivale a r0 a r3.

Restrições

As restrições vêm dentro de params, no formato $nome=valor:

Restrição	Significado	Exemplo
$min	Menor valor aceito.	$min=-15
$max	Integer: maior valor aceito. String e Buffer: número máximo de caracteres.	$max=99
$maxBytes	Buffer: número máximo de bytes.	$maxBytes=128
$inc, $dec	Aparecem nos parâmetros Integer, no formato $inc=[a,b].	$inc=[1,20]

Exemplo de parâmetro Integer: o volume de uma zona do LOUD aceita de 0 a 99.

{ "name": "vl", "friendlyName": "volume", "type": "Integer", "params": ["$inc=[1,20]", "$dec=[1,20]", "$max=99", "$min=0"] }

Parâmetros agrupados

$6A6F>/ac/rs@0?r[0,1]=off&_to=192.168.0.1<99999# — Dispositivo: $6A6F, Ação: >/ac/rs, Protocolo: @0, Valores: ?r[0,1]=off, Destino: &_to=192.168.0.1, Sequência: <99999, Fim: #$6A6F>/ac/rs@0?r[0,1]=off&_to=192.168.0.1<99999#

Parâmetros com o mesmo valor podem ser agrupados: r[0,1]=off equivale a r0=off&r1=off. Essa forma vale para firmwares 2.x ou mais novos; firmwares 1.x não a aceitam.