Что такое плагин?

SignalRGB использует пользовательские USB-плагины на JavaScript для поддержки сторонних RGB-устройств. Если у вас есть устройство, которое пока не поддерживается, вы можете написать для него собственный плагин. Если у вас есть Arduino или другой микроконтроллер с открытым исходным кодом, вы также можете создать плагин для SignalRGB для полностью DIY RGB-решений.

Все наши выпущенные плагины имеют открытый исходный код и доступны в публичном репозитории плагинов SignalRGB. Если вы создали что-то полезное для других, не стесняйтесь создать pull request или обратиться в нашу официальную службу поддержки!

---

Как работает плагин

Плагин — это единственный файл JavaScript, который SignalRGB загружает для конкретного USB-устройства. Он выполняет две функции:

1. Описывает устройство — экспорты, сообщающие SignalRGB имя устройства, идентификаторы, схему светодиодов и протокол связи.
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) для чтения цветов пикселей и их отправки на устройство. Интервал кадров по умолчанию — 30 мс.

Shutdown

Вызывается при корректном завершении SignalRGB или отключении переключателя потоковой передачи. Если устройство поддерживает аппаратный режим освещения, восстановите его здесь, чтобы светодиоды пользователя не гасли при неработающем SignalRGB.

Обратные вызовы 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.

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

VendorId и ProductId

USB-идентификаторы, используемые SignalRGB для поиска устройства в системе. Должны быть точными шестнадцатеричными значениями. Если плагин не отображается, скорее всего причина — несовпадение идентификатора.

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

Type

Устанавливает протокол USB-связи. По умолчанию "hid", если не экспортирован. См. Определение типа устройства для полного списка и выбора.

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 и LedPositions

Эти три экспорта совместно определяют отображение устройства на canvas.

• Size() — ограничивающий прямоугольник [ширина, высота] сетки пикселей устройства. device.color() может брать образцы только в пределах этого прямоугольника.
• LedNames() — упорядоченный массив имён светодиодов. Имена должны соответствовать списку поддерживаемых имён клавиш для поддержки эффектов нажатия клавиш и покраски светодиодов.
• LedPositions() — упорядоченный массив позиций [x, y] в сетке Size, по одной на светодиод, соответствующий порядку 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

Управляет тем, какие USB-конечные точки открывает SignalRGB. Каждая обнаруженная конечная точка передаётся в 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. Стандартный размер — 1024×1024 с рабочей областью 920×920.

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

---

Следующие шаги

• Шаблон плагина — готовая начальная точка для редактирования
• Записи и чтения — отправка данных на устройство
• Определение типа устройства — выбор правильного протокола
• Пользовательские элементы управления — добавление настроек на страницу конфигурации устройства
• Модули и функции — аккумулятор, ввод клавиатуры/мыши, сеть и многое другое