node-dmx
    Preparing search index...

    node-dmx

    node-dmx 🎛️

    node-dmx is a TypeScript library for controlling DMX over IP from Node.js.

    It supports:

    • sACN (E1.31)
    • Art-Net 4
    • RDM over Art-Net
    • RDMnet (ANSI E1.33: root layer + Broker session + RPT RDM transactions + real LLRP UDP discovery)
    • A fixture plugin system
    • Root layer (rdmnet/packet), Broker PDU (rdmnet/broker), and RPT PDU (rdmnet/rpt) are wire-format-correct per ANSI E1.33, verified byte-for-byte against ETCLabs' open-source E1.33 reference implementation (root-layer extended flags+length, Broker Connect/Connect Reply/Client Entry/Client List/Disconnect/Null, RPT header + Request/Notification/Status PDUs including the RDM Command PDU's leading-0xCC encoding).
    • LLRP (rdmnet/llrp-transport: LlrpManager, LlrpTarget) implements the real ANSI E1.33 §6 UDP multicast transport — two multicast groups (request/response), the 27-byte LLRP PDU header, Probe Request/Reply, RDM command passthrough, and the reference discovery algorithm (ranged probing with a known-UID exclusion list, gated by consecutive clean rounds). It is intentionally not carried over RdmnetClient's TCP connection, matching the spec's requirement that LLRP work without a live Broker session.
    • Not implemented: EPT client entries/messages beyond basic pass-through, Dynamic UID assignment, and Redirect V6. These are lower-traffic corners of E1.33 that most controllers/devices don't exercise.
    • Not claimed: formal/full E1.33 compliance certification — that requires running the ANSI/ESTA conformance test suite against real third-party brokers/controllers/devices in your target environment, which is outside what a library alone can certify.
    Area Feature sACN (E1.31) Art-Net 4 RDMnet (E1.33) Notes
    Core I/O DMX Send ✅ ✅ ❌ DMXController sends DMX via sACN/Art-Net
    Core I/O DMX Receive / Listen ✅ ✅ ❌ Receiver, ArtNetReceiver — RDMnet carries RDM device management, not DMX slot data
    Core I/O Synchronization / Discovery ✅ ✅ (ArtSync) n/a Sender.sendSync, UniverseDiscoverySource (E1.31 §6/§8)
    Device Discovery Controller/Node Discovery ⚠️ Discovery packets ✅ ✅ ArtNetDiscovery, RdmnetDiscovery (DNS-SD + mDNS), LlrpManager
    Device Management RDM Messaging (controller) ❌ ✅ ✅ ArtNetRdmClient full flow, RdmnetClient RPT rdmTransaction, LlrpManager RDM passthrough
    Device Management RDM Responder (fixture/device) n/a ✅ ✅ RdmResponder core + ArtNetRdmResponder / RdmnetClient.useRdmResponder / LlrpTarget
    Security Secure Transport ❌ ❌ ✅ RdmnetClient supports transport: 'tls', peer auth policy, post-connect auth hook
    Ecosystem Fixture Plugin System ✅ ✅ ❌ Fixture API currently targets DMX output protocols
    Compliance Formal Protocol Compliance Claim ✅ E1.31 implementation ✅ Art-Net implementation ⚠️ Wire-format verified RDMnet: root/Broker/RPT/LLRP wire-verified; full claim depends on third-party conformance runs

    This guide is written for students and first-time users: start simple, then move to advanced features.

    • Node.js 18+
    • A DMX-over-IP device (sACN or Art-Net)
    • Computer and lighting device on the same network
    npm install node-dmx
    • A universe has 512 channels.
    • A channel value is 0-255.
    • You set values in memory, then call flush() to send them.
    import {DMXController} from 'node-dmx';

    const controller = new DMXController({protocol: 'sacn'});
    const universe = controller.addUniverse(1);

    universe.setChannel(1, 255); // channel 1 at full

    await controller.flush();
    controller.close();

    import {DMXController} from 'node-dmx';

    const controller = new DMXController({
      protocol: 'artnet',
      artSync: true,
      artnet: {
        host: '255.255.255.255',
        broadcast: true,
      },
    });

    controller.setChannel(1, 1, 255); // universe 1, channel 1, full
    await controller.flush();
    controller.close();

    import {DMXController} from 'node-dmx';

    const controller = new DMXController({protocol: 'sacn'});
    const u1 = controller.addUniverse(1);
    const u2 = controller.addUniverse(2);

    u1.setChannel(1, 255);
    u2.setChannel(1, 128);

    await controller.flush(); // sends all dirty universes

    import {ArtNetDiscovery} from 'node-dmx';

    const discovery = new ArtNetDiscovery();
    const replies = await discovery.pollOnce();

    for (const node of replies) {
      console.log(node.ip, node.shortName, node.longName);
    }

    discovery.close();

    import {ArtNetRdmClient, RdmCommandClass, PIDS} from 'node-dmx';

    const client = new ArtNetRdmClient({host: '192.168.0.10'});

    const response = await client.rdmTransaction(1, {
      destinationUid: {manufacturerId: 0x7a70, deviceId: 0x00000001},
      sourceUid: {manufacturerId: 0x7a70, deviceId: 0x00000002},
      transactionNumber: 1,
      portId: 1,
      subDevice: 0,
      commandClass: RdmCommandClass.GET_COMMAND,
      pid: PIDS.DEVICE_INFO,
    });

    console.log(response);
    client.close();

    RdmResponder is a transport-agnostic RDM device core — it answers GET/SET for the standard PID set (DEVICE_INFO, DMX_START_ADDRESS, IDENTIFY_DEVICE, DEVICE_LABEL, DMX_PERSONALITY, MANUFACTURER_LABEL, SUPPORTED_PARAMETERS, DISC_MUTE/UN_MUTE...) for you — no manual ACK/NACK frame or checksum handling. Three wrappers plug it into each transport:

    import {ArtNetRdmResponder, RdmResponder} from 'node-dmx';

    const uid = {manufacturerId: 0x7a70, deviceId: 0x00000042};
    const responder = new RdmResponder({
      uid,
      deviceLabel: 'Sim Fixture 1',
      dmxStartAddress: 1,
      personalities: [{footprint: 3, description: 'RGB'}],
      onIdentifyChange: (on) => console.log('identify', on),
    });

    // Art-Net: answers ArtPoll/ArtTodRequest/ArtRdm; discoverable via ArtNetDiscovery.
    const fixture = new ArtNetRdmResponder({responder, universe: 1});
    fixture.on('dmx', (frame) => console.log('levels', frame.subarray(0, 3)));
    • Art-Net: ArtNetRdmResponder (also receives ArtDMX for the configured universe).
    • RDMnet: RdmnetClient.useRdmResponder(responder) — auto-answers inbound RPT Requests.
    • LLRP: new LlrpTarget({..., onRdmCommand: (frame) => responder.respond(frame)}).

    See examples/artnet-fixture-simulator.ts, examples/rdmnet-fixture-simulator.ts, and examples/rdmnet-llrp-fixture-simulator.ts.

    import {DMXController, Fixture, RGBDimmerFixture} from 'node-dmx';

    const controller = new DMXController({protocol: 'sacn'});
    controller.addUniverse(1);

    const fixture = new Fixture(
      controller,
      RGBDimmerFixture,
      1,     // universe
      1,     // start address
      '4ch', // personality id
    );

    // RGBDimmerFixture expects state with `dimmer` and `rgb` array values in range 0..1
    fixture.set({dimmer: 1, rgb: [1, 0.25, 0.1]});
    fixture.render();

    await controller.flush();

    Available built-in example fixture plugins:

    • RGBDimmerFixture (4ch: dimmer + RGB)
    • RGBWW5Fixture (5ch: R + G + B + warm white + cool white)

    All examples live in examples/.

    Core examples:

    • examples/sacn-basic.ts
    • examples/sacn-animate.ts
    • examples/sacn-animate-orignal.ts (older single-universe variant)
    • examples/sacn-rainbow.ts
    • examples/sacn-sync.ts — Synchronization Packets (E1.31 §6)
    • examples/sacn-universe-discovery.ts — Universe Discovery (E1.31 §8)
    • examples/sacn-listen-matrix.ts
    • examples/artnet-animate.ts
    • examples/artnet-listen-matrix.ts
    • examples/artnet-discover.ts
    • examples/artnet-fixture-simulator.ts — simulate a DMX+RDM fixture
    • examples/rdm-tod.ts
    • examples/rdmnet-listen.ts
    • examples/rdmnet-discover.ts
    • examples/rdmnet-interop-smoke.ts
    • examples/rdmnet-rdm-transaction.ts — RDM GET over RPT
    • examples/rdmnet-llrp-discover.ts — real LLRP UDP device discovery
    • examples/rdmnet-fixture-simulator.ts — simulate an RDMnet RDM device
    • examples/rdmnet-llrp-fixture-simulator.ts — simulate an LLRP Target
    • examples/fixture-rgbww5.ts
    • examples/list-network-interfaces.ts

    Additional animation examples:

    • examples/sacn-comet-chase.ts
    • examples/sacn-fire-flicker.ts
    • examples/sacn-police-strobe.ts
    • examples/sacn-breathing-pastels.ts
    • examples/sacn-color-wipe.ts
    • examples/sacn-sparkle.ts
    • examples/sacn-theater-chase.ts
    • examples/sacn-aurora.ts
    • examples/sacn-pulse-stack.ts
    • examples/sacn-storm.ts
    • examples/sacn-halloween.ts
    • examples/sacn-christmas.ts

    Run an example:

    npm run example/sacn-rainbow

    All sacn-* examples read DMX_IFACE to override the hardcoded interface IP:

    DMX_IFACE=192.168.1.50 npm run example/sacn-rainbow

    Useful options for DMXController:

    • protocol: 'sacn' | 'artnet'
    • iface: local interface IPv4 address
    • reuseAddr: allow multiple listeners/senders on same UDP port
    • unicastDestination: send unicast instead of multicast/broadcast
    • artSync: send ArtSync after flush (Art-Net)

    RDMnet client options:

    • uid: required — this component's RDM UID ({manufacturerId, deviceId}), carried in the Broker Client Entry and every RPT header
    • transport: 'tcp' | 'tls' (default tcp)
    • tls: Node TLS options (CA, client cert/key, ciphers, min/max version, etc.)
    • requireTlsAuthorization: reject unauthorized TLS peers (default true when transport: 'tls')
    • postConnectAuth: async hook for environment-specific auth/profile checks

    Use real brokers/devices for compliance verification (not mocks only).

    Smoke-runner against a real broker:

    RDMNET_INTEROP_HOST=192.168.1.50 \
    RDMNET_INTEROP_PORT=5568 \
    npm run example/rdmnet-interop-smoke

    Environment-gated integration test:

    RDMNET_INTEROP_HOST=192.168.1.50 \
    RDMNET_INTEROP_PORT=5568 \
    RDMNET_INTEROP_SCOPE=default \
    npm run test:interop:rdmnet

    Useful flags:

    • RDMNET_INTEROP_TLS=1: use TLS transport
    • RDMNET_INTEROP_TLS_STRICT=0: allow non-authorized TLS peer for lab setups
    • RDMNET_INTEROP_CHECK_LISTS=1: also validate the broker client-list request
    • RDMNET_INTEROP_TIMEOUT_MS=5000: per-request timeout override

    TypeDoc output uses README.md as the landing page.

    Build docs:

    npm run docs:build

    Output:

    • generated/docs
    • Verify your interface IP (iface) is on the same subnet as the fixture.
    • If multicast does not work on your network, use unicast.
    • Try universe numbering differences (some devices start at 0, most at 1).
    • For Art-Net broadcast, ensure network allows UDP broadcasts.

    Settings

    Member Visibility

    On This Page

    node-dmx 🎛️