ArtNet
Home


Foreword

Foreword
Foreword
Additional information
•
Notes on the documentation
•
Safety instructions


Notes on the documentation

Foreword [image] Notes on the documentation
Notes on the documentation
This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.
The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.
Disclaimer
The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.
Trademarks
Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE®, XFC®and XTS® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.
Patent Pending
The EtherCAT Technology is covered, including but not limited to the following patent applications and patents:
EP1590927, EP1789857, DE102004044764, DE102007017835
with corresponding applications or registrations in various other countries.
The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.
EtherCAT® is registered trademark and patented technology, licensed by Beckhoff Automation GmbH, Germany
Copyright
© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Safety instructions

Foreword [image] Safety instructions
Safety instructions
Safety regulations
Please note the following safety instructions and explanations!
Product-specific safety instructions can be found on following pages or in the areas mounting, wiring, commissioning etc.
Exclusion of liability
All the components are supplied in particular hardware and software configurations appropriate for the application. Modifications to hardware or software configurations other than those described in the documentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.
Personnel qualification
This description is only intended for trained specialists in control, automation and drive engineering who are familiar with the applicable national standards.
Description of symbols
In this documentation the following symbols are used with an accompanying safety instruction or note. The safety instructions must be read carefully and followed without fail!
DANGER
Serious risk of injury!
Failure to follow the safety instructions associated with this symbol directly endangers the life and health of persons.
WARNING
Risk of injury!
Failure to follow the safety instructions associated with this symbol endangers the life and health of persons.
CAUTION
Personal injuries!
Failure to follow the safety instructions associated with this symbol can lead to injuries to persons.
Attention
Damage to the environment or devices
Failure to follow the instructions associated with this symbol can lead to damage to the environment or equipment.
Note
Tip or pointer
This symbol indicates information that contributes to better understanding.


Overview

Overview
Overview
Art-Net™ is a protocol specification, developed by Artistic Licence Holdings Ltd, to utilize the benefits of Ethernet for transferring DMX universes.
DMX is a standard that is widely used for controlling lighting elements in stage equipment and building services applications.
The corresponding Beckhoff range includes the EL6851 DMX master terminal and the EL6851-0010 DMX slave terminal.
Art-Net™ transfers DMX universes via UDP/IP, whereby DMX data are embedded in an Art-Net™ frame as a complete universe and thus tunneled through UDP/IP using another layer.
From Art-Net™ II, telegrams can also be sent in 'unicast' mode, as well as 'directed broadcast'.
Further information can be found on our website at: PC-based control for stage and show equipment
The Art-Net™ specification can be found at: www.Art-Net.org.uk
Art-Net™ is a trade mark of Artistic Licence Holdings Ltd. The Art-Net protocol and associated documentation is copyright Artistic Licence Holdings Ltd.


Programming

Programming
Programming
Additional information
•
Blocks
•
Error Codes
•
Structures, enumerations


Blocks

Programming [image] Blocks
Blocks
Additional information
•
FB_ArtNetSend
•
FB_ArtNetReceive


FB_ArtNetSend

Programming [image] Blocks [image] FB_ArtNetSend
FB_ArtNetSend
This function block sends Art-Net telegrams via UDP.
VAR_INPUT
bExecute : BOOL;
bArtPoll : BOOL;
bArtPollReply : BOOL;
stPollReplyParameter : ST_PollReplyParameter;
sSrvNetId : T_AmsNetId,
sLocalHost : T_IPv4Addr;
nLocalPort : UDINT;
sRemoteHost : T_IPv4Addr;
sDirectedBroadcastAddress : T_IPv4Addr;
nRemotePort : UDINT;
tCycleTimeTransmit : TIME;
tTimeout : TIME;
stDmxData : ST_DmxArtNetData;
bExecute: The block starts processing if a positive edge is encountered at this input. A negative edge terminates processing.
bArtPoll: A one-off 'ArtPoll' telegram is sent via a positive edge at this input.
All Art-Net™ devices (including the sender) then respond with an 'ArtPollReply' telegram.
bArtPollReply: A one-off 'ArtPollReply' telegram is sent via a positive edge at this input.
stPollReplyParameter: This structure provides information for other Art-Net™ devices.
sSrvNetId: String containing the network address of the TwinCAT TCP/IP Connection Server. For the local computer (default) an empty string may be specified.
sLocalHost: The local IP address (IPv4) of the UDP client/server socket as a string (e.g. '2.168.0.5'). An empty string may be specified for the default network adapter.
nLocalPort: The local IP port number of the UDP client/server socket (e.g. 6454).
sRemoteHost: The remote IP address (IPv4) of the UDP client/server socket as a string (e.g. '2.17.54.239').
sDirectedBroadcastAddress: The IP address (IPv4) for 'directed broadcasts' as a string (e.g. '2.255.255.255').
This address is used in 'broadcast' mode, and also for sending 'ArtPoll' and 'ArtPollReply' telegrams.
nRemotePort: The remote IP port number of the UDP client/server socket (e.g. 6454).
tCycleTimeTransmit: Determines the cycle in which the telegrams are sent (e.g. t#20ms).
tTimeout: States the length of the timeout that may not be exceeded during execution of the command.
stDmxData: This structure contains the data to be sent.
VAR_OUTPUT
bBusy : BOOL;
bError : BOOL;
nErrorID : UDINT;
stFrameCounterErrorID : ST_FrameCounter;
bBusy: When the function block is activated this output is set. It remains set until a feedback is received.
bError: In the event of an error during the command transfer, this output is set once the bBusy output has been reset.
nErrorID: Returns the error code of the last executed step, if the bError output is set.
See Error codes.
stFrameCounter: Structure with information about the number of sent 'ArtPoll', 'ArtPollReply' and 'ArtDmx' telegrams.
VAR_IN_OUT
hSocket : T_HSOCKET;
hSocket: Input/output variable with the handle of an opened UDP socket. If the transfer takes place at input 0, the system tries to create a new socket.
If successful, a new socket is opened, and hSocket provides the associated socket handle.


FB_ArtNetReceive

Programming [image] Blocks [image] FB_ArtNetReceive
FB_ArtNetReceive
This function block receives Art-Net telegrams via UDP.
VAR_INPUT
bExecute : BOOL;
sSrvNetId : T_AmsNetId,
sLocalHost : T_IPv4Addr;
nLocalPort : UDINT;
tTimeout : TIME;
bExecute: The block starts processing if a positive edge is encountered at this input. A negative edge terminates processing.
sSrvNetId: String containing the network address of the TwinCAT TCP/IP Connection Server. For the local computer (default) an empty string may be specified.
sLocalHost: The local IP address (IPv4) of the UDP client/server socket as a string (e.g. '2.168.0.5'). An empty string may be specified for the default network adapter.
nLocalPort: The local IP port number of the UDP client/server socket (e.g. 6454).
tTimeout: States the length of the timeout that may not be exceeded during execution of the command.
VAR_OUTPUT
bBusy : BOOL;
bError : BOOL;
nErrorID : UDINT;
bArtPollReceived : BOOL;
stDmxData : ST_DmxArtNetData;
stFrameCounter : ST_FrameCounter;
aAvailableNodes : ARRAY[0..31] OF ST_PollReplyParameter;
bBusy: When the function block is activated this output is set. It remains set until a feedback is received.
bError: If an error should occur during the transfer of the command, then this output is set once the bBusy output was reset.
nErrorID: Returns the error code of the last executed step, if the bError output is set.
See Error codes.
stDmxData: This structure contains the most recently received data.
stFrameCounter: Structure with information about the number of received 'ArtPoll', 'ArtPollReply' and 'ArtDmx' telegrams.
aAvailableNodes: Provides an array of a structure with information on further Art-Net™ devices, from which an 'ArtPollReply' telegram was sent.
VAR_IN_OUT
hSocket : T_HSOCKET;
hSocket: Input/output variable with the handle of an opened UDP socket. If the transfer takes place at input 0, the system tries to create a new socket.
If successful, a new socket is opened, and hSocket provides the associated socket handle.


Error Codes

Programming [image] Error Codes
Error Codes
Error Codes
Value (hex) | Value (dec) | Description
0x0000 | 0 | No error.
0x8001 | 32769 | The specified UDP port could not be opened.
0x8002 | 32770 | Ports opened by the TwinCAT PLC runtime system could not be closed.
0x8003 | 32771 | Invalid socket for receiving UDP telegrams.
0x8004 | 32772 | Invalid socket for sending UDP telegrams.


Structures, enumerations

Programming [image] Structures, enumerations
Structures, enumerations
Additional information
•
E_ArtNet_ErrorCodes
•
E_ArtNet_OpCodes
•
ST_ArtNetDmxData
•
ST_ArtNetFrameCounter
•
ST_ArtDMX_Frame
•
ST_ArtPOLL_Frame
•
ST_ArtPOLLREPLY_Frame


E_ArtNet_ErrorCodes

Programming [image] Structures, enumerations [image] E_ArtNet_ErrorCodes
E_ArtNet_ErrorCodes
TYPE E_ArtNet_ErrorCodes
(
eArtNetError_NoError := 0,
eArtNetError_UDPOpeningPort := 32769,
eArtNetError_UDPClosePorts := 32770,
eArtNetError_UDPReceive := 32771,
eArtNetError_UDPSend := 32772
);
END_TYPE


E_ArtNet_OpCodes

Programming [image] Structures, enumerations [image] E_ArtNet_OpCodes
E_ArtNet_OpCodes
TYPE E_ArtNet_OpCodes
(
E_OpPoll :=16#2000, (*This is an ArtPoll packet, no other data is contained in this UDP packet.*)
E_OpPollReply :=16#2100, (*This is an ArtPollReply Packet. It contains device status information.*)
E_OpDiagData :=16#2300, (*Diagnostics and data logging packet.*)
E_OpCommand :=16#2400, (*Used to send text based parameter commands.*)
E_OpDmx :=16#5000, (*This is an ArtDmx data packet. It contains zero start code DMX512 information for a single Universe.*)
E_OpNzs :=16#5100, (*This is an ArtNzs data packet. It contains non-zero start code (except RDM) DMX512 information for a single Universe.*)
E_OpAddress :=16#6000, (*This is an ArtAddress packet. It contains remote programming information for a Node.*)
E_OpInput :=16#7000, (*This is an ArtInput packet. It contains enable – disable data for DMX inputs.*)
E_OpTodRequest :=16#8000, (*This is an ArtTodRequest packet. It is used to request a Table of Devices (ToD) for RDM discovery.*)
E_OpTodData :=16#8100, (*This is an ArtTodData packet. It is used to send a Table of Devices (ToD) for RDM discovery.*)
E_OpTodControl :=16#8200, (*This is an ArtTodControl packet. It is used to send RDM discovery control messages.*)
E_OpRdm :=16#8300, (*This is an ArtRdm packet. It is used to send all non discovery RDM messages.*)
E_OpRdmSub :=16#8400, (*This is an ArtRdmSub packet. It is used to send compressed, RDM Sub-Device data.*)
E_OpVideoSetup :=16#A010, (*This is an ArtVideoSetup packet. It contains video screen setup information for nodes that implement the extended video features.*)
E_OpVideoPalette :=16#A020, (* This is an ArtVideoPalette packet. It contains colour palette setup information FOR nodes that implement the extended video features.*)
E_OpVideoData :=16#A040, (*This is an ArtVideoData packet. It contains display data for nodes that implement the extended video features.*)
E_OpMacMaster :=16#F000, (*This is an ArtMacMaster packet. It is used to program the Node’s MAC address, Oem device type and ESTA manufacturer code. This is for factory initialisation of a Node. It is not to be used by applications.*)
E_OpMacSlave :=16#F100, (*This is an ArtMacSlave packet. It is returned by the node to acknowledge receipt of an ArtMacMaster packet.*)
E_OpFirmwareMaster :=16#F200, (*This is an ArtFirmwareMaster packet. It is used to upload new firmware or firmware extensions to the Node.*)
E_OpFirmwareReply :=16#F300, (*This is an ArtFirmwareReply packet. It is returned BY the node TO acknowledge receipt OF an ArtFirmwareMaster packet OR ArtFileTnMaster packet.*)
E_OpFileTnMaster :=16#F400, (*Uploads user file to node. *)
E_OpFileFnMaster :=16#F500, (*Downloads user file from node.*)
E_OpFileFnReply :=16#F600, (*Node acknowledge for downloads.*)
E_OpIpProg :=16#F800, (*This is an ArtIpProg packet. It is used to reprogramme the IP, Mask and Port address of the Node. *)
E_OpIpProgReply :=16#F900, (*This is an ArtIpProgReply packet. It is returned by the node to acknowledge receipt of an ArtIpProg packet.*)
E_OpMedia :=16#9000, (*This is an ArtMedia packet. It is Unicast by a Media Server and acted upon by a Controller.*)
E_OpMediaPatch :=16#9100, (*This is an ArtMediaPatch packet. It is Unicast by a Controller and acted upon by a Media Server. *)
E_OpMediaControl :=16#9200, (*This is an ArtMediaControl packet. It is Unicast by a Controller and acted upon by a Media Server. *)
E_OpMediaContrlReply :=16#9300, (*This is an ArtMediaControlReply packet. It is Unicast by a Media Server and acted upon by a Controller.*)
E_OpTimeCode :=16#9700, (*This is an ArtTimeCode packet. It is used to transport time code over the network.*)
E_OpTimeSync :=16#9800, (*Used to synchronise real time date and clock*)
E_OpTrigger :=16#9900, (*Used to send trigger macros*)
E_OpDirectory :=16#9A00, (*Requests a node's file list*)
E_OpDirectoryReply :=16#9B00 (*Replies to OpDirectory with file list*)
);
END_TYPE


ST_ArtNetDmxData

Programming [image] Structures, enumerations [image] ST_ArtNetDmxData
ST_ArtNetDmxData
TYPE ST_ArtNetDmxData:
STRUCT
nNet : BYTE; (*The top 7 bits of the 15 bit Port-Address to which this packet is destined*)
nSubUni : BYTE; (*The low byte of the 15 bit Port-Address to which this packet is destined*)
aDmxChannels : ARRAY[1..512] OF BYTE;
END_STRUCT
END_TYPE
nNet: contains the higher 7 bits of the 15-bit address.
nSubUni: contains the lower byte of the 15-bit address.
aDmxChannels: Array with DMX data of a universe.
Information on addressing can be found in the Art-Net™-specification under: www.Art-Net.org.uk


ST_ArtNetFrameCounter

Programming [image] Structures, enumerations [image] ST_ArtNetFrameCounter
ST_ArtNetFrameCounter
TYPE ST_ArtNetFrameCounter:
STRUCT
nDMX_Frames : UDINT;
nPOLL_Frames : UDINT;
nPOLL_REPLY_Frames : UDINT;
nUnknown_ArtNet_Frames : UDINT;
END_STRUCT
END_TYPE
This structure is used for counting different Art-Net™ telegrams.


ST_ArtDMX_Frame

Programming [image] Structures, enumerations [image] ST_ArtDMX_Frame
ST_ArtDMX_Frame
TYPE ST_ArtDMX_Frame:
STRUCT
aPreamble : ARRAY [0..7] OF BYTE; (*'Art-Net' 0x00*)
aOpCode : ARRAY [0..1] OF BYTE; (*OpDmx,transmitted low byte first – see E_ArtNet_OpCodes*)
aProtocolVersion : ARRAY [0..1] OF BYTE; (*The Art-Net protocol revision number*)
nSequence : BYTE; (*The sequence number is used to ensure that ArtDmx packets are used in the correct order.*)
nPhysical : BYTE; (*The physical input port from which DMX512 data was input.*)
nSubUni : BYTE; (*The low byte of the 15 bit Port-Address to which this packet is destined.*)
nNet : BYTE; (*The top 7 bits of the 15 bit Port-Address to which this packet is destined.*)
aLenght : ARRAY [0..1] OF BYTE; (*Length of the data array - should be an even number in the range 2–512.*)
aData : ARRAY [0..1] OF BYTE; (*array of DMX data*)
END_STRUCT
END_TYPE
This structure is used for sending and receiving DMX data. It matches the telegram described in the Art-Net™ specification (www.Art-Net.org.uk) under 'ArtDMX'.


ST_ArtPOLL_Frame

Programming [image] Structures, enumerations [image] ST_ArtPOLL_Frame
ST_ArtPOLL_Frame
TYPE ST_ArtPOLL_Frame:
STRUCT
aPreamble : ARRAY [0..7] OF BYTE; (*'Art-Net' 0x00*)
aOpCode : ARRAY [0..1] OF BYTE; (*OpDmx,transmitted low byte first – see E_ArtNet_OpCodes*)
aProtocolVersion : ARRAY [0..1] OF BYTE; (*the Art-Net protocol revision number*)
nTalkToMe : BYTE; (*Set behaviour of Node*)
nPriority : BYTE; (*Diagnostics Priority Code*)
END_STRUCT
END_TYPE
This structure is used for sending 'Poll' telegrams. It is based on the telegram described in the Art-Net™ specification (www.Art-Net.org.uk) under 'ArtPOLL'.


ST_ArtPOLLREPLY_Frame

Programming [image] Structures, enumerations [image] ST_ArtPOLLREPLY_Frame
ST_ArtPOLLREPLY_Frame
TYPE ST_ArtPOLLREPLY_Frame:
STRUCT
aPreamble : ARRAY [0..7] OF BYTE; (*'Art-Net' 0x00*)
aOpCode : ARRAY [0..1] OF BYTE; (*OpDmx,transmitted low byte first – see E_ArtNet_OpCodes*)
aIP : ARRAY [0..3] OF BYTE; (*Array containing the Node’s IP address*)
aPort : ARRAY [0..1] OF BYTE; (*The value of the used UDP Port, should always be 0x1936, transmitted low byte first.*)
aVersionInfo : ARRAY [0..1] OF BYTE; (*Node’s firmware revision number.*)
nNetSwitch : BYTE; (*Bits 14-8 of the 15 bit Port-Address are encoded into the bottom 7 bits of this field.*)
nSubSwitch : BYTE; (*Bits 7-4 of the 15 bit Port-Address are encoded into the bottom 4 bits of this field.*)
aOem : ARRAY [0..1] OF BYTE; (*The Oem describes the equipment vendor*)
nUbeaVersion : ARRAY [0..1] OF BYTE; (*This field contains the firmware version of the User Bios Extension Area (UBEA).)
nStatus1 : BYTE; (*General Status register*)
nESTA : ARRAY [0..1] OF BYTE; (*The ESTA manufacturer code*)
aShortName : ARRAY [0..17] OF BYTE; (*Node’s short name*)
aLongName : ARRAY [0..63] OF BYTE; (*Node’s long name*)
aNumPorts : ARRAY [0..1] OF BYTE; (*The low byte describing the number of input or output ports. The maximum value is 4.*)
aPortTypes : ARRAY [0..3] OF BYTE; (*This array defines the operation and protocol of each channel.*)
aGoodInput : ARRAY [0..3] OF BYTE; (*This array defines input status of the node.*)
aGoodOutput : ARRAY [0..3] OF BYTE; (*This array defines output status of the node.*)
aSwIn : ARRAY [0..3] OF BYTE; (*Bits 3-0 of the 15 bit Port-Address for each of the 4 possible input ports are encoded into the low nibble.*)
aSwOut : ARRAY [0..3] OF BYTE; (*Bits 3-0 of the 15 bit Port-Address for each of the 4 possible output ports are encoded into the low nibble.*)
nSwVideo : BYTE; (*Set to 00 when video display is showing local data. Set to 01 when video is showing ethernet data.*)
nSwMacro : BYTE; (*If the Node supports macro key inputs, this byte represents the trigger values.*)
nSwRemote : BYTE; (*If the Node supports remote trigger inputs, this byte represents the trigger values.*)
aSpare : ARRAY [0..2] OF BYTE;
nStyle : BYTE; (*The Style code defines the equipment style of the device.*)
aMAC : ARRAY [0..5] OF BYTE; (*Node’s MAC-Address*)
aBindIP : ARRAY [0..3] OF BYTE; (*If this unit is part of a larger or modular product, this is the IP of the root device.*)
nBindIndex : BYTE; (*Set to zero if no binding, otherwise this number represents the order of bound devices*)
nStatus2 : BYTE; (*Status register*)
END_STRUCT
END_TYPE
This structure is used for sending and receiving PollRepl-' telegrams. It matches the telegram described in the Art-Net™ specification (www.Art-Net.org.uk) under 'ArtPOLLREPLY'.


Examples

Examples
Examples
Additional information
•
Art-Net Send / Receive in Broadcast mode
•
Art-Net Send / Receive in Unicast mode


Art-Net Send / Receive in Broadcast mode

Examples [image] Art-Net Send / Receive in Broadcast mode
Art-Net Send / Receive in Broadcast mode
The example consists of a PLC program and a Lightjams project file.
Data are sent and received in Broadcast mode to/from a computer, on which the Lightjams project is executed.

The individual function blocks of the example are explained in the "Programming" section.
The TwinCAT supplement TwinCAT TCP/IP Server is required for the example.
Based on this example, the user data of the Art-Net™ frame can be linked with any PLC variables. Links enabled by the modular Beckhoff control system include
▪
Art-Net™ to DMX (EL6851 and EL6851-0010)
▪
Art-Net™ to dimmer (KL2761 and KL2751)
▪
Art-Net™ to DALI (KL6811)
▪
Art-Net™ to stepper or DC motor
▪
Art-Net™ to digital IOs (e.g. 24V or 230V)
▪
Art-Net™ to analog IOs (e.g. 0-10V or 4-20mA).
@Mit obigem Satz übersetzt. Bitte löschen@
Documents about this
•


Art-Net Send / Receive in Unicast mode

Examples [image] Art-Net Send / Receive in Unicast mode
Art-Net Send / Receive in Unicast mode
The example includes a PLC program and a Lightjams project file, plus a short video clip that describes the configuration.
Data are sent and received in Unicast mode to/from a computer, on which the Lightjams project is executed.
The individual function blocks of the example are explained in the "Programming" section.
The TwinCAT supplement TwinCAT TCP/IP Server is required for the example.
Based on this example, the user data of the Art-Net™ frame can be linked with any PLC variables. Links enabled by the modular Beckhoff control system include
▪
Art-Net™ to DMX (EL6851 and EL6851-0010)
▪
Art-Net™ to dimmer (KL2761 and KL2751)
▪
Art-Net™ to DALI (KL6811)
▪
Art-Net™ to stepper or DC motor
▪
Art-Net™ to digital IOs (e.g. 24V or 230V)
▪
Art-Net™ to analog IOs (e.g. 0-10V or 4-20mA).
@Mit obigem Satz übersetzt. Bitte löschen@
Documents about this
•