Allow sending data to a specific IP address instead of the whole LAN

.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [10.x, 12.x, 14.x, 16.x, 18.x]
+        node-version: [10.x, 12.x, 14.x, 16.x, 18.x, 20.x]
 
     steps:
       - name: ⏬ Checkout code

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.4.0] - 2023-07-22
+
+### Added
+
+- [#52]: Allow sending data to a specific IP address instead of the whole LAN
+
 ## [4.3.0] - 2023-02-10
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sacn",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "💡 🎭 Send and Receive sACN data (DMX over IP)",
   "author": "Kyle Hensel",
   "license": "Apache-2.0",

readme.md

@@ -125,6 +125,7 @@ main(); // wrapped in a main() function so that we can `await` the promise
 | `reuseAddr`            | `boolean` | Optional. Allow multiple programs on your computer to send to the same sACN universe.                      |
 | `defaultPacketOptions` | `object`  | Optional. You can specify options like `sourceName`, `cid`, and `priority` here instead of on every packet |
 | `iface`                | `string`  | Optional. Specifies the IPv4 address of the network interface/card to use.                                 | OS default interface (=active internet connection)
+| `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. |
 
 # Contribute
 
@@ -135,7 +136,7 @@ npm test # run tests
 
 # Network Requirements
 
-- [x] Multicast must be enabled. sACN uses port `5568` on `239.255.x.x`
+- [x] Multicast must be enabled<sup id="footnote-source1">[1](#footnote1)</sup>. sACN uses port `5568` on `239.255.x.x`
 - [x] Network infrastructure that supports at least 100Mbps (100BaseT)
 
 # Protocol Docs
@@ -144,3 +145,10 @@ The Architecture for Control Networks (ACN) and derived protocols are created by
 
 - sACN is defined in [ANSI E1.31](./docs/E1.31-2018.pdf)
 - RDMNet is defined in [ANSI E1.33](./docs/E1.33-2019.pdf)
+
+---
+<small id="footnote1">
+
+1&shy;. 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)
+
+</small>

src/sender.ts

@@ -20,6 +20,14 @@ interface Props {
 
   // IPv4 address of the network interface
   iface?: string;
+
+  /**
+   * If you set this option to an IP address, then data will be sent
+   * purely to this address, instead of the whole network.
+   *
+   * This option is not recommended and may not be supported by all devices.
+   */
+  useUnicastDestination?: string;
 }
 
 export class Sender {
@@ -29,7 +37,11 @@ export class Sender {
 
   public readonly universe: Props['universe'];
 
-  private readonly multicastDest: string;
+  /**
+   * this is normally a multicast address, but it could be
+   * a unicast address if the user configures `useUnicastDestination`
+   */
+  readonly #destinationIp: string;
 
   private readonly defaultPacketOptions: Props['defaultPacketOptions'];
 
@@ -51,10 +63,11 @@ export class Sender {
     minRefreshRate = 0,
     defaultPacketOptions,
     iface,
+    useUnicastDestination,
   }: Props) {
     this.port = port;
     this.universe = universe;
-    this.multicastDest = multicastGroup(universe);
+    this.#destinationIp = useUnicastDestination || multicastGroup(universe);
     this.defaultPacketOptions = defaultPacketOptions;
 
     this.socket = createSocket({ type: 'udp4', reuseAddr });
@@ -84,7 +97,7 @@ export class Sender {
         sequence: this.sequence,
       });
       this.sequence = (this.sequence + 1) % 256;
-      this.socket.send(buffer, this.port, this.multicastDest, (err) =>
+      this.socket.send(buffer, this.port, this.#destinationIp, (err) =>
         err ? reject(err) : resolve(),
       );
     });

test/integration.test.ts

@@ -286,8 +286,6 @@ describe('Sending to a specific interface', () => {
       await Tx2.send({ payload: { 22: 0xff } });
       await sleep(3500);
 
-      console.error(errors, received1.length, received2.length);
-
       assert.strictEqual(errors.length, 0);
       assert.strictEqual(received1.length, 1);
       assert.strictEqual(received2.length, 1);
@@ -301,3 +299,58 @@ describe('Sending to a specific interface', () => {
     }
   });
 });
+
+describe('Sending to a unicast address', () => {
+  it('can send data to a specific unicast address', async () => {
+    const Tx = new Sender({
+      universe: 51,
+      useUnicastDestination: '127.0.0.1',
+    });
+    const Rx = new Receiver({ universes: [51] });
+    try {
+      const received: Packet[] = [];
+      const errors: Error[] = [];
+      Rx.on('packet', (packet) => received.push(packet));
+
+      collectErrors(Rx, errors);
+
+      // stuff takes time
+      await sleep(3500);
+      await Tx.send({ payload: { 22: 0xff } });
+      await sleep(3500);
+
+      assert.strictEqual(errors.length, 0);
+      assert.strictEqual(received.length, 1);
+      assert.deepStrictEqual(received[0]!.payload, { 22: 100 });
+    } finally {
+      Tx.close();
+      Rx.close();
+    }
+  });
+
+  it('receives nothing when sending data to an invalid unicast address', async () => {
+    const Tx = new Sender({
+      universe: 51,
+      useUnicastDestination: '192.0.2.0', // https://en.wikipedia.org/wiki/Reserved_IP_addresses
+    });
+    const Rx = new Receiver({ universes: [51] });
+    try {
+      const received: Packet[] = [];
+      const errors: Error[] = [];
+      Rx.on('packet', (packet) => received.push(packet));
+
+      collectErrors(Rx, errors);
+
+      // stuff takes time
+      await sleep(3500);
+      await Tx.send({ payload: { 22: 0xff } });
+      await sleep(3500);
+
+      assert.strictEqual(errors.length, 0);
+      assert.strictEqual(received.length, 0); // nothing was recevied
+    } finally {
+      Tx.close();
+      Rx.close();
+    }
+  });
+});