Integração TCP/UDP

Integração TCP/UDP

O protocolo TCP/UDP destina-se a dispositivos que utilizam uma linguagem de comandos simples diretamente através de um socket de rede — sem API web, sem modelo de registos: leitores de áudio e matrizes profissionais (AUDAC XMP44 e módulos SourceCon), projetores (PJLink), ecrãs e amplificadores atrás de conversores RS-232 para IP, e placas personalizadas com microcontroladores. Define as tramas de comando que o HyperVisu envia quando um valor se altera, os padrões de correspondência que extraem valores das tramas que o equipamento devolve, e tramas de interrogação opcionais para polling. Todo o conhecimento específico do dispositivo reside na configuração, nenhum no servidor.

Cada ligação corresponde a um dispositivo, por TCP (uma ligação persistente, mantida aberta e reconectada automaticamente) ou UDP (datagramas). Por TCP, todos os objetos do dispositivo partilham esse único socket — exatamente o que os dispositivos que aceitam apenas um cliente (como o XMP44) exigem.

Do que necessita: o endereço IP e a porta do dispositivo, a sua referência de comandos (sintaxe da trama, delimitador, os comandos e o feedback devolvido), e se o dispositivo envia as alterações de estado por iniciativa própria (push) ou se necessita de ser interrogado.

Ligações. O TCP/UDP é multi-ligação: uma ligação por dispositivo (consulte “Ligações”). Campos:

A janela Add connection solicita o Instance Name, o Device address, a Port, o Poll Interval (seconds), o Transport e o Frame delimiter (valores padrão 30, TCP · persistent connection e \r\n). Os outros campos encontram-se em Framing and timing na ligação guardada: selecione a nova ligação, configure-os e clique em Save connection.

O botão Test na janela Add connection abre um socket para o endereço introduzido. Isto confirma que o dispositivo está acessível, não que compreende as suas tramas. Numa ligação guardada, enquanto o serviço já mantém a ligação única ao dispositivo, o Test reporta o estado em tempo real e a contagem de tramas de entrada e saída em vez de abrir um segundo socket.

Associação de um objeto (consulte “Associação TCP/UDP” abaixo). Por cada objeto define uma Key — um pequeno texto presente em todas as respostas que contêm este valor: apenas as tramas recebidas que contêm a chave são testadas contra o padrão de correspondência do objeto (no caso da AUDAC, o nome do comando de feedback: OG1, FREQ2). A comparação diferencia maiúsculas de minúsculas e a chave não pode conter :. Dois objetos podem partilhar a mesma chave, por exemplo um objeto de comando e o seu respetivo objeto de feedback. O sistema armazena <ligação>:<chave>. O restante é a string de tipo de dados do objeto, gerada a partir dos campos do editor:

Os Modelos utilizam ${value}, além de ${value:d} para arredondar um valor escalado para um número inteiro (um slider de 0–100 % num dispositivo que requer argumentos inteiros), ${value:02d} para um número inteiro com zeros à esquerda e ${value:1f} para um número fixo de casas decimais; em modo HEX, ${value:u8}, ${value:u16be}, ${value:u16le}, ${value:u32be}, ${value:u32le} para bytes de tamanho fixo. \r, \n, \t e \xNN são sequências de escape de bytes. Em modo ASCII, se um modelo omitir o delimitador, este é adicionado automaticamente.

Os Padrões de correspondência utilizam estes identificadores; todo o restante texto é comparado literalmente:

O editor apresenta a secção Frame sent com carateres de controlo visíveis (# | D001 | hv | SOG1 | 28 | U | <CR><LF>) e a string gravada. Frame sent é uma pré-visualização, não um registo real de tráfego: cada ${value…} é substituído pelo valor de exemplo 28, sem a formatação do valor nem a escala, e para objetos com comandos ON e OFF separados é exibido apenas o comando ON. Não mostra o delimitador adicionado automaticamente pelo servidor em modo ASCII. Confirme sempre os comandos e respostas reais diretamente no dispositivo.

Comportamento a ter em conta

• Direção. Os objetos In realizam correspondência (e polling, se tiverem interrogação definida); os objetos Out enviam; os objetos In/Out fazem ambos — o eco do próprio dispositivo serve de confirmação, tal como nos objetos de estado KNX.
• Uma trama, múltiplos objetos. Cada trama recebida é comparada com todos os objetos In da ligação que contenham a respetiva chave, pelo que uma única trama de estado pode atualizar vários objetos. Modelos de interrogação idênticos são enviados apenas uma vez por ciclo de polling.
• TCP. Em caso de falha, a ligação é restabelecida com intervalos progressivos; após a reconexão, as interrogações são reexecutadas se a opção Read everything on connect estiver ativa. As tramas de saída passam por uma fila de espera espaçada pelo Delay between commands.
• UDP. Cada datagrama corresponde a uma trama. Envios não solicitados por push requerem a definição de Listen port.
• Os comandos enviados enquanto o dispositivo está inacessível falham sem bloquear o sistema; a app apresenta o último estado conhecido.

Exemplo prático — Leitor multimédia AUDAC XMP44

O XMP44 escuta em TCP na porta 5001, aceita apenas um cliente e utiliza tramas no formato # | D001 | <origem> | <comando> | <argumento> | <checksum> | <CR><LF> — a letra U é aceite como checksum literal. A regulação do ganho de saída faz-se com SOG1 | <arg> onde arg = 8 − dB; o equipamento responde com uma trama de atualização … | OG1 | <arg> | …, a qual também emite quando o ganho é alterado no painel frontal. Reproduzir e parar são dois comandos distintos (SPPLAY1, SPSTOP1).

1. Crie uma ligação TCP/UDP (consulte “Ligações”): endereço 192.168.1.60, porta 5001, transporte TCP, delimitador \r\n, intervalo de polling 30. Clique em Test e, em seguida, em Create connection. Selecione a nova ligação e, em Framing and timing, mantenha a opção Read everything on connect ativa e configure o heartbeat # | D001 | hv | GTPS | 0 | U | \r\n a cada 120 s. Clique em Save connection.

2. Em Devices, adicione um widget Audio "XMP44 player" e selecione esta ligação em Protocol.

3. No objeto volume (In/Out): chave OG1, modelo de comando # | D001 | hv | SOG1 | ${value:d} | U | \r\n, modelo de interrogação # | D001 | hv | GOG1 | 0 | U | \r\n, padrão de correspondência \i | OG1 | \i\v, escala -1, offset 8 — desta forma, −20 dB é enviado como 28 e um valor 28 recebido é lido como −20 dB.

4. No objeto play (Out, booleano): chave PLAY1, Different commands for ON and OFF: ON # | D001 | hv | SPPLAY1 | 0 | U | \r\n, OFF # | D001 | hv | SPSTOP1 | 0 | U | \r\n.

5. No objeto track title (In, texto): chave SON1, interrogação # | D001 | hv | GSON1 | 0 | U | \r\n, correspondência \i | SON1 | \i\a | .

6. Clique em Save object em cada um dos objetos, clique depois em Apply changes na barra lateral e confirme. Ao mover a barra de volume é enviado o comando SOG1, o eco OG1 do equipamento confirma o novo nível e qualquer alteração feita no painel frontal do dispositivo é refletida na app.

💡 Dica: Mantenha a documentação de comandos do equipamento aberta durante a associação — a chave é o nome de feedback (OG1), que nos equipamentos AUDAC difere do nome do comando de escrita (SOG1).

Associação TCP/UDP

Os objetos TCP/UDP são configurados na janela de definições do objeto (consulte “Definições de Objeto, Registo e Notificações”). Os separadores são:

Endereçamento da trama

Comandos enviados (objetos de saída)

Valores lidos (objetos de entrada)

Abaixo dos separadores, a secção Frame sent mostra a trama de saída gerada para um valor de exemplo com carateres de controlo visíveis (… | 28 | U | <CR><LF>), e Stored as apresenta a string de configuração que será guardada. A sintaxe dos padrões, modelos e um exemplo prático AUDAC encontram-se na secção TCP/UDP acima.