Plugin developer guide

This guide is for third-party developers who want to implement a USB HID lighting plugin that runs inside the RGBJunkie desktop application. It describes the public plugin ABI and the device API available to your script. It does not assume access to the RGBJunkie source tree.

For release notes, downloads, and any packaged templates or validation tools, see rgbjunkie.com.

Related: Effects (Effect lighting mode) — HTML canvas in EFFECT-DEVELOPER-GUIDE.md / effect-developer-guide.html (worked examples); functional .mjs effects in effect-functional-developer-guide.html. Runnable HTML samples under examples/effects/. USB / device coverage — browse supported-devices.html (served with the other docs, e.g. /api/docs/supported-devices.html).

On this page

1. What a plugin is — the mental model
2. Standard export-function format — a complete plugin you can copy
3. Lifecycle exports — when initialize / render / shutdown run
4. device API — HID, channels, colors, settings
5. Common plugin patterns — strip, grid, zones, multi-device
6. Shared code (@rgbj-include)
7. ABI descriptor (advanced)
8. Add-ons
9. Distribution and validation
10. Where to get help

New here? Read Section 1 for the mental model, then copy the complete plugin in Section 2 and adapt it to your hardware.

1. What a plugin is

A plugin is a single JavaScript module (ES module syntax) that RGBJunkie loads from its plugin directory (see Settings → Installed files or Installed files on the website). RGBJunkie runs it in a sandbox and injects the globals your plugin calls.

How a plugin runs

RGBJunkie drives every plugin through the same five steps. Your job is to fill in the functions for each step:

1. Match — RGBJunkie compares each plugged-in USB device against your VendorId() / ProductId().
2. Validate — for a match, Validate(endpoint) picks the right HID interface (Section 4.1).
3. Initialize — Initialize() runs once: choose the HID endpoint, register LED channels or a key grid, add settings.
4. Render loop — Render() runs many times per second: read the colors RGBJunkie computed, pack them into your firmware's byte layout, and send them over HID.
5. Shutdown — Shutdown() runs on app close or PC sleep so you can leave the device in a safe state.

Everything else in this guide is detail on those five steps.

Runtime globals

Your plugin file may also read globals created from settings rows — each property / id in ControllableParameters() or rgbjunkie.settings becomes a variable in your scope (e.g. shutdownColor, pollingRate). See Section 4.5.

Which format should I use?

RGBJunkie ships a large importable device library built as export-function plugins — one .js file per device family with export function Name(), VendorId(), ProductId(), Initialize(), Render(), and related entrypoints. Write new third-party device plugins in this format (Section 2) so they install cleanly and match what users already import from community repos.

When a plugin does not export an export const rgbjunkie descriptor, RGBJunkie synthesizes one from those export functions, so device matching, controllable parameters, and the Initialize/Render/Shutdown lifecycle all flow through the same pipeline.

The export const rgbjunkie descriptor (Section 7) is RGBJunkie’s optional advanced format. It is used internally for RAM, GPU, motherboard, and the WLED virtual device, and remains fully supported — but it is not the starting point for new community device plugins.

2. Standard export-function format (recommended)

Write new device plugins with export function entrypoints — the same format as RGBJunkie's built-in device library. You do not write an export const rgbjunkie descriptor; the host builds one from your exports. (The descriptor is an advanced option — Section 7.)

A complete plugin

This is a full, working plugin. Copy it, change the IDs and the buildPacket byte layout to match your hardware, and load it (how to load):

// 1. Identity — RGBJunkie matches these against plugged-in USB devices
export function Name() { return "Example RGB Strip"; }
export function VendorId() { return 0x1234; }         // your USB vendor ID
export function ProductId() { return 0x5678; }        // one PID, or [0x5678, 0x5679]
export function DeviceType() { return "lightingcontroller"; }
export function Publisher() { return "Your Studio"; }

// 2. Pick the right HID collection during USB probe
export function Validate(endpoint) {
  return endpoint.interface === 0;
}

// 3. Runs once when the device opens
export async function Initialize() {
  device.set_endpoint(0, 0x0001, 0xffc0, 0); // choose the HID endpoint
  device.addChannel("Strip", 30);            // 30 LEDs the host will fill
}

// 4. Runs every lighting frame
export async function Render() {
  const colors = device.channel("Strip").getColors("Inline", "GRB");
  device.write(buildPacket(colors), 65);     // 65 = your device's report size
}

// 5. Runs on app close or PC sleep
export async function Shutdown(systemSuspending) {
  device.write(buildPacket([]), 65);         // e.g. all-black
}

// 6. Your protocol — turn host colors into the bytes your firmware expects
function buildPacket(colors) {
  const packet = new Array(65).fill(0);
  packet[0] = 0x00;                          // report ID (vendor-specific)
  for (let i = 0; i < colors.length; i++) packet[1 + i] = colors[i];
  return packet;
}

What each part does

1. Identity exports (Name, VendorId, ProductId) tell RGBJunkie which USB device this plugin drives. These three are required — without them the plugin will not load.
2. Validate(endpoint) picks the correct HID interface during probing (Section 4.1).
3. Initialize() chooses the HID endpoint and registers a channel — a named LED segment the host fills with colors (Section 4.2).
4. Render() runs every frame: read the host-filled colors, pack them into your firmware's byte layout, and send with device.write (Section 4.1).
5. Shutdown() leaves the device in a safe state.
6. buildPacket is your code — the vendor byte layout. Everything else is the RGBJunkie contract.

Load your plugin

1. Save the file under your plugin folder (path shown in Settings → Installed files), e.g. plugins/<Vendor>/Example_Strip.js.
2. Open the Devices panel and click Rescan.
3. Plug in the device — it appears in the list once a (VendorId, ProductId) pair matches.

To iterate quickly, enable Settings → System → Engine → Hot-reload user plugins, which reloads saved .js files without a restart.

Required exports

Common optional exports

Good to know

• Casing is flexible. Lifecycle can be Initialize / Render / Shutdown (PascalCase) or initialize / render / shutdown (camelCase). The host accepts either.
• The device API is always available (Section 4) — you do not import it.
• Use the descriptor only when you must. Reach for export const rgbjunkie (Section 7) only for descriptor-only fields or RGBJunkie's built-in subsystems.

3. Lifecycle exports

Section 2 shows the three lifecycle hooks in a working plugin. This section covers their timing and behavior.

Each may return a Promise; the host awaits it before continuing.

The render loop

render is the hot path. It runs on every frame, so keep it cheap:

• Read the colors RGBJunkie already computed (device.channel(...).getColors, device.color, device.subdeviceColor) — do not recompute effects yourself.
• Build the packet and send it (device.write / send_report). That is the whole job.
• Avoid allocations, logging, and blocking work in the loop where you can.
• To slow the loop down for hardware that cannot keep up (e.g. LCD encoders), cap it with device.setFrameRateTarget(fps) (Section 4.7).

Shutdown

Use systemSuspending to decide the parting state — often black on sleep, or a saved color otherwise:

export async function Shutdown(systemSuspending) {
  const hex = systemSuspending ? "#000000" : shutdownColor; // shutdownColor is a settings global
  device.write(buildSolidPacket(hex), REPORT_LEN);
}

Never throw from a lifecycle function. Errors are logged and the device may stop updating. Wrap risky work in try/catch.

4. device API (summary)

The global device object is injected into your plugin sandbox — you do not import it. This section is the reference for everything your plugin calls at runtime. Argument and return details are spelled out in each subsection.

What do I need? (cheat sheet)

RGBJunkie's engine is built around lighting (channels, color sampling, HID LED streams), but many shipped plugins also expose vendor hardware options — DPI, polling rate, lift-off distance, and similar controls via ControllableParameters(), rgbjunkie.settings, or device.addProperty.

Also available (where supported): fan/pump registry (createFanControl, setRPM), temperature probes, setImageFromUrl, addFeature("battery"), getBrightness(). sendEvent (keyboard/mouse injection) only when the user enables Settings → System → Allow plugins to send keyboard/mouse input. Monitor DDC/CI brightness is Windows-only for v1.

4.1 HID output and endpoint selection

device.write(packet, length) and device.send_report(packet, length)

Send a raw HID output buffer to the device.

Prefer write for the main LED stream; send_report when the protocol uses feature/output report framing. Bytes clamp to 0–255. Do not throw from render.

const REPORT_LEN = 65;
const packet = new Array(REPORT_LEN).fill(0);
packet[0] = 0x00; packet[1] = 255; packet[2] = 0; packet[3] = 0;
device.write(packet, REPORT_LEN);

device.set_endpoint(interface, usage, usage_page, collection?)

Select which HID interface collection to use for subsequent read/write on this device.

Call once in initialize with the same tuple you match in Validate(endpoint).

Validate(endpoint) (export function)

During USB probe, RGBJunkie calls this with one object per HID collection:

Return true only for the collection your plugin will set_endpoint to.

export function Validate(endpoint) {
  return endpoint.interface === 0 && endpoint.usage_page === 0xffc0;
}

HID reads

4.2 Channels and host-filled colors

Channels are named LED segments (strips, fans, zones). RGBJunkie fills them from the workspace/effect pipeline; your render reads bytes and sends them over HID.

device.addChannel(name, ledCount)

device.channel(name)

Returns an object with:

getColors(format, order)

Returns: flat number[], length mappedLedCount × 3, values 0–255.

const bytes = device.channel("Strip").getColors("Inline", "GRB");
// bytes = [g0, r0, b0, g1, r1, b1, …] for each mapped LED

device.SetLedLimit(n) / device.removeChannel(name)

4.3 Fixed-layout grids (keyboards, mats, matrices)

For per-key/per-cell devices, register a logical grid. Coordinates are integers starting at (0, 0) top-left, one unit per cell, matching Size().

device.setControllableLeds(ledNames, positions)

Alternatively export LedNames() and LedPositions() (or getLedNames / getLedPositions) returning the same shapes — RGBJunkie may call them at startup.

export function LedNames() {
  return ["Key A", "Key B"];
}
export function LedPositions() {
  return [[0, 0], [1, 0]];
}
export function Size() {
  return [15, 5]; // grid is 15 columns × 5 rows
}

device.color(x, y)

Returns: [r, g, b] — three numbers 0–255.

const [r, g, b] = device.color(3, 2); // color at grid cell (3, 2)

device.setControllableLedSizes(sizes) (optional)

4.4 Multiple zones (“subdevices”)

Zones split one physical device into named regions (e.g. keyboard + logo + strip).

4.5 Settings and dynamic parameters

Plugin settings appear under Plugin Settings in the device tree. Each row becomes a global variable in your plugin (saved in user profiles).

Row shape (ControllableParameters, device.addProperty, rgbjunkie.settings)

Export-function plugins use property; descriptor plugins use id — same role.

When the user changes a value, RGBJunkie updates the global and may call onXxxChanged() (e.g. pollingRate → onPollingRateChanged()).

device.addProperty(descriptor) / getProperty / setProperty

You can also read globals directly after registration: if (pollingRate > 500) { … }.

export function ControllableParameters() {
  return [
    { property: "shutdownColor", group: "lighting", label: "Shutdown Color", type: "color", default: "#000000" },
    { property: "ledOrder", group: "lighting", label: "Wire order", type: "combobox", values: ["RGB", "GRB"], default: "GRB" },
  ];
}

export function onLedOrderChanged() {
  // user picked a new wire order — push config packet if needed
}

4.6 Displays and image helpers

For LCD / image surfaces (device-specific):

Confirm support for your hardware and RGBJunkie version on rgbjunkie.com.

4.7 Frame pacing and watchdog

export function initialize() {
  device.addChannel("Strip", 60);
  device.setNeedsWatchdogRefresh(false);
}

4.8 Other helpers

5. Common plugin patterns

Each pattern below lists which functions you call, what you pass, and what you get back.

5.1 Single channel strip or hub

export async function Initialize() {
  device.set_endpoint(0, 0x0001, 0xffc0, 0);
  device.addChannel("Strip", 60);
}

export async function Render() {
  const colors = device.channel("Strip").getColors("Inline", "GRB");
  device.write(packStripPacket(colors), 65);
}

5.2 Fixed LED grid (keyboard, mat)

export function Size() { return [15, 5]; }
export function LedNames() { return ["A", "B"]; }
export function LedPositions() { return [[0, 0], [1, 0]]; }

export async function Render() {
  const [r, g, b] = device.color(0, 0);
  device.write(packKey(r, g, b), REPORT_LEN);
}

5.3 Multiple zones (subdevices)

5.4 Same protocol, multiple VID/PID

6. Shared code (@rgbj-include)

Split protocol tables or helpers into separate .js files and pull them in with a comment at the top of your plugin (or add-on):

// @rgbj-include "relative/path/to/helpers.js"

// @rgbj-include "./protocol/packets.js"
// packets.js defines: function buildSolidPacket(hex) { … }
export async function Render() {
  device.write(buildSolidPacket("#ff0000"), 65);
}

7. ABI descriptor (rgbjunkie) — advanced

Optional. Use the export-function format (Section 2) for new community device plugins. This section documents RGBJunkie’s native descriptor object for maintainers and built-in subsystems.

A descriptor object uses abiVersion: 1.

In this section: 7.1 Fields · 7.2 transportType · 7.3 deviceKind · 7.4 Settings types · 7.5 Color syntax · 7.6 Example · 7.7 Notes · 7.8 Thumbnails & brand CDN

7.1 Required and common fields

match and matchAlternatives

RGBJunkie loads the plugin when any (vendorId, productId) pair from match or matchAlternatives matches plugged-in hardware.

Descriptor fields

7.2 transportType

7.3 deviceKind

7.4 Settings row type

Each object in rgbjunkie.settings (or legacy getControllableParameters()) must include id, label, type, and type-specific fields:

Optional visibility: visibleWhen hides a row until another setting matches:

Referenced property values are other settings’ id (descriptor) or property (export-function rows).

Optional combobox helper: appendTokenToProperty — set to another setting’s id. Choosing a non-first values entry appends that token to the target string field; use values[0]: "" as the idle choice.

settings: [
  { id: "mode", label: "Mode", type: "combobox", values: ["Basic", "Advanced"], default: "Basic" },
  {
    id: "advancedGain",
    label: "Gain",
    type: "slider",
    min: "0",
    max: "100",
    default: "50",
    visibleWhen: { property: "mode", equals: "Advanced" },
  },
]

7.5 Color syntax

RGBJunkie treats plugin-facing colors as 24-bit sRGB hex:

Not accepted: 3-digit CSS shorthand, 8-digit alpha, spaces, or named colors. Unparseable strings map to black (#000000).

7.6 Example

export const rgbjunkie = {
  abiVersion: 1,
  displayName: "Example RGB Strip",
  publisher: "Your Studio",
  match: { vendorId: 0x1234, productIds: [0x5678] },
  transportType: "Hid",
  deviceKind: "lightingcontroller",
  validateEndpoint: (endpoint) => endpoint.interface === 0,
  imageUrl: "",
  size: [18, 6],
  documentation: "example-strip",
  settings: [
    {
      id: "shutdownColor",
      group: "lighting",
      label: "Shutdown Color",
      type: "color",
      default: "#000000",
      min: "0",
      max: "360",
    },
  ],
};

export async function initialize() { /* … */ }
export async function render() { /* … */ }
export async function shutdown(systemSuspending) { /* … */ }

7.7 Notes

• match + matchAlternatives together define every (VID, PID) pair that should load this plugin.
• Each settings[].id becomes a named global in your plugin scope and is persisted with user profiles—treat IDs as stable API.

7.8 Device tree thumbnails (imageUrl) and brand assets

• In the app, Settings / device tree brand art is resolved by src/ui/pluginDeviceImage.ts (tiles at https://assets.rgbjunkie.com/images/brands/<slug>.png).
• Repository maintenance: run npm run plugins:brand-image-urls to set quoted imageUrl strings when a PNG exists. Run npm run docs:supported-devices to refresh the public device browser JSON.

8. Add-ons (extend a plugin without editing it)

An add-on layers extra behavior on top of an existing plugin — extra settings, lighting modes, or zones — without modifying the base file, so the base can keep being updated. Add-ons work for both export-function plugins (Section 2) and rgbjunkie descriptor plugins (Section 7).

In this section: 8.1 File naming · 8.2 How it runs · 8.3 Hook · 8.4 Rules · 8.5 WLED overview · 8.6 WLED naming · 8.7 How to make an add-on · 8.8 WLED rules · 8.9 WLED hook shim · 8.10 Matrix add-ons · 8.11 Licensing

8.1 File naming and location

Place a sibling file next to the base plugin, named <BasePluginFileName>.addon.js:

plugins/Razer/Razer_Modern_Mouse.js        ← base plugin
plugins/Razer/Razer_Modern_Mouse.addon.js  ← add-on (auto-merged)

The same relative path works under your user plugin directory. *.addon.js files are never loaded as standalone devices.

8.2 How it runs

The host concatenates your add-on after the base plugin source and evaluates them together, then calls your exported __rgbjPostWirePluginExports() once — after the base plugin’s exports and the RGBJunkie ABI are wired, and before the host’s render wrapper.

8.3 What you can do in __rgbjPostWirePluginExports()

The host calls this hook once after the base plugin’s exports are wired. It receives no arguments; use closures over exports, rgbjunkie, and settings globals.

export function __rgbjPostWirePluginExports() {
  try {
    rgbjunkie.settings.push({
      id: "addonMode",
      label: "Add-on mode",
      type: "boolean",
      default: false,
    });
    const baseRender = exports.render;
    exports.render = function () {
      if (addonMode) { /* extra HID or color path */ }
      return baseRender();
    };
    exports.Render = exports.render;
  } catch (e) { /* never throw */ }
}

8.4 Rules

• Do not re-declare the base plugin’s top-level function / const / class names. Wrap existing exports at runtime instead.
• Use unique names for helpers you add.
• Keep work inside render cheap — it runs every frame.
• An add-on must never throw; guard your hook with try/catch.

A ready-to-copy starting point ships as plugins/_templates/plugin.addon.template.js.

The subsections below document the WLED add-on path (wled.addon.js, merged by the host’s WLED pipeline). That path predates the generic *.addon.js** mechanism above.

8.5 WLED add-ons — overview

For network template plugins, RGBJunkie can merge an optional second JavaScript file after the main plugin body. The worked example is WLED (plugins/Network/WLED/WLED.js). The host concatenates a prelude, the main WLED.js body, your add-on, and a discovery bridge into one sandbox eval unit.

8.6 WLED — file name and install location

Place wled.addon.js or WLED.addon.js next to WLED.js under your plugin root (e.g. %APPDATA%\RGBJunkie\plugins\Network\WLED\ on Windows). The add-on is never loaded as a standalone device row.

8.7 How to make an add-on

You do not edit the base plugin file. You write a separate add-on file that RGBJunkie merges at load time (Section 8.2). The steps below work for any device plugin; the WLED notes at the end apply to wled.addon.js only.

Step 1 — Create the add-on file

Start from the pattern in Section 8.3 or copy a published template from rgbjunkie.com developer materials.

Step 2 — Optional sidebar title

Export a display name so Plugin Settings can group your rows under a heading:

export const __rgbjAddonDisplayName = "My mouse add-on";           // generic *.addon.js
export const __rgbjWledAddonDisplayName = "My WLED clock add-on"; // wled.addon.js only

Step 3 — Register settings rows

Add Plugin Settings rows your render logic (or the stock plugin) will read as globals. Use unique id / property values — they become variable names and profile keys (Section 7.4).

If the base plugin uses export const rgbjunkie (including merged WLED), push onto rgbjunkie.settings when your file loads:

(function mergeSettings() {
  try {
    if (!rgbjunkie || !Array.isArray(rgbjunkie.settings)) return;
    rgbjunkie.settings.push({
      id: "myAddonMode",
      label: "Add-on mode",
      type: "combobox",
      values: ["Off", "Custom"],
      default: "Off",
      group: "addon", // WLED matrix rows often use group: "matrix"
    });
  } catch (e) {}
})();

If the base is export-function only (no descriptor), wrap exports.ControllableParameters inside __rgbjPostWirePluginExports() to append rows — see the generic template pattern on rgbjunkie.com.

Step 4 — Wire behavior in __rgbjPostWirePluginExports()

Export one hook. The host calls it once with no arguments. Save the base functions, then replace them with wrappers (Section 8.4):

export function __rgbjPostWirePluginExports() {
  try {
    const baseRender = exports.render ?? exports.Render;
    if (typeof baseRender !== "function") return;

    exports.render = function () {
      if (myAddonMode === "Custom") {
        // Your logic: read settings globals, build packets, call device.write, etc.
      }
      return baseRender();
    };
    exports.Render = exports.render;
  } catch (e) { /* never throw */ }
}

For HID device add-ons, your wrapper usually calls device.write / device.channel(...).getColors like a normal plugin (Section 4). For WLED, the stock driver already owns UDP — your wrapper often calls the saved baseRender() for normal effect canvas mode, and only runs custom pixel/matrix code when the user picks a mode you added in Step 3.

Step 5 — Split large helpers with @rgbj-include

Font tables, protocol bytes, and other big static data belong in sibling files (Section 6):

// @rgbj-include "./my-glyph-table.js"

Included files must not declare initialize / render / a second rgbjunkie — only data and pure functions.

Step 6 — Try it on your machine

1. Copy the add-on (and any include files) into the folder shown under Settings → Installed files, beside the base plugin.
2. Rescan in the Devices panel, or restart RGBJunkie.
3. Optional: Settings → System → Engine → Hot-reload user plugins reloads saved .js files while you iterate.

Your new settings appear under Plugin Settings for that device. If nothing loads, check the add-on file name, path beside the base plugin, and that the hook never throws (Section 8.8 for WLED-specific pitfalls).

8.8 WLED — rules so the base plugin keeps working

• Only one export const rgbjunkie and one real initialize / render / shutdown from stock WLED.js.
• Do not ship empty lifecycle stubs in included fragments — hoisting can override the real WLED lifecycle.
• Merge extra settings into rgbjunkie.settings with unique id values.

8.9 WLED — optional hook shim

If the add-on exports __rgbjPostWirePluginExports(), the host may replace it with a built-in shim that wires initialize, shutdown, and render for matrix vs stock UDP canvas modes. Set globalThis.__RGBJUNKIE_WLED_CLOCK_MATRIX_RENDER = true before WLED virtual plugins load to use your hook verbatim.

8.10 WLED — matrix and clock add-ons

WLED add-ons that draw clocks, scrolling text, pixel art, or sensor overlays on a 2D matrix follow the same six steps in Section 8.7, with these conventions:

Advanced: RGBJunkie may supply a built-in shim for stock clock/matrix bundles (Section 8.9). Hand-written add-ons can ignore that and implement __rgbjPostWirePluginExports() entirely in your file.

Minimal WLED add-on shape:

export const __rgbjWledAddonDisplayName = "Example matrix add-on";

(function () {
  try {
    rgbjunkie.settings.push({
      id: "matrixExample",
      group: "matrix",
      label: "Enable example overlay",
      type: "boolean",
      default: false,
    });
  } catch (e) {}
})();

export function __rgbjPostWirePluginExports() {
  try {
    const base = exports.render;
    exports.render = function () {
      if (matrixExample) { /* pack matrix pixels, then send */ }
      return base();
    };
    exports.Render = exports.render;
  } catch (e) {}
}

8.11 WLED — licensing (open source, share-alike)

Add-on files should use SPDX-License-Identifier: GPL-3.0-or-later (or compatible copyleft). Template examples ship with RGBJunkie developer materials on rgbjunkie.com. Full policy: add-on licensing guide published with the docs.

9. Distribution and validation

• Install your .js plugin (and any included fragments) into the user plugins folder documented in Settings → Installed files, or publish a Git repo and share an Install in RGBJunkie link (App links).
• After adding plugins, use Rescan in the Devices panel so RGBJunkie loads them.
• Maintainers (source tree): after changing many plugins’ metadata, run npm run harvest:plugin-db. For brand imageUrl sweeps, see Section 7.8.

10. Where to get help

• Website: https://www.rgbjunkie.com — downloads, licensing, and published developer materials.
• Supported USB devices: /api/docs/supported-devices.html — search VID/PID, transport, and device kind.
• Help Center: rgbjunkie.com/RGBJunkieApp/help/ — end-user guides; Settings → Help in the app loads the same articles.