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

Entender a diferença entre os tipos de transferência USB ajuda você a escolher o método correto e 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/mouse
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 controle HID GET_INPUT_REPORT. Similar a device.get_report() mas solicita especificamente um relatório Input em vez de um relatório Feature. Use isso quando get_report() retorna dados incorretos porque o dispositivo separa 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(), isso permite que você direcione 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 controle 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 controle, 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,     // Esperar 192 bytes de volta
    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 serial/COM port, 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 Conexão

serial.connect({
    baudRate: 115200,  // Padrã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 conexão	bool
serial.write(data)	Enviar dados	bytes escritos
serial.read(maxBytes?, timeoutMs?)	Ler bytes disponíveis (padrã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 conectar à porta serial");
        return;
    }
    device.log(`Conectado 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 conectados 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("Conectado");
        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)	Conectar 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)	Registrar 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 padrão
socket.send(data)	Enviar para o endereço conectado
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 recepção
socket.close()	Fechar o socket
socket.on(event, callback)	Registrar um manipulador de evento

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

---

DTLS (UDP Criptografado)

Para dispositivos que requerem comunicação criptografada (ex. Philips Hue), use a feature dtls. Ela fornece UDP criptografado DTLS usando uma Chave Pré-Compartilhada (PSK).

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

    dtls.onConnectionEstablished(() => { device.log("DTLS conectado"); });
    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 conexão criptografada usando uma PSK
dtls.send(data, endianness?)	Enviar dados criptografados (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Retorna true se a conexão estiver estabelecida
dtls.CloseConnection()	Fechar a conexão
dtls.onConnectionEstablished(cb)	Callback quando a conexão é bem-sucedida
dtls.onConnectionClosed(cb)	Callback quando a conexão fecha
dtls.onConnectionError(cb)	Callback em caso de erro