Read Me

PYCONTROL / QPYCONTROL README
=============================

THIS IS ALPHA CODE!

IF IT BREAKS, YOU CAN KEEP BOTH PIECES!


The purpose of this software (besides being a playground for me to try
some ideas) is to make it simple to create an interface to a SIEMENS
or compatible PLC. Simple means you create a CSV file describing the
process values and pycontrol takes that file and creates the UI from
it. It also means there is no possibility for doing layout or design
other than the order of the process values in the CSV file.

Pycontrol uses libnodave (http://sourceforge.net/projects/libnodave/)
to talk to the PLC. You need to download and install a libnodave
suitable for you OS to use pycontrol. I've tried it on Debian Lenny,
Ubuntu 10.04/10.10 and Maemo 5 (Nokia N900) and Windows XP and 7
32bit. It might work on OSX too, but the loading of libnodave in
module plc.py might have to modified to detect OSX and do the
appropriate thing to load libnodave.

There is a GTK+ and a Qt Version of the UI code which use the same PLC
communications module plc.py. The Qt version reacts to resizing the
window by reorganizing the widgets either in 1 column or 2 column mode
depending on the aspect ratio of the window. The GTK+ version can't do
that. On Maemo the Qt version does kinetic scrolling, the GTK+ version
doesn't. I think Qt is better adapted to the different platforms and
plan to work more on the Qt version in future.


CSV File
--------

There is a sample CSV file main_window.csv which demonstrates possible
types of process values and widgets. The file must be encoded in
utf-8. The first row of the CSV file must contain the column labels:

'id','name','type','db','addr','size','bit','write','error','rb_group','format'

The order of the columns doesn't matter. Text values must be quoted
using single or double quotes and the separator may be comma or semicolon.

id:	  		 an unique id string identifying the process value
name: 		 the name which shows up in the UI for that widget
type:		 the SIEMENS data type of the process value. Possible
			 types are: u8, s8, u16, s16, u32, s32 (unsigned or signed
			 integer types), float, string and bit
db:			 db number
addr:		 offset address into the db
size:		 only needed for strings: the length of the string in
			 bytes including the 2 length bytes. 2 + the max. number
			 of characters the string can hold.
bit:		 only for bits: the bit number
write:		 1 if the value should be writable
error:		 only for bits: this is an error bit. Use an error
			 indicator widget to display. Error indicators are only
			 shown when the bit is True. An error indicator with a
			 name value starting with E: is shown as an error. A W:
			 means a warning and I: means informational text. All
			 other names are shown as infotext too.
rb_group:	 only for writable bits: this button belongs to a radio
			 button group. All buttons in the same group have the same
			 number in that column
format:		 only for float values: python format string used to
			 format the value. %2.4f means 4 decimal places and 2
			 characters minimum field width


Debug
-----

Pycontrol has a test mode (option -t) which works without an actual
PLC. When connecting it instead loads the file pickled_dbs.dat and
reads process values from there. The data in that file matches the
sample CSV file main_window.csv.


Latest Version
--------------

Since this is Python there are no binaries. Get the latest version
from subversion:

svn co https://pycontrol.svn.sourceforge.net/svnroot/pycontrol pycontrol