LIBNODAVE -- Exchange data with Siemens PLCs

using MPI,PPI adapters or Ethernet with CPx43 or Ethernet over IBH/MHJ-Netlink

If you use GE Fanuc PLCs you might also be interested in LibOpenSRTP by same Author.

Donations of (used) hardware are also welcome!

Download Archive contains sources, test programs, precompiled LINUX shared library, win32 dll, pascal interface unit, .NET support dll and examples.

Supported programming languages: C,C++,C#,Delphi,Pascal,Perl,VB(A)

NEWS:

Version 0.8.1

Fixes a bug in MPI which made applications wait forever if PLC doesn't respond

New data conversion functions in .NET

Version 0.8

Windows only: Libnodave can now use communication dlls and drivers from Siemens. This makes it possible to use CP5611, CP5511, USB-MPI cable from Siemens and maybe other devices if the vendor provides support for communiction with s7onlinx.dll

Linux only: Kernel driver for Siemens USB-MPI cable. The precompiled module is for Kernel 2.6.13

Version 0.7.2

Interface declarations and example code to use Libnodave from VB / VBA / MS Excel

PERL Module and example code

All exported functions in the Windows DLL are now declared __stdcall. Users may need to recompile existing applications.

Version 0.7

Changes the API to simplyfy usage with languages other than C

Examples in C# included

Delphi Component included (Thanks to Axel Kinting!)

Can set outputs of S7-200 in stop mode

Version 0.6.3:

Incorporates PPI over IBH/MHJ-Netlink.

Version 0.6.2:

Seemlesly integrates MPI protocol over IBH/MHJ-NetLink MPI to Ethernet Gateway

Code includes workarounds for and has been tested on ARM processors

Pascal unit should be 100% compatible with Borland Delphi now

Version 0.6:

Can write multiple items in a single request

Can use bit variables in multiple read&write requests

Can load program blocks into 300/400 CPUs

Fixes a possible bug in opening COM ports on Win32

Includes some documentation

This version has also been successfully tested with a Speed7 CPU 318 from VIPA, an S7 compatible CPU, but faster and with integrated ethernet connector.
Version 0.5:

Reading and writing of single bits

Reads timers and counters

Support to compile under Win32 and precompiled DLL

Interface unit to use DLL or shared library with Pascal

Version 0.4.3

provides a single library for MPI, PPI and ISO over TCP

Version 0.4.2

supports reading of multiple items with a single request.

supports setting of Profibus/MPI speed with MPI adapters.

new set of alternative conversion routines can do without byteswap.h. This should make it possibl e to compile libnodave under Windows using Cygwin. It should also ease porting to other systems.

Version 0.4

supports ISO over TCP communication with Ethernet Communication Processors CP 243, CP 343, CP 443 and their -IT versions

Can read out Program blocks from the CPU

Can read diagnostic lists (SZL) from 300/400 family PLCs

Support S5 family (thanks to Andrew Rostovtsew!)

Version 0.3.1

fixes a bug in S7-200 PPI communication

Version 0.3

also supports S7-200 family via PPI-cable

supports the IBH-Link MPI/ethernet gateway

Information about this gateway can be found on: IBH Link (manufacturer's page).

Work currently in progress:

Code cleanup and better error handling/error reporting

JAVA library

People interested in testing the early JAVA version should send me an e-mail.
Feedback welcome! thomas.hergenhahn@web.de
a complete SCADA package for LINUX
BIG FAT WARNING:
This is beta code and information. You assume all responsibility for its use.

DANGER: DON'T connect to a PLC unless you are certain it is safe to do so!!! It is assumed that you are experienced in PLC programming/troubleshooting and that you know EXACTLY what you are doing. PLC's are used to control industrial processes, motors, steam valves, hydraulic presses, etc. You are ABSOLUTELY RESPONSIBLE for ensuring that NO-ONE is in danger of being injured or killed because you affected the operation of a running PLC.
Also expect that buggy drivers could write data even when you expect that they will read only !!!

Basics

The PLCs of the S7-300 and S7-400 family have a so called MPI (multipoint) interface. This interface is mainly used to program the device, but can also be used to read and write data from and to the PLC. The physical layer of the MPI interface is a two wire line operated with differential voltage like RS422 or RS485. More than two devices can be connected to that line. The data flow is bidirectional. The baud rate is normally 187.5 kBaud, but you may select others. Because no standard PC hardware can do these baud rates, you cannot use a simple signal level converter. You will allways need an adapter from Siemens or another vendor. These adapters are "intelligent" devices built around some microprocessor. They talk MPI to the PLC and something else to your PC. The rest of this document is about this "something else".

Commercial Solutions

You can buy a library named PRODAVE from Siemens. It is available for Windows and maybe DOS only, as far as I know. There are libraries from third party vendors mostly for Windows only.

The goal of this project

This project aims to provide a free library in C source. It is written with and for LINUX. There is support for compiling it with Borland C-Compiler from Borland's free command line tools for Win32. It has been compiled and found to work also on FreeBSD. Anybody more familiar with other operating systems is hereby encouraged to port it.

The PC-side protocols

Some adapters from Siemens can be used for "teleservice" over a modem connection, some cannot.
There are (at least?) two protocols that can be used between PC and adapter. I guess, there was first a (relatively) simple protocol and later Siemens modified it, added a CRC and some more stuff to make it fit for modem connections. The library currently uses only the simpler protocol.

Sources of information

There is some information about this protocol on www.runmode.com. The rest I found out recording and analyzing the communication between PC and adapter. No information came, officialy or unofficialy, from Siemens.

The equipment used

Tests where done using:

MPI adapter 6ES7 972-0CA22-0XAC.

MPI adapter 6ES7 972-0CA23-0XAC.

Teleservice adapter 6ES7 972-0CA33-0XAC.

MPI adapter 6ES7 972-0CA11-0XAC.

CPU 315-2DP. According to user reports, the library code works with other CPUs from 300 and 400 series as well. Please let me know. More interesting is whether it will work with different adapters too.

Naming rules

Every library function name begins with "dave" to avoid naming conflicts. An underscore before the _dave means that this function is intended for internal use only.

Usage

1. Initialize the serial interface:	fd=setPort("/dev/ttyS1","19200",'O')
2. Initialize a daveInterface	di = daveNewInterface(fd,"Some name")
3. Initialize the MPI adapter	error=daveInitAdapter(di))
4. Initialize a daveConnection	dc = daveNewConnection(di,2);
5. Connect to a PLC with a given MPI address	daveConnectPLC(dc);
6. Exchange data with that PLC	daveReadBytes(dc,daveFlags,0,0,24);
	daveWriteBytes(dc,daveFlags,0,0,24,buf);
7. Disconnect from the PLC	daveDisconnectPLC(dc);
8. Disconnect from the Adapter	daveDisconnectAdapter(di);

Data format and addressing issues

The functions daveReadBytes()and daveWriteBytes()read and write a block of conscutive bytes from or to the PLC.
The first parameter determines which area in the PLC is addressed. Use constants

daveDB

daveFlags

daveOutputs

daveInputs for this parameter. The length of a block is limited by the maximum message length I did not yet determine. Use multiple calls for longer blocks. daveReadBytes() leaves the data in the structure dc->MPImsg. So you must retrieve it before issuing another call using the same daveConnection object. After calling daveReadBytes() the pointer dc->dataPointer points at the first byte, so you could memcpy() from it.
The endianness is different from intel processors. For convenience there exist conversion functions to reorder the bytes:

float daveGetFloat(daveConnection * dc)

unsigned int daveGetDWORD(daveConnection * dc) etc.
These will retrieve the necessary number of bytes from the message and adjust dataPointer. There is no test wether the message contains enough bytes.
For writing, put your data into some buffer. For floating point data use the conversion function

float toPLCfloat(float), for other types LINUX defines makros in .

Basic data exchange

There is a basic sequence used when sending a message and getting back an answer. This is implemented in _daveExchange().

PC	PLC
STX
	DLE
message
	DLE
	STX
DLE
	ackknowledge for message
DLE
	STX
	answer
DLE
STX
	DLE
ackknowledge for answer
	DLE

Forming a message

every message from the PC to PLC begins with the sequence 0x04,0x80+MPI address,0x80,0x0C,0x03,0x14 the follows the contents, the chracters DLE,ETX and a block check code (bcc). The bcc is calculated xoring all bytes of the message, including the final DLE,ETX. If the chracter DLE occurs in the contents string, it is doubled. Both occurances of the DLE contribute to bcc. Note that they effectively cancel out each other's contribution. Messages to the Adpter do not have the prefix.
DLE doubling, adding DLE,ETX and bcc calculation is done in _daveSendWithCRC(). Prefixing, DLE doubling, adding DLE,ETX and bcc calculation is done in _daveSendWithPrefix().

To Do

Make more PLC functions available.
Test with MPI adapters from third party Vendors.
Create Linux drivers for the PC CP-Cards.
Simatic, Simatic S5, Simatic S7, S7-200, S7-300, S7-400 are registered Trademarks of Siemens Aktiengesellschaft, Berlin und Muenchen.