Advanced Communication

This page covers advanced USB communication methods, serial ports, and network sockets. For basic reads and writes see Writes and Reads.

USB Transfer Types

Understanding the difference between USB transfer types will help you choose the right method and debug unexpected errors.

Type	Method	Typical size	Use case
Interrupt	device.write() / device.read()	3–64 bytes	RGB data, small commands, keyboard/mouse input
Bulk	device.write() / device.read()	64–1025 bytes	LCD images, firmware updates, large config blocks
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 bytes	Authentication, HID feature reports, device configuration

The same device.write() and device.read() functions are used for both interrupt and bulk transfers — the USB driver determines the type from the endpoint and packet size.

---

HID Report Methods

device.input_report()

Sends a HID GET_INPUT_REPORT control transfer. Similar to device.get_report() but specifically requests an Input report rather than a Feature report. Use this when get_report() returns wrong data because the device separates its Input and Feature report types.

Parameter	Type	Description	Example
DataArray	1D Array	Report request data	[0x01]
Length	Int	Expected report size in bytes	64

Return	Type	Description
DataArray	1D Array	Bytes received from the device

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

---

Raw USB Methods

device.bulk_transfer()

Performs a direct bulk or interrupt transfer to a specific USB endpoint. Unlike device.write() and device.read() which use the endpoint selected by device.set_endpoint(), this lets you target any endpoint by address.

• Endpoint addresses ending in 0x80 or higher are IN (device → host, read).
• Endpoint addresses below 0x80 are OUT (host → device, write).

Parameter	Type	Description	Example
Endpoint	Hex	USB endpoint address	0x81
DataArray	1D Array	Data to send (OUT), or empty array (IN)	[0x01, 0x02]
Length	Int	Transfer size in bytes	64
Timeout	Int	Milliseconds before giving up	100

Return	Type	Description
DataArray	1D Array	Bytes received (IN transfers), or empty

// 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()

Low-level USB control transfer. Used for authentication handshakes, vendor-specific protocols, and cases where HID methods aren’t sufficient. This is a control transfer, not a bulk transfer.

Parameter	Type	Description	Example
RequestType	Hex	USB request type bitmap (direction, type, recipient)	0xA1
Request	Hex	Request code (device-specific)	0x01
Value	Hex	Value field	0x0100
Index	Int	Interface or endpoint index	0x00
DataArray	1D Array	Data to send (host-to-device), or empty	[]
Length	Int	Expected response length (device-to-host)	192
Timeout	Int	Milliseconds before giving up	1000

Return	Type	Description
DataArray	1D Array	Bytes received (device-to-host transfers)

Common RequestType values:

Value	Direction	Type	Recipient	Use case
0x21	Host → Device	Class	Interface	HID SET_REPORT
0xA1	Device → Host	Class	Interface	HID GET_REPORT
0x80	Device → Host	Standard	Device	Descriptor reads
0x00	Host → Device	Standard	Device	Standard commands

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

---

Serial Communication

For serial/COM port devices, import the serial module and set your plugin’s Type() to "serial".

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

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

Connection Options

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 Methods

Method	Description	Returns
serial.connect(options?)	Open the serial port	bool
serial.disconnect()	Close the serial port	void
serial.isConnected()	Check connection state	bool
serial.write(data)	Send data	bytes written
serial.read(maxBytes?, timeoutMs?)	Read available bytes (default: all, 1000ms timeout)	byte array
serial.readAll()	Read all available bytes immediately	byte array
serial.availablePorts()	List available COM ports	array
serial.getPortName()	Current port name	string
serial.getBaudRate()	Current baud rate	number
serial.getDeviceInfo()	Port info with VID, PID, etc.	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();
}

---

Network Communication (TCP / UDP)

For network-connected devices, import the TCP or UDP module and set Type() to "network". Both modules use an event-based callback model.

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 Methods:

Method	Description
tcp.createSocket()	Create a new TCP socket
socket.connect(address, port)	Connect to a host
socket.send(data)	Send string or byte array
socket.bind(port)	Bind to a local port
socket.close()	Close the socket
socket.on(event, callback)	Register an event handler

TCP Events: "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 Methods:

Method	Description
udp.createSocket()	Create a new UDP socket
socket.connect(address, port)	Set default send destination
socket.send(data)	Send to connected address
socket.write(data, address, port)	Send to a specific address without calling connect() first
socket.bind(port)	Bind to a local port for receiving
socket.close()	Close the socket
socket.on(event, callback)	Register an event handler

UDP Events: "connected", "disconnected", "message", "error"

---

DTLS (Encrypted UDP)

For devices that require encrypted communication (e.g. Philips Hue), use the dtls feature. It provides DTLS-encrypted UDP using a Pre-Shared Key (PSK).

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 Methods:

Method	Description
dtls.createConnection(host, port, identity, key)	Open an encrypted connection using a PSK
dtls.send(data, endianness?)	Send encrypted data (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Returns true if the connection is established
dtls.CloseConnection()	Close the connection
dtls.onConnectionEstablished(cb)	Callback when connection succeeds
dtls.onConnectionClosed(cb)	Callback when connection closes
dtls.onConnectionError(cb)	Callback on error