| 1 | # sACN receiver in node.js
|
| 2 |
|
| 3 | [](https://github.com/k-yle/sACN/actions)
|
| 4 | [](https://coveralls.io/github/k-yle/sACN?branch=master)
|
| 5 | [](https://badge.fury.io/js/sacn)
|
| 6 | [](https://www.npmjs.com/package/sacn)
|
| 7 |
|
| 8 | 💡 🎠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/)).
|
| 9 |
|
| 10 | > 🔦 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).
|
| 11 |
|
| 12 | ## Install
|
| 13 |
|
| 14 | ```bash
|
| 15 | npm install sacn
|
| 16 | ```
|
| 17 |
|
| 18 | ## Usage
|
| 19 |
|
| 20 | ```js
|
| 21 | const { Receiver, objectify } = require('sacn');
|
| 22 |
|
| 23 | const sACN = new Receiver({
|
| 24 | universes: [1, 2],
|
| 25 | // see table 1 below for all options
|
| 26 | });
|
| 27 |
|
| 28 | sACN.on('packet', (packet) => {
|
| 29 | console.log('got dmx data:', objectify(packet.slotsData));
|
| 30 | // see table 2 below for all packet properties
|
| 31 | });
|
| 32 |
|
| 33 | sACN.on('PacketCorruption', (err) => {
|
| 34 | // trigged if a corrupted packet is received
|
| 35 | });
|
| 36 |
|
| 37 | sACN.on('PacketOutOfOrder', (err) => {
|
| 38 | // trigged if a packet is recieved out of order
|
| 39 | });
|
| 40 |
|
| 41 | /* advanced usage below */
|
| 42 |
|
| 43 | sACN.on('error', (err) => {
|
| 44 | // trigged if there is an internal error (e.g. the supplied `iface` does not exist)
|
| 45 | });
|
| 46 |
|
| 47 | // start listening to a new universe (universe 3 in this example)
|
| 48 | sACN.addUniverse(3);
|
| 49 |
|
| 50 | // stop listening to a universe 1
|
| 51 | sACN.removeUniverse(1);
|
| 52 |
|
| 53 | // close all connections; terminate the server
|
| 54 | sACN.close();
|
| 55 |
|
| 56 | sACN.universes; // is a list of the universes being listened to
|
| 57 | ```
|
| 58 |
|
| 59 | The `objectify` function is a helper that converts the Buffer (e.g. `Buffer<ff 00 ff>`) into a human-readable object (e.g. `{ 1: 100, 2: 0, 3: 100 }`).
|
| 60 |
|
| 61 | ### Table 1 - Options
|
| 62 |
|
| 63 | | Name | Type | Purpose | Default |
|
| 64 | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
| 65 | | `universes` | `number[]` | Required. List of universes to listen to. Must be within 1-63999 | `[]` |
|
| 66 | | `port` | `number` | Optional. The multicast port to use. All professional consoles broadcast to the default port. | `5568` |
|
| 67 | | `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` |
|
| 68 | | `reuseAddr` | `boolean` | Optional. Allow multiple programs on your computer to listen to the same sACN universe. | `false` |
|
| 69 |
|
| 70 | ### Table 2 - Packet properties
|
| 71 |
|
| 72 | ```js
|
| 73 | {
|
| 74 | "sourceName": "Onyx", // controller that sent the packet
|
| 75 | "sourceAddress": "192.168.1.69", // ip address of the controller
|
| 76 | "universe": 1, // DMX universe
|
| 77 | "sequence": 172, // packets are numbered 0-255 to keep them in order
|
| 78 | "priority": 100, // 0-200. used if multiple controllers send to the same universe
|
| 79 | "slotsData": Buffer, // a buffer with length 512 containing the values of DMX channels 1-512
|
| 80 |
|
| 81 | /* there are more low-level properties which most
|
| 82 | users won't need, see the ./src/packet.ts file */
|
| 83 | }
|
| 84 | ```
|
| 85 |
|
| 86 | # Contribute
|
| 87 |
|
| 88 | ```bash
|
| 89 | npm run build # compile typescript
|
| 90 | npm test # run tests
|
| 91 | ```
|
| 92 |
|
| 93 | # Network Requirements
|
| 94 |
|
| 95 | - [x] Multicast must be enabled. sACN uses port `5568` on `239.255.x.x`
|
| 96 | - [x] Network infrastructure that supports at least 100Mbps (100BaseT)
|
| 97 |
|
| 98 | # Protocol Docs
|
| 99 |
|
| 100 | The Architecture for Control Networks (ACN) and derived protocols are created by the Entertainment Services and Technology Association.
|
| 101 |
|
| 102 | - sACN is defined in [ANSI E1.31](./docs/E1.31-2018.pdf)
|
| 103 | - RDMNet is defined in [ANSI E1.33](./docs/E1.33-2019.pdf)
|