For an introduction to ArtPoll and ArtPollReply, please refer to Discovery Packets.
ArtPollReply
The ArtPollReply packet contains the headline status and configuration information of all Art-Net devices. ArtPollReply is always unicast and is sent in the following circumstances:
- Upon receipt of ArtPoll packet
- Upon receipt of ArtAddress packet
- Upon receipt of ArtInput packet
- Whenever device status changes if this functionality is enabled by ArtPoll->Flags->1
The ArtPollReply must be sent in response to an ArtPoll within 3s using a random delay of up to 1s in order to avoid packet bunching. This is used as the timeout mechanism for a controller to detect nodes which are on or offline.
Upon receipt of an ArtPoll, all Art-Net devices unicast an ArtPollReply. Any device that does not respond with an ArtPollReply within 3s of the ArtPoll is considered to have disconnected.
Art-Net devices can send multiple ArtPollReply in order to publish a number of ports greater than 4. The sequence of ArtPollReply is differentiated by the BindIndex. ArtPollReply can encode the information for 4 input ports and 4 output ports; however they must all share the most significant 11-bits of the Port-Address. For this reason, the preferred implementation in Art-Net 4 is to encode only one port per ArtPollReply. If a product has 16 output ports, it will send 16 ArtPollReply using binding.
ArtPollReply – Packet Definition
Minimum Packet Length
The size of ArtPollReply has increased since the original release. For this reason consumers of ArtPollReply must accept a packet of length 207 bytes or larger .
ID
The ID field is 8 bytes in length and contains the null terminated string of ASCII characters:
A r t – N e t
The purpose of the field is to identify the packet as an Art-Net protocol packet. All Art-Net packets start with this field. Receivers must check this field is correct and discard the packet if it is not.
OpCode
The OpCode field is a 16-bit word transmitted low byte first. The OpCode identifies the packet type. In the ArtPollReply packet this field is set to ‘OpPollReply’.
IpAddress
The IpAddress field is an array of 4 bytes containing the IPv4 address of the device which transmitted this packet. This information is a duplicate of the Source Address field in the encapsulating UDP packet. The most significant byte is transmitted first.
PortNumber
The PortNumber field is a 16-bit field containing the ethernet port-number of the originator of the packet. This information is a duplicate of the Source Port-Number field in the encapsulating UDP packet. Art-Net packets always use the port-number 193616.
Receivers should always test that this value is correct and discard the packet if it is not. This is because some manufacturers have implemented manufacturer specific ‘extensions’ to Art-Net by using a different number in the field.
VersInfo
The VersInfo field is a 16-bit word transmitted high byte first. The field is used for display purposes and also allows the controller to automatically identify Art-Net devices which can be firmware upgraded. By convention, a higher number equates to a more recent version.
NetSwitch & SubSwitch
NetSwitch defines bits 14-8 of the 15-bit Port-Address of all the inputs and outputs supported by this node. The most significant bit of NetSwitch is always zero.
SubSwitch defines bits 7-4 of the 15-bit Port-Address of all the inputs and outputs supported by this node. The most significant 4 bits of SubSwitch are always zero.
The following fields are combined to form the full 15-bit Port-Address of each input or output port:
- ArtPollReply->NetSwitch
- ArtPollReply->SubSwitch
- ArtPollReply->SwIn[p]
- ArtPollReply->SwOut[p]
The bit organisation of the Port-Address is shown in the diagram below. The array variable ‘p’ defines each of the four physical Input-Ports or Output-Ports of the Node.
Oem
The OEM Code is a 16-bit number which uniquely defines an Art-Net product and its manufacturer.
UbeaVersion
The UBEA is the User Bios Extension Area. It can be considered as a product specific configuration file or plug-in.
The Art-Net protocol includes functionality for uploading both product firmware and UBEA. This field contains the version or revision number of the currently installed UBEA. If there is no UBEA this field is zero. By convention, a higher number equates to a more recent version.
The existence or otherwise of the UBEA is defined in the following field:
ArtPollReply->Status1->0
Status1
Status1 is an 8-bit field containing numerous configuration and status bits.
EstaMan
The ESTA Manufacturer code is a 16-bit number which uniquely defines a given equipment manufacturer. It is transmitted least significant byte first.
ESTA codes are defined in sections E4 and D4.12 of the DMX512-A (ANSI E1.11-2004) standard.
The following URL lists all registered codes:
www.tsp.plasa.org/tsp/working_groups/CP/mfctrIDs.php
Some codes are actually two ASCII characters representing the initials of the manufacturer. This can be particularly useful when decoding data captures from software such as Wireshark.
ShortName
The ShortName field is an array of 18 ASCII characters that form a human readable name for the Art-Net device.
The field is null terminated meaning that the very last entry must be zero; so a total of 17 useable characters exists. The field is fixed length although the string it contains can be shortened by right padding with zeroes.
The packet ArtAddress is used to programme this parameter.
Numerous manufacturers factory default ShortName to contain the IP Address.
LongName
The LongName field is an array of 64 ASCII characters that form a human readable name for the Art-Net device.
The field is null terminated meaning that the very last entry must be zero; so a total of 63 useable characters exists. The field is fixed length although the string it contains can be shortened by right padding with zeroes.
The packet ArtAddress is used to programme this parameter.
The LongName and ShortName parameters can contain any human readable data the user so chooses. The difference between them is purely length.
Numerous manufacturers factory default the LongName to:
Manufacture + Product Name + IP Address
NodeReport
The NodeReport field is an array of 64 ASCII characters that form a human readable report on the devices status. The field has specific formatting which is intended to make it simply to parse in software.
The field is null terminated meaning that the last character must be zero. Report strings shorter than the maximum should be right padded with zeroes.
The string format is defined below:
#xxxx [yyyy] zzzzz
The first character is a hash symbol (2316).
The field xxxx is a four character hexadecimal status code as defined in the Node Report Code. This field gives an overview of the node status and is exceedingly useful for developers.
Then follows a space character (2016) followed by an opening square bracket (5b16).
The field yyyy is a four character decimal counter which is initialised to zero and increments prior to and every time the device sends an ArtPollReply. Once this count reaches 9999 it rolls over to 0000.
Then follows a closing square bracket (5d16) followed by a space character (2016).
The field zzzz is free form ASCII text describing the current device status.
The following example is from a product that has just booted without error:
#0001 [0000] ACME Art-Net Product. Good Boot.
While this example represents a product which has booted and detected a hardware fault:
#0002 [0000] ACME Art-Net Product. Power On Test FAIL.
NumPorts
NumPorts is a 16-bit number which uniquely defines the maximum number of Input-Ports or Output-Ports implemented by the device. This number can only take values in the range 0 – 4.
If the number of Input-Ports and Output-Ports is different, then the higher number is used.
For example, a device which has 2 Input-Ports and 3 Output-Ports will set NumPorts = 3.
It is legal for a device to report NumPorts = 0 if it has no Input-Ports or Output-Ports.
Nodes can ignore this field as the information is implicit in PortTypes[].
PortTypes [4]
PortTypes is an array of four 8-bit fields that define the Input-Ports and Output-Ports.
Example 1:
A product supporting 4 DMX outputs (Output-Ports) and 2 DMX inputs (Input-Ports) will report a PortTypes array of: c016, c016, 8016, 8016.
Example 2:
A product supporting 2 Art-Net outputs (Output-Ports) and 2 Art-Net Inputs will report a PortTypes array of: c516, c516, 0016, 0016.
A common error is to assume that NumPorts defines the number of array entries. That is incorrect; PortTypes is a fixed array with 4 entries.
GoodInput [4]
GoodInput is an array of four 8-bit fields that show the receive status of the 4 Input-Ports.
GoodOutput [4]
GoodOutput is an array of four 8-bit fields that show the configuration and status of the Output-Ports.
SwIn[4] & SwOut[4]
SwIn and SwOut are both arrays of 4-bytes of which only the low 4-bits are used. They represent 3-0 of the 15-bit Port-Address of each Input-Port and Output-Port respectively.
The following fields are combined to form the full 15-bit Port-Address of each input or output port:
- ArtPollReply->NetSwitch
- ArtPollReply->SubSwitch
- ArtPollReply->SwIn[p]
- ArtPollReply->SwOut[p]
The bit organisation of the Port-Address is shown in the diagram below. The array variable ‘p’ defines each of the four physical Input-Ports or Output-Ports of the Node.
SwVideo
SwVideo is an 8-bit field used to select the channel of ArtVideoData output by a Node. The field is now deprecated and was only ever used on the ADB Netgate XT.
SwMacro & SwRemote
SwMacro and SwRemote are 8-bit fields used for simple triggering. The fields are now deprecated; their functionality having been replaced by ArtTrigger. These fields were only ever implemented by the ADB Netgate XT.
Spare & Filler
A number of spare and filler fields exist in the packet for future expansion. These should be set to zero for transmission and ignored by receivers.
Style
Style is an 8-bit field that defines the category of equipment to which the device belongs. The Style setting is intended to provide general information about a device.
Mac
The Mac field is an array of 6 bytes containing the MAC (Media Access Control) address of the device which transmitted this packet.
The most significant byte is transmitted first.
BindIp
The BindIp field is an array of 4 bytes containing the IPv4 address to which this device is bound. The most significant byte is transmitted first.
The BindIp represents the IP address of the Root device in an Art-Net product that has multiple IP addresses. In Art-Net 4, the BindIp is always identical to the IP of the root device.
BindIndex
The BindIndex is an 8-bit field that represents the order of bound devices. One is used to represent the Root device. A number greater than one indicates a bound device. Note that a value of zero was used to represent the Root device prior to Art-Net 4. As such, a receiver should treat the values of both 0 and 1 as identical, both indicate the Root Device.
Status2
Status2 is an 8-bit field containing numerous status and configuration flags.
