고급 통신

이 페이지에서는 고급 USB 통신 방법, 시리얼 포트, 네트워크 소켓을 다룹니다. 기본 읽기 및 쓰기에 대해서는 쓰기 및 읽기를 참조하십시오.

USB 전송 유형

USB 전송 유형의 차이를 이해하면 올바른 방법을 선택하고 예상치 못한 오류를 디버깅하는 데 도움이 됩니다.

유형	방법	일반적인 크기	사용 사례
인터럽트	device.write() / device.read()	3–64 바이트	RGB 데이터, 소형 명령, 키보드/마우스 입력
벌크	device.write() / device.read()	64–1025 바이트	LCD 이미지, 펌웨어 업데이트, 대용량 설정 블록
제어	device.send_report() / device.get_report() / device.control_transfer()	32–192 바이트	인증, HID 기능 보고서, 장치 설정

인터럽트와 벌크 전송 모두 동일한 device.write() 및 device.read() 함수를 사용합니다 — USB 드라이버가 엔드포인트와 패킷 크기에서 유형을 결정합니다.

---

HID 보고서 방법

device.input_report()

HID GET_INPUT_REPORT 제어 전송을 전송합니다. device.get_report()와 유사하지만 기능 보고서 대신 입력 보고서를 특별히 요청합니다. 장치가 입력 및 기능 보고서 유형을 분리하여 get_report()가 잘못된 데이터를 반환할 때 사용하십시오.

매개변수	유형	설명	예시
DataArray	1D 배열	보고서 요청 데이터	[0x01]
Length	Int	예상 보고서 크기(바이트)	64

반환값	유형	설명
DataArray	1D 배열	장치에서 수신한 바이트

var inputData = device.input_report([0x01], 64);

---

Raw USB 방법

device.bulk_transfer()

특정 USB 엔드포인트에 직접 벌크 또는 인터럽트 전송을 수행합니다. device.set_endpoint()로 선택된 엔드포인트를 사용하는 device.write() 및 device.read()와 달리, 주소로 특정 엔드포인트를 대상으로 할 수 있습니다.

• 0x80 이상으로 끝나는 엔드포인트 주소는 IN (장치 → 호스트, 읽기)입니다.
• 0x80 미만의 엔드포인트 주소는 OUT (호스트 → 장치, 쓰기)입니다.

매개변수	유형	설명	예시
Endpoint	Hex	USB 엔드포인트 주소	0x81
DataArray	1D 배열	전송할 데이터 (OUT) 또는 빈 배열 (IN)	[0x01, 0x02]
Length	Int	전송 크기(바이트)	64
Timeout	Int	포기 전 밀리초	100

반환값	유형	설명
DataArray	1D 배열	수신된 바이트 (IN 전송) 또는 비어 있음

// Write to endpoint 0x01
device.bulk_transfer(0x01, [0x00, 0x01, 0x02], 3, 100);

// Read from endpoint 0x81
var response = device.bulk_transfer(0x81, [], 64, 100);

// Large bulk write (e.g. LCD image data)
device.bulk_transfer(0x02, imageData, 1024, 500);

---

device.control_transfer()

저수준 USB 제어 전송입니다. 인증 핸드셰이크, 공급업체별 프로토콜, HID 방법으로 충분하지 않은 경우에 사용합니다. 이것은 벌크 전송이 아닌 제어 전송입니다.

매개변수	유형	설명	예시
RequestType	Hex	USB 요청 유형 비트맵 (방향, 유형, 수신자)	0xA1
Request	Hex	요청 코드 (장치별)	0x01
Value	Hex	값 필드	0x0100
Index	Int	인터페이스 또는 엔드포인트 인덱스	0x00
DataArray	1D 배열	전송할 데이터 (호스트→장치) 또는 비어 있음	[]
Length	Int	예상 응답 길이 (장치→호스트)	192
Timeout	Int	포기 전 밀리초	1000

반환값	유형	설명
DataArray	1D 배열	수신된 바이트 (장치→호스트 전송)

일반적인 RequestType 값:

값	방향	유형	수신자	사용 사례
0x21	호스트 → 장치	클래스	인터페이스	HID SET_REPORT
0xA1	장치 → 호스트	클래스	인터페이스	HID GET_REPORT
0x80	장치 → 호스트	표준	장치	디스크립터 읽기
0x00	호스트 → 장치	표준	장치	표준 명령

// Read authentication token (device → host, class, interface)
var token = device.control_transfer(
    0xA1,    // Device-to-host, class, interface
    0x01,    // GET_REPORT
    0x0100,  // Report type (Feature) + report ID
    0x00,    // Interface 0
    [],      // No outbound data
    192,     // Expect 192 bytes back
    1000     // 1 second timeout
);

// Send a feature report (host → device)
device.control_transfer(0x21, 0x09, 0x0300, 0, [0x03, 0x08, 0x32], 0, 500);

---

시리얼 통신

시리얼/COM 포트 장치의 경우 시리얼 모듈을 가져오고 플러그인의 Type()을 "serial"로 설정하십시오.

import { serial } from "@SignalRGB/serial";

export function Type() { return "serial"; }

연결 옵션

serial.connect({
    baudRate: 115200,  // Default: 115200
    parity: "None",    // "None", "Even", "Odd", "Space", "Mark"
    dataBits: 8,       // 5, 6, 7, or 8
    stopBits: "One"    // "One", "OneAndHalf", "Two"
});

시리얼 방법

방법	설명	반환값
serial.connect(options?)	시리얼 포트 열기	bool
serial.disconnect()	시리얼 포트 닫기	void
serial.isConnected()	연결 상태 확인	bool
serial.write(data)	데이터 전송	쓴 바이트 수
serial.read(maxBytes?, timeoutMs?)	사용 가능한 바이트 읽기 (기본값: 전체, 1000ms 타임아웃)	바이트 배열
serial.readAll()	즉시 사용 가능한 모든 바이트 읽기	바이트 배열
serial.availablePorts()	사용 가능한 COM 포트 목록	배열
serial.getPortName()	현재 포트 이름	string
serial.getBaudRate()	현재 전송 속도	number
serial.getDeviceInfo()	VID, PID 등을 포함한 포트 정보	object

import { serial } from "@SignalRGB/serial";

export function Type() { return "serial"; }

export function Initialize() {
    if (!serial.connect()) {
        device.log("Failed to connect to serial port");
        return;
    }
    device.log(`Connected on ${serial.getPortName()} at ${serial.getBaudRate()} baud`);
}

export function Render() {
    serial.write([0xFF, ...RGBData]);
}

export function Shutdown() {
    serial.disconnect();
}

---

네트워크 통신 (TCP / UDP)

네트워크 연결 장치의 경우 TCP 또는 UDP 모듈을 가져오고 Type()을 "network"로 설정하십시오. 두 모듈 모두 이벤트 기반 콜백 모델을 사용합니다.

import { tcp } from "@SignalRGB/tcp";
import { udp } from "@SignalRGB/udp";

export function Type() { return "network"; }

TCP

import { tcp } from "@SignalRGB/tcp";

let socket;

export function Initialize() {
    socket = tcp.createSocket();

    socket.on("connected", () => {
        device.log("Connected");
        socket.send([0x01, 0x02, 0x03]);
    });

    socket.on("message", (data) => {
        device.log(`Received: ${data}`);
    });

    socket.on("error", (err) => {
        device.log(`Error: ${err}`);
    });

    socket.connect("192.168.1.100", 8080);
}

export function Render() {
    if (socket.state === socket.ConnectedState) {
        socket.send(RGBData);
    }
}

export function Shutdown() {
    socket.close();
}

TCP 방법:

방법	설명
tcp.createSocket()	새 TCP 소켓 생성
socket.connect(address, port)	호스트에 연결
socket.send(data)	문자열 또는 바이트 배열 전송
socket.bind(port)	로컬 포트에 바인딩
socket.close()	소켓 닫기
socket.on(event, callback)	이벤트 핸들러 등록

TCP 이벤트: "connected", "disconnected", "message", "error"

---

UDP

import { udp } from "@SignalRGB/udp";

let socket;

export function Initialize() {
    socket = udp.createSocket();

    socket.on("message", (data) => {
        device.log(`Received: ${data}`);
    });

    socket.connect("192.168.1.100", 21324);
}

export function Render() {
    socket.send(RGBData);
}

export function Shutdown() {
    socket.close();
}

UDP 방법:

방법	설명
udp.createSocket()	새 UDP 소켓 생성
socket.connect(address, port)	기본 전송 대상 설정
socket.send(data)	연결된 주소로 전송
socket.write(data, address, port)	connect()를 먼저 호출하지 않고 특정 주소로 전송
socket.bind(port)	수신을 위한 로컬 포트 바인딩
socket.close()	소켓 닫기
socket.on(event, callback)	이벤트 핸들러 등록

UDP 이벤트: "connected", "disconnected", "message", "error"

---

DTLS (암호화된 UDP)

암호화된 통신이 필요한 장치(예: Philips Hue)의 경우 dtls 기능을 사용하십시오. 사전 공유 키(PSK)를 사용하는 DTLS 암호화 UDP를 제공합니다.

export function Initialize() {
    device.addFeature("dtls");

    dtls.onConnectionEstablished(() => { device.log("DTLS connected"); });
    dtls.onConnectionClosed(() => { device.log("DTLS closed"); });
    dtls.onConnectionError(() => { device.log("DTLS error"); });

    dtls.createConnection("192.168.1.50", 2100, authIdentity, authKey);
}

export function Render() {
    if (dtls.hasEncryptedConnection()) {
        dtls.send(RGBData);
    }
}

export function Shutdown() {
    dtls.CloseConnection();
}

DTLS 방법:

방법	설명
dtls.createConnection(host, port, identity, key)	PSK를 사용하여 암호화된 연결 열기
dtls.send(data, endianness?)	암호화된 데이터 전송 (0 = 리틀 엔디안, 1 = 빅 엔디안)
dtls.hasEncryptedConnection()	연결이 설정되면 true 반환
dtls.CloseConnection()	연결 닫기
dtls.onConnectionEstablished(cb)	연결 성공 시 콜백
dtls.onConnectionClosed(cb)	연결 종료 시 콜백
dtls.onConnectionError(cb)	오류 발생 시 콜백