Czym jest wtyczka?

SignalRGB używa niestandardowych wtyczek USB, napisanych w JavaScript, aby obsługiwać urządzenia RGB firm trzecich. Jeśli masz urządzenie, które nie jest jeszcze obsługiwane, możesz sam napisać wtyczkę. Jeśli masz Arduino lub inny mikrokontroler open-source, możesz również stworzyć wtyczkę dla SignalRGB, aby się z nim komunikować dla w pełni własnoręcznie wykonanych rozwiązań RGB.

Nasze aktualnie wydane wtyczki są wszystkie open-source i dostępne w publicznym repozytorium wtyczek SignalRGB. Jeśli stworzyłeś coś, z czego inni mogą korzystać, możesz swobodnie przesłać pull request lub skontaktować się z naszym oficjalnym wsparciem!

---

Jak działa wtyczka

Wtyczka to pojedynczy plik JavaScript, który SignalRGB ładuje dla konkretnego urządzenia USB. Wykonuje dwie czynności:

1. Opisuje urządzenie — eksporty, które informują SignalRGB o nazwie, identyfikatorach, układzie LED i protokole komunikacyjnym urządzenia.
2. Steruje urządzeniem — funkcje cyklu życia, które SignalRGB wywołuje, aby zainicjować urządzenie, wysyłać kolory w każdej klatce i sprzątać przy wyłączeniu.

---

Struktura wtyczki

Każda wtyczka ma tę samą podstawową formę:

// ── Device identity ──────────────────────────────────────
export function Name()      { return "My Device"; }
export function Publisher() { return "Your Name"; }
export function VendorId()  { return 0x1234; }
export function ProductId() { return 0x5678; }
export function Type()      { return "hid"; }

// ── Canvas size and LED layout ────────────────────────────
export function Size()      { return [7, 3]; }
export function LedNames()  { return ["Logo", "Left", "Right"]; }
export function LedPositions() { return [[3,1], [0,1], [6,1]]; }

// ── Lifecycle ─────────────────────────────────────────────
export function Initialize() {
    // Called once when the device connects or streaming is enabled.
    // Send any initialization packets the device needs here.
    SendInitPacket();
}

export function Render() {
    // Called every frame (~30ms by default).
    // Read colors from the canvas and send them to the device.
    SendColors();
}

export function Shutdown() {
    // Called when SignalRGB exits or streaming is disabled.
    // Return the device to hardware mode here if needed.
    SetHardwareControl();
}

---

Cykl życia

Initialize

Wywoływany raz, gdy urządzenie się łączy lub ponownie łączy, oraz za każdym razem, gdy przełącznik strumieniowania jest włączony na stronie konfiguracji urządzenia. Używaj go do pracy startowej: przełączanie urządzenia w tryb sterowania oprogramowaniem, wysyłanie uścisków dłoni z oprogramowaniem układowym, czytanie zapisanej konfiguracji itp.

Jeśli aktywne są konfliktujące procesy, inicjalizacja czeka, aż zostaną zamknięte lub użytkownik pominie sterowanie.

Render

Pętla renderowania to serce wtyczki. SignalRGB wywołuje Render() w każdej klatce. Kolejność w klatce to:

1. Ustawienia użytkownika są aktualizowane
2. Kolory są pobierane z canvas do bufora pikseli urządzenia
3. Wszelkie callbacki on*Changed są wykonywane (w kolejności zmian)
4. Wywoływana jest Render()

Wewnątrz Render() wywołujesz device.color(x, y), aby odczytać kolory pikseli i wysłać je do sprzętu. Domyślny interwał klatki wynosi 30ms.

Shutdown

Wywoływany, gdy SignalRGB poprawnie się zamyka lub przełącznik strumieniowania jest wyłączony. Jeśli twoje urządzenie ma oświetlenie sprzętowe, przywróć je tutaj, aby diody LED użytkownika nie zgasły, gdy SignalRGB nie jest aktywny.

Callbacki on*Changed

Sterowania skierowane do użytkownika (patrz ControllableParameters) mogą każde mieć pasujący callback, który jest wykonywany przed Render(), gdy użytkownik zmienia to ustawienie. Nadaj funkcji nazwę on[nazwaWłaściwości]Changed() — rozróżnia wielkość liter.

// ControllableParameters entry:
{ "property": "dpi1", "label": "DPI", "type": "number", "min": "200", "max": "18000", "default": "800" }

// Matching callback:
export function ondpi1Changed() {
    setDpi(dpi1);
}

Wbudowany callback onBrightnessChanged() jest wykonywany, gdy główny suwak jasności urządzenia jest przesuwany.

---

Definiowanie urządzenia

Te eksporty mówią SignalRGB wszystko, co musi wiedzieć o urządzeniu przed połączeniem.

Name i Publisher

Wyświetlane w UI SignalRGB.

export function Name()      { return "Corsair K70 RGB"; }
export function Publisher() { return "YourName"; }

VendorId i ProductId

Identyfikatory USB, których SignalRGB używa do znalezienia urządzenia w systemie. Muszą być dokładnymi wartościami szesnastkowymi. Jeśli twoja wtyczka się nie pojawia, nieprawidłowy identyfikator jest najbardziej prawdopodobną przyczyną.

export function VendorId()  { return 0x1B1C; }
export function ProductId() { return 0x1B49; }

Type

Ustawia protokół komunikacji USB. Domyślnie ustawiany na "hid", jeśli nie jest eksportowany. Zobacz Określanie typu urządzenia, aby zapoznać się z pełną listą i sposobem wyboru.

export function Type() { return "hid"; }     // HID (większość urządzeń)
export function Type() { return "rawusb"; }  // Raw USB / libusb
export function Type() { return "hybrid"; }  // Oba jednocześnie
export function Type() { return "serial"; }  // Port COM

Size, LedNames i LedPositions

Te trzy eksporty razem definiują, jak urządzenie pojawia się na canvas.

• Size() — ramka ograniczająca [szerokość, wysokość] siatki pikseli urządzenia. device.color() może próbkować tylko współrzędne w tej ramce.
• LedNames() — uporządkowana tablica nazw LED. Nazwy powinny być zgodne z obsługiwanymi nazwami klawiszy, aby włączyć efekty naciśnięcia klawiszy i malowanie LED.
• LedPositions() — uporządkowana tablica pozycji [x, y] w siatce Size, jedna na LED, odpowiadająca kolejności LedNames.

export function Size()         { return [7, 3]; }
export function LedNames()     { return ["Logo", "Left Side", "Right Side"]; }
export function LedPositions() { return [[3, 1], [0, 1], [6, 1]]; }

Validate

Określa, które punkty końcowe USB SignalRGB otwiera. Każdy wykryty punkt końcowy jest przekazywany do Validate() — zwróć true, aby go otworzyć, false, aby go pominąć. Możesz otwierać wiele punktów końcowych i przełączać się między nimi w czasie wykonywania za pomocą device.set_endpoint().

export function Validate(endpoint) {
    return endpoint.interface === 2 && endpoint.usage_page === 0xFF00;
}

Zobacz Wybieranie punktów końcowych, aby znaleźć odpowiednie wartości.

ControllableParameters

Zwraca tablicę ustawień skierowanych do użytkownika, które pojawiają się na stronie konfiguracji urządzenia. Zobacz Kontrolki użytkownika, aby zapoznać się z pełnym schematem.

export function ControllableParameters() {
    return [
        { "property": "LightingMode", "label": "Lighting Mode", "type": "combobox",
          "values": ["Software", "Hardware"], "default": "Software" },
        { "property": "DPILevel", "label": "DPI", "type": "number",
          "min": "200", "max": "18000", "step": "50", "default": "800" }
    ];
}

ConflictingProcesses

Lista nazw plików exe, które kolidują z tą wtyczką. SignalRGB nie inicjuje się, gdy którykolwiek z nich jest aktywny. Nazwy muszą dokładnie pasować.

export function ConflictingProcesses() {
    return ["iCUE.exe", "CorsairHID.exe"];
}

ImageUrl

Adres URL obrazu urządzenia wyświetlanego w UI SignalRGB. Standardowy format to 1024×1024 z obszarem aktywnym 920×920.

export function ImageUrl() { return "https://..."; }

---

Następne kroki

• Szablon wtyczki — gotowy do edycji punkt startowy
• Zapisy i odczyty — wysyłanie danych do urządzenia
• Określanie typu urządzenia — wybór właściwego protokołu
• Wybieranie punktów końcowych — znajdowanie właściwego punktu końcowego USB
• Kontrolki użytkownika — dodawanie ustawień do strony konfiguracji urządzenia
• Moduły i funkcje — bateria, iniekcja klawiatury/myszy, sieć i więcej