This file contains brief installation, compilation and usage instructions for SampLin version 1.3.1. This is the only documentation at the moment. Features marked as (*) are still under development. NOTE THAT SAMPLIN >= 1.3 SCRIPT LANGUAGE SYNTAX DIFFERS FROM PREVIOUS VERSIONS (array operations, graph and device commands).

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 file 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 configure with debug option, compile again and try to debug core dump after crash. Use `ulimit -c unlimited' to get core dump in bash.
 

CONTENTS
 

0. Introduction
1. Compilation
2. Installation
3.  Usage

3.0 Compatibility
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 Acknowledgments

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 advice 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 Lab cards; 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 algorithms, 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 tool kit. 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 pre compilation takes part. Currently the script language started to evolve into a kind of C-like language.

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 COPYING.
 

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 >= 1.0 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 normally 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'

Read the `INSTALL' file for installation instructions. Start the configure script (use --enable-debug to compile with debug info):

`./configure'

And build SampLin:

`make'
 

2. INSTALLATION

To install SampLin you need just to type:

`make install'

SampLin will be installed by default under $KDEDIR. Use --with-install-root= option to specify different root directory at configure time.

If you'd like to look at sample scripts and sample graph data, copy the directories $KDEDIR/share/apps/SampLin/examples/Data and $KDEDIR/share/apps/SampLin/examples/Scripts to $HOME/SampLin. 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.

Driver modules for PCL Lab cards can be found under $KDEDIR/share/apps/SampLin/modules. Remote server executables are in $KDEDIR/share/apps/SampLin/remote.
 

3. USAGE

3.0 COMPATIBILITY

SampLin graph and device configuration files are only forward compatible. It means SampLin 1.3.1 files are not readable by SampLin version < 1.3 However you can use SampLin 1.3.1 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 [script file]

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

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. Lab cards). 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' fields. (*) Check `Bus master device' for bus controllers (board). (*) other gpib options coming 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 communicate 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 ($KDEDIR/share/apps/SampLin/remote/rgpib_svc) on your server. For serial or void devices you need to run the rdevice_svc executable found also in `remote' subdirectory. 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 (addresses 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, sorry. 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 particularly.

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 milliseconds, use for short delays only !
BELL, BEEP - make sound
AND, OR, NOT - logical binary operators
&, |, ~ - binary operators AND, OR, XOR
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 millisecond. Note that with timer enabled program execution will become slower. 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.

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.

Change cursor icon for all active dialogs. 'Type' is DEFAULT for normal arrow icon or WAIT for clock icon

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.

DEVWRITE name, string$ [,len]

Write ascii string$ to device `name', len is maximum lenght

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'.

Performs IOCTL call to device `name', integer number of service `service', integer parameter `param'

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.

Serial poll GPIB device `name'

Open new graph window called name$

Close graph window called name$

Load data into graph `name$' from file `file$'. If called without specifying `file$', file open dialog will be opened.

Save graph data, look LOADGRAPH

Export graph data, look LOADGRAPH

Print graph name$

Change graph name$'s title to title$

Change graph name$'s comment to comment$, position in None, Bottom or Right; comment$ is optional

Display graph name$'s legend, position in None, Bottom or Right

Change graph name$'s plot area color to pcolor$ and background color to bcolor$

Adds new empty plot series plotname$ to graph name$

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'

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'

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'

Get X and Y data from graph name$, series plotname$ to 1-dim arrays arrayX, arrayY

Change plot style, style = None, Line, Sticks, Dots or Spline

Change plot pen, style = None, Solid, Dash, Dot, Dash-dot or Dash-dot-dot; width is line width and color$ is pen color

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

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.

Changes axis title for `axis' in graph name$ to title$. For `axis' values see SETPLOTAXES.

Changes axis label style for `axis' in graph name$. Style is None, Scientific,General or Fixed. prec is optional precision.

Sets axis autoscaling feature on, ref is reference point, minor is max. number of minor tics (optional)

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)

Sets axis flags, specify as many as desired of these: LOG (logaritmic), SYM (symmetric), INV (inverted), REF (include reference), FLT (floating)

Removes plot plotname$ from graph name$

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

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

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 canceled, otherwise 0. Note that dialog will appear only if estimated total time (estimated during first step) is >3 sec.

Creates new dialog called `name' with caption title$

Deletes dialog called `name'

Show dialog called `name'

Hides dialog called `name'

Returns 1 if dialog `dlg' is active, otherwise 0

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

INPUT ..., variable$

Puts input field into dialog. Entered data will be stored into variable$

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. Behavior 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, color$, 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. color$ is indicator color.

There are 2 drivers for Advantech PCL-818 and PCL-727 cards included in $KDEDIR/share/apps/SampLin/modules 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. 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 in my computer. Driver for PCL812 card has been contributed by Dani Pardo and included in src/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 wonderful 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