Module und Features

Plugins können ihre Fähigkeiten über einfache USB-Lese- und Schreibvorgänge hinaus mit zwei Systemen erweitern: Modulen und Features. Das Verständnis des Unterschieds zwischen ihnen hilft dir, das Verfügbare zu entdecken und den richtigen Mechanismus zu nutzen.

Module vs. Features

	Module	Features
Verwendung	import { x } from "@SignalRGB/name"	device.addFeature("name") in Initialize()
Zweck	Hilfsdienste (Netzwerk, Kodierung, Systeminfo)	Gerätefähigkeiten (Akku, Eingabe-Injektion)
Namespace	Eigene exportierte Namen des Moduls	device.featureName.*
Instanzen	Eine pro Plugin	Können mehrere haben

---

Verfügbare Module

Diese am Anfang deiner Plugin-Datei importieren.

Import-Pfad	Zweck
@SignalRGB/serial	Serielle/COM-Port-Kommunikation
@SignalRGB/tcp	TCP-Socket-Kommunikation
@SignalRGB/udp	UDP-Socket-Kommunikation
@SignalRGB/base64	Base64-Kodierung und -Dekodierung
@SignalRGB/performance	Performance-Profiling und Frame-Timer
@SignalRGB/appInfo	SignalRGB-Anwendungsversionsinformationen
@SignalRGB/systeminfo	System-Hardwareinformationen
@SignalRGB/permissions	Benutzer-Berechtigungsstatus prüfen
Unter Erweiterte Kommunikation findest du Verwendungsbeispiele für serial, tcp und udp.

---

Verfügbare Features

Ruf device.addFeature("name") in deinem Initialize()-Export auf. Das Feature erstellt ein globales Objekt mit demselben Namen wie das Feature.

Feature-Name	Namespace	Zweck
"keyboard"	keyboard	Tastenanschläge injizieren oder Tastaturereignisse an SignalRGB-Makros weiterleiten
"mouse"	mouse	Mauseingabe injizieren oder Mausereignisse an SignalRGB-Makros weiterleiten
"battery"	battery	Akkustand und Ladezustand für kabellose Geräte melden
"dtls"	dtls	DTLS-verschlüsseltes UDP mit PSK-Authentifizierung

---

Keyboard-Feature

Für Plugins, die Tastaturgeräte darstellen. Ermöglicht das Injizieren echter Tastenanschläge in das OS oder das Auslösen von Ereignissen, die SignalRGB-Makros triggern können.

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

keyboard.sendHid(vkCode, options)

Sendet einen rohen Tastenanschlag direkt an das Betriebssystem über keybd_event. Die Taste erscheint als echte Eingabe für alle Anwendungen — sie umgeht das Makro-System vollständig.

Parameter	Typ	Beschreibung	Beispiel
vkCode	Number	Windows Virtual Key Code	0x41 (Taste A)
options.released	Boolean (erforderlich)	true für Key-Up, false für Key-Down	false

keyboard.sendHid(0x41, { released: false }); // A drücken
keyboard.sendHid(0x41, { released: true });  // A loslassen

keyboard.sendEvent(eventData, eventType)

Leitet ein Tastaturereignis durch das SignalRGB-Makro-System. Makros mit einem onKey-Trigger können diese Ereignisse abgleichen. Injiziert keinen echten Tastenanschlag — nur SignalRGB-Makros sehen dieses Ereignis.

Das Makro-System reichert das Ereignis automatisch mit dem aktuellen Modifikator-Status (Strg, Umschalt, Alt, Win) von der physischen Tastatur an, bevor es übermittelt wird.

Parameter	Typ	Beschreibung	Beispiel
eventData	Object oder String	Ereignisdaten. key (String-Name) und optional keyCode (Zahl) für den Schlüsselabgleich angeben.	{ key: "A", keyCode: 0x41 }
eventType	String	Ereignistyp-Label	"KeyPress"

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

Makro-Skripte erhalten event.Sender (die UID des Plugins) und event.SenderType ("Device"), damit sie von Plugin ausgelöste Ereignisse von echten Hardware-Tastenanschlägen unterscheiden können.

---

Mouse-Feature

Für Plugins, die Maus- oder Zeigegeräte darstellen.

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

mouse.sendHid(buttonCode, options)

Sendet ein rohes Mausereignis über SendInput an das OS. Mausbewegungen (MOUSEEVENTF_MOVE, MOUSEEVENTF_ABSOLUTE) sind aus Sicherheitsgründen blockiert.

Parameter	Typ	Beschreibung
buttonCode	Number	Windows MOUSEEVENTF_*-Flag
options.XButton	Number	Erforderlich für X-Taste-Ereignisse — 1 (X1) oder 2 (X2)
options.WheelDelta	Number	Erforderlich für Mausrad-Ereignisse — positiv scrollt hoch, negativ scrollt runter

Häufige Button-Codes:

Code	Konstante	Beschreibung
0x0002	MOUSEEVENTF_LEFTDOWN	Linke Taste drücken
0x0004	MOUSEEVENTF_LEFTUP	Linke Taste loslassen
0x0008	MOUSEEVENTF_RIGHTDOWN	Rechte Taste drücken
0x0010	MOUSEEVENTF_RIGHTUP	Rechte Taste loslassen
0x0020	MOUSEEVENTF_MIDDLEDOWN	Mittlere Taste drücken
0x0040	MOUSEEVENTF_MIDDLEUP	Mittlere Taste loslassen
0x0800	MOUSEEVENTF_WHEEL	Vertikales Scrollen
0x01000	MOUSEEVENTF_HWHEEL	Horizontales Scrollen
0x0080	MOUSEEVENTF_XDOWN	X-Taste drücken (erfordert XButton-Option)
0x0100	MOUSEEVENTF_XUP	X-Taste loslassen (erfordert XButton-Option)

// Linksklick
mouse.sendHid(0x0002, {});  // gedrückt
mouse.sendHid(0x0004, {});  // losgelassen

// Eine Stufe nach oben scrollen
mouse.sendHid(0x0800, { WheelDelta: 120 });

// X1-Taste drücken
mouse.sendHid(0x0080, { XButton: 1 });
mouse.sendHid(0x0100, { XButton: 1 });

mouse.sendEvent(eventData, eventType)

Leitet ein benutzerdefiniertes Mausereignis durch das SignalRGB-Makro-System. Makro-Skripte mit einem onMouse-Trigger können diese Ereignisse abgleichen. Injiziert keine OS-Mauseingabe.

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

---

Battery-Feature

Für kabellose Geräte, die den Akkustatus melden. Nach Hinzufügen des Features den Akkustand und -zustand aktualisieren, wenn das Gerät sie meldet.

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

Akkuzustand setzen

Methode	Beschreibung
battery.setBatteryLevel(level)	Akkuprozentsatz setzen (0–100)
battery.setBatteryState(state)	Ladezustand mit einer Zustandskonstante setzen

Zustandskonstanten (Zugriff über battery.<name>):

Konstante	Beschreibung
battery.disabled	Akkuberichterstattung deaktiviert
battery.unknown	Zustand noch unbekannt
battery.draining	Läuft auf Akku
battery.charging	Lädt über Kabel
battery.fullCharging	Lädt und bereits voll
battery.full	Vollständig geladen, lädt nicht
battery.wirelessCharging	Kabelloses Laden

Akkuzustand lesen

Diese Eigenschaften spiegeln die zuletzt gesetzten Werte wider:

Eigenschaft	Typ	Beschreibung
battery.batteryLevel	Number	Aktueller Stand (0–100)
battery.batteryState	Number	Aktueller Zustandswert
battery.stateString	String	Lesbares Zustandslabel

Akku-Beispiel

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

export function Render() {
    // Nicht-blockierender Lesevorgang — prüfen, ob das Gerät diesen Frame einen Akkubericht gesendet hat
    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
        );
    }
}