Skip to content

Latest commit

 

History

History
348 lines (242 loc) · 13.6 KB

RefManual.md

File metadata and controls

348 lines (242 loc) · 13.6 KB
Raw

LOGO! PG Library Reference Manual

Rev. Ak

Januar 2021

Preface

Siemens (TM) LOGO! library for Arduino.

The library is based on the implementation of Settimino and Snap7. Only LOGO! 0BA4 to 0BA6 are supported via the serial programming interface.

Used and Related Publications

Refer to the following publications for details about the application programming interface:

Refer to the following publication for details about the protocol using the PG-Interface:

Contents

LogoClient Syntax

ARDUINO has not a multithreaded environment and we can only use one LogoClient instance.

API - Administrative functions

LogoClient.Connect()

Connects the Client to the LOGO! with the parameters specified in the previous call of ConnectTo() or SetConnectionParams().

Returns a 0 on success or an Error code (see Errors Code List below).

LogoClient.ConnectTo(Stream *Interface)

Connects the Client to the hardware connected via the serial port.

  • Interface Stream object for example "Serial"

Returns a 0 on success or an Error code (see Errors Code List below).

LogoClient.SetConnectionParams(Stream *Interface)

Links the Client to a stream object.

  • Interface Stream object for example "Serial"

LogoClient.SetConnectionType(ConnectionType)

Sets the connection resource type, i.e the way in which the Clients connects to the LOGO! device.

  • ConnectionType
Connection Type Value Description
PG 0x01 PG

LogoClient.Disconnect()

Disconnects "gracefully" the Client from the LOGO! device.

API - Base Data I/O functions

LogoClient.ReadArea(int Area, word DBNumber, word Start, word Amount, void *ptrData)

This is the main function to read data from a LOGO! device. With it Inputs, Outputs and Flags can be read.

  • Area Area identifier, must always be LogoAreaDB
  • DBNumber DB number if area = LogoAreaDB, must always be 1
  • Start Offset to start
  • Amount Amount of words to read
  • ptrData Pointer to memory area

Returns a 0 on success or an Error code (see Errors Code List below).

API - Block oriented functions

LogoClient.GetDBSize(word DBNumber, size_t *Size)

Returns the size of a given DB Number. This function is useful to upload an entire DB.

  • DBNumber DB number if area = LogoAreaDB, must always be 1
  • Size DB Size in bytes

Returns a 0 on success or an Error code (see Errors Code List below).

LogoClient.DBGet(word DBNumber, void *ptrData, size_t *Size)

This is a wrapper function of ReadArea(). It simply internally calls ReadArea() with Area = LogoAreaDB, Start = 0 and Amount = GetDBSize().

  • DBNumber DB number if area = LogoAreaDB, must always be 1
  • ptrData Pointer to memory area
  • Size In: Buffer size available; Out: Bytes Uploaded

Returns a 0 on success or an Error code (see Errors Code List below).

Remarks: This function first gathers the DB size via GetDBSize then calls ReadArea if the Buffer size is greater than the DB size, otherwise returns an error.

API - Date/Time functions

LogoClient.GetPlcDateTime(TimeElements *dateTime)

Reads LOGO! date and time.

  • dateTime, see below

The dateTime argument is a C structure, defined in the Time Library:

typedef unsigned long time_t;

typedef struct {
  uint8_t Second; // seconds after the minute   0-59 
  uint8_t Minute; // minutes after the hour     0-59
  uint8_t Hour;   // hours since midnight       0-23
  uint8_t Wday;   // day of week, sunday is day 1 
  uint8_t Day;    // day of the month           1-31
  uint8_t Month;  // months                     1-12
  uint8_t Year;   // offset from 1970;
} TimeElements;

Remarks: The Time library includes low-level conversion functions between system time and individual time elements. The function returns 0 seconds for each call.

Returns a 0 on success or an Error code (see Errors Code List below).

LogoClient.SetPlcDateTime(TimeElements dateTime)

Sets the LOGO! date and time.

  • dateTime a element with the C structure TimeElements

Returns a 0 on success or an Error code (see Errors Code List below).

Remarks: This function is subject to the security level set.

LogoClient.SetPlcSystemDateTime()

Sets the LOGO! date and time in accord to the DTE system time. The internal system time is based on the standard Unix time (number of seconds since Jan 1, 1970).

Note: The system time begins at zero when the sketch starts. The internal time can be synchronized to an external time source using the Time library.

Returns a 0 on success or an Error code (see Errors Code List below).

Remarks: This function is subject to the security level set.

API - System info functions

LogoClient.GetOrderCode(TOrderCode *Info)

Gets CPU order code and version info.

  • Info, see below

The Info argument is an C structure defined in the library:

typedef struct {
  char Code[19];  // Order Code
  byte V1;        // Version V1.V2.V3
  byte V2;
  byte V3;
} TOrderCode;

The Order code is a null terminated C string such as 6ED1052-xxx00-0BA6. Please note, for the LOGO! 0BA4 device and in operation mode RUN, the firmware can not be read out (V1 to V3 have a value of 0).

Returns a 0 on success or an Error code (see Errors Code List below).

LogoClient.GetPDULength()

Returns the PDU length negotiated between the client and the LOGO! device during the connection or 0 on error.

Note: All data transfer functions handle this information by themselves and split the telegrams automatically if needed.

API - PLC control functions

LogoClient.PlcStart()

Puts the LOGO! device in operation mode RUN.

Returns a 0 on success and when the LOGO! device is already running, otherwise an Error code (see Errors Code List below).

LogoClient.PlcStop()

Puts the LOGO! device in operation mode STOP.

Returns a 0 on success and when the LOGO! device is already stopped, otherwise an Error code (see Errors Code List below).

LogoClient.GetPlcStatus(int *Status)

Returns the CPU status (running/stopped) into Status reference.

  • Status, see below

Status values:

Const Value Meaning
LogoCpuStatusUnknown 0x00 The CPU status is unknown.
LogoCpuStatusRun 0x08 The CPU is running.
LogoCpuStatusStop 0x04 The CPU is stopped.

Returns a 0 on success or an Error code (see Errors Code List below).

API - Security functions

The password protects the circuit program in LOGO!. Editing values and parameters, or viewing the circuit program in LOGO!, or uploading the circuit program from LOGO! is only possible after you have entered the password.

Note: Depending on the protection level, each library function is checked before the command can be executed. Regardless of the protection level, diagnostic functions and reading of the variable table are possible.

LogoClient.SetSessionPassword(char *password)

Send the password to the LOGO! to meet its security level.

  • password Password

Returns a 0 on success or an Error code (see Errors Code List below).

A password accepted by a LOGO! is an 10 chars string, a longer password will be trimmed. Only upper case charaters from A to Z can be used for the password.

LogoClient.ClearSessionPassword()

Clears the password set for the current session.

Returns a 0 on success or an Error code (see Errors Code List below).

LogoClient.GetProtection(TProtection *Protection)

Gets the CPU protection level info.

  • Protection, see below

The Protection argument is an C structure defined in the library:

typedef struct {
  byte sch_schal;
  byte sch_par;
  byte sch_rel;
  byte bart_sch;
  byte anl_sch;
} TProtection;

Returns a 0 on success or an Error code (see Errors Code List below).

Field Values:

Protection Values Description
sch_schal 1,2,3 Protection level set by the operating mode switch (1:no protection, 2:read protection, 3:read/write protection)
sch_par 0,1,2,3 Parameterized protection level (1:full access, 2:read protection, 3:read/write protection, 0:no password, undefined or cannot be determined)
sch_rel 0,1,2,3 Valid protection level of the CPU (level 1-3, 0: cannot be determined)
bart_sch 1,2,3 Position of the operating mode switch (1:RUN, 2:RUN_P, 3:STOP, 0:undefined or cannot be determined)
anl_sch 0 Position of the startup mode switch (0:undefined, does not exist or cannot be determined)

Remarks:
The LOGO! does not use protection levels like a S7, but protection level 1 (no protection) to 3 (read/write protection) are comparable (value sch_rel).

The LOGO! configuration can only be read out in the operating mode STOP (value bart_sch).

There is no startup mode switch for the LOGO!. Therefore, the value for anl_sch is always 0.

Further information about the SFC 51 system function can be found in the SIMATIC S7 Online Help.

API - Properties

LogoClient.LastError

Returns the last job result.

LogoClient.ErrorText(int Error)

Returns a textual explanation of Error.

LogoClient.RecvTimeout

Returns the timeout value.

LogoClient.Connected

Returns the connection status.

Additional description

Memory models

To save memory we can define different memory models: Small, Normal and Extended

By default library is released as Extended.

These directives are visible from your sketch:

#define _SMALL
or
#define _NORMAL
or
#define _EXTENDED

Error codes

Severe Error codes

Severe errors, the Client should be disconnected:

Mnemonic HEX Meaning
errStreamConnectionFailed 0x0001 Stream Connection error
errStreamConnectionReset 0x0002 Connection reset by the peer
errStreamDataRecvTout 0x0003 A timeout occurred waiting a reply
errStreamDataSend 0x0004 Stream error while sending the data
errStreamDataRecv 0x0005 Stream error while receiving the data
errPGConnect 0x0006 LOGO! connection failed
errPGNegotiatingPDU 0x0007 LOGO! negotiation failed
errPGInvalidPDU 0x0008 Malformed Telegram supplied

Device Error codes

LOGO! device errors such as DB not found or address beyond the limit:

Mnemonic HEX Meaning
errCliInvalidPDU 0x0100 Invalid Telegram received
errCliSendingPDU 0x0200 Error sending a Telegram
errCliDataRead 0x0300 Error during data read
errCliDataWrite 0x0400 Error during data write
errCliFunction 0x0500 The LOGO! reported an error for this function
errCliBufferTooSmall 0x0600 The supplied buffer is too small