Menu
▾
▴
[Nscldaq-cvscommits] clients/sequencer sequencer.xml,NONE,1.1
|
From: Ron F. <ro...@us...> - 2006-11-16 20:32:29
|
Update of /cvsroot/nscldaq/clients/sequencer In directory sc8-pr-cvs7.sourceforge.net:/tmp/cvs-serv20302 Added Files: sequencer.xml Log Message: Provide documentation. --- NEW FILE: sequencer.xml --- <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML 4.3//EN" "file:///usr/share/xml/docbook/schema/dtd/4.3/docbookx.dtd" [ <!ENTITY manpage SYSTEM "ph7106Control.xml"> ] > <book> <article> <refentry> <refmeta> <refentrytitle>sequencer</refentrytitle> <manvolnum>3tcl</manvolnum> </refmeta> <refnamediv> <refname>sequencer</refname> <refpurpose> Provide a ReadoutGui plugin for nscldaq 8.1 and later that can automate several data taking runs. </refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command> package require runSequencer </command> </cmdsynopsis> </refsynopsisdiv> <refsect1> <title>DESCRIPTION</title> <para> The <command>runSequencer</command> package provides support for automating data taking runs of fixed duration. <command>runSequencer</command> is a ReadoutGui plugin that is compatible with nscldaq-8.1 and later. </para> <para> To operate, you must use the ReadoutGUI from nscldaq-8.1 or later. At the NSCL, you can do this by using <command>/usr/opt/daq/8.1/bin/ReadoutShell</command>. See USING for more information on how to use this plugin. </para> <para> For each run you can define a set of run parameters that are set through custom actions just prior to the start of the run. See CUSTOMIZING below for more information about how to setup these actions and how to specify the parameters. </para> <para> Run sequences are called <firstterm>Run plans</firstterm>. Run plans are files that can be loaded into the sequencer, edited, saved, and executed. A run plan provides values for all of the parameters for each run in the sequence. </para> </refsect1> <refsect1> <title>USING</title> <para> This section desribes using in two senses of the word: Incorporating the sequencerGui into ReadoutGUI, and operating the sequencer once it is installed. Setting up the parameter definitions and actions used by the sequencer are described in CUSTOMIZING below </para> <refsect2> <title>Incorporating SequencerGui into ReadoutGUI</title> <para> To incorporate the sequencer into ReadoutGUI you must use a <filename>ReadoutCallouts.tcl</filename> file to extend ReadoutGui. This file must contain the line: <programlisting> package require runSequencer </programlisting> Furthermore you must run a Readout GUI from nscldaq version 8.1 or later. At the NSCL, you can run the 8.1 version of the ReadoutGUI as follows: <command>/usr/opt/daq/8.1/bin/ReadoutShell</command> Note that when you run the Readout GUI, the <filename>sequencer.config</filename> and <filename>sequencerActions.tcl</filename> files are expected to exist. See CUSTOMIZING below for information about the contents of these files. see "FILES and ENVIRONMENT" for where they belong. </para> </refsect2> <refsect2> <title>Operating the sequencer GUI</title> <para> The sequencer creates a second window associated with the Readout GUI. This window consists mainly of a table with column labels defined by the <filename>sequencer.config</filename> file. Each row of the table represents a run in the sequence of runs in a <firstterm>run plan</firstterm> </para> <para> You can edit the table to provide values for each of the parameters (columns) for each step in the run sequence. Navigate in the table by using the arrow keys, the mouse or the tab and shift tab keys. Once you are happy with your run plan you can save it using the <menuchoice><guimenu>File</guimenu><guimenuitem>Save...</guimenuitem></menuchoice> menu command. </para> <para>The <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu command allows you to read in a plan from file. This plan can be edited, and saved. <menuchoice><guimenu>File</guimenu><guimenuitem>Clear...</guimenuitem></menuchoice> clears the table. </para> <para> To execute a run plan, use the ReadoutGUIPanel to set the length of each run. (The sequencer will turn on timed runs when you start the sequence). Then click the <guibutton>Execute Plan</guibutton> button to start the sequence. The button is relabeled <guibutton>Abort Plan</guibutton> while the plan is running. Clicking it while the plan is running ends the active run and stops the sequence. If event recording was enabled for an aborted run plan you are given the option to discard all the event data that was taken for the sequence. </para> </refsect2> </refsect1> <refsect1> <title>CUSTOMIZING</title> <para> The sequencer is completely customizable. The label for each column and actions to take to set each column are defined by the <filename>sequencer.config</filename> file. This file is a text file. Each line in the file describes a column. Blank lines are ignored as are lines for which the first non-blank character is a hash (#) character. Fields in a line are separated by whitespace. Whitespace can be incorporated into a field either by quoting the field with double quotes (") or curly brackets (for example {this has spaces}). </para> <para> Each column definition line of <filename>sequencer.config</filename> has fields in the following order. <variablelist> <varlistentry> <term>Column Name</term> <listitem> <para> The text that labels the column in the run plan. </para> </listitem> </varlistentry> <varlistentry> <term>set action</term> <listitem> <para> A tcl command that is executed when it is time to change the value of the item in the column. The column name and the value of that cell of the table are appended to the command. If the set action is blank, no action is taken. </para> </listitem> </varlistentry> <varlistentry> <term>initialize action</term> <listitem> <para>A tcl command that is executed when the sequencer is set up, before executing any run plan. This is intended to be used for any one-time intialization required to access the item controlled by the table. The column name is appended to this command when it is called. </para> </listitem> </varlistentry> </variablelist> See EXAMPLES for examples of the sequencer.config file. See "FILES and ENVIRONMENT" for information about where this file belongs. </para> <para> The actions defined in the <filename>sequencer.config</filename> file must come from somewhere. During initialization, the sequencer sources the file <filename>sequencerActions.tcl</filename> this file is a Tcl script that can include procedure definitions, data definitions, etc. Normally it provides the tcl commands that are specified as actions in the <filename>sequencer.config</filename> file. For a sample <filename>sequencerActions.tcl</filename> file see EXAMPLES. For information about how the sequender finds this file, see "FILES and ENVIRONMENT" </para> </refsect1> <refsect1> <title>FILES and ENVIRONMENT</title> <para> The sequencer must locate a column configuration file and a script that defines the actions used by that file. By default, these files are: <variablelist> <varlistentry> <term><filename>./sequencer.config</filename></term> <listitem> <para> The column configuration file. By default this is located in the current working directory of the sequencer when it is started. </para> </listitem> </varlistentry> <varlistentry> <term><filename>./sequencerActions.tcl</filename></term> <listitem> <para> A script that defines actions used by the column configuration file. By default, this is sourced from the current working directory of the sequencer when it is started. </para> </listitem> </varlistentry> </variablelist> </para> <para> Environment variables can alter the location and names of these files: <variablelist> <varlistentry> <term><envar>SEQCONFIGDIR</envar></term> <listitem> <para> If defined, this environment variable is the directory from which the two configuration files are loaded for example: <command>export SEQCONFIGDIR=~/config</command> </para> </listitem> </varlistentry> <varlistentry> <term><envar>SEQCONFIGFILE</envar></term> <listitem> <para> If defined, this environment variable is the name of the file used to configure the columns. If, for example, you: <command>export SEQCONFIGDIR=~/config</command> and <command>export SEQCONFIGFILE=columns.def</command> The column configuration file loaded will be <filename>~/config/columns.def</filename>. </para> </listitem> </varlistentry> <varlistentry> <term><envar>SEQACTIONFILE</envar></term> <listitem> <para> If defined, this environment variable is the name of the action script file that defines the actions referenced in the column configurationfile. If, you have <command>export SEQCONFIGDIR=~/config</command> and <command>export SEQACTIONFILE=actions.tcl</command>, The action script file will be sourced from <filename>~/config/actions.tcl</filename>. </para> </listitem> </varlistentry> </variablelist> </para> </refsect1> <refsect1> <title>EXAMPLES</title> <example> <title>Action script example</title> <para> This example shows part of an action script that defines the actions <function>epicsAccess</function> and <function>epicsSet</function> that provide actions to access epics channels. <programlisting> package require epics proc epicsSet {name value} { $name set $value } proc epicsAccess name { epicschannel $name } </programlisting> </para> </example> <example> <title>Sequencer column configuration file</title> <para> The sequencer file below defines a set of columns that are all epics channels: <programlisting> # Column set_action init_action P222ET_TARGET epicsSet epicsAccess P222ER epicsSet epicsAccess FLTCHAN73 epicsSet epicsAccess P#5:406353 epicsSet epicsAccess </programlisting> Not the use of blank lines and comment lines. </para> </example> <para> The directory <filename>examples/sequencer</filename> under the installation directory of the nscl daq includes several sample files. </para> </refsect1> </refentry> </article> </book> |