sACN receiver in Deno.js

💡 This module can receive DMX data sent via sACN from professional lighting consoles (e.g. ETC Eos, Onyx).

This is a Deno.js port of https://github.com/k-yle/sACN, but it is NOT API compatible (especially events). Most parts are rewritten from ground up using modern APIs (ArrayBuffer, TypedArray, AsyncIterator, ...). Unlike k-yle/sACN this one natively supports merging channel priorities.

Install

import {...} from "https://deno.land/x/sacn/mod.ts"

Receiver API

// see https://github.com/LMGU-Technik/sACN-Deno/tree/main/examples

import { globalToDmx, Receiver } from "https://deno.land/x/sacn/mod.ts";

const receiver = new Receiver({
    // options
});
await receiver.addUniverse(1);

for await (const [chan, value] of receiver) {
    const [univ, addr] = globalToDmx(chan);
    console.log(`Chan ${univ}/${addr} = ${value}`);
}

new Receiver(options: ReceiverOptions)

interface ReceiverOptions {
    // nearly every implementation uses this port
    // defaults to 5568
    readonly port: number;
    // network interface to listen on
    // defaults to all (0.0.0.0)
    readonly iface: string;
    // drop all non-zero start code packets
    // defaults to true
    readonly dmxAOnly: boolean;
}

Receiver.addUniverse(universe: number): Promise<boolean>

Adds a universe to listen on. Returns false if already listening on the specified one.

Receiver.removeUniverse(universe: number): Promise<boolean>

Stops listening on universe. Returns false if not listening on the specified one.

Receiver.[Symbol.asyncIterator](): AsyncIterator<[number,number]>

Used to obtain value changes

for await (const [chan, value] of receiver) {
    // chan is a global address, this helper function can be used to split into universe and address
    const [univ, addr] = globalToDmx(chan);
    console.log(`Chan ${univ}/${addr} = ${value}`);
}

Receiver.onPacket(): AsyncGenerator<Packet>

Advanced: Used to obtain bare packets

for await (const packet of receiver.onPacket()) {
    // do stuff ...
}
interface Packet {
    cid: Uint8Array;
    priority: number;
    sequence: number;
    universe: number;
    data: Uint8Array;
    sourceLabel: string;
}

Receiver.[Symbol.dispose](): void / Receiver.dispose(): void

Frees up resources. Supports using keyword.

Sender API

Coming soon. Contributions welcome.

Network Requirements

  • Multicast must be enabled. sACN uses port 5568 on 239.255.x.x
  • Network infrastructure that supports at least 100Mbps (100BaseT)

Protocol Docs

The Architecture for Control Networks (ACN) and derived protocols are created by the Entertainment Services and Technology Association (ESTA).

Testing

  • This software has been tested against sACNView (Third-party software) and ETC Eos (Third-party software)

License

(c) 2023 Hans Schallmoser

Licensed under the terms of the GNU General public license (see LICENSE file)

Based on the work of Kyâ„“e Hensel: https://github.com/k-yle/sACN (Apache-2.0).