Library description 10/2016 Communication Library LCom for ......Warranty and liability Communication Library LCom Entry-ID: 48955385, V2.2, 10/2016 2 G 6 d Warranty and liability

https://support.industry.siemens.com/cs/ww/en/view/48955385

Library description 10/2016

Communication Library LCom for S7-1200/S7-1500


Warranty and liability

Communication Library LCom Entry-ID: 48955385, V2.2, 10/2016 2

S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Warranty and liability

Note The Application Examples are not binding and do not claim to be complete regarding the circuits shown, equipping and any eventuality. The Application Examples do not represent customer-specific solutions. They are only intended to provide support for typical applications. You are responsible for ensuring that the described products are used correctly. These application examples do not relieve you of the responsibility to use safe practices in application, installation, operation and maintenance. When using these Application Examples, you recognize that we cannot be made liable for any damage/claims beyond the liability clause described. We reserve the right to make changes to these Application Examples at any time without prior notice. If there are any deviations between the recommendations provided in these application examples and other Siemens publications – e.g. Catalogs – the contents of the other documents have priority.

We do not accept any liability for the information contained in this document.

Any claims against us – based on whatever legal reason – resulting from the use of the examples, information, programs, engineering and performance data etc., described in this Application Example shall be excluded. Such an exclusion shall not apply in the case of mandatory liability, e.g. under the German Product Liability Act (“Produkthaftungsgesetz”), in case of intent, gross negligence, or injury of life, body or health, guarantee for the quality of a product, fraudulent concealment of a deficiency or breach of a condition which goes to the root of the contract (“wesentliche Vertragspflichten”). The damages for a breach of a substantial contractual obligation are, however, limited to the foreseeable damage, typical for the type of contract, except in the event of intent or gross negligence or injury to life, body or health. The above provisions do not imply a change of the burden of proof to your detriment.

Any form of duplication or distribution of these Application Examples or excerpts hereof is prohibited without the expressed consent of the Siemens AG.

Security informa-tion

Siemens provides products and solutions with industrial security functions that support the secure operation of plants, solutions, machines, equipment and/or networks. They are important components in a holistic industrial security concept. With this in mind, Siemens’ products and solutions undergo continuous development. Siemens recommends strongly that you regularly check for product updates.

For the secure operation of Siemens products and solutions, it is necessary to take suitable preventive action (e.g. cell protection concept) and integrate each component into a holistic, state-of-the-art industrial security concept. Third-party products that may be in use should also be considered. For more information about industrial security, visit http://www.siemens.com/industrialsecurity.

To stay informed about product updates as they occur, sign up for a product-specific newsletter. For more information, visit http://support.industry.siemens.com.

http://www.siemens.com/industrialsecurity

http://support.industry.siemens.com/

Table of contents


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Table of contents Warranty and liability ................................................................................................... 2

1 Library Overview ................................................................................................ 4

1.1 Different user scenarios ....................................................................... 5 1.2 Hardware and software requirements .................................................. 9 1.3 Library resources .................................................................................. 9

2 LCom_Communication ................................................................................... 10

2.1 Parameter ........................................................................................... 11 2.2 Functionality ....................................................................................... 13 2.2.1 Establishment of communication ....................................................... 13 2.2.2 Communication discontinuation ......................................................... 18 2.2.3 Sending data ...................................................................................... 19 2.2.4 Receiving data .................................................................................... 22 2.2.5 Sign of life ........................................................................................... 28 2.2.6 Time synchronization ......................................................................... 29 2.3 Error and diagnostic ........................................................................... 31 2.3.1 Status message .................................................................................. 33 2.4 PLC data types ................................................................................... 43

3 Working with the Library................................................................................. 50

3.1 Integrating the library into STEP 7 ..................................................... 50 3.2 Integrating the library blocks into STEP 7 .......................................... 51

4 Notes and Support ........................................................................................... 52

5 Related literature ............................................................................................. 52

6 Contact.............................................................................................................. 52

7 History............................................................................................................... 52

Library Overview


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

1 Library Overview

What you get

This document describes the LCom block library. The block library provides you with the tested code with clearly defined interfaces.

The LCom block library can be used for the standard TCP communication. The widespread deployment of TCP allows easy data exchange between two different devices, e.g. a camera, CPU or PC.

Since the functional scope of TCP is not sufficient for many applications, the LCom library defines an additional transport protocol (LCom protocol).

The block library LCom offers the following advantages for the user:

No need to know the various system functions (e.g. TCON, TSEND, TRCV) to connect, send, receive and disconnect.

In case of any fault LCom closes automatically the connection and tries to reestablish the connection.

User parameterizable cyclic data transmission

Single data transmission

Consistent data exchange

Comparison of communication parameters

Monitoring of the connection through cyclic transmission of a sign-of-life (faster response times on connection failure). In the case of a native TCP communication, this is typically in the range of seconds

Data records with defined length up to 64 KB when using LCom protocol V1

Data records with defined length up to 16 MB when using LCom protocol V2

Feedback from receiver on successful data transmission on application level

Time synchronization

Built-in diagnostics structure to help trouble shooting

Multi-instance support

Scope of application

STEP 7 Basic/Professional V13 SP1

S7-1200 CPU as of firmware 4.1.1

S7-1500 CPU as of firmware 1.8.0

Library Overview


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

1.1 Different user scenarios

Possible applications for the LCom library

The LCom block library can be used to implement a point-to-point full duplex communication via Industrial Ethernet based on the TCP protocol. The widespread deployment of TCP allows easy data exchange between two different devices, e.g. a camera, CPU or PC.

Since the functional scope of TCP is not sufficient for many applications, the LCom library defines an additional transport protocol (LCom protocol). With the LCom protocol additional communication functionalities are possible.

Figure 1-1 User scenario

The following sections show several scenarios for a possible application of the LCom library:

Application

LCom_Communication

IDB

Ethernet

Interface

CPU

IDB

Camera

S7-1500 CPU

Switch

Library Overview


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Scenario 1

LCom can be used for native TCP communication. The TCP transport protocol guarantees a continuous flow of data. TCP is not packet-oriented and therefore does not permit transmission of data records with a defined overall length. It’s up to the user to separate the data flow into consistent data records (user packets).

Figure 1-2: Native (open user) TCP communication








Application

LCom_Communication

IDB

Ethernet

Interface

CPU

IDB

Camera

Switch

Library Overview


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Scenario 2

When the LCom protocol is used the sender gets feedback from the receiver that the data transmission was successfully (consistent data exchange) exchanged. To detect a disconnection faster, a cyclic life sign telegram is exchanged. The cycle time of the periodic sign of life is specified by the user.

For time synchronization of two controllers, you can send the current time of one controller to the partner and use it there as the system time.

NOTE To be able to use the additional features of LCom both communication partners have to support the LCom protocol.

Hint: LCom protocol V2 provides a fallback strategy to LCom protocol V1 if the partner does not support LCom protocol V2.

Figure 1-3: TCP communication using LCom protocol






Consistent data exchange

Comparison of communication parameters

Monitoring of the connection through cyclic transmission of a sign-of-life (faster response times on connection failure). In the case of a native TCP communication, this is typically in the range of seconds

Data records with defined length up to 64 KB when using LCom protocol V1

Application

LCom_Communication

IDB

Ethernet

Interface

CPU

IDB

S7-1500 CPU

Switch

Library Overview


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Data records with defined length up to 16 MB when using LCom protocol V2

Feedback from receiver on successful data transmission on application level

Time synchronization



Library Overview


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

1.2 Hardware and software requirements

Requirements for this library

To be able to use the functionality of the library described in this document, the following hardware and software requirements must be met:

Hardware

Table 1-1: Hardware components

No. Component Firmware

1. SIMATIC S7-1500 CPU FW V1.8.0

2. CM 1542-1 FW V1.0.6

3. CP 1543-1 FW V1.1.28

4. SIMATIC S7-1200 CPU FW V4.1.1

Software

Table 1-2: Software components

No. Component Article number Quantity

5. Step7 Professional V13 SP1 6ES7822-1..03-.. 1

6. Step7 Basic V13 SP1 6ES7822-0..03-.. 1

1.3 Library resources

What will you find in this section?

The following section gives you an overview of the size of the blocks of the LCom library in the main and load memory.

Size of the individual blocks 1

Table 1-3: Resources

Block Symbol Size in main memory ~[Bytes]

Size in load memory ~[Bytes]

FB 30300 LCom_Communication 35000 380000

DB 30300 instLCom_Communication 9132 27000

typeLCom_Config - 3059

typeLCom_Diagnostics - 5478

1 Instance data blocks (prefix instLCOM_) are not delivered with the library. They will be

generated automatically with the call of a function block.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2 LCom_Communication


This chapter explains the parameter and functionality of the function block LCom_Communication (FB 30300).

Figure 2-1: Block diagram of LCom_Communication

"LCom_Communication" FB30300

Bool

enable connected

Bool

Bool

send sending

Bool

UDInt

sendDataLength dataReceived

Bool

UDInt

readDataLength receivedDataLength

UDInt

typeLCom_Config

configuration busy

Bool

error

Bool

status

Word

Variant sendBuffer

Variant

Variant receiveBuffer

Variant

typeLCom_Diagnostics diagnostics

typeLCom_Diagnostics

Table 2-1: List of the blocks

Block Symbol Classification

FB 30300 LCom_Communication In-house development

SFB 109 TCON System-internal block

SFB 103 TDISCON System-internal block

SFB 150 TSEND System-internal block

SFB 151 TRCV System-internal block

SFC 59 RDREC System-internal block

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.1 Parameter

The following tables show all parameter of the function block LCom_Communication.

Input parameters

Table 2-2: LCom_Communication input parameters

Parameter Data type Description

enable Bool TRUE: A rising edge activates processing and FB tries to

establish a connection to the partner

FALSE (default): A falling edge clears the connection.

send Bool TRUE: User data connected to input sendBuffer will be sent if connection is established.

FALSE (default): No user data will be sent.

sendDataLength UDInt Data length to be sent in bytes.

(default: 4294967295)

readDataLength UDInt Without LCom protocol (configuration.connection.comService = LCOM_TCP_CONNECTION):

0: TCP buffer is not being read. User data from partner will not be available.

1 .. 4294967294: FB is waiting until input number of bytes is available in the TCP buffer from the communication partner. Then output dataReceived is set to TRUE. Additional bytes remain in the TCP buffer.

4294967295, 16#FFFFFFFF (default): All data available in the TCP buffer is read immediately (ad-hoc mode).

With LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION):

0: TCP buffer is not being read. User data from partner will not be available.

1 .. 4294967294: Not relevant.

4294967295, 16#FFFFFFFF (default): Not relevant.

configuration typeLCom_Config FB configuration, see PLC data type typeLCom_Config

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Output parameters

Table 2-3: LCom_Communication output parameters


connected Bool Without LCom protocol (configuration.connection.comService = LCOM_TCP_CONNECTION):

TRUE: TCP connection to partner is established.

FALSE: TCP connection to partner is not established.

With LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION):

TRUE: TCP connection to partner is established and configuration data is negotiated successfully

FALSE: TCP connection to partner is not established or waiting for negotiation of configuration data.

sending Bool TRUE: User data connected to input sendBuffer is being sent. Send buffer should not be changed.

FALSE: Sending of user data is not active.

dataReceived Bool TRUE: New data has been received. TRUE is present for one cycle.

FALSE: No new user data is available.

receivedDataLength UDInt Received user data length in bytes.

busy Bool TRUE: FB is processing. No user action necessary in case of error.

FALSE: FB is not processing. User action necessary in case of error.

error Bool TRUE: Error occurred. User action is necessary, e.g. faulty FB parameters. See output status or FB diagnostics for details.

FALSE: No error active.

status Word FB status, see table Status and error displays

In-Out parameters

Table 2-4: LCom_Communication in-out parameters


sendBuffer Variant Pointer to send data (Array of Byte)

receiveBuffer Variant Pointer to receive data (Array of Byte)

diagnostics typeLCom_Diagnostics Diagnostics structure, see typeLCom_Diagnostics

The diagnostics structure is a ring buffer, Every diagnostic entry provides detailed status information, additional values and timestamp of occurrence

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.2 Functionality

2.2.1 Establishment of communication

In order to establish a connection between two communication partners, you must configure which device is the client and which is the server. Both partners have equal priority when the connection is established. The data transmission can therefore be initiated by both partners.

All relevant communication parameters can be found in the data structure configuration.connection.

Table 2-5 Connection parameter


Connection Struct

interfaceID HW_ANY Hardware identifier of the local interface, see PLC tags->Default tag table->System constants

(default: 64)

connectionID CONN_ANY Unique connection identifier

16#0001 .. 16#0FFF

(default: 16#0FFF)

comService USInt Configuration of the communication protocol

1: LCOM_TCP_CONNECTION Native (open user) TCP protocol is used

2:LCOM_LCOM_CONNECTION (default) LCom protocol with additional functionality is used

isClient Bool TRUE: TCP client Active connection establishment

FALSE: TCP-server (default) Passive connection establishment.

localPort UInt Local port number, see system function TCON

(default: 3456)

partnerPort UInt Only valid by active connection establishment (configuration.connection.isClient = TRUE)

Partner port number, see system function TCON. (default: 3456)

partnerIP IP_V4 Only valid by active connection establishment (configuration.connection.isClient = TRUE)

Partner IP address xxx.xxx.xxx.xxx = [1].[2].[3].[4]

Only valid by passive connection establishment (configuration.connection.isClient = FALSE) and just specified partner is allowed

(configuration.connection.acceptUnknownP

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d


artner = FALSE)

Partner IP address which is allowed.

acceptUnknownPartner Bool Only valid by passive connection establishment (configuration.connection.isClient = FALSE)

TRUE: accept requests from all partners (default)

FALSE: only specified partner is allowed

lifeSignCycleTime Time Only valid with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION)

T#1ms .. T#24d20h31m23s647ms

(default: T#1s)

Figure 2-2: Connection parameters example

With a rising edge at enable input a TCP connection is tried to establish using the configured parameters. If LCom protocol is used the LCom version is checked as soon as the TCP connection is established. If the communication partner does not support LCom protocol V2 the connection is closed and a new connection using LCom protocol V1 is tried to establish.

// Connection parameters

//-----------------------------------------------------------

//hardware identifier of the local interface

"LCom_Communication_DB".configuration.connection.interfaceID

:="Local~PROFINET_interface_1";

//unique connection identifier (16#0001..16#0FFF)

"LCom_Communication_DB".configuration.connection.connectionID := 500;

//1 (LCOM_TCP_CONNECTION) = TCP protocol, 2(LCOM_LCOM_CONNECTION) = LCOM protocol

"LCom_Communication_DB".configuration.connection.comService :=

"LCOM_LCOM_CONNECTION";

//FALSE: passive (server), TRUE: active connection establishment (client)

"LCom_Communication_DB".configuration.connection.isClient := TRUE;

//local port number, see system function TCON

"LCom_Communication_DB".configuration.connection.localPort := 3456;

//partner port number, see system function TCON

"LCom_Communication_DB".configuration.connection.partnerPort := 3456;

//partner IP-address xxx.xxx.xxx.xxx = [1].[2].[3].[4]

"LCom_Communication_DB".configuration.connection.partnerIP.ADDR[1] := 192;




//TRUE: accept requests from all partners, FALSE: only specified partner is allowed

"LCom_Communication_DB".configuration.connection.acceptUnknownPartner := TRUE;

//life sign cycle time (only relevant for use of LCom header)

"LCom_Communication_DB".configuration.connection.lifeSignCycleTime := T#1s;

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Function characteristics

The following figures will illustrate the connection establishment:

Connection establishment using LCom-protocol V1

Connection establishment using LCom-protocol V2

Connection establishment using native (open user) TCP

Figure 2-3: Connection establishment using LCom-protocol V1

status

connected

1) 2) 3)

0

1

16#7001

16#7003

16#7000

16#7006

4) 5) 6)

enable

1

0

16#8613

busy

1

0

error

1

0

1. FB is disabled.

2. With a rising edge at enable input the FB is processing and busy output becomes TRUE. Value of FB status is LCOM_STATUS_FIRST_CALL.

3. The TCP connection is established (TCP client) and LCom protocol V2 negotiation is tried. Value of FB status is LCOM_STATUS_CLIENT_TRY_CONNECT.

4. The communication partner does not support LCom protocol V2. Error output is set and the connection is closed. Value of FB status is LCOM_ERR_WRONG_LCOM_HEADER.

5. The TCP connection is reestablished (TCP client) and LCom protocol V1 negotiation is tried. Value of FB status is LCOM_STATUS_CLIENT_TRY_CONNECT.

6. FB output connected becomes TRUE as soon as LCom protocol negotiation is

completed successfully.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Figure 2-4: Connection establishment using LCom-protocol V2

status

connected

1) 2) 3)

0

1

16#7001

16#7003

16#7000

16#7007

4)

enable

1

0

busy

1

0

error

1

0

1. FB is disabled.


3. The TCP connection is established (TCP client) and LCom protocol V2 negotiation is tried. Value of FB status is LCOM_STATUS_CLIENT_TRY_CONNECT.

4. FB output connected becomes TRUE as soon as LCom protocol negotiation is

completed successfully.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Figure 2-5: Connection establishment using native (open user) TCP

status

connected

1) 2) 3)

0

1

16#7001

16#7003

16#7000

16#7005

4)

enable

1

0

busy

1

0

error

1

0

1. FB is disabled.


3. The TCP connection is tried to establish (TCP client). Value of FB status is LCOM_STATUS_CLIENT_TRY_CONNECT.

4. FB output connected becomes TRUE as soon as the TCP connection to the

partner is established.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.2.2 Communication discontinuation

Discontinuation of communication can be initiated by both communication partners with a falling edge at enable input. FB output connected becomes FALSE. The other side is informed of this discontinuation and the connection is closed by both partners. The status of the closed connection is indicated via a reset of busy output

variable.


Figure 2-6: Communication discontinuation without LCom-protocol

status

connected

1) 2)

0

1

16#7005

16#7008

16#7000

3)

enable

1

0

busy

1

0

error

1

0

1. TCP connection is established.

2. The connection to the partner will be closed with a falling edge at enable input. Value of FB status is LCOM_STATUS_LCOM_DISCONNECTING.

3. The connection to the partner was closed successfully. Output variable busy is

reset.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.2.3 Sending data

Depending on the parameterized values in configuration.sender structure (see PLC data type typeLCom_Config) user data can be exchanged cyclic or user triggered. When using LCom protocol the user data has to be acknowledged within the configured timeout, otherwise the connection is closed and reestablished.

Table 2-6: Parameters for sending


sender Struct

cycleTime Time Time interval used for cyclic communication

T#0ms...T#24d20h31m23s647ms

(default: T#1s)

ackTimeout Time Only valid with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION)

Timeout in case of missing confirmation, only valid with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION); connection will be closed and reestablished after timeout

T#1ms .. T#24d20h31m23s647ms

(default: T#1s)

Figure 2-7: Sender parameters example

NOTE If the communication partner supports LCom protocol V1 only, then the local sender configuration is negotiated with the partner receiver configuration (see V1 sCfgReceiver.u16CycleTime und sCfgReceiver.u16AckTimeout). The negotiated values are the bigger values of both partners. It is recommended to set the values in the partner receiver configuration to 0.

These configuration parameters can be changed at runtime without the need of a rising edge at enable input.

The active (negotiated) values can be monitored in the diagnostics structure.

The user data to be sent provided at input sendBuffer is of data type “ARRAY of BYTE”. Any structured user data has to be converted with system function Serialize (see system manual) and copied to sendBuffer.

Data transmission is started with a rising edge at input send. Length of data to be transferred is provided at input sendDataLength.

//----------------------------------------------------------

//

// Sender configuration

//-----------------------------------------------------------

//timeout in case of missing confirmation

"LCom_Communication_DB".configuration.sender.ackTimeout := T#1s;

//time interval for cyclic communication

"LCom_Communication_DB".configuration.sender.cycleTime := T#1s;

//-----------------------------------------------------------

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

connected

1)

0

1

2)

enable

1

0

busy

1

0

send

1

0

sending

1

0

0 1 2 t in s

To achieve a consistent data transmission the user is not allowed to change the data while output sending is TRUE.

Attention If sendDataLength is greater than the size of sendBuffer, then the amount of data to be sent is limited to the size of sendBuffer. In this case status output shows the value 16#7600 (LCOM_WARN_SEND_DATA_LENGTH). This information is entered in the diagnostics buffer.

When using LCom protocol the size of the partner receive buffer is also taken into account. If this is smaller than sendDataLength a maximum of size of partner receive buffer in bytes is sent. In this case status output shows the value 16#7614 (LCOM_WARN_RECEIVE_BUFFER_LEN). This information is entered in the diagnostics buffer.



Figure 2-8: Single data transmission (configuration.sender.cycleTime = T#0ms)

1. Data transmission is started with a rising edge at send input. Output sending is set to TRUE.

2. Data transmission completed. Output sending is reset.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Figure 2-9 Single data transmission (configuration.sender.cycleTime = T#1s)



3. Send input is reset before send cycle time elapses.

Cyclic data transmission

Figure 2-10: Cyclic data transmission (configuration.sender.cycleTime = T#1s)

connected

1)

0

1

2)

enable

1

0

busy

1

0

send

1

0

sending

1

0

0 1 2 t in s

3)



3. User data is sent every cycle time.

connected

1)

0

1

2)

enable

1

0

busy

1

0

send

1

0

sending

1

0

0 1 2 t in s

3)

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.2.4 Receiving data

The input variable readDataLength can multiply influence the receive characteristics as well as the resulting response behavior of the output variable dataReceived (received user data is valid).

It must be distinguished between native TCP (scenario 1) and LCom protocol (scenario 2).

However for both scenarios applies equally:

with readDataLength=0 there will be no data read from the TCP receive buffer. Receiving is blocked

consistent user data is available when dataReceived = TRUE (just for one cycle). Output receivedDataLength informs about the length of the user

data

The received user data is transferred to receiveBuffer which is of data type “ARRAY of BYTE”. This data can be converted into structured user data with system function Deserialize (see system manual)

The different receiving characteristics with and without LCom protocol within number range 0 to 4294967295 are explained below.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Without LCom protocol = native (open user) TCP protocol (configuration.connection.comService = LCOM_TCP_CONNECTION):

readDataLength = 0: No data is read from the TCP receive buffer. Receiving is

blocked.


Figure 2-11: Receiving data with native (open user) TCP protocol (readDataLength = 0)

Ethernet 1460 ByteEthernet 1460 Byte

NetworkSender application

Ethernet 1176 Byte

sendDataLength = 4096

Application program

Lcom_Communication

IDB

CPU

IDB

LCom_Communication is called

dataReceived = FALSE

receivedDataLength= 0


Ethernet 1460 ByteEthernet 1460 ByteEthernet 1176 ByteLCom_Communication is called






Receiver application




readDataLength=0

1)

2)

2)

2)

1. 1460 bytes have already been received in the TCP receive buffer but the data is not read by the FB because readDataLength = 0. The user does not get any

data. Receiving is blocked.

2. No change with further FB calls. All data remains in the TCP buffer.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

readDataLength = 1 .. 4294967294: Number of bytes to be received before data is transferred to user receiveBuffer and output dataReceived becomes TRUE.


Figure 2-12: Receiving data with native TCP protocol (sendDataLength < readDataLength)

Ethernet 90 Byte


sendDataLength = 90

Application program

Lcom_Communication

IDB

CPU

IDB




sendDataLength = 50

Ethernet 50 Byte


dataReceived = TRUE



dataReceived = TRUE






readDataLength=100

sendDataLength = 60

Ethernet 60 Byte

1)

2)

3)

4)

1. 90 bytes have already been received. The user is waiting for 100 bytes (readDataLength = 100). Therefore dataReceived remains FALSE and receivedDataLength = 0.

2. Subsequent FB call. No new data has been received.

3. Another 50 bytes have been received. Now a total of 140 bytes is available. The first 100 bytes are transferred to user receiveBuffer. (dataReceived = TRUE for one cycle, receivedDataLength =100). The remaining 40 bytes are

used as first part of the next expected 100 bytes.

4. 60 bytes have been received. Now a total of 100 bytes is available for the user in receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength

=100). Data transmission completed successfully.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Figure 2-13: Receiving data with native TCP protocol (sendDataLength > readDataLength)

Ethernet 200 Byte



Application program

Lcom_Communication

IDB

CPU

IDB


dataReceived = TRUE



Ethernet 300 Byte


dataReceived = TRUE



dataReceived = TRUE




dataReceived = TRUE


readDataLength=100

1)

2)

3)

4)


dataReceived = TRUE


5)

1. 200 bytes have been received. The first 100 bytes are transferred to user receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength = 100). The remaining 100 Bytes are used as first part of the next expected 100 bytes.

2. No new data has been received. There are still 100 bytes available Now these 100 bytes are transferred to user receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength = 100). Data transmission completed successfully.

3. 300 bytes have been received. The first 100 bytes are transferred to user receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength = 100). The remaining 200 Bytes are used as first part of the next expected 100 bytes.

4. No new data has been received. There are still 200 bytes available Now the first 100 bytes are transferred to user receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength = 100).

5. No new data has been received. There are still 100 bytes available Now these 100 bytes are transferred to user receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength = 100). Data transmission completed successfully.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

readDataLength = 4294967295 (16#FFFFFFFF): All data is transferred immediately to the user receiveBuffer (Ad-Hoc Mode) and output dataReceived

becomes TRUE with each receiving of data.


Figure 2-14: Receiving data in Ad-Hoc mode (readDataLength = 16#FFFFFFFF)



Ethernet 1176 Byte


Application program

Lcom_Communication

IDB

CPU

IDB


dataReceived = TRUE




dataReceived = TRUE



dataReceived = TRUE




dataReceived = TRUE


readDataLength=FFFFFFFF

1)

2)

3)

4)

1. 1460 bytes have been received. These are transferred immediately to user receiveBuffer (dataReceived = TRUE for one cycle, receivedDataLength =

1460).


2636).


2920).


1176).

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

With LCom protocol

(configuration.connection.comService = LCOM_LCOM_CONNECTION):

readDataLength = 0: No data is read from the TCP receive buffer. Receiving is

blocked.


Figure 2-15: Receiving data with LCom protocol (readDataLength = 0)



Ethernet 1176 Byte


Application program

Lcom_Communication

IDB

CPU

IDB















readDataLength=0

1)

2)

2)

2)

1. 1460bytes have already been received in the TCP receive buffer but the data is not read by the FB because readDataLength = 0. The user does not get any data. Receiving is blocked.

2. No change with further FB calls. All data remains in the TCP buffer.

readDataLength = 1 .. 4294967295: Setting has no impact on receiving behavior.

Figure 2-16: Receiving data with LCom protocol (readDataLength <> 0)



Ethernet 1176 Byte


Application program

Lcom_Communication

IDB

CPU

IDB



Lcom protocol handles receive

characteristics

readDataLength

1…. FFFFFFFF

1)

1. LCom protocol handles correct data receiving.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.2.5 Sign of life

In standard TCP communication, it can take several seconds to detect a failure in the communication partner. Sign-of-life monitoring reduces this period considerably. The sign-of-life is only sent when the LCom protocol is used.

If data is being transferred, it can be assumed that the connection is error-free. This information is not available during a break in transmission.

In cyclic transmission, this can occur when a long cycle time is used.

If single transmission is used, no more data is sent after data exchange has been completed.

In these phases in which no user data is exchanged, a sign-of-life is generated automatically. The cycle time of the periodic sign-of-life can be configured (configuration.sender.lifeSignCycleTime). If no new sign-of-life or new user data is received after 4 sign-of-life cycles, it is assumed that the connection is interrupted and an appropriate message is issued. The connection is reestablishing automatically.

Figure 2-17 Sign of life

NOTE A connection loss is recognized and handled after 4 sign-of-life cycles.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.2.6 Time synchronization

For time synchronization of two controllers, you can send the current time of one controller to the partner and set it there as the system time. This is possible when a connection is active and LCom protocol is used.

A distinction is made between the following types of time synchronization, see configuration.timeSync structure:

Cyclic time synchronization Specification of a cycle time for renewed synchronization

Daily time synchronization Specification of a time-of-day at which the daily synchronization is performed

The sub-structure for time synchronization parameter is defined in PLC-datatype typeLCom_Config.

Table 2-7: Parameter for time synchronization


timeSync Struct

usePartnerTimestamps Bool TRUE: synchronize local time with received timestamps

FALSE: do not use received timestamps (default)

sendMode USInt Time synchronization send mode

0: LCOM_NO_TIME_SYNC (default) time synchronization inactive

1: LCOM_CYCLE_TIME_SYNC cyclic time synchronization see configuration.timeSync.cycleTime

2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day see configuraton.timeSync.sendAtTimeOfDay

cycleTime Time Only valid by sendMode

1, LCOM_CYCLE_TIME_SYNC:

Time interval for cyclic sending of timestamps in case of cyclic time synchronization mode

T#1ms .. T#24d20h31m23s647ms

(default: T#1h)

sendAtTimeOfDay Time_Of_Day Only valid by sendMode

2, LCOM_TIME_OF_DAY_TIME_SYNC:

Time of day at which a timestamp is sent in case of time synchronization at time of day mode

(default: TOD#05:00:00.000)

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Figure 2-18: Time synchronization parameters example

NOTE Only one partner should send time synchronization data and the other one should use the received timestamps. If both partners are sending timestamps or both have the configuration variable usePartnerTimestamps set to TRUE, then no time synchronization will be executed and a warning is shown, see status LCOM_WARN_NO_TIME_SYNC.

//Configure time synchronization

//-----------------------------------------------------------

//TRUE: synchronize local time with received timestamps,

//FALSE: do not use received timestamps

"LCom_Communication_DB".configuration.timeSync.usePartnerTimestamps := FALSE;

//time synchronization send mode; 0: inactive, 1: cyclic, 2: at time of day

"LCom_Communication_DB".configuration.timeSync.sendMode := "LCOM_CYCLE_TIME_SYNC";

//time interval for cyclic mode

"LCom_Communication_DB".configuration.timeSync.cycleTime := T#1h;

//time synchronization at specified time of day (for sendMode = 2 only)

// "LCom_Communication_DB".configuration.timeSync.sendAtTimeOfDay := TOD#05:00:0.000;

//-----------------------------------------------------------

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.3 Error and diagnostic

Status and error messages are displayed via the output variable status.

For better diagnostic analysis, the status information from the user program will additional stored in a diagnostic structure. With the diagnostic structure block history becomes available for the user.

A fault is indicated by setting the boolean variable error. It is to be distinguished whether the cause of the error can be corrected by the user or by the block. If it is a mistake that can be rectified by the block busy remains set. Otherwise busy is reset

(block processing disabled).

The figure below shows the two scenarios as a signal flow diagram:

Figure 2-19: Signal flow diagram error/busy

1

0

error

(OUT)

3)

1

0

enable

(IN)

2)

5)

1

0

busy

(OUT)

1)

4)

6)

1. Busy is set with a rising edge of enable.

2. An error occurs and thus error is set. Since it is an error that can be rectified by the block itself , busy remains set.

3. After error recovery (e.g. re-establishment of the connection) error is reset.

4. An error that can only be remedied by the user. Here error is set and busy is

reset.

5. The pending error can only be acknowledged by the user with a falling edge at enable.

6. The block is started again with a rising edge at enable.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

The output parameter diagnostics contains different substructures which are defined by the PLC data type (typeLCom_Diagnostics). The diagnostic buffer will be explained below. Please refer to section 2.4 PLC data types for the complete description. The diagnostics buffer stores various status and error messages. The array is set to 64 entries and operates as a ring buffer. The variable bufferIndex points to the

last (current) entry.

Each entry consists of the following elements: status or error number, date and time of occurrence as well as the current state of the error. The state at the entry into the buffer is always active. By resetting the error the state in the buffer is set to inactive. The structure also contains the return value of the system function and four additional values, which can include detailed information depending on the occurred error.

Table 2-8: Structure of diagnostics buffer

Parameter Data type Comment

bufferIndex USint Ring buffer index of last diagnostic entry, 16#FF: initialization value

buffer Array [0..63] of Struct Diagnostics buffer

status Word FB status at occurrence of diagnostic entry

timestamp DTL Timestamp at occurrence of diagnostic entry

isActive Bool TRUE: diagnostic entry is active/valid

FALSE: diagnostic entry is inactive/invalid

subFunctionErrorID Word Return value of a system function

additionalValue1 Real Additional information 1



additionalValue4 Time Additional information 4

Figure 2-20: Diagnostics buffer in the application

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.3.1 Status message

The PLC tag table LCom_Constants contains user constants for status, warning, error (see table Status and error displays) and configuration values (see PLC data type typeLCom_Config).

Table 2-9: Status number range

Error cause Number range

No call in process (incl. initial value) 16#7000

First call after enabling 16#7001

Successive call during processing without further details

16#7002

Successive call during processing without further details

16#7003 .. 16#7FFF

Parameterization error 16#8200 .. 16#83FF

Error during internal process (e.g. when calling a system function)

16#8600 .. 16#87FF

Status and warning messages are within number range 16#7000 to 16#7FFF.

In case of an error in parameterization (16#8200 .. 16#83FF) the wrong value must be replaced with an approvable value. The function block must then be restarted using a rising edge at the enable input.

The function block will close the connection if an internal error occurs (16#8600..16#87FF) and try to restart the connection. No new rising edge is necessary at the enable input.

Every constant has a name prefix to facilitate allocation:

STATUS 16#7000 .. 16#75FF LCOM_STATUS_FIRST_CALL

WARN 16#7600 .. 16#7FFF LCOM_WARN_SEND_DATA_LENGTH

ERR 16#8200 .. 16#83FF LCOM_ERR_INTERFACE_ID

16#8600 .. 16#87FF LCOM_ERR_SEND

The used status messages are specified below. They are indicated in the output status and listed in the diagnostics buffer.

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Table 2-10: Status messages

16#7000

LCOM_STATUS_NO_CALL

FB is not processing, default value of status variable

Diagnosis entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3:

additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

16#7001

LCOM_STATUS_FIRST_CALL

First FB call after rising edge at input enable

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

16#7002

LCOM_STATUS_INTERMEDIATE_CALL

Interim call of FB

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

16#7003

LCOM_STATUS_CLIENT_TRY_CONNECT

FB tries to establish the connection as TCP client (active establishment)

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

16#7004

LCOM_STATUS_SERVER_PORT_OPEN

FB waits for partner to establish the connection (passive establishment); FB is TCP server

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1…3:

additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

16#7005

LCOM_STATUS_TCP_CONNECTED

TCP (open user) connection to partner is established

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#7006

LCOM_STATUS_LCOM_CONNECTED_V1

Negotiation of LCom protocol V1 configuration data was successful; maximum user data length is 64 Kbytes

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4:

time of occasion

condition

16#0

0.0

T#0ms

16#7007

LCOM_STATUS_LCOM_CONNECTED_V2

Negotiation of LCom protocol V2 configuration data was successful; maximum user data length is 16 Mbytes

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4:

time of occasion

condition

16#0

0.0

T#0ms

16#7008

LCOM_STATUS_DISCONNECTING

Connection is being closed

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4

time of occasion

condition

16#0

0.0

T#0ms

16#7600

LCOM_WARN_SEND_DATA_LENGTH

Input parameter sendDataLength is too big and is limited automatically to the size of the send buffer (sendBuffer)

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

16#0

sendDataLength

sendBuffer

0.0

T#0ms

16#7610

LCOM_WARN_LIFE_SIGN_LIMITATION

The configured life sign cycle time for connection monitoring (configuration.connection.lifeSignCycleTime) is too big and is limited automatically to 65535 ms

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

time of occasion

condition

16#0

limiting to 65535

0.0

user value

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#7611

LCOM_WARN_SEND_CYCLE_LIMITATION

The configured cycle time for cyclic data exchange (configuration.sender.cycleTime) is too big and is limited automatically to 65535 ms

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

time of occasion

condition

16#0

limiting to 65535

0.0

user value

16#7612

LCOM_WARN_ACK_TIMEOUT_LIMITATION

The configured timeout for acknowledging telegrams (configuration.sender.ackTimeout) is too big and is limited automatically to 65535 ms

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

Time of occasion

Condition

16#0

limiting to 65535

0.0

user value

16#7613

LCOM_WARN_SEND_CYCLE_EXPIRED

The configured send cycle for cyclic data exchange (configuration.sender.cycleTime) cannot be maintained

because a previous transmission has not yet been completed

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

time of occasion

condition

16#0

user value

0.0

hitherto time of previous send task

16#7614

LCOM_WARN_RECEIVE_BUFFER_LEN

With LCom protocol: (configuration.connection.comService = LCOM_LCOM_CONNECTION):

Input parameter sendDataLength is greater than the size of the receive buffer of the partner and is limited automatically to the size of the receive buffer of the partner

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

Time of occasion

Condition

16#0

sendDataLength

receiveBuffer of partner

0.0

T#0ms

Without LCom Protokoll: (configuration.connection.comService = LCOM_TCP_CONNECTION):

Input parameter readDataLength is greater than the size of the receive buffer and is limited automatically to the size of the receive buffer

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

16#0

receiveBuffer

readDataLength

0.0

T#0ms

16#7615

LCOM_WARN_NO_TIME_SYNC

There is no time synchronization active referring to chap. 2.2.6 Time synchronization

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


time of occasion

condition

16#0

0.0

16#8200

LCOM_ERR_COM_SERVICE

The configured communication service value (configuration.connection.comService) is invalid,

see system function TCON Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1

additionalValue2…3:

additionalValue4:

time of occasion

condition

16#0

user value

0.0

T#0ms

16#8201

LCOM_ERR_CONNECTION_ID

The configured connection ID (configuration.connection.connectionID) is invalid, see system function TCON Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1


additionalValue4:

time of occasion

condition

16#0

user value

0.0

T#0ms

16#8202

LCOM_ERR_INTERFACE_ID

The configured local hardware ID (configuration.connection.interfaceID) is invalid, see system function TCON Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1


additionalValue4:

time of occasion

condition

16#0

user value

0.0

T#0ms

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#8203

LCOM_ERR_LOCAL_PORT

The configured local port number (configuration.connection.localPort) is invalid, see system function TCON Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1


additionalValue4:

time of occasion

condition

status of TCON

user value

0.0

T#0ms

16#8204

LCOM_ERR_ PARTNER_IP

The configured partner IP address (configuration.connection.partnerIP) is invalid, see system function TCON Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1


additionalValue4:

time of occasion

condition

status of TCON

user value

0.0

T#0ms

16#8205

LCOM_ERR_ TIME_SYNC_MODE

The configured time synchronization mode (configuration.timeSync.sendMode) is invalid, see chapter 2.2.6 Time synchronization Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1


additionalValue4:

time of occasion

condition

16#0

user value

0.0

T#0ms

16#8206

LCOM_ERR_TIME_CYCLE_TIME

The configured time synchronization cycle time (configuration.timeSync.cycleTime) is invalid, see chapter 2.2.6 Time synchronization Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

user value

16#8207

LCOM_ERR_TIME_OF_DAY

The configured time synchronization value at time of day (configuration.timeSync.sendAtTimeOfDay) is invalid, see

chapter 2.2.6 Time synchronization Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

T#0ms

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#8208

LCOM_ERR_SEND_DATA_TYPE

Input parameter sendBuffer is invalid.

Data type of parameter has to be „ARRAY OF BYTE“ Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

T#0ms

16#8209

LCOM_ERR_RECEIVE_DATA_TYPE

In/Out parameter receiveBuffer is invalid. Data type of parameter has to be „ARRAY OF BYTE“ Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

T#0ms

16#8210

LCOM_ERR_LIFE_SIGN_CYCLE

The configured connection monitoring time (configuration.connection.lifeSignCycleTime) is invalid, see chapter 2.2.1 Establishment of communication

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

user value

16#8211

LCOM_ERR_SEND_CYCLE_TIME

The configured send cycle for cyclic data exchange (configuration.sender.cycleTime) is invalid, see chapter 2.2.3 Sending data Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

user value

16#8212

LCOM_ERR_ACK_TIMEOUT

The configured timeout for acknowledgement telegrams (configuration.sender.ackTimeout) is invalid, see chapter 2.2.3 Sending data

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1..3

additionalValue4:

time of occasion

condition

16#0

0.0

user value

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#8600

LCOM_ERR_OPEN_CLIENT

Error occurred when calling system function TCON, see subFunctionErrorID.

The function block automatically retries to open the connection

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

status of TCON

0.0

0.0

0.0

T#0ms

16#8601

LCOM_ERR_OPEN_SERVER

Error occurred when calling system function TCON, see subFunctionErrorID.

The function block automatically retries to open the connection

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

status of TCON

local Port

0.0

0.0

T#0ms

16#8602

LCOM_ERR_SEND

Error occurred when calling system function TSEND, see subFunctionErrorID.

Connection is reestablished automatically

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

status of TSEND

0.0

length of sendData

0.0

T#0ms

16#8603

LCOM_ERR_RECEIVE

Error occurred when calling system function TRCV, see subFunctionErrorID.

Connection is reestablished automatically

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4:

time of occasion

condition

status of TRCV

0.0

T#0ms

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#8604

LCOM_ERR_CLOSE_CONNECTION

Error occurred when calling system function TDISCON, see subFunctionErrorID.

Connection is re-established automatically

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:


additionalValue4:

time of occasion

condition

status of TDISCON

0.0

T#0ms

16#8610

LCOM__ERR_LIFE_SIGN_EXPIRED

No life sign telegram was received since 4x configured connection monitoring value (configuration.connection.lifeSignCycleTime).


Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

time of occasion

condition

16#0

life sign cycle time

0.0

elapsed time with no message from partner

16#8611

LCOM_ERR_ACK_TIMEOUT_EXPIRED

The monitoring time for a sent data packet has expired but no acknowledgement has been received (configuration.sender.ackTimeout).

Connection is re-established automatically.

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

time of occasion

condition

16#0

monitoring time

0.0

elapsed time with no message from partner

16#8612

LCOM_ERR_ACK_MESSAGE_NUMBER

Unexpected acknowledge message number was received. Connection is re-established automatically

Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

16#0

received acknowledge

message number

send acknowledge message number

0.0

T#0ms

LCom_Communication


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

16#8613

LCOM_ERR_WRONG_LCOM_HEADER

Wrong LCom protocol version received or version does not match partner LCom version.


Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:

additionalValue2:

additionalValue3:

additionalValue4:

time of occasion

condition

16#0

received version

local, active version

0.0

T#0ms

16#8614

LCOM_ERR_WRONG_TELEGRAM_ID

Unexpected telegram identifier received.


Diagnostic entry:

timestamp:

isActive:

subFunctionErrorID:

additionalValue1:


additionalValue4:

time of occasion

condition

16#0

received ID

0.0

T#0ms



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

2.4 PLC data types

Table 2-11: typeLCom_Config


connection Struct

interfaceID HW_ANY Hardware identifier of the local interface, see PLC tags->Default tag table->System constants

(default: 64)

connectionID CONN_ANY Unique connection identifier

16#0001 .. 16#0FFF

(default: 16#0FFF)

comService USInt Configuration of the communication protocol

1: LCOM_TCP_CONNECTION Native (open user) TCP protocol is used

2:LCOM_LCOM_CONNECTION (default) LCom protocol with additional functionality is used


FALSE: TCP-server (default) Passive connection establishment

localPort UInt Local port number, see system function TCON

(default: 3456)

partnerPort UInt Only valid by active connection establishment (configuration.connection.isClient = TRUE)

Partner port number, see system function TCON. (default: 3456)

partnerIP IP_V4 Only valid by active connection establishment (configuration.connection.isClient = TRUE)

Partner IP address xxx.xxx.xxx.xxx = [1].[2].[3].[4]

Only valid by passive connection establishment (configuration.connection.isClient = FALSE) and just specified partner is allowed

(configuration.connection.acceptUnknownPartner = FALSE)

Partner IP address which is allowed.

acceptUnknownPartner Bool Only valid by passive connection establishment (configuration.connection.isClient = FALSE)

TRUE: accept requests from all partners (default)

FALSE: only specified partner is allowed

lifeSignCycleTime Time Only valid with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION)

T#1ms .. T#24d20h31m23s647ms

(default: T#1s)

sender Struct Sender configuration

cycleTime Time Time interval used for cyclic communication



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d


T#0ms...T#24d20h31m23s647ms

(default: T#1s)

ackTimeout Time Only valid with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION)

Timeout in case of missing confirmation, only valid with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION); connection will be closed and reestablished after timeout

T#1ms .. T#24d20h31m23s647ms

(default: T#1s)

timeSync struct Time synchronization configuration; only possible with LCom protocol (configuration.connection.comService = LCOM_LCOM_CONNECTION)


FALSE: do not use received timestamps (default)


0: LCOM_NO_TIME_SYNC (default) time synchronization inactive

1: LCOM_CYCLE_TIME_SYNC cyclic time synchronization see configuration.timeSync.cycleTime

2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day see configuraton.timeSync.sendAtTimeOfDay

cycleTime Time Only valid by sendMode

1, LCOM_CYCLE_TIME_SYNC:

Time interval for cyclic sending of timestamps in case of cyclic time synchronization mode

T#1ms .. T#24d20h31m23s647ms

(default: T#1h)

sendAtTimeOfDay Time_Of_Day Only valid by sendMode

2, LCOM_TIME_OF_DAY_TIME_SYNC:

Time of day at which a timestamp is sent in case of time synchronization at time of day mode

(default: TOD#05:00:00.000)



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Table 2-12: typeLCom_Diagnostics


localConfig Struct

connection Struct

interfaceID HW_ANY Hardware identifier of the local interface

connectionID CONN_ANY Connection identifier

comService USInt Used communication protocol

1: Native (open user) TCP protocol

2: LCom protocol with additional functionality


FALSE: TCP-server Passive connection establishment

localPort UInt Local port number

localIP IP_V4 Local IP address

partnerPort UInt Partner port number

partnerIP IP_V4 Partner IP address

acceptUnknownPartner Bool TRUE: requests from all partners are accepted

FALSE: only the specified partner is allowed

useLComProtocol Bool TRUE: LCom header is used at data transfer

FALSE: data is exchanged in native (open user) format

lifeSignCycleTime Time Local life sign cycle time only valid with LCom protocol

sender Struct

cycleTime Time Local send cycle

ackTimeout Time Local acknowledge timeout only valid with LCom protocol

timeSync Struct


FALSE: do not use received timestamps


0: LCOM_NO_TIME_SYNC time synchronization inactive

1: LCOM_CYCLE_TIME_SYNC cyclic time synchronization

2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day

cycleTime Time Time interval for cyclic sending of timestamps

sendAtTimeOfDay Time_Of_Day Time of day at which a timestamp is sent

sizeOfSendBuffer UDInt Size of user send buffer in bytes

sizeOfReceiveBuffer UDInt Size of user receive buffer in bytes

partnerConfig Struct Active/actual partner configuration only valid with LCom protocol

connnection Struct

lifeSignCycleTime Time Partner life sign cycle time

sender Struct Partner sender configuration

cycleTime Time Partner send cycle



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d


ackTimeout Time Partner acknowledge timeout

timeSync Struct

usePartnerTimestamps Bool TRUE: partner synchronizes local time with received timestamps

FALSE: partner does not use received timestamps

sendMode USInt Partner time synchronization send mode

0: LCOM_NO_TIME_SYNC time synchronization inactive

1: LCOM_CYCLE_TIME_SYNC cyclic time synchronization

2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day

sizeOfSendBuffer UDInt Size of partner send buffer in bytes

sizeOfReceiveBuffer UDInt Size of partner receive buffer in bytes

statistics Struct

avgCallCycle Real Average cycle time of FB calls (ms)

avgReceiveMsgCycle Real Average cycle time of received user messages (ms)

maxReceiveMsgCycle Time Maximum cycle time of received user messages

LComProtocolUsed Bool TRUE: LCom header is used at data transfer

FALSE: data is exchanged in native (open user) format

activeLComVersion USInt Active LCom version only valid with LCom protocol

avgMsgSendingTime Real Average user messages sending time (ms); average time while FB output sending is TRUE

maxMsgSendingTime Time Maximum user messages sending time (ms); maximum time while FB output sending is TRUE

avgMsgReceivingTime Real Average user messages receiving time (ms); average duration between start of a user message and FB output dataReceived becomes TRUE

maxMsgReceivingTime Time Maximum user messages receiving time (ms); maximum duration between start of a message and FB output dataReceived becomes TRUE

numberOfSentMessages UDInt Number of sent user messages since FB enable

numberOfReceivedMessages UDInt Number of received user messages since FB enable

totalAckTimeouts UInt Accumulated number of confirmation times greater than diagnostics.localConfig.sender.ackTimeout

totalSendCycleViolations UInt Accumulated number of send cycle times greater than diagnostics.localConfig.sender.cycleTime

totalReceiveCycleViolations UInt Accumulated number of receive cycles greater than diagnostics.partnerConfig.sender.cycleTime

totalReconnects UInt Accumulated number of TCP reconnects

lastConnect DTL Timestamp of last connection establishment

lastTimeSync DTL Timestamp of last time synchronization

bufferIndex USInt Ring buffer index of last diagnostic entry, 16#FF: initialization value

buffer Array[0..63] of Diagnostics buffer



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d


Struct

status Word FB status at occurrence of diagnostic entry

timestamp DTL Timestamp at occurrence of diagnostic entry

isActive Bool TRUE: diagnostic entry is active/valid

FALSE: diagnostic entry is inactive/invalid

subFunctionErrorID Word Return value of a subsequent function




additionalValue4 Time Additional information 4



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

The table "LCom user constants" shows an overview of all the constants of the block library LCOM.

Table 2-13: LCom user constants

Name Typ Value Comment

LCOM_NO_TIME_SYNC USInt 0 see chapter 2.2.6

LCOM_TCP_CONNECTION USInt 1 see chapter 2.2.1

LCOM_CYCLE_TIME_SYNC USInt 1 see chapter 2.2.6

LCOM_LCOM_CONNECTION USInt 2 see chapter 2.2.1

LCOM_TIME_OF_DAY_TIME_SYNC USInt 2 see chapter 2.2.6

LCOM_STATUS_NO_CALL Word 16#7000 see chapter 2.3.1

LCOM_STATUS_FIRST_CALL Word 16#7001 see chapter 2.3.1

LCOM_STATUS_INTERMEDIATE_CALL Word 16#7002 see chapter 2.3.1

LCOM_STATUS_CLIENT_TRY_CONNECT Word 16#7003 see chapter 2.3.1

LCOM_STATUS_SERVER_PORT_OPEN Word 16#7004 see chapter 2.3.1

LCOM_STATUS_TCP_CONNECTED Word 16#7005 see chapter 2.3.1

LCOM_STATUS_LCOM_CONNECTED_V1 Word 16#7006 see chapter 2.3.1

LCOM_STATUS_LCOM_CONNECTED_V2 Word 16#7007 see chapter 2.3.1

LCOM_STATUS_DISCONNECTING Word 16#7008 see chapter 2.3.1

LCOM_WARN_SEND_DATA_LENGTH Word 16#7600 see chapter 2.3.1

LCOM_WARN_LIFE_SIGN_LIMITATION Word 16#7610 see chapter 2.3.1

LCOM_WARN_SEND_CYCLE_LIMITATION Word 16#7611 see chapter 2.3.1

LCOM_WARN_ACK_TIMEOUT_LIMITATION Word 16#7612 see chapter 2.3.1

LCOM_WARN_SEND_CYCLE_EXPIRED Word 16#7613 see chapter 2.3.1

LCOM_WARN_RECEIVE_BUFFER_LEN Word 16#7614 see chapter 2.3.1

LCOM_WARN_NO_TIME_SYNC Word 16#7615 see chapter 2.3.1

LCOM_ERR_COM_SERVICE Word 16#8200 see chapter 2.3.1

LCOM_ERR_CONNECTION_ID Word 16#8201 see chapter 2.3.1

LCOM_ERR_INTERFACE_ID Word 16#8202 see chapter 2.3.1

LCOM_ERR_LOCAL_PORT Word 16#8203 see chapter 2.3.1

LCOM_ERR_PARTNER_IP Word 16#8204 see chapter 2.3.1

LCOM_ERR_TIME_SYNC_MODE Word 16#8205 see chapter 2.3.1

LCOM_ERR_TIME_CYCLE_TIME Word 16#8206 see chapter 2.3.1

LCOM_ERR_TIME_OF_DAY Word 16#8207 see chapter 2.3.1

LCOM_ERR_SEND_DATA_TYPE Word 16#8208 see chapter 2.3.1

LCOM_ERR_RECEIVE_DATA_TYPE Word 16#8209 see chapter 2.3.1

LCOM_ERR_LIFE_SIGN_CYCLE Word 16#8210 see chapter 2.3.1

LCOM_ERR_SEND_CYCLE_TIME Word 16#8211 see chapter 2.3.1

LCOM_ERR_ACK_TIMEOUT Word 16#8212 see chapter 2.3.1

LCOM_ERR_OPEN_CLIENT Word 16#8600 see chapter 2.3.1

LCOM_ERR_OPEN_SERVER Word 16#8601 see chapter 2.3.1

LCOM_ERR_SEND Word 16#8602 see chapter 2.3.1

LCOM_ERR_RECEIVE Word 16#8603 see chapter 2.3.1

LCOM_ERR_CLOSE_CONNECTION Word 16#8604 see chapter 2.3.1



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

Name Typ Value Comment

LCOM_ERR_LIFE_SIGN_EXPIRED Word 16#8610 see chapter 2.3.1

LCOM_ERR_ACK_TIMEOUT_EXPIRED Word 16#8611 see chapter 2.3.1

LCOM_ERR_ACK_MESSAGE_NUMBER Word 16#8612 see chapter 2.3.1

LCOM_ERR_WRONG_LCOM_HEADER Word 16#8613 see chapter 2.3.1

LCOM_ERR_WRONG_TELEGRAM_ID Word 16#8614 see chapter 2.3.1

3 Working with the Library


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d



This chapter consists of instructions for integrating the LCom library into your STEP 7 project and instructions for using the library blocks.

3.1 Integrating the library into STEP 7

The table below lists the steps for integrating the LCom library into your STEP 7 project. Subsequently, you can use the blocks of the LCom library.

Table 3-1: Integrating the library into STEP 7

No. Action

1. Extract the library LCom_V2_x_x.zip to a local folder.

2. In TIA Portal select “Options” -> “Global libraries” -> “Open library…”

3. Browse to the file LCom.al13. It can be found in the subfolder LCom of the extracted zip file.

4. Open the global library in read-only mode.

5. The LCom library is now available in the task card “Global libraries”

Figure 3-1: LCom integration in STEP7



S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

3.2 Integrating the library blocks into STEP 7

The table below lists the steps for integrating the blocks of the LCom library into your STEP 7 program.

Figure 3-2: LCom_Communication integration in STEP7

Table 3-2: Integrating the library blocks into STEP 7

No. Action

1. Copy the LCom_Communication FB with Drag & Drop into the folder “Program blocks” in the PLC.

2. Copy LCom_Constants with Drag & Drop into the folder “PLC tags” in the PLC.

3. Copy typeLCom_Config und typeLComDiagnostics with Drag & Drop into the folder “PLC data types” in the PLC.

4. Now the block can be configured and called in the user program.

4 Notes and Support


S

iem

en

s A

G 2

01

6 A

ll ri

gh

ts r

ese

rve

d

4 Notes and Support


This chapter provides further support in handling the described LCOM library.

5 Related literature

Table 5-1 Related literature

Topic

\1\ Siemens Industry Online Support

http://support.automation.siemens.com

\2\ Download page of this entry


6 Contact

Siemens AG Digital Factory Division Factory Automation Production Machines DF FA PMA APC Frauenauracher Str. 80 91056 Erlangen, Germany

mailto: [email protected]

7 History

Table 7-1 History

Version Date Modifications

V2.0 06/2015 First version (german)

V2.1 09/2015 Software changes (german) (lifesign tolerance has been increased to a factor of 4, functional enhancement of variable connection.comService)

01/2016 First version (english)

V2.2 10/2016 Correct typing error (LCOM_WARN_RECEIVE_BUFFER_LEN)

http://support.automation.siemens.com/


mailto:[email protected]

Documents

Library description 10/2016 Communication Library LCom for ......Warranty and liability Communication Library LCom Entry-ID: 48955385, V2.2, 10/2016 2 G 6 d Warranty and liability