Controller API Reference

Complete reference for the device global object available in controller plugins.

Device Metadata

device:controller_port()

Returns the device's port identifier.

local port = device:controller_port()  -- e.g. "COM3", "/dev/ttyUSB0"

device:manufacturer()

Returns the manufacturer name. Pre-populated from the USB descriptor if available; can be overridden via set_manufacturer().

device:model()

Returns the device model. Pre-populated from the USB product string if available; can be overridden via set_model().

device:serial_id()

Returns the USB serial number (set via set_serial_id, pre-populated for HID devices).

device:device_id()

Returns the unique device ID (hash computed by Core).

device:description()

Returns the device description.

device:image_url()

Returns the device image URL, or nil.

device:vendor_id()

Returns the USB Vendor ID as a number, or nil.

device:product_id()

Returns the USB Product ID as a number, or nil.

---

Device Configuration

note

These methods can only be called during on_validate() and on_init().

device:set_manufacturer(str)

Override the device manufacturer name. If not called, the value reported by the USB descriptor is used.

device:set_manufacturer("Skydimo")

device:set_model(str)

Override the device model name. If not called, the USB product string is used (serial) or the USB product string if available (HID).

device:set_model("LED Strip v2")

device:set_serial_id(str)

Set the USB serial identifier.

device:set_serial_id("ABC123")

device:set_description(str)

Set a human-readable device description.

device:set_image_url(url)

Set a thumbnail URL for the device. Pass nil to clear.

device:set_device_type(str)

Set the device type. Accepts a case-insensitive string (hyphens are treated as underscores).

Value	Aliases	Description
"light"		Generic LED light
"led_strip"	"ledstrip"	LED strip
"keyboard"		Keyboard
"keypad"		Keypad
"mouse"		Mouse
"mouse_mat"	"mousemat"	Mouse mat
"headset"		Headset
"headset_stand"	"headsetstand"	Headset stand
"gamepad"		Gamepad
"motherboard"		Motherboard
"gpu"		Graphics card
"dram"	"memory"	RAM module
"cooler"		Cooler (fan / AIO)
"case"		PC case
"speaker"		Speaker
"microphone"		Microphone
"monitor"		Monitor
"laptop"		Laptop
"storage"		Storage device
"accessory"		Accessory
"virtual"		Virtual device
"unknown"		Unknown type

device:set_device_type("keyboard")

---

Output Port Registration

note

add_output can only be called during on_init().

device:add_output(config)

Register a hardware output port.

Simple form:

device:add_output("output_id", led_count)

Full form:

device:add_output({
    id = "out1",
    name = "Output 1",
    type = "linear",       -- "single", "linear", "matrix"
    size = 144,
    matrix = {             -- Only for "matrix" type
        width = 12,
        height = 12,
        map = {1, 2, ..., 144}  -- -1 = unmapped
    },
    capabilities = {
        editable = false,
        min_total_leds = 1,
        max_total_leds = 300,
        allowed_total_leds = nil  -- or {60, 120, 144}
    }
})

---

Data I/O

device:write(data)

Send data to the device.

device:write(packet_string)           -- Write full string
device:write(packet_string, length)   -- Write first N bytes
device:write({0x01, 0x02, 0xFF})      -- Write from byte table

Returns: true on success.

Accepts a Lua string (binary data), a table of byte values (0–255), or nil (no-op).

device:read(length)

Read data from the device.

local data = device:read(64)           -- Read up to 64 bytes
local data = device:read(64, 500)      -- With 500ms timeout

Returns: A Lua string of raw bytes, or nil on failure/timeout.

device:clear_input()

Clear the serial input buffer (serial protocol only).

device:clear_input()

---

LED Color Data

device:get_colors(output_id)

Get the mixed LED colors as a Lua table.

local colors = device:get_colors("out1")
-- Returns: {r, g, b, r, g, b, ...} (numbers 0-255)

device:get_rgb_bytes(output_id)

Get the mixed LED colors as a binary string.

local rgb = device:get_rgb_bytes("out1")
-- Returns: binary string of RGB bytes
-- More efficient than get_colors for direct hardware I/O

device:output_led_count(output_id)

Get the LED count for an output.

local count = device:output_led_count("out1")  -- e.g. 144

---

HID-Specific Methods

device:hid_send_feature_report(data)

Send a HID feature report.

device:hid_send_feature_report(packet)
device:hid_send_feature_report(packet, length, selector)

• selector can be an integer or string to select a specific HID interface.

device:hid_get_feature_report(length)

Read a HID feature report.

local report = device:hid_get_feature_report(64)
local report = device:hid_get_feature_report(64, report_id, selector)

device:hid_interfaces()

List all HID interfaces for the device.

local interfaces = device:hid_interfaces()
-- Returns table of interface descriptors

---

Logging

device:log(msg)

Log an info-level message.

device:log("Identified device: " .. device:model())

device:error(msg)

Log an error-level message.

device:error("Failed to send data to device")