4.6.2 • Published 8 months ago

sacn v4.6.2

Weekly downloads
118
License
Apache-2.0
Repository
github
Last release
8 months ago

sACN receiver & sender in node.js

Build Status Coverage Status npm version npm install size

šŸ’” This module can receive DMX data sent via sACN from professional lighting consoles (e.g. ETC, Onyx).

šŸŽ­ It can also send data to DMX fixtures that support sACN, e.g. LED lights, smoke machines, etc.

Install

npm install sacn

Usage - Receiver

šŸ”¦ Sending RDM data to fixtures is not implemented yet, see issue #1.

const { Receiver } = require('sacn');

const sACN = new Receiver({
  universes: [1, 2],
  // see table 1 below for all options
});

sACN.on('packet', (packet) => {
  console.log('got dmx data:', packet.payload);
  // see table 2 below for all packet properties
});

sACN.on('PacketCorruption', (err) => {
  // trigged if a corrupted packet is received
});

sACN.on('PacketOutOfOrder', (err) => {
  // trigged if a packet is received out of order
});

/* advanced usage below */

sACN.on('error', (err) => {
  // trigged if there is an internal error (e.g. the supplied `iface` does not exist)
});

// start listening to a new universe (universe 3 in this example)
sACN.addUniverse(3);

// stop listening to a universe 1
sACN.removeUniverse(1);

// close all connections; terminate the receiver
sACN.close();

sACN.universes; // is a list of the universes being listened to

Table 1 - Options for Receiver

NameTypePurposeDefault
universesnumber[]Required. List of universes to listen to. Must be within 1-63999[]
portnumberOptional. The multicast port to use. All professional consoles broadcast to the default port.5568
ifacestringOptional. If the computer is connected to multiple networks, specify which network adaptor to use by using this computer's local IP addressnull
reuseAddrbooleanOptional. Allow multiple programs on your computer to listen to the same sACN universe.false

Table 2 - Packet properties

{
  "sourceName": "Onyx", // controller that sent the packet
  "sourceAddress": "192.168.1.69", // ip address of the controller
  "universe": 1, // DMX universe
  "sequence": 172, // packets are numbered 0-255 to keep them in order
  "priority": 100, // 0-200. used if multiple controllers send to the same universe
  "payload": { // an object with the percentage values of DMX channels 1-512
    1: 100,
    2: 50,
    3: 0
  },

  /* there are more low-level properties which most
     users won't need, see the ./src/packet.ts file */
}

Usage - Sender

const { Sender } = require('sacn');

const sACNServer = new Sender({
  universe: 1,
  // see table 3 below for all options
});

async function main() {
  await sACNServer.send({
    payload: {
      // Required. An object with the percentages (0-100) for each DMX channel.
      // You can use 0-255 instead of 0-100 by setting `useRawDmxValues: true`
      // per packet, or in the `defaultPacketOptions`.
      1: 100,
      2: 50,
      3: 0,
    },
    sourceName: "My NodeJS app", // optional. LED lights will use this as the name of the source lighting console.
    priority: 100, // optional. value between 0-200, in case there are other consoles broadcasting to the same universe
  });

  sACNServer.close(); // terminate the server when your app is about to exit.
}

main(); // wrapped in a main() function so that we can `await` the promise

Table 3 - Options for Sender

NameTypePurposeDefault
universenumberRequired. The universe to send to. Must be within 1-63999
portnumberOptional. The multicast port to use. All professional consoles broadcast to the default port.5568
reuseAddrbooleanOptional. Allow multiple programs on your computer to send to the same sACN universe.
defaultPacketOptionsobjectOptional. You can specify options like sourceName, cid, priority and useRawDmxValues here instead of on every packet
ifacestringOptional. Specifies the IPv4 address of the network interface/card to use.OS default interface (=active internet connection)
minRefreshRatenumberOptional. How often the data should be re-sent (in Hertz/Hz), even if it hasn't changed. By default data will only be sent once (equivilant of setting refreshRate: 0). To re-send data 5 times per second (5Hz), set refreshRate: 5. This is equivilant to 200ms.0
useUnicastDestinationstringOptional. Setting this attribute to an IPv4 address will cause data to be sent directly to that device, instead of broadcasting to the whole LAN.

Contribute

npm run build # compile typescript
npm test # run tests

Network Requirements

  • Multicast must be enabled1. 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.


1Ā­. Unicast is also supported by default, but this is not how sACN normally works. See Table 3 for how to send data directly to a unicast address. ↩

4.6.2

8 months ago

4.6.1

8 months ago

4.5.0

12 months ago

4.6.0

11 months ago

4.4.0

2 years ago

4.3.0

2 years ago

4.2.0

3 years ago

4.1.0

4 years ago

3.2.1

5 years ago

3.2.0

5 years ago

3.1.1

5 years ago

3.1.0

5 years ago

2.3.2

5 years ago

2.3.1

5 years ago

0.7.3

6 years ago

0.7.2

6 years ago

0.7.1

6 years ago

0.7.0

6 years ago