什么是插件？

SignalRGB 使用以 JavaScript 编写的自定义 USB 插件来支持第三方 RGB 设备。如果您有一个尚未受支持的设备，您可以为其编写自己的插件。如果您有 Arduino 或其他开源微控制器，您也可以创建一个插件，让 SignalRGB 与其通信，实现完全 DIY 的 RGB 解决方案。

我们目前发布的所有插件都是开源的，并在公共 SignalRGB 插件仓库中提供。如果您创建了其他人可以使用的内容，欢迎提交 pull request 或联系我们的官方支持！

---

插件的工作原理

插件是 SignalRGB 为特定 USB 设备加载的单个 JavaScript 文件。它完成两件事：

1. 描述设备 — 导出函数，告知 SignalRGB 设备的名称、ID、LED 布局和通信协议。
2. 驱动设备 — 生命周期函数，SignalRGB 调用这些函数来初始化设备、每帧发送颜色，以及在退出时进行清理。

---

插件结构

每个插件都遵循相同的基本形式：

// ── 设备标识 ──────────────────────────────────────
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 尺寸和 LED 布局 ────────────────────────────
export function Size()      { return [7, 3]; }
export function LedNames()  { return ["Logo", "Left", "Right"]; }
export function LedPositions() { return [[3,1], [0,1], [6,1]]; }

// ── 生命周期 ─────────────────────────────────────────
export function Initialize() {
    // 设备连接或启用串流时调用一次。
    // 在此处发送设备需要的任何初始化数据包。
    SendInitPacket();
}

export function Render() {
    // 每帧调用一次（默认约 30ms）。
    // 从 canvas 读取颜色并将其发送到设备。
    SendColors();
}

export function Shutdown() {
    // 当 SignalRGB 退出或禁用串流时调用。
    // 如果需要，在此处将设备恢复到硬件模式。
    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 条目：
{ "property": "dpi1", "label": "DPI", "type": "number", "min": "200", "max": "18000", "default": "800" }

// 匹配的回调：
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

设备图像的 URL，显示在 SignalRGB UI 中。标准尺寸为 1024×1024，有效区域为 920×920。

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

---

下一步

• 插件模板 — 可直接编辑的起点
• 写入和读取 — 向设备发送数据
• 确定设备类型 — 选择正确的协议
• 选择端点 — 找到正确的 USB 端点
• 用户控件 — 在设备配置页面中添加设置
• 模块和功能 — 电池、键盘/鼠标注入、网络等