Networking

The Node adapter sends and receives sACN/E1.31 over IPv4 UDP on port 5568 by default. Browser and edge runtimes cannot use the UDP adapter. Node.js 22+ is the supported production network runtime.

Pick the interface

On hosts with Wi-Fi, Ethernet, VPNs, containers, or multiple VLANs, set iface to the local IPv4 address of the lighting NIC:

import { createSacnSource } from "@helioslx/core/node";

const source = createSacnSource({
  name: "Show control",
  transportOptions: { iface: "192.168.10.20" },
});

Use the interface address — not a universe multicast group, and not the console's address. Set the same option on NodeSacnReceiver when receiving.

Multicast

sACN usually uses one multicast group per universe. Switches should support IGMP snooping and have an IGMP querier where required. Without a querier, memberships can expire or multicast can flood every port.

Keep lighting multicast on a controlled VLAN. Routers do not forward multicast between subnets without multicast routing. VPNs, virtual interfaces, and container bridges often change which path packets take.

The adapter creates one sender per universe/priority pair and reuses it. Source names are converted to printable ASCII and truncated to the protocol's 64-byte field.

Firewalls

Allow the process to send UDP destination port 5568 on the lighting interface. Receivers also need inbound UDP 5568 and permission to join the relevant multicast groups. Prefer narrow rules (app, interface, subnet) over disabling the host firewall.

If packets appear locally but not at a fixture or node, check VLAN, IGMP, ACL, and multicast routing before raising output rates.

Ports and conflicts

Standards-based sACN uses port 5568. The port option exists for tests and unusual deployments. Multiple receivers on one host may need address reuse; platform behavior differs — test before running duplicate production listeners.

Unicast is a transport-level option (unicastDestination), not a per-universe setting. Multicast destination is derived from the universe number.

Pre-show checklist

1. Inhibit or disconnect fixtures that can move, strobe, fire, or black out.
2. Confirm local interface address and subnet.
3. Confirm universe, priority, CID, and source name.
4. Capture on the lighting interface: destination groups, port, sequence, levels.
5. Test one universe at low-risk values.
6. Confirm receiver behavior on source loss.
7. Add universes gradually while watching switch and process telemetry.

Common symptoms

HTTP binding

The HTTP adapter is unbound. Prefer loopback unless you have auth and a trusted network:

app.listen({ hostname: "127.0.0.1", port: 3000 });

External control changes live output. Authenticate, authorize, rate-limit, and terminate TLS (or put a reverse proxy in front). Do not use wildcard CORS on a live control endpoint. See HTTP.