Comunicação Avançada

Esta página cobre métodos avançados de comunicação USB, portas seriais e sockets de rede. Para leituras e escritas básicas, consulte Escritas e Leituras.

Tipos de Transferência USB

Compreender a diferença entre os tipos de transferência USB ajuda a escolher o método correto e a depurar erros inesperados.

Tipo	Método	Tamanho típico	Caso de uso
Interrupt	device.write() / device.read()	3–64 bytes	Dados RGB, pequenos comandos, entrada de teclado/rato
Bulk	device.write() / device.read()	64–1025 bytes	Imagens LCD, atualizações de firmware, grandes blocos de configuração
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 bytes	Autenticação, relatórios HID feature, configuração do dispositivo

As mesmas funções device.write() e device.read() são usadas para transferências interrupt e bulk — o driver USB determina o tipo pelo endpoint e tamanho do pacote.

---

Métodos de Relatório HID

device.input_report()

Envia uma transferência de controlo HID GET_INPUT_REPORT. Similar a device.get_report() mas solicita especificamente um relatório Input em vez de um relatório Feature. Use isto quando get_report() retorna dados incorretos porque o dispositivo separa os seus tipos de relatório Input e Feature.

Parâmetro	Tipo	Descrição	Exemplo
DataArray	Array 1D	Dados de solicitação de relatório	[0x01]
Length	Int	Tamanho de relatório esperado em bytes	64

Retorno	Tipo	Descrição
DataArray	Array 1D	Bytes recebidos do dispositivo

var inputData = device.input_report([0x01], 64);

---

Métodos USB Brutos

device.bulk_transfer()

Realiza uma transferência bulk ou interrupt direta para um endpoint USB específico. Ao contrário de device.write() e device.read() que usam o endpoint selecionado por device.set_endpoint(), isto permite direcionar qualquer endpoint pelo seu endereço.

• Endereços de endpoint terminando em 0x80 ou superior são IN (dispositivo → host, leitura).
• Endereços de endpoint abaixo de 0x80 são OUT (host → dispositivo, escrita).

Parâmetro	Tipo	Descrição	Exemplo
Endpoint	Hex	Endereço do endpoint USB	0x81
DataArray	Array 1D	Dados a enviar (OUT), ou array vazio (IN)	[0x01, 0x02]
Length	Int	Tamanho da transferência em bytes	64
Timeout	Int	Milissegundos antes de desistir	100

Retorno	Tipo	Descrição
DataArray	Array 1D	Bytes recebidos (transferências IN), ou vazio

// Escrever para o endpoint 0x01
device.bulk_transfer(0x01, [0x00, 0x01, 0x02], 3, 100);

// Ler do endpoint 0x81
var response = device.bulk_transfer(0x81, [], 64, 100);

// Grande escrita bulk (ex. dados de imagem LCD)
device.bulk_transfer(0x02, imageData, 1024, 500);

---

device.control_transfer()

Transferência de controlo USB de baixo nível. Usado para handshakes de autenticação, protocolos específicos de fabricante e casos em que os métodos HID são insuficientes. Esta é uma transferência de controlo, não uma transferência bulk.

Parâmetro	Tipo	Descrição	Exemplo
RequestType	Hex	Bitmap do tipo de solicitação USB (direção, tipo, destinatário)	0xA1
Request	Hex	Código de solicitação (específico do dispositivo)	0x01
Value	Hex	Campo valor	0x0100
Index	Int	Índice de interface ou endpoint	0x00
DataArray	Array 1D	Dados a enviar (host→dispositivo), ou vazio	[]
Length	Int	Comprimento de resposta esperado (dispositivo→host)	192
Timeout	Int	Milissegundos antes de desistir	1000

Retorno	Tipo	Descrição
DataArray	Array 1D	Bytes recebidos (transferências dispositivo→host)

Valores RequestType comuns:

Valor	Direção	Tipo	Destinatário	Caso de uso
0x21	Host → Dispositivo	Class	Interface	HID SET_REPORT
0xA1	Dispositivo → Host	Class	Interface	HID GET_REPORT
0x80	Dispositivo → Host	Standard	Dispositivo	Leituras de descritor
0x00	Host → Dispositivo	Standard	Dispositivo	Comandos padrão

// Ler token de autenticação (dispositivo → host, class, interface)
var token = device.control_transfer(
    0xA1,    // Dispositivo→host, class, interface
    0x01,    // GET_REPORT
    0x0100,  // Tipo de relatório (Feature) + ID do relatório
    0x00,    // Interface 0
    [],      // Sem dados de saída
    192,     // Aguardar 192 bytes de retorno
    1000     // Timeout de 1 segundo
);

// Enviar um relatório feature (host → dispositivo)
device.control_transfer(0x21, 0x09, 0x0300, 0, [0x03, 0x08, 0x32], 0, 500);

---

Comunicação Serial

Para dispositivos de porta serial/COM, importe o módulo serial e defina Type() do seu plugin como "serial".

import { serial } from "@SignalRGB/serial";

export function Type() { return "serial"; }

Opções de Ligação

serial.connect({
    baudRate: 115200,  // Predefinição: 115200
    parity: "None",    // "None", "Even", "Odd", "Space", "Mark"
    dataBits: 8,       // 5, 6, 7 ou 8
    stopBits: "One"    // "One", "OneAndHalf", "Two"
});

Métodos Seriais

Método	Descrição	Retorna
serial.connect(options?)	Abrir a porta serial	bool
serial.disconnect()	Fechar a porta serial	void
serial.isConnected()	Verificar estado da ligação	bool
serial.write(data)	Enviar dados	bytes escritos
serial.read(maxBytes?, timeoutMs?)	Ler bytes disponíveis (predefinição: todos, timeout 1000 ms)	array de bytes
serial.readAll()	Ler todos os bytes disponíveis imediatamente	array de bytes
serial.availablePorts()	Listar portas COM disponíveis	array
serial.getPortName()	Nome da porta atual	string
serial.getBaudRate()	Taxa de baud atual	number
serial.getDeviceInfo()	Informações da porta com VID, PID, etc.	object

import { serial } from "@SignalRGB/serial";

export function Type() { return "serial"; }

export function Initialize() {
    if (!serial.connect()) {
        device.log("Falha ao ligar à porta serial");
        return;
    }
    device.log(`Ligado em ${serial.getPortName()} a ${serial.getBaudRate()} baud`);
}

export function Render() {
    serial.write([0xFF, ...RGBData]);
}

export function Shutdown() {
    serial.disconnect();
}

---

Comunicação de Rede (TCP / UDP)

Para dispositivos ligados em rede, importe o módulo TCP ou UDP e defina Type() como "network". Ambos os módulos usam um modelo de callback baseado em eventos.

import { tcp } from "@SignalRGB/tcp";
import { udp } from "@SignalRGB/udp";

export function Type() { return "network"; }

TCP

import { tcp } from "@SignalRGB/tcp";

let socket;

export function Initialize() {
    socket = tcp.createSocket();

    socket.on("connected", () => {
        device.log("Ligado");
        socket.send([0x01, 0x02, 0x03]);
    });

    socket.on("message", (data) => {
        device.log(`Recebido: ${data}`);
    });

    socket.on("error", (err) => {
        device.log(`Erro: ${err}`);
    });

    socket.connect("192.168.1.100", 8080);
}

export function Render() {
    if (socket.state === socket.ConnectedState) {
        socket.send(RGBData);
    }
}

export function Shutdown() {
    socket.close();
}

Métodos TCP:

Método	Descrição
tcp.createSocket()	Criar um novo socket TCP
socket.connect(address, port)	Ligar a um host
socket.send(data)	Enviar string ou array de bytes
socket.bind(port)	Vincular a uma porta local
socket.close()	Fechar o socket
socket.on(event, callback)	Registar um manipulador de evento

Eventos TCP: "connected", "disconnected", "message", "error"

---

UDP

import { udp } from "@SignalRGB/udp";

let socket;

export function Initialize() {
    socket = udp.createSocket();

    socket.on("message", (data) => {
        device.log(`Recebido: ${data}`);
    });

    socket.connect("192.168.1.100", 21324);
}

export function Render() {
    socket.send(RGBData);
}

export function Shutdown() {
    socket.close();
}

Métodos UDP:

Método	Descrição
udp.createSocket()	Criar um novo socket UDP
socket.connect(address, port)	Definir destino de envio predefinido
socket.send(data)	Enviar para o endereço ligado
socket.write(data, address, port)	Enviar para um endereço específico sem chamar connect() primeiro
socket.bind(port)	Vincular a uma porta local para receção
socket.close()	Fechar o socket
socket.on(event, callback)	Registar um manipulador de evento

Eventos UDP: "connected", "disconnected", "message", "error"

---

DTLS (UDP Cifrado)

Para dispositivos que requerem comunicação cifrada (ex. Philips Hue), use a feature dtls. Fornece UDP cifrado DTLS usando uma Chave Pré-Partilhada (PSK).

export function Initialize() {
    device.addFeature("dtls");

    dtls.onConnectionEstablished(() => { device.log("DTLS ligado"); });
    dtls.onConnectionClosed(() => { device.log("DTLS fechado"); });
    dtls.onConnectionError(() => { device.log("Erro DTLS"); });

    dtls.createConnection("192.168.1.50", 2100, authIdentity, authKey);
}

export function Render() {
    if (dtls.hasEncryptedConnection()) {
        dtls.send(RGBData);
    }
}

export function Shutdown() {
    dtls.CloseConnection();
}

Métodos DTLS:

Método	Descrição
dtls.createConnection(host, port, identity, key)	Abrir uma ligação cifrada usando uma PSK
dtls.send(data, endianness?)	Enviar dados cifrados (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Retorna true se a ligação estiver estabelecida
dtls.CloseConnection()	Fechar a ligação
dtls.onConnectionEstablished(cb)	Callback quando a ligação é bem-sucedida
dtls.onConnectionClosed(cb)	Callback quando a ligação fecha
dtls.onConnectionError(cb)	Callback em caso de erro