ScriptContext describes a system for asynchronous drivers in SICS/SEA written in Tcl. Such a driver is a collection of initialization and action scripts. The action scripts are called from the ScriptContext system within a certain context: a sics hipadaba node and a controller object.
to be done
If different drivers share common code, the common code may be placed in ~/sea/tcl/common/. The individual drivers may then contain only an appropriate source command.
The idea behind this scheme is, to have to edit only one list when adding a new feature. The aim is not to make the source code shorter. In fact, the initialization code is just moved from a central place to the modules. The main goal is to have a better structure of the code, which should be easier to maintain, and less error-prone.
Let us look at the difference when adding a command or driver. Before using this scheme, there were many different places in psi/psi.c where modifications had to be added:
when adding a new command:
when adding a new driver:
With the new scheme, for a module one has one init function, with prototype "void (void)" placed in the source file of the module. In this function, you call AddCmd, AddIniCmd or AddCommand(SCinter.h) to insert a standalone command, startup command or an object command. To create a new driver, use either the MakeDriver function, if you want to use the MakeObject command to create the driver, or the functions MakeInitializer/GetInitializer, if you want to do use an other factory command (see initializer.h). The init function has to be added to the system by inserting one line to the SiteInit (psi.c) or InitGeneral (ofac.c) function.
Suggestion by Markus Zolliker
At present, only the new stuff I inserted uses this scheme. I propose to move to the new scheme during next shutdown.
ofac.c:
psi.c:
These modifications will not change the behaviour of SICS.
A remote object is a link to an object on an other SICS server. The remote object behaves almost equally as if it would live on the same server. At present, the driveable and the callback interface ist supported.
For any remote server supported, there is a remserver object which may be created with the command
remob server <remserver> <host>:<port>
where <remserver> is the name of the remserver object, <host> is the host running the remote SICS server, and <port> is its ServerPort. The remserver may be used to execute commands on the other server.
The result of any command is returned transparently. There is only one visible diffrence: all lines are prefixed with 2 spaces. Messages emitted on the remote server are forwarded to the master client. During a drive or run, the master client is the starting client. If no remote object is driving, any command executed on a client with at least user right makes it a master client.
A string object is similar to a SICS variable (created with VarMake) but with the following differences:
Creating a StrObj variable is done with
makeobject <variable name> stringSetting the value has a different syntax from SICS variables:
<variable> = <value>This syntax is used for all variables based on pardef. It is used in order to have a clear distinction between a subcommand and setting the main value of an object. If someone wants to perform the interest subcommand, and writes vars intrest and vars is a StrObj, then an error message is written because of the typo. If vars would be a SICS variable, its value would get overwritten, which is a less desired behaviour.
The variable vars is a special variable of this type, used by the graphical sea client to obatin a list of variables beeing to be plotted. The value is a space delimited list of variables. After each variable, an identifier might be put, separated with a slash, indicating the plot window to be used. A convention is to put the unit name as identifer for the plot window. Example:
vars = te/K te.t2/K te.htr/%On the graph, two plots will appear, in the first plot the variables te and te.ts are shown, in the second the variable te.htr is shown.
Drivers for sample environment (SE) have some special demands which were not fully supported by the original SICS environment controller (EVC):
pardef.c contains the implementation base class ParData for a new type of SICS object. It contains parameter definition, parameter handling, parameter listing, logging and storing. The parameter definiton function is the heart of any object based on pardef. This function is called by the system for different actions which can be performed on an object.
ease.c contains two classes: EaseBase inherits ParData. It includes the finite state machine, and the handling of a serial connection to the hardware. EaseDriv inherits EaseBase. It makes the object driveable.
fsm.c is the implementation of a simple processor. The tasks which can be executed are functions (FsmFunc) which contain a switch statement, where every case is a step of the task to execute. When combined with EASE, the individual steps normally end with a command written to the device. After any step, the FsmFunc returns the line number of the next step. The system calles the FsmFunc again, when the response is ready. FsmFuncs might be nested.
For a driver, one needs to define
For a list of predefined parameters and subcommands see EaseParametersAndCommands
For list of a available drivers based on EASE see EaseDrivers
(c): command
(r): read-only parameters
(w): writeable parameter. The value has to be added to the command.
Command Syntax DescriptionStandard commands defined for all objects based on pardef
<obj> list (c) make a list of most important parameters. listed
are all parameters defined with a call to ParTail
and not ParList, or with a call to ParList(NULL)
<obj> list all (c) make a full list of all parameters
<obj> list <group> (c) make a list of only a group of parameters. listed
are all parameters defined with a call to
ParList("<group>")
<obj> log <par> (c) switch the logger on for parameter <par>. logging
is on by default, off when defined without an
explicit call to ParSwitch(NULL)
<obj> log <par> <sugar> (c) switch the logger on for parameter <par>, giving
a sugar name (see [SicsSugar])
<obj> unlog <par> (c) switch the logger off for parameter <par>
<obj> sugar (c) return a list of sugar parameters
<obj> save <par> (c) switch on status file saving for parameter <par>
is on by default for changeable parameters, or
when explicitley defined with a call to ParSave
<obj> unsave <par> (c) switch off status file saving for parameter <par>
<obj> interest (c) switch interest callback on. every change will
be notified to the calling client
<obj> uninterest (c) switch interest callback off
Parameters defined in ParStdDef
<obj> verbose (w) verbosity. 0 is quiet, 1 is standard
2 is verbose (logging all serial communication)
<obj> driver (r) driver name
<obj> creationCmd (r) command to create this object
Parameter defined by EaseBasePar
<obj> restart (c) reconnect serial connectionParameter defined by EaseSendPar
<obj> send <command> (c) send a serial command. Warning: the response is
delayed and can therefore not be used in scripts.
Parameters defined by EaseDrivPar
<obj> upperLimit (w) upper limit of target value
<obj> lowerLimit (w) lower limit of target value
<obj> tolerance (w) tolerance
<obj> maxwait (w) maximal time to wait for target value (sec)
or 0 for infinite wait
<obj> settle (w) time to wait after target value is within tolerance
<obj> targetValue (r) target value
Parameter defined by EaseMsgPar
<obj> status (r) connection status of the device (empty when normal)
A sugar variable is an alias to an object parameter. It is used in order to give a parameter a more descriptive name, mainly for the plot label. It is created for example with the following command:
te log t2 TsampleGive the variable te.t2 the name Tsample. This name is also used for the logger file.
te sugargives a list of defined sugar variables connected to parameters of te.
The logger is a utility to write the history of object parameters. For all drivers based on pardef it is automatically switched on. The data is logged typically every 5 seconds to a file, but only changes are stored in order to save disk space. The file specification for the logfiles is:
<logger base path>/<variable name>/MM-DD.log
Files older than one year will be overwritten. The variable name is the object name for the basic value of the object or <object name>.<parameter name> for the parameters. Important parameter names might be configured to have a more descriptive name.
First there is a header line, containing the date and some additional information:
For every logger entry, there is one line, containing the time, a tab as separation and a value, (which may be a text or number). There may also be lines starting with a hash symbol, which may contain the same information as in the header line, or just a comment.
#2005-10-30 00:00:00 isdst 1 period 5 exact 0
00:00:00 100.72
00:00:05 100.73
00:01:10 100.73
00:01:15 100.74
00:01:20 100.73
... many lines omitted
02:59:55 100.56
#isdst 0 change of daylight saving time
02:00:00 100.58
... many lines omitted
07:55:00 100.58 the server was shut down after writing this line
#period 5 exact 0 isdst 0 the server restarts at 8:30
07:55:05 the shutdown time and an empty value
08:30:00 99.95 the first logged value after startup
There is also a utility to read the logged data through the SICS server. The command syntax is:
graph <start time> <end time> np <number of points> <variable> <variable> ... graph <start time> <end time> text <variable> <variable> ...where
The second form with the keyword text does not compress, and is mainly used for text variables.
The returned list has the following syntax:
The SeaServer is a sics server running in parallel to the Server for instrument control. The server program is just a copy of the SICServer. However, when testing new features, different versions might be used for instrument control (sics server process) and for sample environment (sea server process).
All stuff related to sea are placed in $HOME/sea. All script files needed for the sea server process are identical on all instruments and are placed in the directory ~/sea/tcl. There is one exception, ~/sea/sea.tcl. This file contains the location of the files and the instrument name, and calls the instrument independent startup file ~/sea/tcl/seainit.tcl. This file calls all scripts in the directory ~/sea/tcl/startup/'.
The server log files are located in sea/log, and the database for the logger in sea/logger. The copy of the SICServer for sea is sea/SICServer, and there is a link to it (sea/SeaServer) which is started with the script sea/startwithpid.
The following lines should to be included into the instruments startup script:
source $home/sea/tcl/remob.tcl connect_seaThe macro connect_sea tries to make a connection to sea. If the connection is successful, remob objects are created on sics for all objects listed in the variable env_object_list on sea. Likewise the sea server tries to make a connection to sics on startup and initiates the update of configured objects.
To select the sample environment device, the command samenv (defined in sea/tcl/seacom.tcl) is used. It calles the configuration script for the given device (sea/tcl/<name>.config). The configuration scripts do not call makeobject directly, but use the makenv script, which keeps a list of created objects and takes the host:port information from a small database managed by cfgenv.
Syntax:
samenv <device name> configure sea for the given SE device
samenv show the actual configuration
samenv none remove all objects related with the actual
SE device
cfgenv <driver> <host:port> configure the serial connection of a controller
cfgenv list all configured controllers
makenv <object> <driver> make an object, using the configuration defined
with cfgenv (this command can be used in
configuration scripts only)
The Oxford Instruments helium level meters ILM exists in different versions. At SINQ there are two types:
Create a level meter object:
makeobject lev ilm <terminal server> <port>The name might be choosen differently, lev is used by convention, and is also used by the scripts called with the samenv command.
Command Syntax Description
lev (r) helium level
lev lev2 (r) liquid nitrogen level
(r): read-only
Plus standard commands and parameters defined by EaseBasePar, EaseSendPar, EaseMsgPar
Oxford Instruments superconducting magnet power supply IPS
Create an IPS object:
makeobject mf ips <terminal server> <port>The name might be choosen differently, mf is used by convention, and is also used by the scripts called with the samenv command.
Command Syntax Description
mf (r) magnetic field
mf persmode (w) 0: do not work in persistent mode
1: go to persistent mode after a drive
mf perswitch (r) state of persistent mode switch
mf maxlimit (r) maximal limit for field
mf limit (w) soft limit for field (when set the first time
after initialization, maxlimit is also set)
mf ramp (w) ramp rate (the real ramp rate may be limited
by the sweep limits defined in the IPS)
mf current (r) the current in the leads (converted to Tesla)
mf lastfield (r) value the the field before goings to persistent mode
mf confirm (c) confirm the persistent field in case the stored
value in the driver does not match the value
stored in the IPS
mf targetValue (r) target value
(r): read-only
(w): writeable parameter
(c): command
Plus standard commands and parameters defined by EaseBasePar, EaseSendPar, EaseMsgPar
The Oxford Instruments temperature controller and lambda controller exists in 3 different types at SINQ:
Create an ITC object:
makeobject te itc <terminal server> <port> (for ITC4 or ITC503) makeobject te lc <terminal server> <port> (for lambda controller)The name might be choosen differently, te is used by convention, and is also used by the scripts called with the samenv command.
Command Syntax Description
te (r) the sample temperature (pressure on lambda controller)
te sampleChan (w) the channel used for sample (1..3)
te controlChan (w) the channel for control
te dig1 (w) the number of digits after decimal point
te dig2 (must be configured on an ITC-4, is automatic
te dig3 on an ITC-503)
te t1 (r) temperature of channel 1
te t2 (r) temperature of channel 2
te t3 (r) temperature of channel 3
te htrMode (r) heater mode (0: manual, 1: auto, 2:auto needle valve)
te htr (r) heater output
te gasMode (w) gas mode (0: manual, 1: auto)
te gas (r) needle valve position
te setGas (w) set needle valve position
te autoGasLimit (w) when the controlled tempeature goes below this
value, gas is switched to manual mode, using the value
given by setGas. 1 K above this value, gas is
switched to auto mode
r: read-only, w: writeable parameter
Plus standard commands and parameters defined by EaseBasePar, EaseSendPar, EaseDrivePar, EaseMsgPar