Módulos e Funcionalidades

Os plugins podem estender as suas capacidades para além das leituras e escritas USB básicas usando dois sistemas: Módulos e Funcionalidades. Compreender a diferença entre eles ajuda a descobrir o que está disponível e a usar o mecanismo correto.

Módulos vs Funcionalidades

	Módulos	Funcionalidades
Como usar	import { x } from "@SignalRGB/name"	device.addFeature("name") em Initialize()
Propósito	Serviços utilitários (rede, codificação, informações do sistema)	Capacidades do dispositivo (bateria, injeção de entrada)
Namespace	Nomes exportados próprios do módulo	device.featureName.*
Instâncias	Uma por plugin	Pode ter múltiplas

---

Módulos Disponíveis

Importe-os no topo do seu ficheiro de plugin.

Caminho de importação	Propósito
@SignalRGB/serial	Comunicação serial/porta COM
@SignalRGB/tcp	Comunicação via socket TCP
@SignalRGB/udp	Comunicação via socket UDP
@SignalRGB/base64	Codificação e descodificação Base64
@SignalRGB/performance	Profiling de performance e timers de frame
@SignalRGB/appInfo	Informações de versão da aplicação SignalRGB
@SignalRGB/systeminfo	Informações de hardware do sistema
@SignalRGB/permissions	Verificar estado de permissão do utilizador
Consulte Comunicação Avançada para exemplos de utilização de serial, tcp e udp.

---

Funcionalidades Disponíveis

Chame device.addFeature("name") no seu export Initialize(). A funcionalidade cria um objeto global com o mesmo nome da funcionalidade.

Nome da funcionalidade	Namespace	Propósito
"keyboard"	keyboard	Injetar teclas ou encaminhar eventos de teclado para macros do SignalRGB
"mouse"	mouse	Injetar entrada de rato ou encaminhar eventos de rato para macros do SignalRGB
"battery"	battery	Reportar nível de bateria e estado de carga para dispositivos sem fios
"dtls"	dtls	UDP cifrado DTLS com autenticação PSK

---

Funcionalidade de Teclado

Para plugins que representam dispositivos de teclado. Permite injetar teclas reais no SO ou disparar eventos que podem acionar macros do SignalRGB.

export function Initialize() {
    device.addFeature("keyboard");
}

keyboard.sendHid(vkCode, options)

Envia uma tecla diretamente ao sistema operativo via keybd_event. A tecla aparece como entrada real para todas as aplicações — ignora completamente o sistema de macros.

Parâmetro	Tipo	Descrição	Exemplo
vkCode	Number	Código de Tecla Virtual do Windows	0x41 (tecla A)
options.released	Boolean (obrigatório)	true para key-up, false para key-down	false

keyboard.sendHid(0x41, { released: false }); // Pressionar A
keyboard.sendHid(0x41, { released: true });  // Soltar A

keyboard.sendEvent(eventData, eventType)

Encaminha um evento de teclado pelo sistema de macros do SignalRGB. Macros com um acionador onKey podem corresponder a esses eventos. Não injeta uma tecla real — apenas as macros do SignalRGB veem este evento.

O sistema de macros enriquece automaticamente o evento com o estado de modificadores ativos (Ctrl, Shift, Alt, Win) do teclado físico antes de o distribuir.

Parâmetro	Tipo	Descrição	Exemplo
eventData	Object ou String	Dados do evento. Inclua key (nome em string) e opcionalmente keyCode (número) para correspondência de tecla.	{ key: "A", keyCode: 0x41 }
eventType	String	Label do tipo de evento	"KeyPress"

keyboard.sendEvent({ key: "A", keyCode: 0x41, released: false }, "KeyPress");

Scripts de macro recebem event.Sender (o UID do plugin) e event.SenderType ("Device"), para que possam distinguir eventos originados do plugin de teclas reais de hardware.

---

Funcionalidade de Rato

Para plugins que representam dispositivos de rato ou ponteiro.

export function Initialize() {
    device.addFeature("mouse");
}

mouse.sendHid(buttonCode, options)

Envia um evento de rato ao SO via SendInput. Movimentos de rato (MOUSEEVENTF_MOVE, MOUSEEVENTF_ABSOLUTE) são bloqueados por segurança.

Parâmetro	Tipo	Descrição
buttonCode	Number	Flag Windows MOUSEEVENTF_*
options.XButton	Number	Obrigatório para eventos de botão X — 1 (X1) ou 2 (X2)
options.WheelDelta	Number	Obrigatório para eventos de roda de deslocamento — positivo desloca para cima, negativo para baixo

Códigos de botão comuns:

Código	Constante	Descrição
0x0002	MOUSEEVENTF_LEFTDOWN	Pressionar botão esquerdo
0x0004	MOUSEEVENTF_LEFTUP	Soltar botão esquerdo
0x0008	MOUSEEVENTF_RIGHTDOWN	Pressionar botão direito
0x0010	MOUSEEVENTF_RIGHTUP	Soltar botão direito
0x0020	MOUSEEVENTF_MIDDLEDOWN	Pressionar botão do meio
0x0040	MOUSEEVENTF_MIDDLEUP	Soltar botão do meio
0x0800	MOUSEEVENTF_WHEEL	Deslocamento vertical
0x01000	MOUSEEVENTF_HWHEEL	Deslocamento horizontal
0x0080	MOUSEEVENTF_XDOWN	Pressionar botão X (requer opção XButton)
0x0100	MOUSEEVENTF_XUP	Soltar botão X (requer opção XButton)

// Clique esquerdo
mouse.sendHid(0x0002, {});  // pressionar
mouse.sendHid(0x0004, {});  // soltar

// Deslocar um passo para cima
mouse.sendHid(0x0800, { WheelDelta: 120 });

// Pressionar botão X1
mouse.sendHid(0x0080, { XButton: 1 });
mouse.sendHid(0x0100, { XButton: 1 });

mouse.sendEvent(eventData, eventType)

Encaminha um evento de rato personalizado pelo sistema de macros do SignalRGB. Scripts de macro com um acionador onMouse podem corresponder a esses eventos. Não injeta nenhuma entrada de rato ao nível do SO.

mouse.sendEvent({ button: "LeftClick" }, "ButtonPress");

---

Funcionalidade de Bateria

Para dispositivos sem fios que reportam o estado da bateria. Após adicionar a funcionalidade, atualize o nível e o estado da bateria sempre que o seu dispositivo os reportar.

export function Initialize() {
    device.addFeature("battery");
}

Definindo o Estado da Bateria

Método	Descrição
battery.setBatteryLevel(level)	Definir percentagem da bateria (0–100)
battery.setBatteryState(state)	Definir o estado de carga usando uma constante de estado

Constantes de estado (acesso via battery.<name>):

Constante	Descrição
battery.disabled	Relatório de bateria desativado
battery.unknown	Estado ainda desconhecido
battery.draining	A funcionar com bateria
battery.charging	A carregar via cabo
battery.fullCharging	A carregar e já cheio
battery.full	Carga completa, não está a carregar
battery.wirelessCharging	Carregamento sem fios

Lendo o Estado da Bateria

Estas propriedades refletem os últimos valores definidos:

Propriedade	Tipo	Descrição
battery.batteryLevel	Number	Nível atual (0–100)
battery.batteryState	Number	Valor do estado atual
battery.stateString	String	Label de estado legível

Exemplo de Bateria

export function Initialize() {
    device.addFeature("battery");
}

export function Render() {
    // Leitura não bloqueante — verificar se o dispositivo enviou um relatório de bateria neste frame
    var data = device.read([], 64, 0);

    if(device.getLastReadSize() > 0 && data[0] === 0x02) {
        var level = data[1];             // 0–100
        var charging = data[2] === 0x01;

        battery.setBatteryLevel(level);
        battery.setBatteryState(
            charging ? battery.charging : battery.draining
        );
    }
}