Moduły i funkcje

Wtyczki mogą rozszerzać swoje możliwości poza podstawowe operacje odczytu i zapisu USB za pomocą dwóch systemów: Modułów i Funkcji. Zrozumienie różnicy pomaga odkryć, co jest dostępne i używać właściwego mechanizmu.

Moduły a funkcje

	Moduły	Funkcje
Jak używać	`import { x } from "@SignalRGB/nazwa"`	`device.addFeature("nazwa")` w `Initialize()`
Cel	Usługi narzędziowe (sieć, kodowanie, info systemowe)	Możliwości urządzenia (bateria, wstrzykiwanie wejścia)
Przestrzeń nazw	Własne wyeksportowane nazwy modułu	`device.nazwafunkcji.*`
Instancje	Jedna na wtyczkę	Może być wiele

Dostępne moduły

Importuj je na górze pliku wtyczki.

Ścieżka importu	Cel
`@SignalRGB/serial`	Komunikacja szeregowa/przez port COM
`@SignalRGB/tcp`	Komunikacja przez gniazdo TCP
`@SignalRGB/udp`	Komunikacja przez gniazdo UDP
`@SignalRGB/base64`	Kodowanie i dekodowanie Base64
`@SignalRGB/performance`	Profilowanie wydajności i timery klatek
`@SignalRGB/appInfo`	Informacje o wersji aplikacji SignalRGB
`@SignalRGB/systeminfo`	Informacje o sprzęcie systemowym
`@SignalRGB/permissions`	Sprawdzanie statusu uprawnień użytkownika

Zobacz Zaawansowana komunikacja dla przykładów użycia serial, tcp i udp.

Dostępne funkcje

Wywołaj device.addFeature("nazwa") w swoim eksporcie Initialize(). Funkcja tworzy globalny obiekt o tej samej nazwie co funkcja.

Nazwa funkcji	Przestrzeń nazw	Cel
`"keyboard"`	`keyboard`	Wstrzykiwanie naciśnięć klawiszy lub kierowanie zdarzeń klawiatury do makr SignalRGB
`"mouse"`	`mouse`	Wstrzykiwanie wejścia myszy lub kierowanie zdarzeń myszy do makr SignalRGB
`"battery"`	`battery`	Raportowanie poziomu baterii i statusu ładowania dla urządzeń bezprzewodowych
`"dtls"`	`dtls`	Szyfrowany UDP DTLS z uwierzytelnianiem PSK

Funkcja klawiatury

Dla wtyczek reprezentujących urządzenia klawiaturowe. Pozwala wstrzykiwać prawdziwe naciśnięcia klawiszy do systemu operacyjnego lub aktywować zdarzenia, które mogą uruchamiać makra SignalRGB.

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

keyboard.sendHid(vkCode, options)

Wysyła surowe naciśnięcie klawisza bezpośrednio do systemu operacyjnego przez keybd_event. Klawisz pojawia się jako prawdziwe wejście dla wszystkich aplikacji — całkowicie omija system makr.

Parametr	Typ	Opis	Przykład
vkCode	Liczba	Wirtualny kod klawisza Windows	0x41 (klawisz A)
options.released	Boolean (wymagane)	`true` dla zwolnienia klawisza, `false` dla naciśnięcia	false

keyboard.sendHid(0x41, { released: false }); // Naciśnij A
keyboard.sendHid(0x41, { released: true });  // Zwolnij A

keyboard.sendEvent(eventData, eventType)

Kieruje zdarzenie klawiatury przez system makr SignalRGB. Makra z wyzwalaczem onKey mogą dopasowywać te zdarzenia. Nie wstrzykuje prawdziwego naciśnięcia klawisza — tylko makra SignalRGB widzą to zdarzenie.

System makr automatycznie wzbogaca zdarzenie o aktualny status modyfikatorów (Ctrl, Shift, Alt, Win) z fizycznej klawiatury przed wysłaniem.

Parametr	Typ	Opis	Przykład
eventData	Obiekt lub String	Dane zdarzenia. Dodaj `key` (nazwa ciągu) i opcjonalnie `keyCode` (liczba) do dopasowywania klawiszy.	`{ key: "A", keyCode: 0x41 }`
eventType	String	Etykieta typu zdarzenia	`"KeyPress"`

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

Skrypty makr otrzymują event.Sender (UID wtyczki) i event.SenderType ("Device"), dzięki czemu mogą odróżnić zdarzenia pochodzące z wtyczki od prawdziwych naciśnięć klawiszy sprzętowych.

Funkcja myszy

Dla wtyczek reprezentujących urządzenia mysz lub wskaźnikowe.

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

mouse.sendHid(buttonCode, options)

Wysyła surowe zdarzenie myszy do systemu operacyjnego przez SendInput. Ruch myszy (MOUSEEVENTF_MOVE, MOUSEEVENTF_ABSOLUTE) jest zablokowany ze względów bezpieczeństwa.

Parametr	Typ	Opis
buttonCode	Liczba	Flaga Windows `MOUSEEVENTF_*`
options.XButton	Liczba	Wymagane dla zdarzeń przycisku X — `1` (X1) lub `2` (X2)
options.WheelDelta	Liczba	Wymagane dla zdarzeń kółka przewijania — dodatnie przewija w górę, ujemne w dół

Często używane kody przycisków:

Kod	Stała	Opis
`0x0002`	`MOUSEEVENTF_LEFTDOWN`	Naciśnięcie lewego przycisku
`0x0004`	`MOUSEEVENTF_LEFTUP`	Zwolnienie lewego przycisku
`0x0008`	`MOUSEEVENTF_RIGHTDOWN`	Naciśnięcie prawego przycisku
`0x0010`	`MOUSEEVENTF_RIGHTUP`	Zwolnienie prawego przycisku
`0x0020`	`MOUSEEVENTF_MIDDLEDOWN`	Naciśnięcie środkowego przycisku
`0x0040`	`MOUSEEVENTF_MIDDLEUP`	Zwolnienie środkowego przycisku
`0x0800`	`MOUSEEVENTF_WHEEL`	Przewijanie pionowe
`0x01000`	`MOUSEEVENTF_HWHEEL`	Przewijanie poziome
`0x0080`	`MOUSEEVENTF_XDOWN`	Naciśnięcie przycisku X (wymaga opcji `XButton`)
`0x0100`	`MOUSEEVENTF_XUP`	Zwolnienie przycisku X (wymaga opcji `XButton`)

// Left click
mouse.sendHid(0x0002, {});  // down
mouse.sendHid(0x0004, {});  // up

// Scroll up one notch
mouse.sendHid(0x0800, { WheelDelta: 120 });

// X1 button press
mouse.sendHid(0x0080, { XButton: 1 });
mouse.sendHid(0x0100, { XButton: 1 });

mouse.sendEvent(eventData, eventType)

Kieruje niestandardowe zdarzenie myszy przez system makr SignalRGB. Skrypty makr z wyzwalaczem onMouse mogą dopasowywać te zdarzenia. Nie wstrzykuje wejścia myszy na poziomie systemu operacyjnego.

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

Funkcja baterii

Dla urządzeń bezprzewodowych raportujących status baterii. Po dodaniu funkcji aktualizuj poziom baterii i status za każdym razem, gdy urządzenie to raportuje.

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

Ustawianie statusu baterii

Metoda	Opis
`battery.setBatteryLevel(level)`	Ustawia procent baterii (0–100)
`battery.setBatteryState(state)`	Ustawia status ładowania za pomocą stałej stanu

Stałe stanu (dostępne przez battery.<nazwa>):

Stała	Opis
`battery.disabled`	Raportowanie baterii wyłączone
`battery.unknown`	Stan jeszcze nieznany
`battery.draining`	Działa na baterii
`battery.charging`	Ładowanie przez kabel
`battery.fullCharging`	Ładowanie i już pełna
`battery.full`	W pełni naładowana, nie ładuje się
`battery.wirelessCharging`	Ładowanie bezprzewodowe

Odczytywanie statusu baterii

Te właściwości odzwierciedlają ostatnio ustawione wartości:

Właściwość	Typ	Opis
`battery.batteryLevel`	Liczba	Aktualny poziom (0–100)
`battery.batteryState`	Liczba	Aktualna wartość stanu
`battery.stateString`	String	Czytelna etykieta stanu

Przykład baterii

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

export function Render() {
    // Non-blocking read — check if the device sent a battery report this 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
        );
    }
}