플러그인이란 무엇인가요?

SignalRGB는 서드파티 RGB 장치를 지원하기 위해 JavaScript로 작성된 커스텀 USB 플러그인을 사용합니다. 아직 지원되지 않는 장치가 있다면 직접 플러그인을 작성할 수 있습니다. Arduino나 다른 오픈소스 마이크로컨트롤러가 있다면 SignalRGB가 해당 장치와 통신할 수 있는 플러그인을 만들어 완전한 DIY RGB 솔루션을 구현할 수도 있습니다.

현재 배포된 플러그인은 모두 오픈소스이며 SignalRGB 플러그인 공개 저장소에서 확인할 수 있습니다. 다른 사람들이 사용할 수 있는 플러그인을 만들었다면 풀 리퀘스트를 제출하거나 공식 지원팀에 문의하십시오!

---

플러그인의 작동 방식

플러그인은 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. 캔버스에서 장치의 픽셀 버퍼로 색상이 가져와짐
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입니다. 정확한 16진수 값이어야 합니다. 플러그인이 표시되지 않는다면 ID 불일치가 가장 일반적인 원인입니다.

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

이 세 가지 내보내기 함수는 장치가 캔버스에서 어떻게 나타나는지를 정의합니다.

• 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 엔드포인트 찾기
• 사용자 컨트롤 — 장치 설정 페이지에 설정 추가
• 모듈 및 기능 — 배터리, 키보드/마우스 주입, 네트워크 등