sacn.md

The sacn backend

The sACN backend provides read-write access to the Multicast-UDP based streaming ACN protocol (ANSI E1.31-2016), used for lighting fixture control. The backend sends universe discovery frames approximately every 10 seconds, containing all write-enabled universes.

Global configuration

Option	Example value	Default value	Description
name	sACN source	MIDIMonster	sACN source name
cid	0xAA 0xBB 0xCC ...	MIDIMonster	Source CID (16 bytes)
bind	0.0.0.0 5568	none	Binds a network address to listen for data. This option may be set multiple times, with each descriptor being assigned an index starting from 0 to be used with the interface instance configuration option. At least one descriptor is required for operation.
detect	on, verbose	off	Output additional information on received data packets to help with configuring complex scenarios

The bind configuration value can be extended by the keyword local to allow software on the local host to process the sACN output frames from the MIDIMonster (e.g. bind = 0.0.0.0 5568 local). This has the side effect of mirroring the output of instances on those descriptors to their input.

Instance configuration

Option	Example value	Default value	Description
universe	1	none	Universe identifier between 1 and 63999
interface	1	0	The bound address to use for data input/output
priority	100	none	The data priority to transmit for this instance. Setting this option enables the instance for output and includes it in the universe discovery report.
destination	10.2.2.2	Universe multicast	Destination address for unicast output. If unset, the multicast destination for the specified universe is used.
from	0xAA 0xBB ...	none	16-byte input source CID filter. Setting this option filters the input stream for this universe.
unicast	1	0	Prevent this instance from joining its universe multicast group
realtime	1	0	Disable the recommended rate-limiting (approx. 44 packets per second) for this instance

Note that instances accepting multicast input also process unicast frames directed at them, while instances in unicast mode will not receive multicast frames.

Channel specification

A channel is specified by it's universe index. Channel indices start at 1 and end at 512.

Example mapping:

sacn1.231 < sacn2.123

A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax

sacn.1+2 > sacn2.5+123

A normal channel that is part of a wide channel can not be mapped individually.

Known bugs / problems

The DMX start code of transmitted and received universes is fixed as 0.

Universe synchronization is currently not supported, though this feature may be implemented in the future.

To use multicast input, all networking hardware in the path must support the IGMPv2 protocol.

The Linux kernel limits the number of multicast groups an interface may join to 20. An instance configured for input automatically joins the multicast group for its universe, unless configured in unicast mode. This limit can be raised by changing the kernel option in /proc/sys/net/ipv4/igmp_max_memberships.

When using this backend for output with a fast event source, some events may appear to be lost due to the packet output rate limiting mandated by the E1.31 specification (Section 6.6.1 Transmission rate). The rate limiter can be disabled on a per-instance basis using the realtime option.