什麼是外掛程式？

SignalRGB 使用以 JavaScript 撰寫的自訂 USB 外掛程式來支援第三方 RGB 裝置。如果您有尚未支援的裝置，您可以為其撰寫自己的外掛程式。如果您有 Arduino 或其他開源微控制器，您也可以建立外掛程式讓 SignalRGB 與其通訊，實現完全 DIY 的 RGB 解決方案。

我們目前發佈的所有外掛程式都是開源的，可在公開的 SignalRGB 外掛程式存儲庫中取得。如果您建立了其他人可以使用的內容，歡迎提交 pull request 或聯絡我們的官方支援！

---

外掛程式的工作原理

外掛程式是 SignalRGB 為特定 USB 裝置載入的單個 JavaScript 檔案。它做兩件事：

1. 描述裝置 — 告訴 SignalRGB 裝置的名稱、ID、LED 佈局和通訊協定的匯出函數。
2. 驅動裝置 — SignalRGB 呼叫的生命週期函數，用於初始化裝置、每幀發送顏色以及在退出時進行清理。

---

外掛程式結構

每個外掛程式都遵循相同的基本形式：

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

---

生命週期

Initialize

在裝置連接或重新連接時，以及在裝置設定頁面上啟用串流切換時呼叫一次。用於任何啟動工作：將裝置切換到軟體控制模式、發送韌體握手、讀取已儲存的設定等。

如果有任何衝突程序正在執行，初始化將等待直到它們關閉或使用者繞過檢查。

Render

渲染循環是外掛程式的核心。SignalRGB 每幀呼叫 Render()。每幀的順序為：

1. 使用者設定更新
2. 顏色從 canvas 提取到裝置的像素緩衝區
3. 任何 on*Changed 回調觸發（按更改發生的順序）
4. 呼叫 Render()

在 Render() 內部，您呼叫 device.color(x, y) 來讀取像素顏色並將其發送到硬體。預設幀間隔為 30ms。

Shutdown

在 SignalRGB 正常退出或串流切換停用時呼叫。如果您的裝置有硬體燈光模式，請在此處還原，這樣當 SignalRGB 未執行時使用者的 LED 就不會熄滅。

on*Changed 回調

面向使用者的控制項（請參閱 ControllableParameters）可以各自有一個匹配的回調，在使用者更改該設定時在 Render() 之前觸發。函數命名為 on[propertyName]Changed() — 區分大小寫。

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

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

內建的 onBrightnessChanged() 回調在移動裝置的主亮度滑桿時觸發。

---

定義裝置

這些匯出告訴 SignalRGB 在連接之前需要了解的有關裝置的所有資訊。

Name 和 Publisher

顯示在 SignalRGB UI 中。

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

VendorId 和 ProductId

SignalRGB 用於在系統上找到裝置的 USB ID。必須是精確的十六進位值。如果您的外掛程式未出現，最可能的原因是 ID 不匹配。

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

Type

設定 USB 通訊協定。如果未匯出，預設為 "hid"。請參閱確定裝置類型以獲取完整清單和選擇方式。

export function Type() { return "hid"; }     // HID（大多數裝置）
export function Type() { return "rawusb"; }  // 原始 USB / libusb
export function Type() { return "hybrid"; }  // 兩者同時
export function Type() { return "serial"; }  // COM 連接埠

Size、LedNames 和 LedPositions

這三個匯出共同定義了裝置在 canvas 上的顯示方式。

• Size() — 裝置像素網格的邊界框 [寬度, 高度]。device.color() 只能取樣此框內的坐標。
• LedNames() — 有序的 LED 名稱陣列。名稱應遵循支援的按鍵名稱清單，以啟用按鍵特效和 LED 繪製。
• LedPositions() — Size 網格內 [x, y] 位置的有序陣列，每個 LED 一個，與 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

控制 SignalRGB 開啟哪些 USB 端點。每個發現的端點都會傳遞給 Validate() — 返回 true 以開啟它，返回 false 跳過它。您可以開啟多個端點，並在執行時使用 device.set_endpoint() 在它們之間切換。

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

請參閱選擇端點了解如何找到正確的值。

ControllableParameters

返回顯示在裝置設定頁面上的面向使用者的設定陣列。請參閱使用者控制項以獲取完整結構描述。

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

與此外掛程式衝突的 exe 名稱清單。如果這些程式中的任何一個正在執行，SignalRGB 將不會初始化。名稱必須完全匹配。

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

ImageUrl

SignalRGB UI 中顯示的裝置圖片 URL。標準尺寸為 1024×1024，有效區域為 920×920。

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

---

後續步驟

• 外掛程式模板 — 可直接編輯的起始點
• 寫入與讀取 — 向裝置發送資料
• 確定裝置類型 — 選擇正確的協定
• 選擇端點 — 找到正確的 USB 端點
• 使用者控制項 — 在裝置設定頁面中新增設定
• 模組和功能 — 電池、鍵盤/滑鼠注入、網路等