@tiuxo/opencode-openrgb 0.0.0-stage → 0.1.0

package/src/palette.ts

@@ -0,0 +1,86 @@
+/**
+ * Color parsing and brightness scaling.
+ *
+ * Brightness is applied in software rather than via the mode's brightness
+ * field: "Direct" modes commonly report `brightness_min == brightness_max == 0`
+ * (both devices on the reference machine do), meaning the hardware exposes no
+ * brightness control at all in that mode.
+ */
+
+import { rgb, unpackRgb } from "./protocol.js"
+
+const NAMED_COLORS: Record<string, string> = {
+  black: "#000000",
+  white: "#ffffff",
+  red: "#ff0000",
+  green: "#00ff00",
+  blue: "#0000ff",
+  yellow: "#ffff00",
+  orange: "#ff8c00",
+  amber: "#ffbf00",
+  cyan: "#00ffff",
+  magenta: "#ff00ff",
+  violet: "#b400ff",
+  purple: "#8000ff",
+  pink: "#ff40a0",
+  teal: "#00c0a0",
+  lime: "#80ff00",
+  gold: "#ffd000",
+  off: "#000000",
+}
+
+/**
+ * Parse a color into an OpenRGB `RGBColor`.
+ *
+ * Accepts `#rgb`, `#rrggbb` (with or without the leading `#`), `rgb(r, g, b)`,
+ * and the named colors above. Returns null if the input is not understood, so
+ * callers can fall back to a default rather than silently lighting up black.
+ */
+export function parseColor(input: unknown): number | null {
+  if (typeof input === "number" && Number.isFinite(input)) {
+    return input >>> 0
+  }
+  if (typeof input !== "string") return null
+
+  const raw = input.trim().toLowerCase()
+  if (raw.length === 0) return null
+
+  const named = NAMED_COLORS[raw]
+  const value = named ?? raw
+
+  const fn = /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/.exec(value)
+  if (fn) {
+    return rgb(Number(fn[1]), Number(fn[2]), Number(fn[3]))
+  }
+
+  const hex = value.startsWith("#") ? value.slice(1) : value
+  if (/^[0-9a-f]{3}$/.test(hex)) {
+    const r = hex[0]!
+    const g = hex[1]!
+    const b = hex[2]!
+    return rgb(parseInt(r + r, 16), parseInt(g + g, 16), parseInt(b + b, 16))
+  }
+  if (/^[0-9a-f]{6}$/.test(hex)) {
+    return rgb(
+      parseInt(hex.slice(0, 2), 16),
+      parseInt(hex.slice(2, 4), 16),
+      parseInt(hex.slice(4, 6), 16),
+    )
+  }
+
+  return null
+}
+
+/** Scale a color's intensity by `factor`, clamped to [0, 1]. */
+export function scaleColor(color: number, factor: number): number {
+  const f = Math.max(0, Math.min(1, factor))
+  if (f === 1) return color >>> 0
+  const { r, g, b } = unpackRgb(color)
+  return rgb(r * f, g * f, b * f)
+}
+
+export function formatColor(color: number): string {
+  const { r, g, b } = unpackRgb(color)
+  const hex = (v: number) => v.toString(16).padStart(2, "0")
+  return `#${hex(r)}${hex(g)}${hex(b)}`
+}

package/src/protocol.ts

@@ -0,0 +1,611 @@
+/**
+ * OpenRGB SDK binary protocol codec.
+ *
+ * Wire format verified against OpenRGB 1.0rc3.1 (protocol 5) and the upstream
+ * sources `RGBController.cpp`, `RGBController_Network.cpp` and
+ * `RGBControllerInterface.h`.
+ *
+ * Every integer on the wire is little-endian. Every string is a `uint16`
+ * byte-length (which *includes* the NUL terminator) followed by that many
+ * bytes, the last of which is NUL.
+ */
+
+export const MAGIC = "ORGB"
+export const HEADER_SIZE = 16
+export const DEFAULT_HOST = "127.0.0.1"
+export const DEFAULT_PORT = 6742
+
+/**
+ * Highest protocol version this client implements.
+ *
+ * Negotiation is `min(server, CLIENT_PROTOCOL_VERSION)`, so advertising 5 to a
+ * protocol-6 server is forward compatible: the server simply speaks 5 back.
+ * Protocol 6 changes device addressing (unique IDs instead of list indices),
+ * adds ACKs and drops `mode.value`; the decoders below are version-guarded so
+ * raising this constant is a contained change.
+ */
+export const CLIENT_PROTOCOL_VERSION = 5
+
+export const PacketId = {
+  REQUEST_CONTROLLER_COUNT: 0,
+  REQUEST_CONTROLLER_DATA: 1,
+  REQUEST_PROTOCOL_VERSION: 40,
+  SET_CLIENT_NAME: 50,
+  DEVICE_LIST_UPDATED: 100,
+  RGBCONTROLLER_RESIZEZONE: 1000,
+  RGBCONTROLLER_UPDATELEDS: 1050,
+  RGBCONTROLLER_UPDATEZONELEDS: 1051,
+  RGBCONTROLLER_UPDATESINGLELED: 1052,
+  RGBCONTROLLER_SETCUSTOMMODE: 1100,
+  RGBCONTROLLER_UPDATEMODE: 1101,
+  RGBCONTROLLER_SAVEMODE: 1102,
+} as const
+
+/** Bit flags on `Mode.flags`. From `RGBControllerInterface.h`. */
+export const ModeFlag = {
+  HAS_SPEED: 1 << 0,
+  HAS_DIRECTION_LR: 1 << 1,
+  HAS_DIRECTION_UD: 1 << 2,
+  HAS_DIRECTION_HV: 1 << 3,
+  HAS_BRIGHTNESS: 1 << 4,
+  HAS_PER_LED_COLOR: 1 << 5,
+  HAS_MODE_SPECIFIC_COLOR: 1 << 6,
+  HAS_RANDOM_COLOR: 1 << 7,
+  MANUAL_SAVE: 1 << 8,
+  AUTOMATIC_SAVE: 1 << 9,
+  REQUIRES_ENTIRE_DEVICE: 1 << 10,
+  HAS_DIRECTION_DIAG: 1 << 11,
+} as const
+
+/** Values for `Mode.colorMode`. */
+export const ModeColors = {
+  NONE: 0,
+  PER_LED: 1,
+  MODE_SPECIFIC: 2,
+  RANDOM: 3,
+} as const
+
+/** Indexed by the `Device.type` integer. Order is significant. */
+export const DEVICE_TYPES = [
+  "motherboard",
+  "dram",
+  "gpu",
+  "cooler",
+  "ledstrip",
+  "keyboard",
+  "mouse",
+  "mousemat",
+  "headset",
+  "headset_stand",
+  "gamepad",
+  "light",
+  "speaker",
+  "virtual",
+  "storage",
+  "case",
+  "microphone",
+  "accessory",
+  "keypad",
+  "laptop",
+  "monitor",
+  "unknown",
+] as const
+
+/** Indexed by the `Zone.type` integer. Order is significant. */
+export const ZONE_TYPES = [
+  "single",
+  "linear",
+  "matrix",
+  "linear_loop",
+  "matrix_loop_x",
+  "matrix_loop_y",
+  "segmented",
+] as const
+
+export function deviceTypeName(type: number): string {
+  return DEVICE_TYPES[type] ?? "unknown"
+}
+
+export function zoneTypeName(type: number): string {
+  return ZONE_TYPES[type] ?? "unknown"
+}
+
+/*---------------------------------------------------------------------------*\
+| Colors                                                                      |
+\*---------------------------------------------------------------------------*/
+
+/**
+ * An OpenRGB `RGBColor` is a `uint32` laid out as `0x00BBGGRR`, i.e. the
+ * little-endian byte order on the wire is red, green, blue, zero.
+ *
+ * Mirrors `ToRGBColor(r, g, b)` from `RGBControllerInterface.h`.
+ */
+export function rgb(r: number, g: number, b: number): number {
+  return ((clampByte(b) << 16) | (clampByte(g) << 8) | clampByte(r)) >>> 0
+}
+
+export function unpackRgb(color: number): { r: number; g: number; b: number } {
+  return {
+    r: color & 0xff,
+    g: (color >>> 8) & 0xff,
+    b: (color >>> 16) & 0xff,
+  }
+}
+
+function clampByte(v: number): number {
+  if (!Number.isFinite(v)) return 0
+  return Math.max(0, Math.min(255, Math.round(v)))
+}
+
+/*---------------------------------------------------------------------------*\
+| Reader / Writer                                                             |
+\*---------------------------------------------------------------------------*/
+
+export class Reader {
+  constructor(
+    private readonly buf: Buffer,
+    private off = 0,
+  ) {}
+
+  get offset(): number {
+    return this.off
+  }
+
+  get remaining(): number {
+    return this.buf.length - this.off
+  }
+
+  u16(): number {
+    const v = this.buf.readUInt16LE(this.off)
+    this.off += 2
+    return v
+  }
+
+  u32(): number {
+    const v = this.buf.readUInt32LE(this.off)
+    this.off += 4
+    return v
+  }
+
+  i32(): number {
+    const v = this.buf.readInt32LE(this.off)
+    this.off += 4
+    return v
+  }
+
+  /** Length-prefixed, NUL-terminated string. The prefix counts the NUL. */
+  str(): string {
+    const len = this.u16()
+    const raw = this.buf.toString("utf8", this.off, this.off + len)
+    this.off += len
+    // Strip the trailing NUL (and defensively any extra padding).
+    return raw.replace(/\0+$/, "")
+  }
+
+  skip(n: number): void {
+    this.off += n
+  }
+}
+
+class Writer {
+  private buf = Buffer.alloc(256)
+  private off = 0
+
+  private ensure(n: number): void {
+    if (this.off + n <= this.buf.length) return
+    let size = this.buf.length
+    while (size < this.off + n) size *= 2
+    const next = Buffer.alloc(size)
+    this.buf.copy(next, 0, 0, this.off)
+    this.buf = next
+  }
+
+  u16(v: number): this {
+    this.ensure(2)
+    this.buf.writeUInt16LE(v >>> 0, this.off)
+    this.off += 2
+    return this
+  }
+
+  u32(v: number): this {
+    this.ensure(4)
+    this.buf.writeUInt32LE(v >>> 0, this.off)
+    this.off += 4
+    return this
+  }
+
+  i32(v: number): this {
+    this.ensure(4)
+    this.buf.writeInt32LE(v | 0, this.off)
+    this.off += 4
+    return this
+  }
+
+  /** Length-prefixed, NUL-terminated string. The prefix counts the NUL. */
+  str(s: string): this {
+    const bytes = Buffer.from(s, "utf8")
+    this.u16(bytes.length + 1)
+    this.ensure(bytes.length + 1)
+    bytes.copy(this.buf, this.off)
+    this.off += bytes.length
+    this.buf.writeUInt8(0, this.off)
+    this.off += 1
+    return this
+  }
+
+  done(): Buffer {
+    return this.buf.subarray(0, this.off)
+  }
+}
+
+/*---------------------------------------------------------------------------*\
+| Types                                                                       |
+\*---------------------------------------------------------------------------*/
+
+export interface Mode {
+  name: string
+  /** Device-internal value. Must be round-tripped verbatim on protocol < 6. */
+  value: number
+  flags: number
+  speedMin: number
+  speedMax: number
+  brightnessMin: number
+  brightnessMax: number
+  colorsMin: number
+  colorsMax: number
+  speed: number
+  brightness: number
+  direction: number
+  colorMode: number
+  colors: number[]
+}
+
+export interface Segment {
+  name: string
+  type: number
+  startIdx: number
+  ledsCount: number
+}
+
+export interface Zone {
+  name: string
+  type: number
+  typeName: string
+  ledsMin: number
+  ledsMax: number
+  ledsCount: number
+  matrix?: { height: number; width: number; data: number[] }
+  segments: Segment[]
+  flags: number
+}
+
+export interface Led {
+  name: string
+  value: number
+}
+
+export interface Device {
+  /** Index in the server's controller list; used as `pkt_dev_id`. */
+  index: number
+  type: number
+  typeName: string
+  name: string
+  vendor: string
+  description: string
+  version: string
+  serial: string
+  location: string
+  activeMode: number
+  modes: Mode[]
+  zones: Zone[]
+  leds: Led[]
+  colors: number[]
+  ledDisplayNames: string[]
+  flags: number
+}
+
+/*---------------------------------------------------------------------------*\
+| Packet framing                                                              |
+\*---------------------------------------------------------------------------*/
+
+export function encodePacket(devId: number, pktId: number, data?: Buffer): Buffer {
+  const body = data ?? Buffer.alloc(0)
+  const header = Buffer.alloc(HEADER_SIZE)
+  header.write(MAGIC, 0, "ascii")
+  header.writeUInt32LE(devId >>> 0, 4)
+  header.writeUInt32LE(pktId >>> 0, 8)
+  header.writeUInt32LE(body.length, 12)
+  return body.length === 0 ? header : Buffer.concat([header, body])
+}
+
+export interface Frame {
+  devId: number
+  pktId: number
+  data: Buffer
+}
+
+/**
+ * Pull as many complete frames as possible off the front of `buf`.
+ * Returns the frames plus whatever bytes remain unconsumed.
+ */
+export function decodeFrames(buf: Buffer): { frames: Frame[]; rest: Buffer } {
+  const frames: Frame[] = []
+  let cursor = buf
+
+  while (cursor.length >= HEADER_SIZE) {
+    if (cursor.toString("ascii", 0, 4) !== MAGIC) {
+      // Desynchronised. Resynchronise on the next magic value, or drop
+      // everything if none is present.
+      const next = cursor.indexOf(MAGIC, 1, "ascii")
+      if (next === -1) return { frames, rest: Buffer.alloc(0) }
+      cursor = cursor.subarray(next)
+      continue
+    }
+
+    const size = cursor.readUInt32LE(12)
+    if (cursor.length < HEADER_SIZE + size) break
+
+    frames.push({
+      devId: cursor.readUInt32LE(4),
+      pktId: cursor.readUInt32LE(8),
+      data: cursor.subarray(HEADER_SIZE, HEADER_SIZE + size),
+    })
+    cursor = cursor.subarray(HEADER_SIZE + size)
+  }
+
+  return { frames, rest: cursor }
+}
+
+/*---------------------------------------------------------------------------*\
+| Mode                                                                        |
+\*---------------------------------------------------------------------------*/
+
+export function decodeMode(r: Reader, protocol: number): Mode {
+  const name = r.str()
+  // `mode.value` was removed in protocol 6.
+  const value = protocol < 6 ? r.i32() : 0
+  const flags = r.u32()
+  const speedMin = r.u32()
+  const speedMax = r.u32()
+  const brightnessMin = protocol >= 3 ? r.u32() : 0
+  const brightnessMax = protocol >= 3 ? r.u32() : 0
+  const colorsMin = r.u32()
+  const colorsMax = r.u32()
+  const speed = r.u32()
+  const brightness = protocol >= 3 ? r.u32() : 0
+  const direction = r.u32()
+  const colorMode = r.u32()
+
+  const numColors = r.u16()
+  const colors: number[] = []
+  for (let i = 0; i < numColors; i++) colors.push(r.u32())
+
+  return {
+    name,
+    value,
+    flags,
+    speedMin,
+    speedMax,
+    brightnessMin,
+    brightnessMax,
+    colorsMin,
+    colorsMax,
+    speed,
+    brightness,
+    direction,
+    colorMode,
+    colors,
+  }
+}
+
+/**
+ * Inverse of {@link decodeMode}. Field order mirrors
+ * `RGBController::GetModeDescriptionData` exactly.
+ */
+function encodeMode(w: Writer, mode: Mode, protocol: number): void {
+  w.str(mode.name)
+  if (protocol < 6) w.i32(mode.value)
+  w.u32(mode.flags)
+  w.u32(mode.speedMin)
+  w.u32(mode.speedMax)
+  if (protocol >= 3) {
+    w.u32(mode.brightnessMin)
+    w.u32(mode.brightnessMax)
+  }
+  w.u32(mode.colorsMin)
+  w.u32(mode.colorsMax)
+  w.u32(mode.speed)
+  if (protocol >= 3) w.u32(mode.brightness)
+  w.u32(mode.direction)
+  w.u32(mode.colorMode)
+  w.u16(mode.colors.length)
+  for (const c of mode.colors) w.u32(c)
+}
+
+/*---------------------------------------------------------------------------*\
+| Zone / device                                                               |
+\*---------------------------------------------------------------------------*/
+
+function decodeZone(r: Reader, protocol: number): Zone {
+  const name = r.str()
+  const type = r.i32()
+  const ledsMin = r.u32()
+  const ledsMax = r.u32()
+  const ledsCount = r.u32()
+
+  let matrix: Zone["matrix"]
+  const matrixLen = r.u16()
+  if (matrixLen > 0) {
+    const height = r.u32()
+    const width = r.u32()
+    const cells = Math.max(0, (matrixLen - 8) >> 2)
+    const data: number[] = []
+    for (let i = 0; i < cells; i++) data.push(r.u32())
+    matrix = { height, width, data }
+  }
+
+  const segments: Segment[] = []
+  if (protocol >= 4) {
+    const numSegments = r.u16()
+    for (let i = 0; i < numSegments; i++) {
+      segments.push({
+        name: r.str(),
+        type: r.i32(),
+        startIdx: r.u32(),
+        ledsCount: r.u32(),
+      })
+    }
+  }
+
+  const flags = protocol >= 5 ? r.u32() : 0
+
+  return {
+    name,
+    type,
+    typeName: zoneTypeName(type),
+    ledsMin,
+    ledsMax,
+    ledsCount,
+    ...(matrix ? { matrix } : {}),
+    segments,
+    flags,
+  }
+}
+
+/**
+ * Decode a `REQUEST_CONTROLLER_DATA` response body.
+ *
+ * The body opens with a `uint32` total size (which includes itself) followed by
+ * the device description block.
+ */
+export function decodeDevice(data: Buffer, protocol: number, index: number): Device {
+  return decodeDeviceChecked(data, protocol, index).device
+}
+
+/**
+ * As {@link decodeDevice}, but also reports how many bytes were left over.
+ *
+ * A correct decode consumes the block exactly, so `trailingBytes` should always
+ * be 0. Any other value means the field layout has drifted from the server's —
+ * which is exactly what `scripts/probe.ts` asserts.
+ */
+export function decodeDeviceChecked(
+  data: Buffer,
+  protocol: number,
+  index: number,
+): { device: Device; trailingBytes: number } {
+  const r = new Reader(data)
+  r.u32() // data_size, includes itself
+
+  const type = r.i32()
+  const name = r.str()
+  const vendor = protocol >= 1 ? r.str() : ""
+  const description = r.str()
+  const version = r.str()
+  const serial = r.str()
+  const location = r.str()
+
+  const numModes = r.u16()
+  const activeMode = r.i32()
+  const modes: Mode[] = []
+  for (let i = 0; i < numModes; i++) modes.push(decodeMode(r, protocol))
+
+  const numZones = r.u16()
+  const zones: Zone[] = []
+  for (let i = 0; i < numZones; i++) zones.push(decodeZone(r, protocol))
+
+  const numLeds = r.u16()
+  const leds: Led[] = []
+  for (let i = 0; i < numLeds; i++) {
+    const ledName = r.str()
+    // `led.value` was removed in protocol 6.
+    const ledValue = protocol < 6 ? r.u32() : 0
+    leds.push({ name: ledName, value: ledValue })
+  }
+
+  const numColors = r.u16()
+  const colors: number[] = []
+  for (let i = 0; i < numColors; i++) colors.push(r.u32())
+
+  const ledDisplayNames: string[] = []
+  let flags = 0
+  if (protocol >= 5) {
+    const numDisplayNames = r.u16()
+    for (let i = 0; i < numDisplayNames; i++) ledDisplayNames.push(r.str())
+    flags = r.u32()
+  }
+
+  return {
+    device: {
+      index,
+      type,
+      typeName: deviceTypeName(type),
+      name,
+      vendor,
+      description,
+      version,
+      serial,
+      location,
+      activeMode,
+      modes,
+      zones,
+      leds,
+      colors,
+      ledDisplayNames,
+      flags,
+    },
+    trailingBytes: r.remaining,
+  }
+}
+
+/*---------------------------------------------------------------------------*\
+| Request bodies                                                              |
+\*---------------------------------------------------------------------------*/
+
+export function encodeProtocolVersion(version: number): Buffer {
+  const b = Buffer.alloc(4)
+  b.writeUInt32LE(version >>> 0, 0)
+  return b
+}
+
+export function encodeClientName(name: string): Buffer {
+  return Buffer.from(`${name}\0`, "utf8")
+}
+
+/**
+ * `UPDATELEDS` body: `data_size` (uint32, **including itself**), `num_colors`
+ * (uint16), then one `RGBColor` per LED.
+ *
+ * Confirmed against `RGBController_Network::CreateUpdateLEDsPacket`, which
+ * computes `data_size = sizeof(data_size) + GetColorDescriptionSize(...)` and
+ * passes that same value as the packet header size.
+ */
+export function encodeUpdateLeds(colors: readonly number[]): Buffer {
+  const size = 4 + 2 + colors.length * 4
+  const b = Buffer.alloc(size)
+  b.writeUInt32LE(size, 0)
+  b.writeUInt16LE(colors.length, 4)
+  for (let i = 0; i < colors.length; i++) {
+    b.writeUInt32LE((colors[i] ?? 0) >>> 0, 6 + i * 4)
+  }
+  return b
+}
+
+/**
+ * `UPDATEMODE` body: `data_size` (uint32, **including itself**), `mode_idx`
+ * (int32), then the mode description block.
+ *
+ * `SAVEMODE` uses an identical body.
+ */
+export function encodeUpdateMode(modeIdx: number, mode: Mode, protocol: number): Buffer {
+  const inner = new Writer()
+  encodeMode(inner, mode, protocol)
+  const modeBytes = inner.done()
+
+  const size = 4 + 4 + modeBytes.length
+  const b = Buffer.alloc(size)
+  b.writeUInt32LE(size, 0)
+  b.writeInt32LE(modeIdx | 0, 4)
+  modeBytes.copy(b, 8)
+  return b
+}