Apa itu Plugin?

SignalRGB menggunakan plugin USB kustom yang dibuat dalam JavaScript untuk mendukung perangkat RGB pihak ketiga. Jika Anda memiliki perangkat yang belum didukung, Anda dapat menulis plugin sendiri untuknya. Jika Anda memiliki Arduino atau mikrokontroler open-source lainnya, Anda juga dapat membuat plugin agar SignalRGB berkomunikasi dengannya untuk solusi RGB yang sepenuhnya DIY.

Plugin yang telah kami rilis saat ini semuanya open-source dan tersedia di repositori plugin SignalRGB publik. Jika Anda telah membuat sesuatu yang dapat digunakan orang lain, jangan ragu untuk mengajukan pull request atau menghubungi dukungan resmi kami!

---

Cara Kerja Plugin

Plugin adalah satu file JavaScript yang dimuat SignalRGB untuk perangkat USB tertentu. Plugin melakukan dua hal:

1. Mendeskripsikan perangkat — ekspor yang memberi tahu SignalRGB nama perangkat, ID, tata letak LED, dan protokol komunikasi.
2. Mengendalikan perangkat — fungsi lifecycle yang dipanggil SignalRGB untuk menginisialisasi perangkat, mengirim warna setiap frame, dan membersihkan saat keluar.

---

Struktur Plugin

Setiap plugin mengikuti bentuk dasar 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();
}

---

Lifecycle

Initialize

Dipanggil sekali saat perangkat terhubung atau terhubung kembali, dan setiap kali toggle streaming diaktifkan di halaman konfigurasi perangkat. Gunakan untuk pekerjaan startup apa pun: mengalihkan perangkat ke mode kontrol software, mengirim handshake firmware, membaca konfigurasi yang tersimpan, dll.

Jika ada proses yang konflik yang berjalan, inisialisasi menunggu hingga proses tersebut ditutup atau pengguna melewati pemeriksaan.

Render

Loop render adalah inti dari plugin. SignalRGB memanggil Render() setiap frame. Urutan setiap frame adalah:

1. Pengaturan pengguna diperbarui
2. Warna diambil dari canvas ke buffer piksel perangkat
3. Callback on*Changed apa pun dipanggil (dalam urutan perubahan terjadi)
4. Render() dipanggil

Di dalam Render() Anda memanggil device.color(x, y) untuk membaca warna piksel dan mengirimkannya ke hardware. Interval frame default adalah 30ms.

Shutdown

Dipanggil saat SignalRGB keluar dengan normal atau toggle streaming dinonaktifkan. Jika perangkat Anda memiliki mode pencahayaan hardware, kembalikan di sini agar LED pengguna tidak mati saat SignalRGB tidak berjalan.

Callback on*Changed

Kontrol yang dihadapkan ke pengguna (lihat ControllableParameters) masing-masing dapat memiliki callback yang cocok yang dipanggil sebelum Render() setiap kali pengguna mengubah pengaturan tersebut. Beri nama fungsi on[propertyName]Changed() — ini case-sensitive.

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

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

Callback bawaan onBrightnessChanged() dipanggil saat slider kecerahan utama perangkat digeser.

---

Mendefinisikan Perangkat

Ekspor ini memberi tahu SignalRGB semua yang perlu diketahui tentang perangkat sebelum terhubung.

Name dan Publisher

Ditampilkan di UI SignalRGB.

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

VendorId dan ProductId

ID USB yang digunakan SignalRGB untuk menemukan perangkat di sistem. Harus berupa nilai hex yang tepat. Jika plugin Anda tidak muncul, ID yang tidak cocok adalah penyebab yang paling mungkin.

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

Type

Mengatur protokol komunikasi USB. Default ke "hid" jika tidak diekspor. Lihat Menentukan Tipe Perangkat untuk daftar lengkap dan cara memilihnya.

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

Ketiga ekspor ini bersama-sama mendefinisikan bagaimana perangkat muncul di canvas.

• Size() — kotak pembatas [lebar, tinggi] dari grid piksel perangkat. device.color() hanya dapat mengambil sampel koordinat di dalam kotak ini.
• LedNames() — array nama LED yang berurutan. Nama harus mengikuti daftar nama kunci yang didukung untuk mengaktifkan efek penekanan tombol dan pengecatan LED.
• LedPositions() — array posisi [x, y] yang berurutan di dalam grid Size, satu per LED, sesuai 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

Mengontrol endpoint USB mana yang dibuka SignalRGB. Setiap endpoint yang ditemukan diteruskan ke Validate() — kembalikan true untuk membukanya, false untuk melewatinya. Anda dapat membuka beberapa endpoint dan beralih di antara mereka saat runtime dengan device.set_endpoint().

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

Lihat Memilih Endpoint untuk cara menemukan nilai yang tepat.

ControllableParameters

Mengembalikan array pengaturan yang dihadapkan ke pengguna yang muncul di halaman konfigurasi perangkat. Lihat Kontrol Pengguna untuk skema lengkapnya.

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

Daftar nama exe yang konflik dengan plugin ini. SignalRGB tidak akan menginisialisasi selama ada yang berjalan. Nama harus cocok persis.

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

ImageUrl

URL gambar perangkat yang ditampilkan di UI SignalRGB. Ukuran standar adalah 1024×1024 dengan area live 920×920.

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

---

Langkah Selanjutnya

• Template Plugin — titik awal yang siap diedit
• Writes dan Reads — mengirim data ke perangkat
• Menentukan Tipe Perangkat — memilih protokol yang tepat
• Memilih Endpoint — menemukan endpoint USB yang tepat
• Kontrol Pengguna — menambahkan pengaturan ke halaman konfigurasi perangkat
• Modul dan Fitur — baterai, injeksi keyboard/mouse, jaringan, dan lainnya