UDP_RECEIVE

Type	Function block
Description	The function block is used to receive an UDP (Universal Datagram Protocol) datagram from an UDP-capable Ethernet device via an IP socket. The IP socket must first be opened using the UDP_SOCKET function block before data can be received. Each receive operation is triggered by a rising edge at the EN_R input (EN_R = ENable_Receive). If data has been successfully received, the NDR output (NDR = New Data Received) is set to TRUE for each cycle in which data has been copied to the DATA buffer. During the cycle, the data at the DATA input are valid and must be processed. In case that processing cannot be completed within the cycle, the data must be copied or the EN_R input must be set to FALSE. If EN_R is still set to TRUE and new data is received in the next cycle, NDR remains TRUE and the new data is copied to the variable connected to the DATA parameter. If no new data is received, NDR is set to FALSE. The device from which data are received is indicated at the outputs SOURCE_IP (IP address of the sending device) and SOURCE_PORT (port number of the sending device). 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 IP socket opened by the UDP_SOCKET function block can only be used for subsequent calls of the UDP_RECEIVE function block as long as the ACTIVE output of the UDP_SOCKET function block is TRUE. Calling the UDP_RECEIVE function block while ACTIVE = FALSE causes an error at the UDP_RECEIVE function block (ERROR = TRUE and STATUS code = 0xC210 issued). While EN_R is set to FALSE, datagrams that are not received might get lost. 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. 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 EN_R Data type: BOOL Description: With a rising edge at the EN_R input (EN_R = ENable_Receive), the data reception is started. As long as EN_R = TRUE, receiving data is possible. HANDLE Data type: DWORD Description: Socket handle that has been opened with the UDP_SOCKET function block (see also the notes above). Input/Output DATA Data type: ANY Description: Data buffer which contains the data received from the device identified by the SOURCE_IP and SOURCE_PORT parameters. If the data type of the connected variable is a STRUCT (or ARRAY OF STRUCT), the variable in the controller memory may contain padding bytes which have to be considered in the incoming data. Outputs NDR Data type: BOOL Description: NDR (New Data Received) is set to TRUE for one cycle once the data has been received successfully. You can only evaluate the success of the transmission during the cycle while NDR = TRUE. ERROR Data type: BOOL Description: If an error occurs, the ERROR output is set to TRUE. The corresponding error code is indicated at the STATUS output. 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. SOURCE_IP Data type: STRING Description: IP address of the device from which data have been received. Note The string contains an IPv4 address that consists of four numbers (0 to 255) separated by dot. SOURCE_PORT Data type: UINT Description: Port number of the device from which data have been received. DATA_CNT Data type: UDINT Description: Number of successfully received bytes (DATA_CNT = DATA_CouNT). The number of bytes is less or equal to the number of bytes provided with the variable connected to the DATA buffer. The parameter has to be evaluated in the cycle in which NDR = TRUE. If the datagram received is longer than the variable connected to DATA, an error is reported, the datagram is rejected and no data is copied to the DATA buffer. Tip: You can use the SIZEOF function to determine the size of a variable (number of bytes reserved for the variable in the controller memory).