모듈 및 기능

플러그인은 두 가지 시스템, 모듈과 기능을 사용하여 기본 USB 읽기/쓰기 이상의 기능을 확장할 수 있습니다. 둘의 차이를 이해하면 사용 가능한 것을 파악하고 적절한 메커니즘을 사용하는 데 도움이 됩니다.

모듈 vs 기능

	모듈	기능
사용 방법	import { x } from "@SignalRGB/name"	Initialize()에서 device.addFeature("name")
목적	유틸리티 서비스 (네트워킹, 인코딩, 시스템 정보)	장치 기능 (배터리, 입력 주입)
네임스페이스	모듈 자체의 내보낸 이름	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 사용 예시는 고급 통신을 참조하십시오.

---

사용 가능한 기능

Initialize() 내보내기에서 device.addFeature("name")을 호출하십시오. 기능은 기능과 같은 이름의 전역 객체를 생성합니다.

기능 이름	네임스페이스	목적
"keyboard"	keyboard	키 입력 주입 또는 키보드 이벤트를 SignalRGB 매크로로 라우팅
"mouse"	mouse	마우스 입력 주입 또는 마우스 이벤트를 SignalRGB 매크로로 라우팅
"battery"	battery	무선 장치의 배터리 수준 및 충전 상태 보고
"dtls"	dtls	PSK 인증을 사용하는 DTLS 암호화 UDP

---

키보드 기능

키보드 장치를 나타내는 플러그인에 사용합니다. OS에 실제 키 입력을 주입하거나 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 or 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")을 받으므로 플러그인 소스 이벤트와 실제 하드웨어 키 입력을 구분할 수 있습니다.

---

마우스 기능

마우스 또는 포인터 장치를 나타내는 플러그인에 사용합니다.

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

mouse.sendHid(buttonCode, options)

SendInput을 통해 OS에 원시 마우스 이벤트를 전송합니다. 마우스 이동(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 트리거가 있는 매크로 스크립트가 이 이벤트를 매칭할 수 있습니다. OS 수준의 마우스 입력을 주입하지 않습니다.

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

---

배터리 기능

배터리 상태를 보고하는 무선 장치에 사용합니다. 기능을 추가한 후 장치가 배터리 상태를 보고할 때마다 배터리 수준과 상태를 업데이트하십시오.

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	사람이 읽을 수 있는 상태 레이블

배터리 예시

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
        );
    }
}