SampLin 1.3                 Samuel Kvasnica                        29.11.1998

This file contains brief instalation, compilation and usage instructions for
SampLin version 1.3. This is the only documentation at the moment. Features
marked as (*) are still under development. NOTE THAT SAMPLIN 1.3 SCRIPT
LAGUAGE SYNTAX DIFFERS FROM PREVIOUS VERSIONS (array operations, graph and device
commands), THUS YOU'LL HAVE TO UPGRADE YOUR SCRIPTS A BIT.


SampLin Home Page is located at sites:

http://www.iaee.tuwien.ac.at/sensor/samplin
http://www.troja.mff.cuni.cz/~kvasnica/samplin.html

For comments, bug-reports and questions contact me at email address:
kvasnica@iaee.tuwien.ac.at. Please read this README as well as BUGS 
and TODO files (and try to find out the problem yourself in source
code) before contacting me. In case of segfault uncomment debug
option at first line of Makefile, compile again and try to debug
core dump after crash. Use `ulimit -c unlimited' to get coredump in
bash.


CONTENTS

0  Introduction
1  Compilation
2  Instalation
3  Usage 
3.0  Comptibility
3.1  Running SampLin
3.2  Configuring devices
3.3  Remote devices, network support
3.4  Script programming
3.5  Script commands
4  Device drivers
5  Acknowledgements


0. INTRODUCTION

SampLin is Scientific Data Acquisition, Visualization and Process Control
software for Linux and other unix platforms.

I started writing SampLin in september'97 just to be able to control mass
and optical spectrometers and other devices in our plasma lab at TU-WIEN.
The reason was I didn't find anything suitable for Linux except some clever
advices to use Tcl/Tk.

I needed _stable_ software running _stable_ OS. I needed software to control
variety of devices connected via serial, GPIB ports or Labcards; to process,
display and load/save/print acquired data. This software had to be really 
universal to enable to connect devices with very different control algoritms,
data formats and data processing. It was desired to control more devices
simultaneously using one computer. Remote control over TCP/IP was also
desired.

SampLin has been build around script language based on YABASIC and Qt
toolkit. The script language implements default BASIC commands, commands for
creating and maintaining dialog windows with widgets and commands for easy data
transfer and visualization. It's interpreted language but don't be afraid,
it's not so slow. Before execution a kind of precompilation takes part.

I don't claim SampLin currently flawlessly solves all problems mentioned above.
But it tries to. It has been proved to be very useful and reliable in our lab.
There are many new features to add and many old features to tune up. To write
versatile and reliable software it's important to test it in variety of 
environments and with variety of devices. That's why I need your feedback and
help.

SampLin is distributed under the terms of GPL. For copyright details see file
LINCENSE. 


1. COMPILATION

To compile SampLin you'll need Linux 2.0, gcc > 2.7.2.1, X11R6 3.3, Qt > 1.40
(www.troll.no), KDE one libs (www.kde.org) and drivers from Linux gpib library 
package (www.llp.fu-berlin.de). SampLin should run also other unix systems
but has been tested only on Linux so far. The essential porting problem would
be the drivers from gpib library which support only linux. I've been told
SampLin compiles and works also with libc6.

Since version 1.2 SampLin doesn't use the gpib library, it communicates directly
with gpib drivers. That means, you have just to install the gpib drivers if you
need GPIB support. If you don't need GPIB support, you don't need anything from
gpib library package.

If you'd like to play around with script language grammar you'll also need
flex++ and bison++ (flex and bison won't work). Flex++ and Bison++ generated
.cpp files are included so normaly you won't need flex++ and bison++.

Download the SampLin package SampLin_x.y.z.tar.gz (x.y.z stands for
version number). Unpack the package using `tar -zxf' or `gunzip; tar -xf'
commands. 

`cd SampLin'

Look into Makefile. Check the paths, especially if your X11, KDE and Qt
root directories differ from /usr/X11, /usr/local/KDE, /usr/local/qt.

`make'

If everything works, you should get the executables ./SampLin,
./Net/rdevice_svc and ./Sgpib/Net/rgpib_svc.


2. INSTALATION

To install SampLin place the SampLin executable somewhere on your path, e.g.
/usr/local/kde/bin. Copy icons from Icons directory to
/usr/local/kde/share/apps/SampLin/pics or somewhere to $HOME/.kde/share/aps...

If you'd like to look at sample scripts and sample graph data, copy files
from directories Examples/Data and Examples/Scripts to $HOME/SampLin/Data and
$HOME/SampLin/Scripts. Script file `widgets.Script' demonstrates usage of
various widgets, `flow.Script' is script to control MKS flow controllers
using Advantech PCL818 and PCL727 cards, `qms.Script' controls BALZERS QMG420
quadrupole mass spectrometer over serial port.


3. USAGE

3.0 COMPATIBILITY

SampLin graph and device configuration files are only forward compatible.
It means SampLin 1.3 files are not readable by SampLin version < 1.3.
However you can use SampLin 1.3 to open old files, they'll be automatically
converted to new format during save operation. Version 1.3 has a bit
different script syntax, so you'll have to change your 1.2 script files a bit.

3.1  RUNNING SAMPLIN

SampLin [scriptfile]

After invoking SampLin without parameters, main window appears. If running
the first time SampLin creates the directories $HOME/SampLin/Data,
$HOME/SampLin/Scripts and config file $HOME/kde/share/config/SampLinrc. 

Use menu items File/New,Open,Save,SaveAs to create new, open existing, or
save script. (By default in directory $HOME/SampLin/Scripts.) File/Ext.editor
opens current script in external editor. Use Script/Run, Stop,Step,Goto,Reset
to run, stop, step one line, go to line at cursor or reset (stop and initialize)
current script.

Graph/New graph opens new graph window. This can be used to load/edit/export
(text,BMP,Qt Pic)/ print(postscript)/save existing graph data. (By default 
located in $HOME/SampLin/Data directory.)

Samplin may be invoked with script name as parameter. If the full path
doesn't exit, it will look for it in your $HOME/SampLin/Data directory.

Configuration/Preferences opens dialog with program and script language
options.

Section PATHS contains edit fields for SampLin root directory name and
it's subdirectory names where SampLin looks for scripts and data by
default. Edit field `Devices file' contains the name of the file where
SampLin stores device configuration. `Ext editor' contains name of external
editor invoked by File/Ext.editor, for e.g. `xterm -e jed %f', %f will
be replaced by file name. Section Script contains script language options:

  Infolevels sets the level of interpreter messages

  Error      - report only severe errors that disable to continue the execution
  Warning    - report also warnings such as `Unable to open device' etc
  Note       - report more details about program parsing and execution, i/o
               operations
  Diagnostic - report everything: parsing/compilation details, useful for
               interpreter diagnostics
  	     
  Output/Messages selects output destination for interpreter messages and
  print output. `Window' sends messages to SampLin main window, `stdout/stderr'
  prints messages to the terminal from which was SampLin invoked.

Use Configuration/Devices to define your devices. See section 3.2 for details.

For all frequently used menu commands there are appropriate buttons located
on toolbar.


3.2  CONFIGURING DEVICES

Menu item Configuration/Devices invokes device configuration dialog. New,Copy,
Rename and Delete buttons located at bottom are used to create new, copy, rename
or delete device selected in the list box. 

The *name* of the device entered when creating new, copying or renaming device
will be used later to control it from within the script language. 

It's necessary to define device parameters for new device in *Path*, 
*Common options*, *Serial options* and *GPIB options* section of the dialog. 

*Path* section

Field `Path' contains device path - e.g. /dev/ttyS0 for first serial port,
/dev/gpib0/master for first linux-gpib card etc. DON'T PUT GPIB-LIB DEVICE 
NAME IN THIS FIELD ANYMORE, SAMPLIN USES GPIB DRIVERS DIRECTLY. YOU 
EITHER DON'T NEED TO CONFIGURE GPIB DEVICES IN /etc/gpib.conf. In case of
remote device place the host name into the `Host' edit field. Type in some
description of the device into the `Title' field (optional).

*Common options*

Three type of devices can be defined: GPIB, Serial or Void (e.g. Labcards).
Select appropriate type from combo box `type'. In case of serial/GPIB device
fill out also the *Serial options* / *GPIB options* section of dialog. 
Select big or little endian option from `Endian' combo. (Usually little for
Intel-based devices and big for Motorola-based devices). Click `Read enable'
`Write enable' to enable reading or/and writing from/to the device. Fill in
default delay in microseconds after device write in `Delay' field. Put default
timeout for remote devices in seconds into the `Net timeout' field.
(*) Type in hexadecimal code of the `end of string' character into the `EOS'
field.

*Serial options*

Select `Baud rate', `Data bits', `Stop bits' and `Parity' for serial
device.

*GPIB options*

Type in GPIB bus address of the device into the `GPIB address' fiels.
(*) Check `Bus master device' for bus controlles (board). 
(*) other gpib options comming in next version.

Device configuration is stored in file Samplin.devices located in
$HOME/.kde/share/apps/SampLin

3.3  REMOTE DEVICES, NETWORK SUPPORT

For remote devices fill in the host name where device is connected into the
`Host' field as mentioned in section 3.2 *Path*. Nothing else is needed to
configure on client side. Since SampLin remote features use the RPC to
comunicate with server, you need the RPC portmapper running on both client
and server side. For GPIB devices you'll need to run rgpib_svc executable
(./Sgpib/Net/rgpib_svc) on your server. For serial or void devices you need
to run the rdevice_svc executable found in ./Net directory. They must be run as
root in order to register RPC service. rdevice_svc allocates service number
0x20004321, rgpib_svc number 0x20004322. Invoking rdevice_svc or rgpib_svc with
`--debug' option will cause them to print all requests and device operations
on console. Device permissions file /etc/rdevice.conf is needed in order to
enable access to serial and void devices from remote host. Sample rdevice.conf
file is included in this `Doc' directory. It contains one line per device,
each line contains device path, `:' colon separator and comma separated host
list (adresses or IP numbers). File /tmp/rdevice.status shows opened devices
along with hosts name, uid, gid, fd and flags. Note that rdevice server is
limited by maximum opened files per process which is usually 255. There's NO 
rgpib_svc authentication by now, but it'll come soon. DON'T use rgpib_svc from
linux-gpib library package with SampLin, it won't work (not only because it 
uses different service number).


3.4  SCRIPT PROGRAMMING

SampLin script language is based on YABASIC. Thus read file yabasic.txt to
learn the syntax of language. Note that WIN95 features as well as drawing
features have been removed. Next section contains list of all script
language commands. However only SampLin specific commands are described
particulary.

To communicate with devices, device *names* defined in device configuration
dialog (section 3.2) are used.

!!! IMPORTANT CHANGES IN VERSION 1.3:

1. Since version 1.3 all array operations use [] brackets instead of ().
It means DIM A[10], not DIM A(10). Similar A[1]=A[2]+3. If passing array as
argument square brackets are also required: DEVREAD QMS, A[], 10,1

2. DEVRD, DEVRDB, DEVWR, DEVWRB commands have been removed; DEVREAD, DEVWRITE
are used for both binary and ascii transfers.

3. Graph commands have changed. See ADDPLOT and SETPLOTDATA commands in
section 3.5



3.5  SCRIPT COMMANDS

REM, `#' - comment
FOR, TO, STEP, NEXT - cycle FOR i = 1 to 10 STEP 2: ... : NEXT i
GOTO label - jump to label
GOSUB - call subroutine label
ON num GOSUB label1, label2... - call subroutine depending on value of num
LABEL label - label of subroutine
RETURN - return from subroutine
END - end of program
IF,THEN,ELSE,ENDIF (or just FI) - condition
OPEN,CLOSE - open, close file
PRINT - print string, value
DIM - dim an array, e.g. DIM A[10]
DATA - define data
READ - read from data
RESTORE [label] - restore to pointer to beginning of data at label
WAIT num, PAUSE num - make pause of num seconds, use for long delays
SLEEP num - sleep for num miliseconds, use for short delays only !
BELL, BEEP - make sound
AND, OR, NOT - logical binary operators
SIN(), ASIN(), COS(), ACOS(), TAN(), ATAN(), EXP(), LOG(), SQRT() 
- various math functions
INT() - return integer part of value
FRAC() - return fraction part of value
RAN() - random generator function
LEFT$(),RIGHT$(), MID$() - string operators
LEN() - return lenght of string
VAL() - return string value
STR$ - convert value to string
CHR$ - convert ASCII value to string
ASC - convert string character to ASCII value

DATE$ - contains current date
TIME$ - contains current time

TIMER ON|OFF - start or stop time; variable timer_sec will be incremented
every second, timer_msec every milisecond. Note that with timer enabled 
program execution will become slowlier. That's because gettimeofday() is
called after every program step. I have no idea how to make it better now.

MESSAGE [type,] mesg$
- shows a message dialog containing text mesg$ and Ok button. `Type' can be
  empty, INFO, WARNING or ERROR. Default is INFO.

INPUT [title] variable 
- input string or value (using input dialog) into `variable'. `Title' is
  string to be displayed as prompt. Current value of `variable' will be 
  displayed in input field.

CURSOR type
- change cursor icon for all active dialogs. `Type' is DEFAULT for normal arrow
  icon or WAIT for clock icon.

DEVOPEN name - open device `name'

DEVCLOSE name - close device `name'

DEVREAD name, string$ [,len]
- read ascii string$ from device `name', len is maximum lenght

DEVREAD name, array[], lenght, size 
- read binary data from device `name' to array[]. Array must be dimmed
before as 1-dimensional array of values. `Lenght' is number of items to read. 
`Size' is size of items in bytes. If `size' is equal 0 then item size in 1 bit.
Order of read bytes when composing an item depends on little/big endian 
setting in device configuration dialog. Use negative value of size (with 
absolute value of item size) for signed conversion.

DEVWR name, string$ [,len]
- write ascii string$ to device `name', len is maximum lenght

DEVWRITE name, array[], lenght, bytes
- write binary data to device `name' from array[]. Array must be dimmed 
before as 1-dimensional array of values. `Lenght' is the number of array items
to write. `Bytes' is the number of bytes each array value is separated into
before writing to device. Order of bytes written to device depends on
little/big endian setting in device configuration dialog. Zero and negative
value of `bytes' have similar meaning as DEVREAD parameter `size'.

DEVCTL name, service, param
- performs IOCTL call to device `name', integer number of service `service',
  integer parameter `param'

DEVREADY(name)
- this function returns 1 if there are data available to read from device
  `name', otherwise returns 0. Useful when waiting for data on serial port.
  
DEVSPOLL(name)
- serial poll GPIB device `name'

ADDGRAPH name$
- open new graph window called name$

DELGRAPH name$
- close graph window called name$

LOADGRAPH name$ [, file$]
- load data into graph `name$' from file `file$'. If called without 
  specifying `file$', file open dialog will be opened.
  
SAVEGRAPH name$ [, file$]
- save graph data, look LOADGRAPH

EXPORTGRAPH name$ [, file$]
- export graph data, look LOADGRAPH

PRINTGRAPH name$
- print graph name$

SETGRAPHTITLE name$, title$
- change graph name$'s title to title$

SETGRAPHCOMMENT name$, position [, comment$]]
- change graph name$'s comment to comment$, position in None, Bottom or Right;
  comment$ is optional

SETGRAPHLEGEND name$, position
- display graph name$'s legend, position in None, Bottom or Right

SETGRAPHCOLORS name$, pcolor$, bcolor$
- change graph name$'s plot area color to pcolor$ and background color to
  bcolor$

ADDPLOT name$, plotname$
- adds new empty plot series plotname$ to graph name$

SETPLOTDATA name$, plotname$, arrayX[], arrayY[], [len]
- sets plot series plotname$ data in the graph name$. X data are taken from
  1-dim array `arrayX'. Y data are taken from 1-dim array `arrayY'. You can 
  restrict data lenght using `len'

SETPLOTDATA name$, plotname$, begin, step, arrayY[], [len]
- sets plot series plotname$ data in the graph name$. X data begin at `begin',
  X axis step has a value of `step'. Y data are taken from 1-dim array `arrayY'.
  You can restrict data lenght using `len'  

SETPLOTDATA name$, plotname$, arrayX[], begin, step, [len]
- sets plot series plotname$ data in the graph name$. Y data begin at `begin',
  Y axis step has a value of `step'. X data are taken from 1-dim array `arrayX'.
  You can restrict data lenght using `len'

GETPLOTDATA name$, plotname$, arrayX[], arraY[]
- get X and Y data from graph name$, series plotname$ to 1-dim arrays
  arrayX, arrayY

SETPLOTSTYLE name$, plotname$, style
- change plot style, style = None, Line, Sticks, Dots or Spline

SETPLOTPEN name$, plotname$, style, width, color$
- change plot pen, style = None, Solid, Dash, Dot, Dash-dot or Dash-dot-dot;
  width is line width and color$ is pen color

SETPLOTSYMBOL name$, plotname$, style, width, size, fcolor$, lcolor$
- change plot pen, style = None, Circle, Rectangle, Diamond, Triangle,
  DTriangle, UTriangle, LTriangle, RTriangle, Cross or XCross; width is
  symbol outline width, size is symbol size, fcolor$ is fillcolor and
  lcolor is outline color

SETPLOTAXES name$, plotname$, axis1, axis2
- assigns plot series plotname$ in graph name$ to X,Y axes axis1, axis2. 
  Possible values for axis1 & axis2: Left, Right, Bottom, Top. Default
  setting is Bottom, Left.

SETAXISTITLE name$, axis, title$
- changes axis title for `axis' in graph name$ to title$. For `axis' values
  see SETPLOTAXES.

SETAXISSTYLE name$, axis, style [,prec]
- changes axis label style for `axis' in graph name$. Style is None,
  Scientific,General or Fixed. prec is optional precision.

SETAXISSCALE AUTO [,ref [,minor]]
- sets axis autoscaling feature on, ref is reference point, minor is max.
  number of minor tics (optional)
  
SETAXISSCALE min,max,step [,ref [,minor]]
- sets axis manual scale, min is minimum value, max maximum and step is major
  tic step (0 mean automatic); ref is reference point, minor is max. number
  of minor tics (optional)

SETAXISFLAGS name$, axis, flag1 [,flag2 [,flag2 ...]]
- sets axis flags, specify as many as desired of these: LOG (logaritmic),
  SYM (symmetric), INV (inverted), REF (include reference), FLT (floating)

DELPLOT name$, plotname$
- removes plot plotname$ from graph name$

MULTI ON|OFF
- MULTI OFF disables receiving signals from dialog widgets. MULTI ON enables
  receiving signals again. Useful if communication with device may not be
  disturbed.

IDLE
- call this in a loop where your programs has nothing to do (waiting for data
  etc.) It will increase widgets response.

PROGRESSDLG [text$ ,] step
- call this with both parameters to initialize progress dialog. `Step' is
  total number of steps, text$ message to be displayed. Subsequent calls 
  with one paramater `step' will update progress bar. Variable `progress_cancel'
  will be equal 1 is dialog was cancelled, otherwise 0. Note that dialog will
  apear only if estimated total time (estimated during first step) is >3 sec.

ADDDLG name, title$
- creates new dialog called `name' with caption title$

DELDLG name
- deletes dialog called `name'

SHOWDLG name
- show dialog called `name'

HIDEDLG name
- hides dialog called `name'

DLGACTIVE(dlg)
- returns 1 if dialog `dlg' is active, otherwise 0

ADDWIDGET name, type, x,y,w,h, ...
- add widget into the dialog called `name'. Type may be one of: FRAME, TEXT,
  BUTTON, SWITCH, LCD, LED, SELECT. x,y,w,h are left top coordinates and 
  width and height of widget. Widget specific parameters follow:
  
  FRAME ..., flags, width
  - Draws a frame. `flags' specify frame type (0 no frame, 1 box, 2 panel, 3
    winpanel, 4 horiz. line, 5 vert. line + 0x10 plain, 0x20 raised, 0x30
    sunken ), `width' is width of frame in pixels

  TEXT ..., text$
  - Puts text into dialog. text$ contains string to be displayed
  
  BUTTON ..., text$, label
  - Places a push button into the dialog. text$ contains button title,
    `label' is the subroutine label to be called upon button press 

  SWITCH ..., text$, label, variable
  - Places a switch (check box) into the dialog. text$ contains switch
    title, `label' is the subroutine label to be called when switch changes
    its state, switch state is stored into `variable' On = 1, Off = 0

  LED ..., variable, text$, color$
  - Places a led diode into the panel. `variable' determines led state (0
    light Off, <> 0 light On), text$ is led title,  color$ led light color.
  
  LCD ..., prec, format , variable, color$
  - Places an lcd display into the dialog. `prec' is the display precision
    (number of decimal places to be displayed), `format' selects format 
    (0 decimal, 1 scientific, 2 octal, 3 binary, 4 hexadecimal), `variable'
    is the variable to be displayed, color$ determines the color of lcd
    segments
  
  SELECT ..., array$[], variable
  - Places an select widget (combo box) into the dialog. array$[] is a string
    array containing the labels to fill the select widget with. `Variable'
    is set to index of selected string from array$.

  GRAPH ..., name$
  - Places graph widget into the dialog. name$ is name of the graph. Behaviour
    is the same of the graph window.
  
  KNOB ..., from, to, step, variable
  - Places potentiometer knob into the dialog. Range of the knob is defined
    by `from' and `to' values, step by `step' value. `variable' will contain
    current position (setting) of the knob.
  
  SLIDER ..., from, to, step, variable, scale
  - Places slider control into the dialog. Similar as KNOB. For `scale' = 0,
    no scale will be displayed, for `scale' 1 resp. 2 scale will be displayed 
    in the top resp. left or bottom resp. right position depending on 
    widht/height ratio.
  
  LEVEL ..., scalewidth, from, to, variable, scale
  - Places level indicator into the dialog. `scalewidth' is width of scale
    in pixels to be drawn.  For `scale' = 0, no scale will be displayed, for
    `scale' 1 resp. 2 scale will be displayed in the top resp. left or bottom
    resp. right position depending on widht/height ratio.

4. DEVICE DRIVERS

There are 2 drivers for Advantech PCL-818 and PCL-727 cards included in
Drivers directory. These drivers are experimental only. PCL-818 driver
supports only autodetect configuration and A/D, D/A input/output by now.
PCL-727 supports only D/A output. Type `make' to compile drivers. Run
`insmod devname.o' as root to insert driver to kernel. pcl818dev.tgz
and pcl727dev.tgz contain device files to be created in /dev directory.
Use `forceirq=IRQ' argument when running  insmod pcl818.o to force driver
to use interrupt IRQ. Use `base=ADDRESS' argument when running insmod
pcl727.o to tell driver card base ADDRESS. I don't know why, but PCL818
card doesn't work with IRQ 6. 
Driver for PCL812 card has been contributed by Dani Pardo and included in
Drivers/pcl812 directory. I didn't test it by now since I don't have PCL812
card, but looks to be similar to PCL818.

5. ACKNOWLEDGEMENTS

I'd like to thank especially following people for their work:

- Richard Stallman for the wonderfull idea of GNU GPL 
- Linus Torvalds for starting Linux project (Without Linux I'd be still one
  of the damned (l)users of Micro$oft software)
- Troll Tech team (www.troll.no) for writing Qt tookit and releasing free
  edition.
- ? (ihm@kph.uni-mainz.de) for writing YABASIC which has become predecessor
  of SampLin's script language
- People around the KDE project for creating 1st consistent and free desktop
  for linux
- Claus Schroeter (www.llp.fu-berlin.de) for writing the Linux GPIB package
- Josef Wilgen (jwlg@mail.desy.de) for writing Qwt - The Qt Widget Library for
  Technical Applications
  
... and everybody else who helped me with SampLin development.
