1 | # sACN receiver & sender in node.js
|
2 |
|
3 | [![Build Status](https://github.com/k-yle/sACN/workflows/Build%20and%20Test/badge.svg)](https://github.com/k-yle/sACN/actions)
|
4 | [![Coverage Status](https://coveralls.io/repos/github/k-yle/sACN/badge.svg?branch=main)](https://coveralls.io/github/k-yle/sACN?branch=main)
|
5 | [![npm version](https://badge.fury.io/js/sacn.svg)](https://badge.fury.io/js/sacn)
|
6 | [![npm](https://img.shields.io/npm/dt/sacn.svg)](https://www.npmjs.com/package/sacn)
|
7 | [![install size](https://packagephobia.com/badge?p=sacn)](https://packagephobia.com/result?p=sacn)
|
8 |
|
9 | 💡 This module can receive [DMX](https://en.wikipedia.org/wiki/DMX512) data sent via [sACN](https://en.wikipedia.org/wiki/E1.31) from professional lighting consoles (e.g. [ETC](https://www.etcconnect.com/), [Onyx](https://obsidiancontrol.com/)).
|
10 |
|
11 | 🎠It can also send data to DMX fixtures that support sACN, e.g. LED lights, smoke machines, etc.
|
12 |
|
13 | ## Install
|
14 |
|
15 | ```bash
|
16 | npm install sacn
|
17 | ```
|
18 |
|
19 | ## Usage - Receiver
|
20 |
|
21 | 🔦 Sending [RDM](<https://en.wikipedia.org/wiki/RDM_(lighting)>) data to fixtures is not implemented yet, see [issue #1](https://github.com/k-yle/sACN/issues/1).
|
22 |
|
23 | ```js
|
24 | const { Receiver } = require('sacn');
|
25 |
|
26 | const sACN = new Receiver({
|
27 | universes: [1, 2],
|
28 | // see table 1 below for all options
|
29 | });
|
30 |
|
31 | sACN.on('packet', (packet) => {
|
32 | console.log('got dmx data:', packet.payload);
|
33 | // see table 2 below for all packet properties
|
34 | });
|
35 |
|
36 | sACN.on('PacketCorruption', (err) => {
|
37 | // trigged if a corrupted packet is received
|
38 | });
|
39 |
|
40 | sACN.on('PacketOutOfOrder', (err) => {
|
41 | // trigged if a packet is received out of order
|
42 | });
|
43 |
|
44 | /* advanced usage below */
|
45 |
|
46 | sACN.on('error', (err) => {
|
47 | // trigged if there is an internal error (e.g. the supplied `iface` does not exist)
|
48 | });
|
49 |
|
50 | // start listening to a new universe (universe 3 in this example)
|
51 | sACN.addUniverse(3);
|
52 |
|
53 | // stop listening to a universe 1
|
54 | sACN.removeUniverse(1);
|
55 |
|
56 | // close all connections; terminate the receiver
|
57 | sACN.close();
|
58 |
|
59 | sACN.universes; // is a list of the universes being listened to
|
60 | ```
|
61 |
|
62 | ### Table 1 - Options for Receiver
|
63 |
|
64 | | Name | Type | Purpose | Default |
|
65 | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
66 | | `universes` | `number[]` | Required. List of universes to listen to. Must be within 1-63999 | `[]` |
|
67 | | `port` | `number` | Optional. The multicast port to use. All professional consoles broadcast to the default port. | `5568` |
|
68 | | `iface` | `string` | Optional. If the computer is connected to multiple networks, specify which network adaptor to use by using this computer's local IP address | `null` |
|
69 | | `reuseAddr` | `boolean` | Optional. Allow multiple programs on your computer to listen to the same sACN universe. | `false` |
|
70 |
|
71 | ### Table 2 - Packet properties
|
72 |
|
73 | ```js
|
74 | {
|
75 | "sourceName": "Onyx", // controller that sent the packet
|
76 | "sourceAddress": "192.168.1.69", // ip address of the controller
|
77 | "universe": 1, // DMX universe
|
78 | "sequence": 172, // packets are numbered 0-255 to keep them in order
|
79 | "priority": 100, // 0-200. used if multiple controllers send to the same universe
|
80 | "payload": { // an object with the percentage values of DMX channels 1-512
|
81 | 1: 100,
|
82 | 2: 50,
|
83 | 3: 0
|
84 | },
|
85 |
|
86 | /* there are more low-level properties which most
|
87 | users won't need, see the ./src/packet.ts file */
|
88 | }
|
89 | ```
|
90 |
|
91 | ## Usage - Sender
|
92 |
|
93 | ```js
|
94 | const { Sender } = require('sacn');
|
95 |
|
96 | const sACNServer = new Sender({
|
97 | universe: 1,
|
98 | // see table 3 below for all options
|
99 | });
|
100 |
|
101 | async function main() {
|
102 | await sACNServer.send({
|
103 | payload: { // required. object with the percentages for each DMX channel
|
104 | 1: 100,
|
105 | 2: 50,
|
106 | 3: 0,
|
107 | },
|
108 | sourceName: "My NodeJS app", // optional. LED lights will use this as the name of the source lighting console.
|
109 | priority: 100, // optional. value between 0-200, in case there are other consoles broadcasting to the same universe
|
110 | });
|
111 |
|
112 | sACNServer.close(); // terminate the server when your app is about to exit.
|
113 | }
|
114 |
|
115 | main(); // wrapped in a main() function so that we can `await` the promise
|
116 |
|
117 | ```
|
118 |
|
119 | ### Table 3 - Options for Sender
|
120 |
|
121 | | Name | Type | Purpose | Default |
|
122 | | ---------------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ------- |
|
123 | | `universe` | `number` | Required. The universes to listen to. Must be within 1-63999 | `[]` |
|
124 | | `port` | `number` | Optional. The multicast port to use. All professional consoles broadcast to the default port. | `5568` |
|
125 | | `reuseAddr` | `boolean` | Optional. Allow multiple programs on your computer to send to the same sACN universe. |
|
126 | | `defaultPacketOptions` | `object` | Optional. You can specify options like `sourceName`, `cid`, and `priority` here instead of on every packet |
|
127 | | `iface` | `string` | Optional. Specifies the IPv4 address of the network interface/card to use. | OS default interface (=active internet connection)
|
128 | | `useUnicastDestination`| `string` | Optional. Setting this attribute to an IPv4 address will cause data to be sent directly to that device, instead of broadcasting to the whole LAN. |
|
129 |
|
130 | # Contribute
|
131 |
|
132 | ```bash
|
133 | npm run build # compile typescript
|
134 | npm test # run tests
|
135 | ```
|
136 |
|
137 | # Network Requirements
|
138 |
|
139 | - [x] Multicast must be enabled<sup id="footnote-source1">[1](#footnote1)</sup>. sACN uses port `5568` on `239.255.x.x`
|
140 | - [x] Network infrastructure that supports at least 100Mbps (100BaseT)
|
141 |
|
142 | # Protocol Docs
|
143 |
|
144 | The Architecture for Control Networks (ACN) and derived protocols are created by the Entertainment Services and Technology Association.
|
145 |
|
146 | - sACN is defined in [ANSI E1.31](./docs/E1.31-2018.pdf)
|
147 | - RDMNet is defined in [ANSI E1.33](./docs/E1.33-2019.pdf)
|
148 |
|
149 | ---
|
150 | <small id="footnote1">
|
151 |
|
152 | 1­. Unicast is also supported by default, but this is not how sACN normally works. See [_Table 3_](#table-3---options-for-sender) for how to send data directly to a unicast address. [↩](#footnote-source1)
|
153 |
|
154 | </small>
|