Fixtures (DMX)

DMX lighting fixtures — moving heads, color washes, and other E1.31-addressable devices on the animatronic network. Each fixture has a set of named channels, an optional persisted universe assignment, and a library of stored patterns that can be triggered ad-hoc or wired to bindings.

GET /api/v1/fixture — List all DMX fixtures known to the server.

GET /api/v1/fixture/{fixtureId} — Get a single fixture by its UUID.

POST /api/v1/fixture — Upsert a fixture’s configuration. Accepts a raw fixture JSON config string. Required fields: id, name, type, channel_offset, channels.

POST /api/v1/fixture/validate — Validate a fixture config payload without saving it.

DELETE /api/v1/fixture/{fixtureId} — Delete a fixture and any state attached to it.

Universe Assignment

Unlike creatures (whose universe is runtime-only), a fixture’s universe is persisted on the document so the server can stream DMX to it across restarts. The assignment is mirrored into a runtime lookup map for fast frame dispatch.

PUT /api/v1/fixture/{fixtureId}/universe — Assign the fixture to an E1.31 universe. Valid values are in [1, 63999].

{
  "universe": 1
}

DELETE /api/v1/fixture/{fixtureId}/universe — Clear a fixture’s universe assignment.

Pattern Playback

Patterns are stored channel-value snapshots with optional fade-in / hold / fade-out timing. They can be wired to bindings, fired manually for testing, or previewed live from the Creature Console pattern editor without saving. Both endpoints require the fixture to have an assigned universe.

POST /api/v1/fixture/{fixtureId}/pattern/{patternId}/trigger — Manually fire a stored pattern, bypassing the binding match. Body is optional; if present, stop_after_ms must be in (0, 600000] (10 minutes max).

{
  "stop_after_ms": 2000
}

POST /api/v1/fixture/{fixtureId}/pattern/preview — Fire a one-shot, not-persisted pattern built from the request body. Used by the Creature Console pattern editor’s Fire button to preview unsaved edits without an upsert round-trip. Refused with 400 if a live session is active on the fixture.

{
  "values": [
    { "channel": "red", "value": 255 },
    { "channel": "green", "value": 128 },
    { "channel": "blue", "value": 0 }
  ],
  "fade_in_ms": 250,
  "hold_ms": 1000,
  "fade_out_ms": 500,
  "stop_after_ms": 2000
}

Live Control

Live control bypasses patterns and bindings to drive a fixture’s channels directly — intended for slider-driven tuning in the Creature Console. The active pattern (if any) is cancelled immediately on the first live call, and new patterns are refused on this fixture until the live session expires. The server enforces an auto-blackout deadline so a disconnected client can’t leave lights stuck on.

POST /api/v1/fixture/{fixtureId}/live — Write per-channel DMX values directly. Channels not named in values retain their previous live value (or default to 0 on the first call). timeout_ms is required and must be in (0, 600000].

{
  "values": [
    { "channel": "pan", "value": 127 },
    { "channel": "tilt", "value": 64 }
  ],
  "timeout_ms": 5000
}