LOUD — Controle de Zonas via UDP

Referência técnica para integradores. Mostra como descobrir e controlar as zonas de um amplificador LOUD na rede local usando o protocolo ASCII dos dispositivos Xcene/LOUD.

Zonas e entradas variam por aparelho

O protocolo é o mesmo para toda a linha LOUD, mas o número de zonas e de entradas depende do aparelho. Os exemplos abaixo mostram até 6 zonas (zona0 a zona5) e as entradas AUX1 a AUX5, BT e OPT. O APL 420S, por exemplo, tem 2 zonas. Para saber o que um aparelho tem, use a descoberta (@9, seção 3): ele responde com as zonas e os parâmetros que expõe.

---

1. Formato do pacote ASCII

$<ID>><PATH>@<PROTOCOLO>?<QUERY>&_to=<IP><SEED>#

Exemplo:

$3A7F>/ac/zona0@0?vl=50&_to=192.168.0.10<123456#

Campo	Descrição
$3A7F	4 últimos dígitos do MAC do device destino. 0000 = broadcast.
>/ac/zona0	Path da ação.
@0	Número do protocolo (tabela abaixo).
?vl=50	Parâmetros chave=valor separados por &. Vazio = leitura do estado atual.
&_to=192.168.0.10	(Opcional) IP para resposta exclusiva. Device abre TCP de volta neste IP.
<123456	Seed — número único por envio, evita processamento duplicado. Use 0 apenas para testes.
#	Fim do pacote.

Os separadores $ > @ ? < # são obrigatórios, mesmo que o campo esteja vazio.

Tabela de protocolos

Código	Nome	Uso
0	Set Data	Ler ou definir valores no device
1	Delete Data	Remover dados (ex.: itens de cena)
8	Send All	Broadcast — mesma mensagem para vários devices
9	Description	Descobrir ações e parâmetros disponíveis

---

2. Device LOUD

Propriedade	Valor
ID	3A7F
Modelo	Multiroom
Zonas de controle	/ac/zona0, /ac/zona1, /ac/zona2, /ac/zona3, /ac/zona4, /ac/zona5
Config avançada de zonas	/lb/Zona (indexada por _n=0..5)

Outras ações (Bluetooth, Inputs, IR, WiFi, modo Dualzone/Singlezone/4.1) também estão disponíveis via path /lb/*, mas não são cobertas aqui.

---

3. Descoberta — Protocolo 9 (DESCRIPTION)

Pergunta ao device quais zonas e parâmetros ele expõe. Suporta wildcard ou path específico.

Listar todas as ações do device:

$3A7F>/*@9?<12345#

Listar apenas a zona 0:

$3A7F>/ac/zona0@9?<12345#

Modelo de resposta (zona 0):

$3A7F>/ac/zona0@9?{"name":"zona0","path":"/ac/zona0","params":[
 {"name":"pw","friendlyName":"power","params":["toggle","on","off"],"type":"Boolean"},
 {"name":"mt","friendlyName":"mute","params":["toggle","on","off"],"type":"Boolean"},
 {"name":"in","friendlyName":"input","params":["AUX1","AUX2","AUX3","AUX4","AUX5","BT","OPT"],"type":"Chosen"},
 {"name":"vl","friendlyName":"volume","params":["$inc=[1,20]","$dec=[1,20]","$max=99","$min=0"],"type":"Integer"},
 {"name":"bs","friendlyName":"bass","params":["$inc=[1,20]","$dec=[1,20]","$max=0","$min=-15"],"type":"Integer"},
 {"name":"tr","friendlyName":"treble","params":["$inc=[1,20]","$dec=[1,20]","$max=0","$min=-15"],"type":"Integer"},
 {"name":"md","friendlyName":"middle","params":["$inc=[1,20]","$dec=[1,20]","$max=0","$min=-15"],"type":"Integer"}
]}<12345#

---

4. Parâmetros de uma zona (/ac/zonaN)

Param	Nome amigável	Tipo	Valores / Faixa	Exemplo
pw	power	Boolean	on, off, toggle	pw=on
mt	mute	Boolean	on, off, toggle	mt=off
in	input	Chosen	AUX1, AUX2, AUX3, AUX4, AUX5, BT, OPT	in=BT
vl	volume	Integer	0 a 99	vl=50
bs	bass	Integer	-15 a 0 (dB)	bs=-5
tr	treble	Integer	-15 a 0 (dB)	tr=-3
md	middle	Integer	-15 a 0 (dB)	md=-2

---

5. Comandos práticos

Todos os exemplos usam a zona 0 (/ac/zona0) do device 3A7F. Para outras zonas, troque o path (/ac/zona1, /ac/zona2, …). A seed (<123#) deve ser trocada a cada envio.

5.1 Consultar estado completo

Envio:

$3A7F>/ac/zona0@0?<111#

Resposta:

$3A7F>/ac/zona0@0?code=1&pw=on&mt=off&in=AUX1&vl=50&bs=0&tr=0&md=0<111#

code=1 = sucesso.

5.2 Ligar / desligar / toggle

$3A7F>/ac/zona0@0?pw=on<112#
$3A7F>/ac/zona0@0?pw=off<113#
$3A7F>/ac/zona0@0?pw=toggle<114#

Resposta (eco de confirmação):

$3A7F>/ac/zona0@0?code=1&pw=on<112#

5.3 Mutar / desmutar

$3A7F>/ac/zona0@0?mt=on<115#
$3A7F>/ac/zona0@0?mt=off<116#

Resposta:

$3A7F>/ac/zona0@0?code=1&mt=on<115#

5.4 Trocar fonte de áudio

$3A7F>/ac/zona0@0?in=AUX1<117#
$3A7F>/ac/zona0@0?in=BT<118#
$3A7F>/ac/zona0@0?in=OPT<119#

Resposta:

$3A7F>/ac/zona0@0?code=1&in=BT<118#

5.5 Definir volume

$3A7F>/ac/zona0@0?vl=75<120#

Resposta:

$3A7F>/ac/zona0@0?code=1&vl=75<120#

5.6 Ajustar equalização (graves, médios, agudos)

$3A7F>/ac/zona0@0?bs=-5<121#
$3A7F>/ac/zona0@0?md=-3<122#
$3A7F>/ac/zona0@0?tr=-2<123#

Resposta:

$3A7F>/ac/zona0@0?code=1&bs=-5<121#

6.7 Comando combinado (múltiplos parâmetros)

$3A7F>/ac/zona0@0?pw=on&in=BT&vl=60&mt=off<124#

Resposta:

$3A7F>/ac/zona0@0?code=1&pw=on&in=BT&vl=60&mt=off<124#

---

6. Configuração avançada da zona (/lb/Zona)

/lb/Zona guarda a configuração persistente de cada zona (nome, limites, defaults). Como o device tem 6 zonas, as operações usam o parâmetro _n (0 a 5) para indicar qual zona está sendo lida/gravada.

Parâmetros

Param	Tipo	Faixa / Valores	Descrição
nmc	String	até 15 caracteres	Nome amigável da zona
vli	Integer	0 a 30	Volume inicial (ao ligar)
vll	Integer	40 a 99	Volume máximo permitido
ii	Chosen	AUX1..AUX5, BT, OPT	Fonte padrão ao ligar
mdda	Chosen	Normal, Power Automático	Modo de ligar automático
md	Integer	-15 a 0	Médio default
tb	Integer	-15 a 0	Agudo default
bs	Integer	-15 a 0	Grave default

6.1 Ler a configuração da zona 0

Envio:

$3A7F>/lb/Zona@0?_n=0<130#

Resposta:

$3A7F>/lb/Zona@0?code=1&nmc=Sala&vli=15&vll=99&ii=AUX1&mdda=Normal&md=-5&tb=-3&bs=-2&_n=0<130#

6.2 Renomear a zona 0 para “Sala”

$3A7F>/lb/Zona@0?nmc=Sala&_n=0<131#

O valor em nmc pode ser URI-encoded se tiver espaços/acentos (ex.: nmc=Sala%20de%20Estar).

6.3 Definir volume inicial e máximo da zona 1

$3A7F>/lb/Zona@0?vli=20&vll=80&_n=1<132#

---

7. Notas rápidas

• Seed única por envio: o device descarta pacotes com seed repetida recente (deduplicação anti-eco). Gere um número novo a cada pacote.
• _to=<IP>: opcional mas recomendado quando você quer resposta unicast direta para a sua máquina (ex.: atrás de firewall multicast restritivo). O device também pode abrir TCP de volta neste IP na porta 5203.
• Separadores: $ > @ ? < # são obrigatórios mesmo se o campo estiver vazio. Ex.: leitura sem parâmetros é $3A7F>/ac/zona0@0?<SEED#.
• Envios sequenciais: equipamentos são low-energy; evite enviar múltiplos pacotes UDP em paralelo. Use intervalo de ~50 ms entre envios consecutivos.
• code na resposta: code=1 (ou que começa com 1) indica sucesso. Respostas sem code em protocolo @9 (DESCRIPTION) são normais.
• Broadcast 0000: substitua $3A7F por $0000 para enviar a todos os devices da rede. Útil apenas para descoberta (/if/device@0), não para controle.

---