communication simotion - cache.industry.siemens.com · communication, this is typically in the...

Communication Library LCom for SIMOTION

SIMOTION

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

Siemens Industry Online Support

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

Warranty and liability

Communication Library LCom Entry-ID: 48955385, V2.0, 04/2017 2

S

iem

en

s A

G 2

01

7 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, systems, machines and networks. In order to protect plants, systems, machines and networks against cyber threats, it is necessary to implement – and continuously maintain – a holistic, state-of-the-art industrial security concept. Siemens’ products and solutions only form one element of such a concept. Customer is responsible to prevent unauthorized access to its plants, systems, machines and networks. Systems, machines and components should only be connected to the enterprise network or the internet if and to the extent necessary and with appropriate security measures (e.g. use of firewalls and network segmentation) in place. Additionally, Siemens’ guidance on appropriate security measures should be taken into account. For more information about industrial security, please visit http://www.siemens.com/industrialsecurity.

Siemens’ products and solutions undergo continuous development to make them more secure. Siemens strongly recommends to apply product updates as soon as available and to always use the latest product versions. Use of product versions that are no longer supported, and failure to apply latest updates may increase customer’s exposure to cyber threats. To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed under http://www.siemens.com/industrialsecurity.

http://www.siemens.com/industrialsecurity



Table of contents


S

iem

en

s A

G 2

01

7 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

2 FBLCom_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 .................................................................................. 23 2.2.5 Sign of life ......................................................................................... 29 2.2.6 Time synchronization ...................................................................... 30 2.3 Error and diagnostic ........................................................................ 32 2.3.1 Status message ................................................................................ 34 2.4 Structures and constants ................................................................ 44

3 Working with the Library................................................................................. 51

3.1 Library structure ............................................................................... 51 3.2 Integrating the library into SCOUT ................................................. 52

4 Notes and Support ........................................................................................... 53

5 Related literature ............................................................................................. 54

6 Contact.............................................................................................................. 54

7 History............................................................................................................... 54

1 Library Overview


S

iem

en

s A

G 2

01

7 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. tcpOpenClient/ tcpOpenServer, tcpSend, tcpReceive, tcpCloseConnection) 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

SIMOTION SCOUT as from V4.4

SCOUT TIA as from V4.4

SIMOTION D4x5-2

SIMOTION D410

SIMOTION C230, C240

SIMOTION P320, 350

1 Library Overview


S

iem

en

s A

G 2

01

7 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

1 Library Overview


S

iem

en

s A

G 2

01

7 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

1 Library Overview


S

iem

en

s A

G 2

01

7 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

Application

LCom_Communication

IDB

Ethernet

Interface

CPU

IDB

S7-1500 CPU

Switch

1 Library Overview


S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

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



1 Library Overview


S

iem

en

s A

G 2

01

7 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-Version

1. SIMOTION D4x5-2 Firmware-Version as from V4.4

2. SIMOTION D410

3. SIMOTION C230, C240

4. SIMOTION P320, P350

Software

Table 1-2: Software components

No. Component Article number Quantity

5. SIMOTION SCOUT - 1

6. SCOUT TIA - 1

2 FBLCom_Communication


S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d


What will you find in this section?

This chapter explains the parameter and functionality of the function block FBLCom_Communication.

Figure 2-1: Block diagram of FBLCom_Communication

FBLCom_Communication

Bool

enable connected

Bool

Bool

send sending

Bool

UDInt

sendDataLength dataReceived

Bool

UDInt

readDataLength receivedDataLength

UDInt

sLCOM_ConfigType

configurations busy

Bool

error

Bool

status

Word

Array of Byte sendBuffer

Array of Byte

Array of Byte receiveBuffer

Array of Byte

sLCOM_DiagnosticsType diagnostics

sLCOM_DiagnosticsType



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

2.1 Parameter

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

Input parameters

Table 2-1: FBLCom_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 (configurations.sConnection.u8ComService = 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 (configurations.sConnection.u8ComService = 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.

configurations Struct FB configuration



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Output parameters

Table 2-2: FBLCom_Communication output parameters


connected Bool Without LCom protocol (configurations.sConnection.u8ComService = LCOM_TCP_CONNECTION):

TRUE: TCP connection to partner is established.

FALSE: TCP connection to partner is not established.

With LCom protocol (configurations.sConnection.u8ComService = 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 chapter 2.3 Error and diagnostic

In-Out parameters

Table 2-3: FBLCom_Communication in-out parameters


sendBuffer Array of Byte Pointer to send data

receiveBuffer Array of Byte Pointer to receive data

diagnostics Struct 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



S

iem

en

s A

G 2

01

7 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 sConnectionType.

Table 2-4: Connection parameter

Parameter Type Description

sConnectionType Struct

u8ComService 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

boIsClient Bool TRUE: TCP client Active connection establishment

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

u16LocalPort UInt Local port number, see system function TCON

(default: 3456)

u16PartnerPort UInt Only valid with active connection establishment (configurations.sConnection.boIsClient = TRUE)

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

au8PartnerIP Array of USint

Only valid with active connection establishment (configurations.sConnection.boIsClient = TRUE)

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

Only valid with passive connection establishment (configurations.sConnection.boIsClient =

FALSE) and just specified partner is allowed

(configurations.sConnection.boAcceptUnknownPartner = FALSE)

Partner IP address which is allowed.



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

boAcceptUnknownPartner Bool Only valid with passive connection establishment (configurations.sConnection.boIsClient = FALSE)

TRUE: accept requests from all partners (default)

FALSE: only specified partner is allowed

tLifeSignCycleTime Time Only valid with LCom protocol (configurations.sConnection.u8ComService = 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.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

2.2.3 Sending data

Depending on the parameterized values in configurations.sSender structure (see data struct sConnectionType) 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-5: Parameters for sending


sSenderType Struct

tCycleTime Time Time interval used for cyclic communication

T#0ms...T#24d20h31m23s647ms

(default: T#1s)

tAckTimeout Time Only valid with LCom protocol (configurations.sConnection.u8ComService = LCOM_LCOM_CONNECTION)

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

T#1ms .. T#24d20h31m23s647ms

(default: T#1s)

Figure 2-7: Sender parameters example



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

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”. For this purpose, the data must be marshalled.

Marshalling describes the conversion of elementary data types or structures to a uniform format. The user must convert the data accordingly before transferring it to the function block.

To do this, you can use the SIMOTION system functions ANYTYPE_TO_BIGBYTEARRAY and ANYTYPE_TO_LITTLEBYTEARRAY to convert data to a byte array with the Big Endian or Little Endian orientation. This is necessary for the data to be sent.

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

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.



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d



Figure 2-8: Single data transmission (configurations.sSender.tCycleTime = 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.

Figure 2-9 Single data transmission (configurations.sSender.tCycleTime = T#1s)

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


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

connected

1)

0

1

2)

enable

1

0

busy

1

0

send

1

0

sending

1

0

0 1 2 t in s

connected

1)

0

1

2)

enable

1

0

busy

1

0

send

1

0

sending

1

0

0 1 2 t in s

3)



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Cyclic data transmission

Figure 2-10: Cyclic data transmission (configurations.sSender.tCycleTime = 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)

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


3. User data is sent every cycle time.



S

iem

en

s A

G 2

01

7 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 to the desired data via the SIMOTION system functions BIGBYTEARRAY_TO_ANYTYPE for orientation according to Big Endian and LITTLEBYTEARRAY_TO_ANYTYPE for orientation according to Little Endian.

NOTE It is recommended that the data be transferred in Big Endian format, since SIMATIC controllers operate with this orientation. By default, the data orientation of the additional data of the LCom protocol is configured as Big Endian.

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



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Without LCom protocol = native (open user) TCP protocol (configurations.sConnection.u8ComService = 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.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 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).

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

2636).


2920).


1176).



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

With LCom protocol

(configurations.sConnection.u8ComService = 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.



S

iem

en

s A

G 2

01

7 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 (configurations.sSender.tLifeSignCycleTime). 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.



S

iem

en

s A

G 2

01

7 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:

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 data struct sTimeSyncType.

Table 2-6: Parameter for time synchronization


sTimeSyncType Struct

boUsePartnerTimestamps Bool TRUE: synchronize local time with received timestamps

FALSE: do not use received timestamps (default)

u8SendMode USInt Time synchronization send mode

0: LCOM_NO_TIME_SYNC (default) time synchronization inactive

1: LCOM_CYCLE_TIME_SYNC cyclic time synchronization

2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day see

tCycleTime 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)

todSendAtTimeOfDay 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

7 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 boUsePartnerTimestamps set to TRUE, then no time synchronization will be executed and a warning is shown, see status LCOM_WARN_NO_TIME_SYNC.



S

iem

en

s A

G 2

01

7 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.



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

The output parameter diagnostics contains different substructures defined by the struct sLCOM_DiagnosticsType. The diagnostic buffer will be explained below. Please refer to section 2.4Fehler! Verweisquelle konnte nicht gefunden werden. Structures and constants 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 u8bufferIndex 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-7: Structure of diagnostics buffer

Parameter Data type Comment

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

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

b16Status Word FB status at occurrence of diagnostic entry

dtTimestamp DT Timestamp at occurrence of diagnostic entry

boIsActive Bool TRUE: diagnostic entry is active/valid

FALSE: diagnostic entry is inactive/invalid

i32SubFunctionErrorID DInt Return value of a system function

r32AdditionalValue1 Real Additional information 1



tAdditionalValue4 Time Additional information 4

Figure 2-20: Diagnostics buffer in the application



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

2.3.1 Status message

Following number ranges are defined for status-, warning- and error messages.

Table 2-8: 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.



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Table 2-9: Status messages

16#7000

LCOM_STATUS_NO_CALL

FB is not processing, default value of status variable

Diagnosis entry:

dtTimestamp:

boIsActive:

i32SubFunctionErrorID:

r32AdditionalValue1..3:

tAdditionalValue4

time of occasion

condition

0

0.0

T#0ms

16#7001

LCOM_STATUS_FIRST_CALL

First FB call after rising edge at input enable

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

0

0.0

T#0ms

16#7002

LCOM_STATUS_INTERMEDIATE_CALL

Interim call of FB

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

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:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

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:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

0

0.0

T#0ms

16#7005

LCOM_STATUS_TCP_CONNECTED

TCP (open user) connection to partner is established

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

0

0.0

T#0ms



S

iem

en

s A

G 2

01

7 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:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

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:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

0

0.0

T#0ms

16#7008

LCOM_STATUS_DISCONNECTING

Connection is being closed

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4

time of occasion

condition

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:

dtTimestamp:

boIsActive:


r32AdditionalValue1:



tAdditionalValue4

time of occasion

condition

0

sendDataLength

sendBuffer

0.0

T#0ms

16#7610

LCOM_WARN_LIFE_SIGN_LIMITATION

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

Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4

time of occasion

condition

0

user value

0.0

T#0ms



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

16#7611

LCOM_WARN_SEND_CYCLE_LIMITATION

The configured cycle time for cyclic data exchange (configurations.sSender.tCycleTime) is too big and is limited automatically to 65535 ms

Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4

time of occasion

condition

0

limited to 65535

0.0

user value

16#7612

LCOM_WARN_ACK_TIMEOUT_LIMITATION

The configured timeout for acknowledging telegrams (configurations.sSender.tAckTimeout) is too big and is limited automatically to 65535 ms

Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4

time of occasion

condition

0

limited to 65535

0.0

user value

16#7613

LCOM_WARN_SEND_CYCLE_EXPIRED

The configured send cycle for cyclic data exchange (configurations.sSender.tCycleTime) cannot be maintained because a previous transmission has not yet been completed

Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4

time of occasion

condition

0

user value

0.0

hitherto time of previous send task

16#7614

LCOM_WARN_RECEIVE_BUFFER_LEN

With LCom protocol: (configurations.sConnection.u8ComService = 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:

dtTimestamp:

boIsActive:





tAdditionalValue4

time of occasion

condition

0

sendDataLength

receiveBuffer of partner

0.0

hitherto time of previous send task

Without LCom protocol: (configurations.sConnection.u8ComService = LCOM_TCP_CONNECTION):



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Input parameter readDataLength is greater than the size

of the receive buffer and is limited automatically to the size of the receive buffer

Diagnostic entry:

dtTimestamp:

boIsActive:





tAdditionalValue4

time of occasion

condition

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:

dtTimestamp:

boIsActive:



time of occasion

condition

0

0.0

16#8200

LCOM_ERR_COM_SERVICE

The configured communication service value (configurations.sConnection.u8ComService) is invalid, see system function tcpOpenClient/tcpOpenServer. Diagnostic entry:

dtTimestamp:

boIsActive:


r32AdditionalValue1

r32AdditionalValue2…3:

tAdditionalValue4:

time of occasion

condition

0

user value

0.0

T#0ms

16#8201

LCOM_ERR_CONNECTION_ID

The configured connection ID is invalid.

Diagnostic entry:

dtTimestamp:

boIsActive:


r32AdditionalValue1


tAdditionalValue4:

time of occasion

condition

0

user value

0.0

T#0ms

16#8202

LCOM_ERR_INTERFACE_ID

The configured local hardware ID is invalid. Diagnostic entry:

dtTimestamp:

boIsActive:


r32AdditionalValue1


tAdditionalValue4:

time of occasion

condition

0

user value

0.0

T#0ms

16#8203

LCOM_ERR_LOCAL_PORT

The configured local port number (configurations.sConnection.au8LocalPort) is invalid,

see system function tcpOpenClient/tcpOpenServer. Diagnostic entry:

dtTimestamp:

boIsActive:


time of occasion

condition

status of



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

r32AdditionalValue1


tAdditionalValue4:

tcpOpenClient/tcpOpenServer

user value

0.0

T#0ms

16#8204

LCOM_ERR_ PARTNER_IP

The configured partner IP address (configurations.sConnection.u16PartnerIP) is invalid, see system function tcpOpenClient. Diagnostic entry:

dtTimestamp:

boIsActive:


r32AdditionalValue1


tAdditionalValue4:

time of occasion

condition

status of tcpOpenClient

user value

0.0

T#0ms

16#8205

LCOM_ERR_ TIME_SYNC_MODE

The configured time synchronization mode (configurations.sTimeSync.u8SendMode) is invalid, see chapter 2.2.6 Time synchronization Diagnostics entry:

dtTimestamp:

boIsActive:


r32AdditionalValue1


tAdditionalValue4:

time of occasion

condition

0

user value

0.0

T#0ms

16#8206

LCOM_ERR_TIME_CYCLE_TIME

The configured time synchronization cycle time (configurations.sTimeSync.tCycleTime) is invalid, see chapter 2.2.6 Time synchronization Diagnostics entry:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

0

0.0

user value

16#8207

LCOM_ERR_TIME_OF_DAY

The configured time synchronization value at time of day (configurations.sTimeSync.todSendAtTimeOfDay) is

invalid, see chapter 2.2.6 Time synchronization Diagnostic entry:

dtTimestamp:

boIsActive:


r32AdditionalValue1..3

tAdditionalValue4:

time of occasion

condition

0

0.0

T#0ms



S

iem

en

s A

G 2

01

7 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:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

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:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

0

0.0

T#0ms

16#8210

LCOM_ERR_LIFE_SIGN_CYCLE

The configured connection monitoring time (configurations.sConnection.tLifeSignCycleTime) is invalid, see chapter 2.2.1 Establishment of communication

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

0

0.0

user value

16#8211

LCOM_ERR_SEND_CYCLE_TIME

The configured send cycle for cyclic data exchange (configurations.sSender.tCycleTime) is invalid, see

chapter 2.2.3 Sending data Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

0

0.0

user value

16#8212

LCOM_ERR_ACK_TIMEOUT

The configured timeout for acknowledgement telegrams (configurations.sSender.tAckTimeout) is invalid, see chapter 2.2.3 Sending data

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

0

0.0

user value



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

16#8600

LCOM_ERR_OPEN_CLIENT

Error occurred when calling system function tcpOpenClient, see subFunctionErrorID.

The function block automatically retries to open the connection

Diagnostic entry:

dtTimestamp:

boIsActive:





tAdditionalValue4:

time of occasion

condition

status of tcpOpenClient

0.0

0.0

0.0

T#0ms

16#8601

LCOM_ERR_OPEN_SERVER

Error occurred when calling system function tcpOpenServer, see subFunctionErrorID.

The function block automatically retries to open the connection

Diagnostic entry:

dtTimestamp:

boIsActive:





tAdditionalValue4:

time of occasion

condition

status of tcpOpenServer

local port

0.0

0.0

T#0ms

16#8602

LCOM_ERR_SEND

Error occurred when calling system function tcpSend, see subFunctionErrorID.

Connection is reestablished automatically

Diagnostic entry:

dtTimestamp:

boIsActive:





tAdditionalValue4:

time of occasion

condition

status of tcpSend

0.0

sendDataLength

0.0

T#0ms

16#8603

LCOM_ERR_RECEIVE

Error occurred when calling system function tcpReceive, see subFunctionErrorID.

Connection is reestablished automatically

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

status of tcpReceive

0.0

T#0ms



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

16#8604

LCOM_ERR_CLOSE_CONNECTION

Error occurred when calling system function tcpCloseConnection, see subFunctionErrorID.

Connection is re-established automatically

Diagnostic entry:

dtTimestamp:

boIsActive:



tAdditionalValue4:

time of occasion

condition

status of tcpCloseConnection

0.0

T#0ms

16#8610

LCOM__ERR_LIFE_SIGN_EXPIRED

No life sign telegram was received since 4x configured connection monitoring value (configurations.sConnection.tLifeSignCycleTime).


Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4:

time of occasion

condition

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 (configurations.sSender.tAckTimeout).

Connection is re-established automatically.

Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4:

time of occasion

condition

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:

dtTimestamp:

boIsActive:





tAdditionalValue4:

time of occasion

condition

0

received acknowledge

message number

send acknowledge message number

0.0

T#0ms



S

iem

en

s A

G 2

01

7 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:

dtTimestamp:

boIsActive:





tAdditionalValue4:

time of occasion

condition

0

received version

local, active version

0.0

T#0ms

16#8614

LCOM_ERR_WRONG_TELEGRAM_ID

Unexpected telegram identifier received.


Diagnostic entry:

dtTimestamp:

boIsActive:




tAdditionalValue4:

time of occasion

condition

0

received ID

0.0

T#0ms



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

2.4 Structures and constants

Table 2-10: typeLCom_Config

Parameter Data type Default value

Description

sConnection Struct

u8ComService USInt 2 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

boIsClient Bool FALSE TRUE: TCP client Active connection establishment

FALSE: TCP-server (default) Passive connection establishment

u16LocalPort UInt 3456 Local port number, see system function tcpOpenClient/tcpOpenServer

u16PartnerPort UInt 3456 Only valid by active connection establishment (configurations.sConnection.boIsClient = TRUE)

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

au8PartnerIP Array of USint - Only valid by active connection establishment (configurations.sConnection.boIsClient = TRUE)

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

boAcceptUnknownPartner Bool TRUE Only valid by passive connection establishment (configurations.sConnection.boIsClient = FALSE) and just specified partner is allowed

(configurations.sConnection.boAcceptUnknownPartner = FALSE)

Partner IP address which is allowed.

tLifeSignCycleTime Time T#1s Only valid by passive connection establishment (configurations.sConnection.boIsClient = FALSE)

TRUE: accept requests from all partners (default)

FALSE: only specified partner is allowed



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Parameter Data type Default value

Description

sSender Struct Sender configuration

tCycleTime Time T#1s Time interval used for cyclic communication

T#0ms...T#24d20h31m23s647ms

(default: T#1s)

tAckTimeout Time T#1s Only valid with LCom protocol (configurations.sConnection.u8ComService = LCOM_LCOM_CONNECTION)

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

T#1ms .. T#24d20h31m23s647ms

(default: T#1s)

sTimeSync struct Time synchronization configuration; only possible with LCom protocol (configurations.sConnection.u8ComService = LCOM_LCOM_CONNECTION)

boUsePartnerTimestamps Bool FALSE TRUE: synchronize local time with received timestamps

FALSE: do not use received timestamps (default)

u8SendMode USInt 0 Time synchronization send mode

0: LCOM_NO_TIME_SYNC (default) time synchronization inactive

1: LCOM_CYCLE_TIME_SYNC cyclic time synchronization see configurations.sTimeSync.tCycleTime

2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day see

tCycleTime Time T#1h 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)

todSendAtTimeOfDay Time_Of_Day TOD#05:00:0.000

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

7 A

ll ri

gh

ts r

ese

rve

d

Table 2-11: Structure sLCOM_DiagnosticsType

Name Type Description

sLocalConfig Struct

sConnection Struct

u8ComService USInt Used communication protocol

1: Native (open user) TCP protocol

2: LCom protocol with additional functionality

boIsClient Bool TRUE: TCP client Active connection establishment

FALSE: TCP-server Passive connection establishment

u16LocalPort UInt Local port number

u16PartnerPort UInt Partner port number

au8PartnerIP Array of USint

Partner IP address

boAcceptUnknownPartner Bool TRUE: requests from all partners are accepted

FALSE: only the specified partner is allowed

boUseLComProtocol Bool TRUE: LCom header is used at data transfer

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

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

sSender Struct

tCycleTime Time Local send cycle

tAckTimeout Time Local acknowledge timeout only valid with LCom protocol

sTimeSync Struct

boUsePartnerTimestamps Bool TRUE: synchronize local time with received timestamps

FALSE: do not use received timestamps

u8SendMode USInt Time synchronization send mode

0: LCOM_NO_TIME_SYNC time synchronization inactive


2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day

tCycleTime Time Time interval for cyclic sending of timestamps

todSendAtTimeOfDay Time_Of_Day

Time of day at which a timestamp is sent

u32SizeOfSendBuffer UDInt Size of user send buffer in bytes

u32SizeOfReceiveBuffer UDInt Size of user receive buffer in bytes

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

sConnnection Struct

tLifeSignCycleTime Time Partner life sign cycle time

sSender Struct Partner sender configuration

tCycleTime Time Partner send cycle



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d


tAckTimeout Time Partner acknowledge timeout

sTimeSync Struct

boUsePartnerTimestamps Bool TRUE: partner synchronizes local time with received timestamps

FALSE: partner does not use received timestamps

u8SendMode USInt Partner time synchronization send mode

0: LCOM_NO_TIME_SYNC time synchronization inactive


2: LCOM_TIME_OF_DAY_TIME_SYNC time synchronization at time of day

u32SizeOfSendBuffer UDInt Size of partner send buffer in bytes

u32SizeOfReceiveBuffer UDInt Size of partner receive buffer in bytes

sStatistics Struct

r32AvgCallCycle Real Average cycle time of FB calls (ms)

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

tMaxReceiveMsgCycle Time Maximum cycle time of received user messages

boLComProtocolUsed Bool TRUE: LCom header is used at data transfer

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

u8ActiveLComVersion USInt Active LCom version only valid with LCom protocol

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

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

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

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

u32NumberOfSentMessages UDInt Number of sent user messages since FB enable

u32NumberOfReceivedMessages

UDInt Number of received user messages since FB enable

u16TotalAckTimeouts UInt Accumulated number of confirmation times greater than sLCOM_DiagnosticsType.sLocalConfig.sSender.tAckTimeout

u16TotalSendCycleViolations UInt Accumulated number of send cycle times greater than sLCOM_DiagnosticsType.sLocalConfig.sSender.tCycleTime

u16TotalReceiveCycleViolations UInt Accumulated number of receive cycles greater than sLCOM_DiagnosticsType.sPartnerConfig.sSen



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d


der.tCycleTime

u16TotalReconnects UInt Accumulated number of TCP reconnects

dtLastConnect DT Timestamp of last connection establishment

dtLastTimeSync DT Timestamp of last time synchronization

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

asBuffer Array[0..63] of Struct

Diagnostics buffer

b16Status Word FB status at occurrence of diagnostic entry

dtTimestamp DT Timestamp at occurrence of diagnostic entry

boIsActive Bool TRUE: diagnostic entry is active/valid

FALSE: diagnostic entry is inactive/invalid

i32SubFunctionErrorID DInt Return value of a subsequent function




tAdditionalValue4 Time Additional information 4



S

iem

en

s A

G 2

01

7 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-12: LCom user constants

Name Type 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

LCOM_ERR_LIFE_SIGN_EXPIRED Word 16#8610 See chapter 2.3.1



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

Name Type Value Comment

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

7 A

ll ri

gh

ts r

ese

rve

d


What will you find in this section?

This chapter consists of instructions for integrating the LCom library into your SIMOTION SCOUT-project.

3.1 Library structure

The LCom library is subdivided into the following units.

Table 3-1: Units in the LCom library

Unit name Description

aVersion Unit for change tracking

cProtected Unit for know-how protected constants

cPublic Unit for user-modifiable constants and error constants

dProtected Unit for know-how protected data types

fCom Unit with the know-how protected FBLCom_Communication function block

fSub Unit with auxiliary functions for communication (know-how protected) Only functions of this library to be used externally are documented. Other functions are only used internally in the library and are

therefore not documented.

The constants of the cPublic unit can be changed by the user.



S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

3.2 Integrating the library into SCOUT

The LCom library is supplied as an XML export file. This can be imported into the SIMOTION project in SIMOTION SCOUT or SCOUT TIA.

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

2. Open the dialog window via right click on the folder LIBRARIES.

3. Choose Export/Import: Import folders/objects and navigate to your local folder where the LCom library was extracted to.

4. Select the file with the ending .xml

5. The library will now be integrated.

Figure 3-1 LCom Integration in SCOUT

4 Notes and Support


S

iem

en

s A

G 2

01

7 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


S

iem

en

s A

G 2

01

7 A

ll ri

gh

ts r

ese

rve

d

5 Related literature

Table 5-1 Related literature

Topic

\1\ Siemens Industry Online Support

http://support.automation.siemens.com

\2\ Link to this entry page of this application example https://support.industry.siemens.com/cs/ww/en/view/48955385

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 04/2017 First release

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

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

mailto:[email protected]

communication simotion - cache.industry.siemens.com · communication, this is typically in the...

Documents