Módulos e Funcionalidades

Plugins podem estender suas capacidades além das leituras e escritas USB básicas usando dois sistemas: Módulos e Funcionalidades. Entender a diferença entre eles ajuda você a descobrir o que está disponível e 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 arquivo de plugin.

Caminho de importação	Propósito
@SignalRGB/serial	Comunicação serial/COM port
@SignalRGB/tcp	Comunicação via socket TCP
@SignalRGB/udp	Comunicação via socket UDP
@SignalRGB/base64	Codificação e decodificação Base64
@SignalRGB/performance	Profiling de performance e timers de frame
@SignalRGB/appInfo	Informações de versão do aplicativo SignalRGB
@SignalRGB/systeminfo	Informações de hardware do sistema
@SignalRGB/permissions	Verificar estado de permissão do usuário
Consulte Comunicação Avançada para exemplos de uso 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 rotear eventos de teclado para macros do SignalRGB
"mouse"	mouse	Injetar entrada de mouse ou rotear eventos de mouse para macros do SignalRGB
"battery"	battery	Reportar nível de bateria e estado de carga para dispositivos sem fio
"dtls"	dtls	UDP criptografado 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 bruta diretamente ao sistema operacional via keybd_event. A tecla aparece como entrada real para todos os aplicativos — 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)

Roteia 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 distribuí-lo.

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 Mouse

Para plugins que representam dispositivos de mouse ou ponteiro.

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

mouse.sendHid(buttonCode, options)

Envia um evento de mouse bruto ao SO via SendInput. Movimentos de mouse (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 rolagem — positivo rola 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	Rolagem vertical
0x01000	MOUSEEVENTF_HWHEEL	Rolagem 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

// Rolar 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)

Roteia um evento de mouse 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 mouse no nível do SO.

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

---

Funcionalidade de Bateria

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

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

Definindo o Estado da Bateria

Método	Descrição
battery.setBatteryLevel(level)	Definir porcentagem 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	Funcionando na bateria
battery.charging	Carregando via cabo
battery.fullCharging	Carregando e já cheio
battery.full	Carga completa, não carregando
battery.wirelessCharging	Carregamento sem fio

Lendo o Estado da Bateria

Essas 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
        );
    }
}