SAPI-S7 .

NET Interface for Siemens SIMATIC NET Programming instructions

Version 1.0

SoftwareOption GmbH Waldstrasse 30 52080 Aachen Germany

Tel. +49 (0)2405 4716730 Fax +49 (0)2405 4716729 [email protected] www.SoftwareOption.de

General terms and conditions (GTC) Please note: The unlicensed versions of the SIMATIC NET interfaces for .NET are only delivered to you for the purpose of temporary evaluation in a testing environment. They may not be used in a productive environment. By using the interfaces you accept our general terms and conditions (GTC) which you have got in PDF format (SoftwareOption-AGB-GTC.pdf) with your software package. For productive operations please order a license with the order form which is included in your package, too.

SAPI-S7 .NET SIMATIC NET programming interface for Microsoft .NET

Table of contents 1 2 3 4 5 6 Introduction ........................................................................................................................... 2 Prerequisites ......................................................................................................................... 2 Limitations of the demo version ............................................................................................. 3 Implemented SAPI-S7 .NET functions / status quo................................................................ 3 Installation of the SAPI-S7 .NET programming interface ....................................................... 3 Overview of the programming interface ................................................................................. 4 6.1 Methods of the Class S7Core ........................................................................................ 4 6.2 Methods of the Class S7Vfd .......................................................................................... 4 6.3 Methods and Events of the Class S7Connection ........................................................... 5 6.4 Methods of the Class S7Log .......................................................................................... 7

SAPI-S7 .NET programming interface, page 1

Introduction

With SAPI-S7 you get access (e.g. read/write variables) to Siemens PLCs of type S7-300, S7-400, etc. For PC user programs Siemens provides the programming interface SAPI-S7 for the language C/C++. With SAPI-S7 .NET interface of SoftwareOption access is given to .NET programs. Advantages: 1. Performance: Compared to OPC the interface has less overhead and is therefore faster. 2. Support for native .NET data types: The interface casts .NET data types (byte, short, float, etc.) into the necessary S7 net representation and vice versa. 3. Support for the .NET event model: All events of the S7 interface are encapsulated in .NET events. 4. Sample program: The included sample will assist you in building your program very quickly.

Prerequisites Operating system Windows XP or higher Microsoft Visual Studio 2008 or higher Microsoft .NET Framework 3.5 or higher An installed product Siemens SIMATIC NET PC-Software Version 7 or higher The Siemens SAPI-S7 documentation for C/C++

It is required, that you are familiar with Siemens automation software. Furthermore knowledge of the SAIP-S7 API (for C/C++) is required. Telephone support: Buyers of the .NET interface get up to one hour support at no charge. Please call Carsten Buchloh, Tel. +49 (0)2405 47 16 730

SAPI-S7 .NET programming interface, page 2

Limitations of the demo version

The unregistered version is limited by a popup window only. When ordering the registered version, you will get a license file, which has to be copied to the same directory, where your program resides.

Implemented SAPI-S7 .NET functions / status quo

Currently not all functions of the SAPI-S7 interface are implemented. The following functions will be implemented by SoftwareOption at a later date: Blockoriented services (s7_bsend_req, s7_get_bsend_cnf, s7_brcv_init, s7_get_brcv_ind, s7_brcv_stop) Message services (s7_msg_initiate_req, s7_get_msg_initiate_cnf, s7_msg_abort_req, s7_get_msg_abort_cnf, s7_get_scan_ind, s7_get_alarm_ind) VFD Services (s7_vfd_state_req, s7_get_vfd_state_cnf) Diagnostic services (s7_diag_init, s7_get_diag_ind, s7_diag_stop)

Dont hesitate to call us, if your project needs functions of the above list. 5 Installation of the SAPI-S7 .NET programming interface

Included in delivery / installation: 1. The Assembly S7dotNetLibrary.dll. This file contains the implementation of the SAPI-S7 .NET interface. Please copy the file to a directory of your choice. 2. The directory S7dotNetSample with a C# sample program project. Please copy the project to a directory of your choice. 3. Add a reference of the assembly S7dotNetLibrary.dll to your project: - Open the solution S7dotNetSample.sln - Make a right click onto the project S7dotNetSample -> Add reference - Navigate to the Assembly S7dotNetLibrary.dll

SAPI-S7 .NET programming interface, page 3

Overview of the programming interface

In the following the methods and events of the implemented classes of the programming interface are listed. We have intentionally not described every function in detail here. Instead we refer to the well documented sample program, where every function is implemented. Additionally the Siemens SAPI-S7 documentation is required. The .NET programming interface contains the following classes: 6.1 S7Core (contains all constants and structures equivalent to the Siemens include file %ProgramFiles%\SIEMENS\SIMATIC.NET\sapi_s7\include\sapi_s7.h) S7Vfd (an instance contains a list of instances of typ S7Connection for the corresponding VFD) S7Connection (contains the information for a single connection) S7Log (contains logging functions) Methods of the Class S7Core equivalent Siemens C-functions s7_get_device_list s7_get_vfd_list

.NET methods S7Core

Constructor: S7Core(S7Log s7log) List<string> GetDeviceList() List<string> GetVfdList(string deviceName)

6.2

Methods of the Class S7Vfd equivalent Siemens C-functions

s7_init s7_shut s7_set_window_handle_msg s7_mini_db_get s7_mini_db_set -

.NET methods S7Vfd

Constructor: S7Vfd(string deviceName,string vfdName, S7Log s7log) int Init() int Shut() int SetWindowHandleMsg(uint hWnd, uint messageID) S7Connection GetConnection(string connectionName) S7Connection GetConnection(ushort cref) string MiniDbGet(ushort type) int MiniDbSet(ushort type, string value) void MessageReceived()

SAPI-S7 .NET programming interface, page 4

6.3

Methods and Events of the Class S7Connection equivalent Siemens C-functions

.NET methods S7Connection Constructor

No public constructor. An instance of type S7Vfd creates a list of connections of type S7Connection automatically.

Connection management:
int int int int InitiateRequest() InitiateResponse(ushort accept) AwaitInitiateRequest() Abort() s7_initiate_req s7_initiate_resp s7_await_initiate_req s7_abort

Variable services:
int ReadRequest(string symbolicName, ushort orderId) int GetReadConfirmation<T>(ushort var_length, ref T myVariable) int MultipleReadRequest(string[] symbolicNames, ushort orderId) int GetMultipleReadConfirmation<T>(ref ushort[] result_array, ushort[] var_length_array, ref T myMultiVariableStruct) where T : struct int WriteRequest<T>(string symbolicName, ushort var_length, ref T var_value, ushort orderId) int WriteLongRequest<T>(string symbolicName, ushort var_length, ref T var_value, ushort orderId) int MultipleWriteRequest<T>(string[] symbolicNames, ushort[] var_length_array, ref T myMultiVariableStruct, ushort orderId) s7_read_req s7_get_read_cnf s7_multiple_read_req s7_get_multiple_read_cnf

s7_write_req s7_write_long_req s7_multiple_write_req

Cyclic variable services:

int CycleReadInitRequest(string[] symbolicNames, ushort cycl_time, ushort orderId) int CycleReadDeleteRequest(ushort orderId) int CycleReadStartRequest(ushort orderId) int CycleReadStopRequest(ushort orderId) int GetCycleReadIndication<T>(ref ushort[] result_array, ushort[] var_length_array, ref T myMultiVariableStruct) where T : struct s7_cycl_read_init_req s7_cycl_read_delete_req s7_cycl_read_start_req s7_cycl_read_stop_req s7_get_cycl_read_ind

Others:
string GetStateString()

SAPI-S7 .NET programming interface, page 5

Events S7Connection
STATE_CHANGE_Event S7_INITIATE_CNF_Event Eventparameter: int iRet = s7_get_initiate_cnf(..) S7_AWAIT_INITIATE_CNF_Event Eventparameter: int iRet = s7_get_await_initiate_cnf(..) S7_INITIATE_IND_Event Eventparameter: int iRet = s7_get_initiate_ind(..) S7_ABORT_IND Eventparameter: int iRet = s7_get_abort_ind(..) S7_READ_CNF_Event Eventparameter: ushort orderId S7_MULTIPLE_READ_CNF_Event Eventparameter: ushort orderId S7_WRITE_CNF_Event Eventparameter: int iRet = s7_get_write_cnf(..) ushort orderId S7_MULTIPLE_WRITE_CNF_Event Eventparameter: int iRet = s7_get_multiple_write_cnf(..) ushort orderId ushort[] result_array S7_CYCL_READ_INIT_CNF_Event Eventparameter: int iRet = s7_get_cycl_read_init_cnf(..) ushort orderId S7_CYCL_READ_DELETE_CNF_Event Eventparameter: int iRet = s7_get_cycl_read_delete_cnf(..) ushort orderId S7_CYCL_READ_START_CNF_Event Eventparameter: int iRet = s7_get_cycl_read_start_cnf(..) ushort orderId S7_CYCL_READ_STOP_CNF_Event Eventparameter: int iRet = s7_get_cycl_read_stop_cnf(..) ushort orderId S7_CYCL_READ_ABORT_IND_Event Eventparameter: int iRet = s7_get_cycl_read_abort_ind(..) ushort orderId S7_CYCL_READ_IND_Event Eventparameter: ushort orderId

Equivalent Siemens events

S7_INITIATE_CNF

S7_AWAIT_INITIATE_CNF

S7_INITIATE_IND

S7_ABORT_IND

S7_READ_CNF

S7_MULTIPLE_READ_CNF

S7_WRITE_CNF

S7_MULTIPLE_WRITE_CNF

S7_CYCL_READ_INIT_CNF

S7_CYCL_READ_DELETE_CNF

S7_CYCL_READ_START_CNF

S7_CYCL_READ_STOP_CNF

S7_CYCL_READ_ABORT_IND

S7_CYCL_READ_IND_Event

SAPI-S7 .NET programming interface, page 6

6.4

Methods of the Class S7Log Equivalent Siemens C-functions

.NET Methods S7Log Constructor

public S7Log(uint logTarget, uint logLevel)

Methods
public void Log(string logString) s7_trace and/or Debug.Write

SAPI-S7 .NET programming interface, page 7