libnodave/readme

THIS IS EXPERIMENTAL CODE !!!!
DON'T CONNECT TO REAL MACHINERY !!!!

IF YOU CONNECT TO PLCs, EXPECT RANDOM PLC DATA, PROGRAM INCLUDED, TO BE
**** OVERWRITTEN ****

EXPECT OUPUTS TO !!! CHANGE RANDOMLY !!!

EXPECT PLCs TO !!! STOP !!!

EXPECT PLCs TO REQIRE !!! COMPLETE ERASE PROCEDURES !!!

DO NOT run the test programs on PLCs if something is connected to their outputs.
DO NOT run the test programs on PLCs if current state must be preserved.
THE TEST PROGRAMS DO INTENTIONALLY MODIFY PLC MEMORY CONTENTS !!!

To use the test programs, you will have to adapt the name of the serial interface to
your needs.

If you test this code with devices others than those listed in the source code,
please let me know whether the code works with them.

News for release 0.8:
- The Delphi/Pascal glue unit nodave.pas should be fixed now.
- More MPI adapters should work now, among them those from Helmholz (or some of them).
  If your adapter didn't work with former versions, try testMPI with options -2,-3 or -4.
Another FAT WARNING: The following new features are not as stable and well implemented as the old
ones. Expect difficulties, specially in error handling and when connections are interrupted!
- Libnodave can now use CPs and probably every other means of communicating with S7 CPUs
  using already installed Siemens libraries & drivers for transport.
  Of cause, this is for Win32 only.
  To test this use testS7online /S7ONLINE.
  /S7ONLINE is the name of an "access point", in this case the one Step7 uses. Usually,
  the Siemens Software installs a control in System Controls where you can assign physical 
  interfaces to acces points and create new ones.
  
- Libnodave can now use Siemens USB-MPI-Adapters. 
  Under Linux, use the kernel module. 
  This will map the USB device to the first free USB serial port, e.g. /dev/ttyUSB0.
  Then use:
    testMPI -3 /dev/ttyS0
  The -3 is a must. It selects the ONLY variant of "envelopes" around MPI-packets this device
  can use.
  If you cannot use the kernel module, because your kernel is to old or you cannot recompile it 
  for your kernel, try testUSB. This needs libUSB which can handle USB devices from userspace
    testUSB anyNonsense. "anyNonsense" is just a placeholder, because the program prints out
    the usage hints if called with no argument at all. testUSB may work or not. I had to 
    implement a ring buffer in usbGlue.c when I didn't have the adapter any more.
 
  Under Win32 use testS7online together with original Siemens driver and dlls.

- Libnodave can now use the same transport protocol on serial ports Step7 uses with newer 
  adapters. I had to implement it for USB-MPI. You can try it with other MPI-adapters
  specifying option -3 to testMPI or daveProtoMPI3 to daveNewInterface.
- Some MPI adapters that work with option -2 seem to need an STX at some place of in the 
  connectPLC function, others don't. 
  Specifying option -4 to testMPI or daveProtoMPI4 to daveNewInterface does the same as
  option -2 or daveProtoMPI2, but with this extra STX. What works for your adapter is right.
  If -2 and -4 work, what connects faster is right...
- Parts of the AS511 protocol for S5 PLCs have been integrated into libnodave. Beware, they 
  are NOT USEABLE at the moment. Don't mail me about bugs or nonsensical behaviour!!! 

News for release 0.7.2:
- Visual Basic Declarations
- Visual Basic Demo courtesy of ....
- .dll has been compiled with the __stdcall directive. This was necessary for VB. I hope
  it is ok for other languages also.

News for release 0.7:
- Delphi Component and demo courtesy of Axel Kinting.
- Reworked error reporting. Applications will get more detailed information. There should be less
  situations where the library tries to continue current actions while it doesn't make sense any 
  more. 
- Global variable daveDebug is no longer accessible. Use daveSetDebug, daveGetDebug instead.
- Examples how to use the Win32 .dll with C#
- Precompiled .dll generated by MSVC.
- Functions daveGetByte, daveGetWord etc. are no longer present. Use daveGetU8, daveGetS8 etc.

News for release 0.6.3:
Integration of PPI protocol for IBH-NetLink. More complete Pascal interface.

News for release 0.6.2:
Seemless integration of (MPI) protocol for IBH-NetLink. PPI over NetLink is still to do.
Pascal unit should be completely compatible with Borland Delphi now.
Users who miss the readoutXXX, runXXX, stopXXX programs: It's in the main tests now. See the options.

News for release 0.6:
Can load program blocks into CPU over MPI, ISO/TCP and PPI. See testMPIload, testPPILoad.
Can write multiple variables in a single request.
Can use single bit variables in multiple read/multiple write requests.

News for release 0.5:
Unified library for MPI, PPI and ISO over TCP.
Can read timers and counters.
Can read and write single bits.

News for release 0.4:

General:
The following applies to all versions of transport but IBH-Link, as I currently 
have none to do tests :-(
Test programs now take options and the name of the serial port.
They do no longer write to your PLC unless you specify it with the -w option.
daveNewConnection has got 2 new parameters, rack and slot, to specify rack and slot for Ethernet
connections.
More of the common stuff went into daveCommon. This way, all transport variants should benefit
immediately from additional possibilities.
A few functions now return correct error codes.


New Features:
Libnodave can now use Ethernet connections to CPs 243,343,443 and both, IT and non-IT versions
of these.
Libnodave can now readout program and data blocks from a PLC. Try the readoutXXX programs.
Libnodave readout SZL Information. I don't know how this is called in English. It's diagnostic
information. SZL stands for "System Zustands-Liste", literally "System State Lists". You
will get only a sequence of bytes. See Siemens Manuals about their meanings. To try it, use
the -z option on the testXXX programs.


ISO over TCP:
Usage:
type ./testISO_TCP to get some hints.
The program assumes you use a CP 343 or 443 with a CPU on rack 0,slot 2.
If somebody has CPUs/other communicating devices on other positions, she can
specify that in daveNewConnection(). Let me know whether it works.
If you use a CP 243, you must specify the -2 option.
This makes a connection of the same kind as MicroWin does. Your CFG-LED will light.
This does not mean that libnodave changes anything in any configuration.
I saw 3rd party OPC servers using the same kind of connection and I gues they will
light your CFG led as well.
The CPs, at least the 243, begin to send a sort of keepalive packets when the connection
is idle. I don't whether LINUX answers these packets correctly. I doubt the way Siemens
implemented that is fully correct.
Anyway, the CP closes the (ISO or logical, NOT tcp) connection after 30 seconds idle. You 
need to connect again with connectPLC() if this happens, or you will get no more answers.
If your application intentionally polls the PLC less often, you should consider to close
the TCP connection willingly and reconnect completely. This may save money on network
connections you pay by time or volume.

MPI:
I integrated the protocol version found by Andrew Rostovtsew, which had been in the /rostic
subdirectory. You can choose it specifying the option -2 to testMPI. See testMPI source about
how to specify the protocol version. I found that an adapter with order code
6ES7 972-0C821-0XAC (or was it 6ES7 972-0CA21-0XAC ?) worked only with that version.

News for release 0.4.1:

MPI:
Fixed a bug in initialization of TS adapter 6ES7 972-0CA33-0XAC.
Seems it didn?t work since 0.3 :-(
New Features:
Libnodave can now make your PLC stop and run.

THE READING OF MULTIPLE VARIABLES, EVEN IF ALREADY BENCHMARKED, IS NOT YET
USEABLE. YOU CANNOT YET RETRIEVE THE RESULTS !!


News for release 0.4.2:

Applied patch for variable Profibus speed from Andrew Rostovtsew. 
The Profibus speed is a new parameter to daveNewInterface, so you will need to change 
existing programs :-(
The parameter is only meaningful for the MPI protocol. It is meaningful for but 
not yet supported by nodaveIBH. For all other protocols, any integer will do.

Cleaned up most warnings.

Bryan D. Payne compiled libnodave under Cygwin successfully, but tested only
ISO over TCP. I did not quite apply his changes, but cleaned up include directives,
provided support in the Makefile and replaced the byteswap.h he used by
conversion functions that can do without it. This will hopefully also easy porting
to other systems.

THE NEW MULTIPLE READ FEATURE:

The protocol allows to read from multiple addresses in the PLC with a single request,
minmizing overhead and time consumtion. The problem with that is that the result cannot 
be returned as a continous byte array. The reason for this is that one of the addresses 
might not exist, e.g. a data block that is not present in the PLC. So there is an error 
information for each single address and the position the user data in the answer varies.

To use multiple read function, do:

PDU p;
daveResultSet rs;	// a special structure to hold result data


davePrepareReadRequest(dc, &p);			// This prepares a read request
daveAddVarToReadRequest(&p,daveInputs,0,0,1);   // Adds a request to read 1 byte from IB0
daveAddVarToReadRequest(&p,daveFlags,0,0,4);	// Adds a request to read 4 bytes from FB0
daveAddVarToReadRequest(&p,daveDB,6,20,2);	// Adds a request to read 2 bytes from DB6:DBB20
daveAddVarToReadRequest(&p,daveFlags,0,12,2);	// Adds a request to read 2 bytes from FB12
res=daveExecReadRequest(dc, &p, &rs);		// Execute all these requests	
/*
    Now, res has the information whether the entire request succeeded.
    If so, the result set contains the four results and their error states. For the exact 
    structure refer to nodaveCommon.h. To read the data using the conversion functions 
    like daveGetByte, daveGetWORD etc., you have to call daveUseResult(dc, rs, <result number>)
    first. daveUseResult() also returns the error status for this particular result.
*/
res=daveUseResult(dc, rs, 0); // first result

/*
    Last, you should call daveFreeResults() with the daveResultSet, to free the memory
    occupied by it.
*/



News for release 0.5:
    Made a unique library for MPI, PPI and ISO over TCP.
    Protocol specific functions are called via pointers to these functions. The pointers
    are initialized in daveNewInterface depending on the choosen protocol.
    As some users reported problems using shared libraries, this is how to do it:
	type make		This will build statically linked test programs and the 
				shared libraries libnodave.so and libnodaveIBH.so.
	type make install	This will copy the shared libraries to /usr/local/lib and
				invoke ldconfig. Now the libraries are available to both, linker
				and program loading mechanism. You may need root rights to execute
				this step successfully.
	type make dynamic	This will build dynamically linked versions of the test programs
				testMPI, testPPI and testISO_TCP named testMPId, testPPId and 
				testISO_TCPd.
				
Have Fun !