| Type | Function block |
| Description | The function block is used to receive data via TLS (Transmission Layer Security) from a TLS-capable Ethernet device. This is done using a TLS socket. The socket must first be opened using the TLS_SOCKET function block before data can be received.Once the socket is opened and a connection is established, the function block receives data from the communication partner either via a pure TCP connection or a TLS-secured connection. The type of connection used depends on the value of the START_TLS input of the TLS_SOCKET function block:
- With START_TLS = FALSE, the function block uses a pure TCP connection to receive data.
- With START_TLS = TRUE, the function block receives data via a TLS-secured connection.
The function block provides a security check for identifying whether the IEC application expects the data to be received unsecure (via a TCP connection) or secure (via TLS-secured connection). The security check is done by comparing the values of the RECEIVE_SECURE input of the function block and the START_TLS input of the TLS_SOCKET FB. If an inconsistency of the input values is detected, for example, RECEIVE_SECURE = TRUE (IEC application requires secure reception of data) and START_TLS = FALSE (TLS protocol not yet initialized), the ERROR output is set to TRUE and the error code 16#C150 is indicated at the STATUS output.If the EN_R input (EN_R - ENable_Receive) is TRUE, the function block receives data. If data has been successfully received, the NDR output (NDR = New Data Received) is set to TRUE for each cycle in which the specified amount of data has been copied to the DATA buffer. 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).
Unintended machine operation
Verify that the influence of the output data cannot result in an unintended or hazardous behavior of the entire system. |
|
| Notes |
- The TLS socket opened by the TLS_SOCKET function block can only be used for subsequent calls of the TLS_RECEIVE function block as long as the ACTIVE output of the TLS_SOCKET function block is TRUE. Calling the TLS_RECEIVE function block while ACTIVE = FALSE causes an error at the TLS_RECEIVE function block (ERROR = TRUE and STATUS code = 0xC210 issued).
- The TLS socket handle created by the TLS_SOCKET function block is not compatible with the TCP socket handle created by the TCP_SOCKET function block. The TLS socket handle can only be used with the TLS_SEND/TLS_RECEIVE function blocks and the TCP socket only with the TCP_SEND/TCP_RECEIVE function blocks.
- 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 TLS_SOCKET function block (see also the notes above).The parameter is only evaluated in the cycle in which the EN_R parameter switches to TRUE. |
EXP_DATA_CNT
| Data type: | UDINT |
| Description: | Number of bytes of the data to be received (EXP_DATA_CNT = EXPected 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 following applies:
- If the value is greater than 0, only the specified number of bytes is copied to the variable connected to the DATA buffer.
- If less than the specified number of bytes have been received, these bytes are appended to the already received bytes in the variable connected to the DATA buffer. The output DATA_CNT is incremented accordingly. If the EXP_DATA_CNT bytes have been received, the output NDR is set to TRUE. Otherwise further calls of this instance are necessary to receive all expected data.
- If more than the specified number of bytes have been received, only EXP_DATA_CNT bytes are copied to the variable connected to the DATA buffer. The output DATA_CNT is incremented accordingly and NDR is set to TRUE. The remaining bytes (received but not yet copied) can be read by the next calls of the instance.
- If the value is 0, all data that have been received since the last call are copied to the variable connected to the DATA buffer (with the number of copied bytes being restricted to the size of the connected variable). The output DATA_CNT is incremented accordingly. If one or more bytes have been received (DATA_CNT > 0), the output NDR is set to TRUE.
The parameter is only evaluated in the cycle in which the EN_R parameter switches to TRUE.
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). |
RECEIVE_SECURE
| Data type: | BOOL |
| Description: | Determines whether the IEC application expects the data to be received unsecure (via TCP connection) or secure (via TLS-secured connection).
- TRUE: application expects secure data reception (via TLS-secured connection).
- FALSE: application expects unsecure data reception (via TCP connection).
The input value is compared with the value of the START_TLS input of the TLS_SOCKET FB. If an inconsistency of the input values is detected, for example, RECEIVE_SECURE = TRUE (IEC application requires secure reception of data) and START_TLS = FALSE (TLS protocol not yet initialized), the ERROR output is set to TRUE and the error code 16#C150 is indicated at the STATUS output. |
Input/Output
DATA
| Data type: | ANY |
| Description: | Data buffer which contains the received data.Data is transmitted as byte stream. There is no Little-/Big-Endian conversion. 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 stream. |
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.If NDR is TRUE, the next call (if some bytes were received) will overwrite DATA (NDR may be TRUE again)If NDR is FALSE, the next call (if some bytes were received) will append the received bytes to DATA. DATA_CNT will be incremented accordingly. If the expected number of bytes is reached, NDR will be TRUE |
ERROR
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 TLS_* Function Blocks. |
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. 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.
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). |
|