Hvad er et plugin?

SignalRGB bruger brugerdefinerede USB-plugins skrevet i JavaScript til at understøtte RGB-enheder fra tredjeparter. Hvis du har en enhed, der endnu ikke understøttes, kan du selv skrive et plugin til den. Hvis du har en Arduino eller en anden open source-mikrocontroller, kan du også oprette et plugin, så SignalRGB kan kommunikere med den, og lave fuldt hjemmebyggede RGB-løsninger.

Alle vores hidtil udgivne plugins har læsbar kildekode og kan ses i det offentlige SignalRGB plugins-repository. Hvis du har skabt noget, som andre kan bruge, er du velkommen til at oprette en pull request eller kontakte vores officielle support!

---

Sådan fungerer et plugin

Et plugin er en enkelt JavaScript-fil, som SignalRGB indlæser for en bestemt USB-enhed. Den gør to ting:

1. Beskriver enheden – exports, der fortæller SignalRGB enhedens navn, ID’er, LED-layout og kommunikationsprotokol.
2. Styrer enheden – livscyklusfunktioner, som SignalRGB kalder for at initialisere enheden, sende farver hvert frame og rydde op ved afslutning.

---

Pluginstruktur

Alle plugins følger den samme grundlæggende 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();
}

---

Livscyklus

Initialize

Kaldes én gang, når en enhed tilsluttes eller genforbindes, og hver gang streaming-kontakten slås til på enhedens konfigurationsside. Brug den til alt opstartsarbejde: at skifte enheden til softwarestyringstilstand, sende firmware-handshakes, læse gemt konfiguration osv.

Hvis der kører modstridende processer, venter initialiseringen, indtil de lukkes, eller brugeren springer kontrollen over.

Render

Render-løkken er kernen i pluginet. SignalRGB kalder Render() hvert frame. Rækkefølgen i hvert frame er:

1. Brugerindstillinger opdateres
2. Farver hentes fra canvas’et ind i enhedens pixelbuffer
3. Eventuelle on*Changed-callbacks udløses (i den rækkefølge, ændringerne skete)
4. Render() kaldes

Inde i Render() kalder du device.color(x, y) for at læse pixelfarver og sende dem til hardwaren. Standardintervallet mellem frames er 30 ms.

Shutdown

Kaldes, når SignalRGB afsluttes korrekt, eller streaming-kontakten slås fra. Hvis din enhed har en hardwarebelysningstilstand, skal du gendanne den her, så brugerens LED’er ikke bliver mørke, når SignalRGB ikke kører.

on*Changed-callbacks

Brugervendte kontroller (se ControllableParameters) kan hver have en tilsvarende callback, der udløses før Render(), når brugeren ændrer den pågældende indstilling. Navngiv funktionen on[propertyName]Changed() – der skelnes mellem store og små bogstaver.

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

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

Den indbyggede callback onBrightnessChanged() udløses, når enhedens primære lysstyrkeskyder flyttes.

---

Definition af enheden

Disse exports fortæller SignalRGB alt, hvad den behøver at vide om enheden, før den forbindes.

Name og Publisher

Vises i SignalRGB’s brugerflade.

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

VendorId og ProductId

De USB-ID’er, SignalRGB bruger til at finde enheden på systemet. De skal være præcise hex-værdier. Hvis dit plugin ikke vises, er et forkert ID den mest sandsynlige årsag.

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

Type

Angiver USB-kommunikationsprotokollen. Standard er "hid", hvis den ikke eksporteres. Se Bestemmelse af enhedstype for den fulde liste og hvordan du vælger.

export function Type() { return "hid"; }     // HID (most devices)
export function Type() { return "rawusb"; }  // Raw USB / libusb
export function Type() { return "hybrid"; }  // Both simultaneously
export function Type() { return "serial"; }  // COM port

Size, LedNames og LedPositions

Disse tre exports definerer tilsammen, hvordan enheden vises på canvas’et.

• Size() – afgrænsningsboksen [width, height] for enhedens pixelgitter. device.color() kan kun sample koordinater inden for denne boks.
• LedNames() – et ordnet array af LED-navne. Navnene bør følge listen over understøttede tastnavne for at muliggøre tastetrykeffekter og LED-maling.
• LedPositions() – et ordnet array af [x, y]-positioner inden for Size-gitteret, én pr. LED, i samme rækkefølge som 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

Styrer, hvilke USB-endpoints SignalRGB åbner. Hvert fundet endpoint sendes til Validate() – returner true for at åbne det og false for at springe det over. Du kan åbne flere endpoints og skifte mellem dem under kørsel med device.set_endpoint().

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

Se Valg af endpoints for at finde de rigtige værdier.

ControllableParameters

Returnerer et array af brugervendte indstillinger, der vises på enhedens konfigurationsside. Se Brugerkontroller for det fulde skema.

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

En liste over exe-navne, der er i konflikt med dette plugin. SignalRGB initialiserer ikke, mens nogen af disse kører. Navnene skal matche præcist.

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

ImageUrl

URL’en til enhedens billede, der vises i SignalRGB’s brugerflade. Standardstørrelsen er 1024×1024 med et aktivt område på 920×920.

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

---

Næste trin

• Plugin-skabelon – et klar-til-redigering udgangspunkt
• Skrivning og læsning – afsendelse af data til enheden
• Bestemmelse af enhedstype – valg af den rigtige protokol
• Valg af endpoints – find det rigtige USB-endpoint
• Brugerkontroller – tilføjelse af indstillinger til enhedens konfigurationsside
• Moduler og funktioner – batteri, tastatur-/museinjektion, netværk og mere