UDP_SOCKET_2

Type	Function block
Description	The function block opens and closes an IP socket which is used for IP communication via User Datagram Protocol (UDP). The IP socket is represented by the HANDLE output parameter. This handle has to be forwarded to the function blocks UDP_SEND_2 and UDP_RECEIVE_2, which require the socket handle for the data exchange with a communication partner. With a rising edge at the ACTIVATE input, the system starts to open a socket. Once the socket has been opened and the connection has been established successfully, the ACTIVE output is set to TRUE. Only while ACTIVE = TRUE, the socket handle provided at the HANDLE output can be used for subsequent calls of the UDP_SEND_2/UDP_RECEIVE_2 function blocks. While ACTIVE = FALSE, calling the UDP_SEND_2/UDP_RECEIVE_2 function blocks with the socket handle causes an error at the function blocks. The socket is kept open as long as the ACTIVATE input is TRUE. The BUSY output is set to TRUE while ACTIVATE is TRUE and the socket is still not open. As soon as the socket is opened, BUSY is set to FALSE and remains FALSE while ACTIVE = TRUE. The IP address and port of the Ethernet adapter to be used for the data exchange can be specified with the BIND_IP and BIND_PORT inputs. The BROADCAST input controls whether one specific communication partner is addressed or (if TRUE is applied) all potential addressees in the network. If the ACTIVATE input switches to FALSE, the socket is closed and the ACTIVE output is set to FALSE (see also the notes below). WARNING Unintended machine operation Verify that the influence of the output data cannot result in an unintended or hazardous behavior of the entire system.1 1 When running the application logic in simulation mode, the function blocks for Ethernet communication establish a real connection to other devices/servers. Thus, outputs and variables connected to real hardware may be set and therefore may cause real damage to the machine.
Notes	The function blocks for UDP communication are processed asynchronously. This means, the function blocks issue commands and wait for their processing. In case of a warm start or cold start or a controller reset, the firmware closes all sockets that have been opened with the corresponding instance of the UDP_SOCKET_2 instance. For controllers with integrated firewall, make sure that the firewall does not block the ports involved in the communication. Otherwise, the connection cannot be established. All IP addresses used are IPv4 addresses that consist of four numbers (0 to 255) separated by dot. The number of IP sockets that are currently opened is indicated by the system variable IP_ACTIVE_SOCKETS (contained in the Data List of the controller node and 'IEC 61131-3' node in the PLANT). Function blocks have to be instantiated. The instance name of the function block has to be declared in the 'Variables' table of the POU where the FB is going to be used. The instance name must be unique within the POU.
Parameters	Inputs ACTIVATE Data type: BOOL Description: The function block starts opening a socket when a rising edge is detected at the input. A falling edge triggers the closing of the socket. The socket is kept open as long as the ACTIVATE input is TRUE. BIND_IP Data type: STRING Description: Defines the local IP address (IPv4 address) of the Ethernet adapter to which the created socket is bound. The selected Ethernet adapter is used for the data exchange between the network devices (useful, for example, with UDP servers for controllers that use several Ethernet adapters). Together with the port number bound to the created socket (BIND_PORT input) the IP address identifies the Ethernet adapter. If the string is empty or contains the value 0.0.0.0., a suitable Ethernet adapter is selected. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. BIND_PORT Data type: UINT Description: Defines the local port number associated with the IP address of the selected Ethernet adapter (BIND_IP input) to which the created socket is bound. The selected port number is used by the UDP socket for incoming data. If the value is 0 (= initial value of the parameter), the stack assigns a temporary port. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. BROADCAST Data type: BOOL Description: If BROADCAST = TRUE, the created socket can send UDP datagrams to the broadcast address 255.255.255.255. Note Ensure that the gateway in your IP configuration is set to a valid value unequal to 0.0.0.0 (address 0.0.0.0 is treated as a missing gateway). (It is not required that the network contains a device with the configured gateway address.) If no valid gateway address is specified, no broadcast is sent and the error 0xC212 is thrown when calling the UDP_SEND_2 FB. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. Outputs HANDLE Data type: DWORD Description: Created IP socket handle. The socket handle is required by subsequently calls to the function blocks UDP_RECEIVE_2 and UDP_SEND_2 in order to send or receive data, for example, to or from an UDP server. Note Do not use a handle created with an instance of the older function block implementation UDP_SOCKET with the new function blocks UDP_SEND_2/UDP_RECEIVE_2 and vice versa. Only use handles within the same "FB generation". The socket handle can only be used for subsequent calls of the UDP_SEND_2/UDP_RECEIVE_2 function blocks as long as ACTIVE = TRUE. Calling the UDP_* function blocks while ACTIVE = FALSE causes an error at the function blocks (see the description of the *_UDP function blocks for the generated STATUS code). ACTIVE Data type: BOOL Description: Indicates whether a socket is open. TRUE: Connection established successfully and socket is open. As long as ACTIVE = TRUE, the socket HANDLE can be used for calls of the UDP_SEND_2/UDP_RECEIVE_2 function blocks for send/receive operations. FALSE: Socket is closed. While ACTIVE = FALSE, calling the UDP_SEND_2/UDP_RECEIVE_2 function blocks with the socket HANDLE causes an error at the function blocks. BUSY Data type: BOOL Description: Set to TRUE if the ACTIVE input is TRUE and the socket is still not open. When the socket has been opened, BUSY is set to FALSE and remains FALSE while ACTIVE = TRUE. ERROR Data type: BOOL Description: If an error occurs, the ERROR output is set to TRUE. The corresponding error code can be read at the STATUS output as long as ERROR = TRUE. See Error Codes / Status Codes for Ethernet FBs. STATUS Data type: WORD Description: Provides the error code in the event of an error (ERROR = TRUE) or the current status of the function block (ERROR = FALSE). Error codes start with 16#Cxxx and status codes with 16#8xxx. See Error Codes / Status Codes for Ethernet FBs. USED_PORT Data type: UINT Description: Indicates the port that is used for the socket creation (automatically assigned or port number specified with the BIND_PORT parameter). The output can be used for diagnostic purposes, if needed.