This library creates an array for sending DMX-512 messages using streaming ACN (sACN). This affords control of many modern stage lighting fixtures over UDP. The library wraps a UDP transport object in the constructor so it can send UDP packets.
The Library uses the Arduino WiFiUDP library. It can work with any boards using a variant of the Arduino WiFi library, including the MKR1000 (WiFi101), Nano 33 IoT and Nano RP2040 Connect (WiFiNINA) or Uno R4 WiFI (WiFiS3), or ESP8266 boards using the ESP8266WiFi library.
For more detail on the sACN protocol, see the ESTA E.131 protocol document
WiFiUDP Udp; // instance of UDP library
sACNSource myController(Udp); // Your Ethernet-to-DMX device
takes a UDP object for transport
void
Initializes the sACN packet.
myController.begin(myDevice, myUuid, myUniverse);
myController.begin(myDevice, myUuid, myUniverse, thisPort);
myDevice - a character string containing the name of the source device
myUuid - a character string containing the UUID of the source device. This must be in ASCII-encoded hexadecimal, but can include dashes as delimiters. See UUID Generator for examples.
myUniverse - an integer containing the DMX universe you want to control.
thisPort - if you want to use a port other than the sACN standard (5568), you can pass in an int with your port number
Note: You can change the universe, UUID, and device name after initialization using the appropriate commands for setting them.
void
Sets the initial parameters for the sACN packet.
myController.setUuid(myUuid);
myUuid - a character string containing the UUID of the source device.
void
This must be in ASCII-encoded hexadecimal, but can include dashes as delimiters. See UUID Generator for examples.
myController.setSourceName(myDevice);
myDevice - a character array containing the device name of your source. Max. 64 characters.
void
myController.setUniverse(dmxUniverse);
dmxUniverse - an integer containing the DMX universe that you wish to control.
void
The sACN formula for setting the IP address based on the universe number is: 239.255.universeHigh.universeLow. For example, a unverse number anywhere from 0-255 would be 239.255.0.universeNumber. For a universe number 256, it would be 239.255.1.0. For universe 1023 it would be 239.255.3.255. This comes from ETC's multicast calculator.
NOTE: the library currently does not recalculate the multicast IP based on the universe number.
myController.setChannel(dmxChannel, level);
dmxChannel - an integer containing the DMX channel you want to set (1-512)
level - a byte containing the level to which you want to set the channel ( 0 - 255)
void
Note that DMX channels are usually 1-indexed, rather than 0-indexed. So the first channel is channel 1.
myController.sendPacket(receiverAddress);
myController.sendPacket(receiverAddress, thisPort);
receiverAddress - a character array containing the numeric IP address of the receiver
thisPort - if you want to use a port other than the sACN standard (5568), you can pass in an int with your port number
void
This function auto-increments the sequence number for packets, so you don't have to.
myController.setSequenceNumber(seqNumber);
seqNumber - a byte containing the packet sequence number.
void
sACN packets are given a packet sequence number so that the receiver can keep the sequence of packets from a given sender. The sendPacket function automatically increments the sequence number, so there's no real need to set this unless you want to set a specific number.
byte num = myController.getSequenceNumber();
none
a byte containing the latest packet sequence number.
myController.setSyncAddress(syncAddress);
syncAddress - an int containing the sync universe address. Default is 0.
void
myController.setOptions(options);
a byte containing the options flags for preview data, stream termination, and forced synchronization.
void
Not implemented in version 0.0.2
myController.readData(byteNumber);
byteNumber - a byte containing the number of the byte in the packet that you want to read.
a byte variable containing the value of the byte you requested
myController.packetSize();
none
an int variable containing the size of the packet.
Unless modified, this will always be 638.