Apakah Plugin?

SignalRGB menggunakan plugin USB tersuai, yang ditulis dalam JavaScript, untuk menyokong peranti RGB pihak ketiga. Jika Anda mempunyai peranti yang belum disokong, Anda boleh menulis plugin Anda sendiri untuknya. Jika Anda mempunyai Arduino atau pengawal mikro sumber terbuka lain, Anda juga boleh mencipta plugin untuk SignalRGB berkomunikasi dengannya untuk penyelesaian RGB DIY sepenuhnya.

Plugin yang dikeluarkan kami pada masa ini semuanya adalah sumber terbuka dan tersedia di repositori plugin SignalRGB awam. Jika Anda telah mencipta sesuatu yang boleh digunakan oleh orang lain, jangan ragu untuk mengeluarkan pull request atau hubungi sokongan rasmi kami!

---

Cara Plugin Berfungsi

Plugin adalah satu fail JavaScript yang dimuatkan oleh SignalRGB untuk peranti USB tertentu. Ia melakukan dua perkara:

1. Menerangkan peranti — eksport yang memberitahu SignalRGB nama peranti, ID, susun atur LED, dan protokol komunikasi.
2. Memandu peranti — fungsi kitaran hayat yang dipanggil oleh SignalRGB untuk memulakan peranti, menghantar warna setiap bingkai, dan membersihkan pada keluar.

---

Struktur Plugin

Setiap plugin mengikuti bentuk asas yang sama:

// ── 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();
}

---

Kitaran Hayat

Initialize

Dipanggil sekali apabila peranti disambungkan atau disambungkan semula, dan setiap kali togol penstriman didayakan pada halaman konfigurasi peranti. Gunakan untuk sebarang kerja permulaan: menukar peranti ke mod kawalan perisian, menghantar jabat tangan firmware, membaca konfigurasi yang disimpan, dll.

Jika sebarang proses yang bercanggah sedang berjalan, permulaan menunggu sehingga ia ditutup atau pengguna memintas pemeriksaan.

Render

Gelung render adalah inti plugin. SignalRGB memanggil Render() setiap bingkai. Urutan setiap bingkai adalah:

1. Tetapan pengguna dikemas kini
2. Warna ditarik dari kanvas ke dalam penimbal piksel peranti
3. Sebarang panggilan balik on*Changed diaktifkan (mengikut urutan perubahan berlaku)
4. Render() dipanggil

Di dalam Render() Anda memanggil device.color(x, y) untuk membaca warna piksel dan menghantarnya ke perkakasan. Selang bingkai lalai adalah 30ms.

Shutdown

Dipanggil apabila SignalRGB keluar dengan sopan atau togol penstriman dilumpuhkan. Jika peranti Anda mempunyai mod pencahayaan perkakasan, pulihkan di sini supaya LED pengguna tidak padam apabila SignalRGB tidak berjalan.

Panggilan Balik on*Changed

Kawalan yang menghadap pengguna (lihat ControllableParameters) masing-masing boleh mempunyai panggilan balik yang sepadan yang diaktifkan sebelum Render() setiap kali pengguna mengubah tetapan tersebut. Namakan fungsi on[propertyName]Changed() — ia sensitif terhadap huruf besar-kecil.

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

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

Panggilan balik terbina dalam onBrightnessChanged() diaktifkan apabila gelangsar kecerahan utama peranti digerakkan.

---

Mentakrifkan Peranti

Eksport ini memberitahu SignalRGB semua yang perlu diketahui tentang peranti sebelum ia disambungkan.

Name dan Publisher

Dipaparkan dalam UI SignalRGB.

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

VendorId dan ProductId

ID USB yang digunakan SignalRGB untuk mencari peranti pada sistem. Mesti berupa nilai heks yang tepat. Jika plugin Anda tidak muncul, ID yang tidak sepadan adalah kemungkinan punca utamanya.

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

Type

Menetapkan protokol komunikasi USB. Lalai kepada "hid" jika tidak dieksport. Lihat Menentukan Jenis Peranti untuk senarai penuh dan cara memilih.

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, dan LedPositions

Tiga eksport ini bersama-sama menentukan cara peranti kelihatan pada kanvas.

• Size() — kotak pembatas [lebar, tinggi] grid piksel peranti. device.color() hanya boleh mengambil sampel koordinat dalam kotak ini.
• LedNames() — susunan nama LED yang tersusun. Nama harus mengikuti senarai nama kekunci yang disokong untuk mendayakan kesan ketukan kekunci dan lukisan LED.
• LedPositions() — susunan kedudukan [x, y] yang tersusun dalam grid Size, satu per LED, sepadan dengan urutan 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

Mengawal endpoint USB mana yang dibuka oleh SignalRGB. Setiap endpoint yang ditemui dihantar ke Validate() — kembalikan true untuk membukanya, false untuk melangkaukannya. Anda boleh membuka berbilang endpoint dan bertukar antara mereka semasa runtime dengan device.set_endpoint().

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

Lihat Memilih Endpoint untuk cara mencari nilai yang betul.

ControllableParameters

Mengembalikan susunan tetapan yang menghadap pengguna yang muncul pada halaman konfigurasi peranti. Lihat Kawalan Pengguna untuk skema penuh.

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

Senarai nama exe yang bercanggah dengan plugin ini. SignalRGB tidak akan memulakan selagi mana-mana daripada ini sedang berjalan. Nama mesti sepadan dengan tepat.

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

ImageUrl

URL imej peranti yang ditunjukkan dalam UI SignalRGB. Saiz standard adalah 1024×1024 dengan kawasan aktif 920×920.

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

---

Langkah Seterusnya

• Templat Plugin — titik permulaan yang sedia untuk diedit
• Penulisan dan Pembacaan — menghantar data ke peranti
• Menentukan Jenis Peranti — memilih protokol yang betul
• Memilih Endpoint — mencari endpoint USB yang betul
• Kawalan Pengguna — menambah tetapan ke halaman konfigurasi peranti
• Modul dan Ciri — bateri, suntikan papan kekunci/tetikus, rangkaian, dan lagi