Модули и функции

Плагины могут расширять свои возможности за пределы базовых операций чтения и записи USB с помощью двух систем: модулей и функций. Понимание разницы между ними поможет вам обнаружить доступные возможности и использовать правильный механизм.

Модули vs Функции

	Модули	Функции
Как использовать	import { x } from "@SignalRGB/name"	device.addFeature("name") в Initialize()
Назначение	Служебные сервисы (сеть, кодирование, системная информация)	Возможности устройства (аккумулятор, ввод)
Пространство имён	Собственные экспортируемые имена модуля	device.featureName.*
Экземпляры	Один на плагин	Может быть несколько

---

Доступные модули

Импортируйте их в начале файла плагина.

Путь импорта	Назначение
@SignalRGB/serial	Связь через последовательный/COM-порт
@SignalRGB/tcp	Связь через TCP-сокет
@SignalRGB/udp	Связь через UDP-сокет
@SignalRGB/base64	Кодирование и декодирование Base64
@SignalRGB/performance	Профилирование производительности и таймеры кадров
@SignalRGB/appInfo	Информация о версии приложения SignalRGB
@SignalRGB/systeminfo	Информация об аппаратном обеспечении системы
@SignalRGB/permissions	Проверка состояния разрешений пользователя

Примеры использования serial, tcp и udp см. в разделе Расширенная связь.

---

Доступные функции

Вызовите device.addFeature("name") в экспорте Initialize(). Функция создаёт глобальный объект с тем же именем, что и функция.

Имя функции	Пространство имён	Назначение
"keyboard"	keyboard	Инжектирование нажатий клавиш или маршрутизация событий клавиатуры в макросы SignalRGB
"mouse"	mouse	Инжектирование ввода мыши или маршрутизация событий мыши в макросы SignalRGB
"battery"	battery	Отчёт об уровне заряда и состоянии зарядки для беспроводных устройств
"dtls"	dtls	DTLS-зашифрованный UDP с PSK-аутентификацией

---

Функция keyboard

Для плагинов, представляющих клавиатурные устройства. Позволяет инжектировать реальные нажатия клавиш в ОС или генерировать события, которые могут запускать макросы SignalRGB.

export function Initialize() {
    device.addFeature("keyboard");
}

keyboard.sendHid(vkCode, options)

Отправляет необработанное нажатие клавиши напрямую в операционную систему через keybd_event. Клавиша воспринимается как реальный ввод всеми приложениями — полностью обходит систему макросов.

Параметр	Тип	Описание	Пример
vkCode	Number	Код виртуальной клавиши Windows	0x41 (клавиша A)
options.released	Boolean (обязательный)	true для события отпускания, false для нажатия	false

keyboard.sendHid(0x41, { released: false }); // Press A
keyboard.sendHid(0x41, { released: true });  // Release A

keyboard.sendEvent(eventData, eventType)

Маршрутизирует событие клавиатуры через систему макросов SignalRGB. Макросы с триггером onKey могут сопоставляться с этими событиями. Не инжектирует реальное нажатие клавиши — только макросы SignalRGB видят это событие.

Система макросов автоматически дополняет событие актуальным состоянием модификаторов (Ctrl, Shift, Alt, Win) с физической клавиатуры перед диспетчеризацией.

Параметр	Тип	Описание	Пример
eventData	Object или String	Данные события. Включите key (строковое имя) и опционально keyCode (число) для сопоставления клавиш.	{ key: "A", keyCode: 0x41 }
eventType	String	Метка типа события	"KeyPress"

keyboard.sendEvent({ key: "A", keyCode: 0x41, released: false }, "KeyPress");

Скрипты макросов получают event.Sender (UID плагина) и event.SenderType ("Device"), чтобы отличать события плагина от нажатий на реальном оборудовании.

---

Функция mouse

Для плагинов, представляющих мышь или указательные устройства.

export function Initialize() {
    device.addFeature("mouse");
}

mouse.sendHid(buttonCode, options)

Отправляет необработанное событие мыши в ОС через SendInput. Перемещение мыши (MOUSEEVENTF_MOVE, MOUSEEVENTF_ABSOLUTE) заблокировано в целях безопасности.

Параметр	Тип	Описание
buttonCode	Number	Флаг Windows MOUSEEVENTF_*
options.XButton	Number	Обязателен для событий X-кнопки — 1 (X1) или 2 (X2)
options.WheelDelta	Number	Обязателен для событий колёсика прокрутки — положительное значение прокручивает вверх, отрицательное — вниз

Распространённые коды кнопок:

Код	Константа	Описание
0x0002	MOUSEEVENTF_LEFTDOWN	Нажатие левой кнопки
0x0004	MOUSEEVENTF_LEFTUP	Отпускание левой кнопки
0x0008	MOUSEEVENTF_RIGHTDOWN	Нажатие правой кнопки
0x0010	MOUSEEVENTF_RIGHTUP	Отпускание правой кнопки
0x0020	MOUSEEVENTF_MIDDLEDOWN	Нажатие средней кнопки
0x0040	MOUSEEVENTF_MIDDLEUP	Отпускание средней кнопки
0x0800	MOUSEEVENTF_WHEEL	Вертикальная прокрутка
0x01000	MOUSEEVENTF_HWHEEL	Горизонтальная прокрутка
0x0080	MOUSEEVENTF_XDOWN	Нажатие X-кнопки (требует опции XButton)
0x0100	MOUSEEVENTF_XUP	Отпускание X-кнопки (требует опции XButton)

// Left click
mouse.sendHid(0x0002, {});  // down
mouse.sendHid(0x0004, {});  // up

// Scroll up one notch
mouse.sendHid(0x0800, { WheelDelta: 120 });

// X1 button press
mouse.sendHid(0x0080, { XButton: 1 });
mouse.sendHid(0x0100, { XButton: 1 });

mouse.sendEvent(eventData, eventType)

Маршрутизирует пользовательское событие мыши через систему макросов SignalRGB. Скрипты макросов с триггером onMouse могут сопоставляться с этими событиями. Не инжектирует никакого ввода мыши на уровне ОС.

mouse.sendEvent({ button: "LeftClick" }, "ButtonPress");

---

Функция battery

Для беспроводных устройств, сообщающих о состоянии аккумулятора. После добавления функции обновляйте уровень заряда и состояние при каждом соответствующем сообщении от устройства.

export function Initialize() {
    device.addFeature("battery");
}

Установка состояния аккумулятора

Метод	Описание
battery.setBatteryLevel(level)	Установить процент заряда (0–100)
battery.setBatteryState(state)	Установить состояние зарядки с помощью константы состояния

Константы состояния (доступ через battery.<name>):

Константа	Описание
battery.disabled	Отчёт об аккумуляторе отключён
battery.unknown	Состояние ещё неизвестно
battery.draining	Работает от аккумулятора
battery.charging	Зарядка через кабель
battery.fullCharging	Зарядка при полном заряде
battery.full	Полный заряд, не заряжается
battery.wirelessCharging	Беспроводная зарядка

Чтение состояния аккумулятора

Эти свойства отражают последние установленные значения:

Свойство	Тип	Описание
battery.batteryLevel	Number	Текущий уровень заряда (0–100)
battery.batteryState	Number	Текущее значение состояния
battery.stateString	String	Метка состояния для чтения

Пример использования battery

export function Initialize() {
    device.addFeature("battery");
}

export function Render() {
    // Non-blocking read — check if the device sent a battery report this frame
    var data = device.read([], 64, 0);

    if(device.getLastReadSize() > 0 && data[0] === 0x02) {
        var level = data[1];             // 0–100
        var charging = data[2] === 0x01;

        battery.setBatteryLevel(level);
        battery.setBatteryState(
            charging ? battery.charging : battery.draining
        );
    }
}