APP S7 Full Library Documentation

APP S7 is a pure C# implementation of the S7 Protocol. APP S7 is deployed as a single source file that contains some classes that you can use directly in your .NET project to communicate with S7 PLCs. It’s designed to work with small hardware .NET-based or even for large projects which don’t need extended control functions.

Main features 

• Fully standard “safe managed” C# code without any dependencies.
• Virtually every hardware with an Ethernet adapter able to run a .NET Core can be connected to an S7 PLC.
• Packed protocol headers to improve performances.
• Helper class to access to all S7 types without worrying about Little-Big endian conversion.
• Compatible with Universal Windows Platform including Win10 IoT 

 Licensing

The APP_S7 Driver requires a license for long term operation. This can be requested by contacting:

contact@appliedprojectsengineering.com

S7Client reference

Administrative functions 

These methods allow controlling the behavior a Client Object. 

SetConnectionType

Description

Sets the connection resource type, i.e. the way in which the Clients connects to a PLC.

Declaration

public void SetConnectionType(short ConnectionType) 

Parameters

Connection type table 

ConnectTo

Description

Connects the client to the hardware at (IP, Rack, Slot) Coordinates.

Declaration

public int ConnectTo(String Address, int Rack, int Slot) 

Parameters

Return value

• 0 : The Client is successfully connected (or was already connected).
• Other values : see the Errors Code List.  

Rack and Slot 

In addition to the IP Address, that we all understand, there are two other parameters that index the unit : Rack (0..7) and Slot (1..31) that you find into the hardware configuration of your project, for a physical component, or into the Station Configuration manager for WinAC. 

There is however some special cases for which those values ​​are fixed or can work with a default as you can see in the next table. 

 Let’s see some examples of hardware configuration: 

S7 400 Rack 

 The same concept for WinAC CPU which index can vary inside the PC Station Rack.  

S7300 Rack 

S7300 CPU is always present in Rack 0 at Slot 2

SetConnectionParams

Description

Sets internally (IP, LocalTSAP, RemoteTSAP) Coordinates.

Declaration

public void SetConnectionParams(String Address, int LocalTSAP,
   int RemoteTSAP) 

Parameters

 Remarks

This function must be called just before Connect(). 

Connect

Description

Connects the client to the PLC with the parameters specified in the previous call of ConnectTo() or SetConnectionParams().

Declaration

public int Connect() 

Return value

• 0 : The Client is successfully connected (or was already connected).
• Other values : see the Errors Code List.  

Remarks

This function can be called only after a previous of ConnectTo() or SetConnectionParams() which internally sets Address and TSAPs.  

Disconnect

Description

Disconnects “gracefully” the Client from the PLC.

Declaration

public void Disconnect() 

Remarks

This function can be called safely multiple times.

After calling this function LastError = 0 and Connected = false. 

Base Data I/O functions 

These functions allow the Client to exchange data with a PLC. 

ReadArea

Description

This is the main function to read data from a PLC.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.

Declaration

public int ReadArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer)

public int ReadArea(int Area, int DBNumber, int Start, int Amount, int  WordLen, byte[] Buffer, ref int BytesRead)

Parameters

(1)   Note the use of the parameter name “amount”, it means quantity of elements, not byte size.

Area table

WordLen table

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

Remarks

As said, every data packet exchanged with a PLC must fit in a PDU, whose size is fixed and varies from 240 up to 960 bytes.

This function completely hides this concept, the data that you can transfer in a single call depends only on the size available of the data area (i.e. obviously, you cannot read 1024 bytes from a DB whose size is 300 bytes).

If this data size exceeds the PDU size, the packet is automatically split across more subsequent transfers.

If either S7AreaCT or S7AreaTM is selected, WordLen must be either S7WLCounter or S7WLTimer (However no error is raised and the values are internally fixed).

Your buffer should be large enough to receive the data.

Particularly:

Buffer size (byte) = Word size * Amount

Where:

 Notes

(2)  When WordLen=S7WLBit the Offset (Start) must be expressed in bits.
Ex. The Start for DB4.DBX 10.3 is (10*8)+3 = 83.

(3)  Since Amount is the number of elements read, BytesRead returns the effective number of bytes. 

WriteArea

Description

This is the main function to write data into a PLC. It’s the complementary function of ReadArea(), the parameters and their meanings are the same.

The only difference is that the data is transferred from the byte buffer into PLC.

Declaration

public int WriteArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer)

public int WriteArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer, ref int BytesWritten) 

See ReadArea() for parameters and remarks. 

Use S7 helper methods to insert S7 data types (int, word, real …) into the byte buffer. 

ReadMultiVars

Description

This is function allows to read different kind of variables from a PLC in a single call.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.

Declaration

public int ReadMultiVars(S7DataItem[] Items, int ItemsCount) 

Parameters

S7DataItem struct

(1)   Note the use of the parameter name “amount”, it means quantity of words, not byte size.

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

(2)  Since could happen that some variables are read, some other not because maybe they don't exist in PLC. Is important to check the single item Result.

Remarks

To use ReadMultiVars a special class is supplied S7MultiVar that avoids the use of unsafe code (since there is a IntPtr)

Due the different kind of variables involved , there is no split feature available for this function, so the maximum data size must not exceed the PDU size.

The advantage of this function becomes big when you have many small noncontiguous variables to be read.

WriteMultiVars

Description

This is function allows to write different kind of variables from a PLC in a single call.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.

Declaration

public int WriteMultiVars(S7DataItem[] Items, int ItemsCount) 

Parameters

S7DataItem struct

(2)   Note the use of the parameter name “amount”, it means quantity of words, not byte size.

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

(2)  Since could happen that some variables are written, some other not because maybe they don't exist in PLC. Is important to check the single item Result.

Remarks

To use WriteMultiVars a special class is supplied S7MultiVar that avoids the use of unsafe code (since there is a IntPtr)

Due the different kind of variables involved , there is no split feature available for this function, so the maximum data size must not exceed the PDU size

The advantage of this function becomes big when you have many small noncontiguous variables to be written.

Lean Data I/O functions 

These are utility functions that simplify the use of ReadArea and WriteArea.

I.e. they call internally ReadArea and WriteArea passing the correct Area and  WordLen. 

Block oriented functions 

GetAgBlockInfo

Description

Returns some information about a given block.
This function is very useful if you need to read or write data in a DB which you do not know the size in advance (see MC7Size field).

This function is used internally by DBGet. 

Declaration

public int GetAgBlockInfo(int BlockType, int BlockNumber,

  ref S7BlockInfo Block) 

Parameters

BlockType values

S7BlockInfo struct

This struct is filled by the function, some fields require additional info:

SubBlockType table

LangType table

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List.  

DBGet

Description

Read an entire DB from the PLC without the need of specifying its size. As output SizeRead will contain the size read.

This function is not subject to the security level set. 

Declaration

public int DBGet(int DBNumber, byte[] usrData, ref int Size) 

Parameters

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

Remarks

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

DBFill

Description

Fills a DB in AG with a given byte without the need of specifying its size.

Declaration

public int Cli_DBFill(int DBNumber, int FillChar);

 Parameters

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List.  

Remarks

Fillchar is an integer for efficiency reasons, only the lowest byte is used.

Date/Time functions 

These functions allow to read/modify the date and time of a PLC.

Imagine a production line in which each PLC saves the data with date/time field inside, it is very important that the date be up to date.

Both CP X43 and internal PN allow to synchronize date and time but you need an NTP server, and in some cases (old hardware or CP343-1 Lean or old firmware release) this doesn’t work properly.

Snap7 Client, using the same method of S7 Manager, always works. 

GetPlcDateTime

Description

Reads PLC date and time into a C# DateTime class instance.

Declaration

public int GetPlcDateTime(ref DateTime DT) 

Parameters

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List.  

SetPlcDateTime

Description

Sets the PLC date and time.

Declaration

public int SetPlcDateTime(DateTime DT) 

Parameters

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List.  

SetPlcSystemDateTime

Description

Sets the PLC date and time in accord to the PC system Date/Time.

Declaration

public int SetPlcSystemDateTime() 

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

 System info functions 

these functions access to SZL (or SSL - System Status List) to give you all the same information that you can get from S7 Manager. 

System Status List

The system status list (SSL) describes the current status of a programmable logic controller.

The contents of the SSL can only be read using information functions but cannot be modified. The partial lists are virtual lists, in other words, they are only created by the operating system of the CPUs when specifically requested.

You can access to system status list using SFC 51 too "RDSYSST."

To read a partial list you must specify its ID and Index.

For a detailed description of SZL see:

• 33 of "System Software for S7-300/400 System and Standard Functions".

ReadSZL

Description

Reads a partial list of given ID and INDEX. 

Declaration

public int ReadSZL(int ID, int Index, ref S7SZL SZL, ref int Size)

Parameters

S7SZL

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

Remarks

Remember to allocate the Data[] buffer (see the demo)

GetOrderCode

Description

Gets CPU order code and version info. 

Declaration

public int GetOrderCode(S7OrderCode Info) 

Parameters

 The Order code is a string such as “6ES7 151-8AB01-0AB0” 

GetCpuInfo

Description

Gets CPU module name, serial number and other info. 

Declaration

public int GetCpuInfo(S7CpuInfo Info)  

Parameters

 Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List.  

GetCpInfo

Description

Gets CP (communication processor) info. 

Declaration

public int GetCpInfo(S7CpInfo Info) 

Parameters

 S7CpInfo 

 Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List.  

PLC control functions 

With these control function it’s possible to Start/Stop a CPU and read the PLC status. 

PlcColdStart

Description

Puts the CPU in RUN mode performing an COLD START.

 Declaration

public int PlcColdStart()

Return value

• 0 : The function was accomplished with no errors.
• Other values : Either the PLC is already running or the current protection level is not met to perform this operation.

Remarks

This function is subject to the security level set.

PlcHotStart

Description

Puts the CPU in RUN mode performing an HOT START.

 Declaration

public int PlcHotStart()

 Return value

• 0 : The function was accomplished with no errors.
• Other values : Either the PLC is already running or the current protection level is not met to perform this operation.

Remarks

This function is subject to the security level set.

PlcStop

Description

Puts the CPU in STOP mode.

Declaration

public int PlcStop()

Return value

• 0 : The function was accomplished with no errors.
• Other values : Either the PLC is already stopped or the current protection level is not met to perform this operation.

Remarks

This function is subject to the security level set.

PlcGetStatus

Description

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

Declaration

public int GetPlcStatus(ref int Status)

Parameters

Status values

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

Security functions

With these functions is possible to know the current protection level, and to set/clear the current session password.

The correct name of the below functions SetSessionPassword and ClearSessionPassword, would have to be Login and Logout to avoid misunderstandings about their scope.

Especially because, if you look at the source code, there is an encoding function that translates the plain password before send it to the PLC.

PASSWORD HACKING IS VERY FAR FROM THE AIM OF THIS PROJECT, MOREOVER YOU NEED TO KNOW THE CORRECT PASSWORD TO MEET THE CPU SECURITY LEVEL.

Detailed information about the protection level can be found in §33.19 of  "System Software for S7-300/400 System and Standard Functions".

 SetSessionPassword

Description

Send the password to the PLC to meet its security level.

Declaration

public int SetSessionPassword(string Password);

 Parameters

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

Remarks

A password accepted by a PLC is an 8 chars string, a greater password will be truncated, and a smaller one will be "right space padded".

ClearSessionPassword

Description

Clears the password set for the current session (logout).

Declaration

public int ClearSessionPassword()

Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

GetProtection

Description

Gets the CPU protection level info.

 Declaration

public int GetProtection(ref S7Protection Protection)

Parameters

 TS7Protection fields

Field Values 

See also §33.19 of "System Software for S7-300/400 System and Standard Functions"

 Return value

• 0 : The function was accomplished with no errors.
• Other values : see the Errors Code List. 

Properties/Info Functions

ConnTimeout

int, in/Out – Gets/Sets the connection timeout (in milliseconds) for a telegram.

RecvTimeout

int, in/out – Gets/Sets the receiving timeout (in milliseconds) for a telegram.

SendTimeout

int, in/out – Gets/Sets the sending timeout (in milliseconds) for a telegram.

Connected

bool, out – It’s true if the Client is connected.

PduSizeNegotiated

int, out – Returns the PDU size negotiated.

PduSizeRequested

int, in/out – Gets/Sets the PDU size to be negotiated.

PLCPort

int, in/out – Gets/Sets the connection Port (by default is 102).ExecutionTime

int, out – Returns the last operation execution time in ms.

public int LastError()

Returns the last operation error.

public string ErrorText(int Error)

Returns a textual explanation of Error

public int ExecTime()

Returns the last operation execution time in ms. (compatibility with Snap7.net.cs)

S7 Helper reference

This class allow to read/write an “S7” value into a byte buffer, all new S71200/1500 types are supported.

Read functions are in format:

public static <.NET native Type> Get<S7 Type>At(byte[] Buffer, int Pos)

They extract a <S7 Type> var from the byte buffer starting from the byte number “pos”.

Write functions are in format:

public static void Set<S7 Type>At(byte[] Buffer, int Pos, <.NET native Type> Value)

They insert a .net native type var into the byte buffer starting from the byte number “pos”.

Data access example

 Now, just a real example of how to read a S7 struct from a PLC into .NET struct using this class in C# and VB.

Let’s suppose that we make a leak test on an automotive component and that we want to acquire the result of this test.

The data of this test consists of some values (Component serial number, Leak Value etc..) stored in DB 100 as in figure.

Every time a component is tested this struct is filled by the PLC and we want to read it into a .NET struct, picking the fields and adjusting their byte-order (the PLC is Big-Endian, the PC is Little-Endian, so the bytes must be reversed).

This is our C# sample struct:

And this is the C# sample function that fills the struct. Notice that the outcome of any Client function call should be checked, here is skipped for brevity.

The struct 

 The function 

Finally, if you put a button and 4 labels in the form of VB demo, with this simple code you can test the mechanism.

S7MultiVar reference

This class allows to fill the S7DataItem[] and performs a ReadMultivar or WriteMultivar without using unsafe code.

The best way to understand the use of this class is analyzing an example.

The process is simple:

1. Instantiate the class.
2. Add the vars reference (i.e. your buffer) specifying the kind of element that we want read or write.
3. Call Read or Write method.

Read example

 If everything is ok into DB_A, DB_B, DB_C we will find the first 16 bytes of DB1, DB2 and DB3.

Remarks

1. Reader.Result[] will contain the single outcome of the items, it’s possible that some items were read and some other not.
2. The parameters of Add() are the same of Read/WriteArea, you can read/write non only DB but also E/A/MK/T/C and also bits.

Error codes

 Please refer to code of the function ErrorText() for the explanation

errTCPSocketCreation         = 0x00000001;

errTCPConnectionTimeout      = 0x00000002;

errTCPConnectionFailed       = 0x00000003;

errTCPReceiveTimeout         = 0x00000004;

errTCPDataReceive            = 0x00000005;

errTCPSendTimeout            = 0x00000006;

errTCPDataSend               = 0x00000007;

errTCPConnectionReset        = 0x00000008;

errTCPNotConnected           = 0x00000009;

errTCPUnreachableHost        = 0x00002751;

errIsoConnect                = 0x00010000;

errIsoInvalidPDU             = 0x00030000;

errIsoInvalidDataSize        = 0x00040000;

errCliNegotiatingPDU         = 0x00100000;

errCliInvalidParams          = 0x00200000;

errCliJobPending             = 0x00300000;

errCliTooManyItems           = 0x00400000;

errCliInvalidWordLen         = 0x00500000;

errCliPartialDataWritten     = 0x00600000;

errCliSizeOverPDU            = 0x00700000;

errCliInvalidPlcAnswer       = 0x00800000;

errCliAddressOutOfRange      = 0x00900000;

errCliInvalidTransportSize   = 0x00A00000;

errCliWriteDataSizeMismatch  = 0x00B00000;

errCliItemNotAvailable       = 0x00C00000;

errCliInvalidValue           = 0x00D00000;

errCliCannotStartPLC         = 0x00E00000;

errCliAlreadyRun             = 0x00F00000;

errCliCannotStopPLC          = 0x01000000;

errCliCannotCopyRamToRom     = 0x01100000;

errCliCannotCompress         = 0x01200000;

errCliAlreadyStop            = 0x01300000;

errCliFunNotAvailable        = 0x01400000;

errCliUploadSequenceFailed   = 0x01500000;

errCliInvalidDataSizeRecvd   = 0x01600000;

errCliInvalidBlockType       = 0x01700000;

errCliInvalidBlockNumber     = 0x01800000;

errCliInvalidBlockSize       = 0x01900000;

errCliNeedPassword           = 0x01D00000;

errCliInvalidPassword        = 0x01E00000;

errCliNoPasswordToSetOrClear = 0x01F00000;

errCliJobTimeout             = 0x02000000;

errCliPartialDataRead        = 0x02100000;

errCliBufferTooSmall         = 0x02200000;

errCliFunctionRefused        = 0x02300000;

errCliDestroying             = 0x02400000;

errCliInvalidParamNumber     = 0x02500000;

errCliCannotChangeParam      = 0x02600000;

errCliFunctionNotImplemented = 0x02700000;