Acquisifier User Manual

Contents

Introduction

The Acquisifier is a one of the data acquisition tools provided by our LWDAQ Software. The LWDAQ Software reads out and controls LWDAQ Hardware. The Acquisifier allows you to define a LWDAQ acquisition cycle through many LWDAQ Instruments and record their results and images to disk. It is an example of a LWDAQ Tool. Select Acquisifier from the Tools menu to open the Acquisifier window, as shown below.

Figure: The Acquisifier Window on MacOS.

The Acquisifier can operate with or without its graphical user interface. When the graphical user interface is available, it presents buttons, entry boxes, and a color text window to the user. It reports its progress in the text window, and allows the user to start and stop script execution with the buttons. When it is absent, the Acquisifier responds to commands entered at the console, or uploaded via a TCPIP socket.

We define a data acquisition cycle with an Acquisifier Script. We can pass this script to the Acquisifier directly through a TCL variable, or upload it through a TCPIP socket. Most often we read the script out of an Acquisifier Script File. And Acquisifier script file is a text file stored to disk in ASCII-only format. In the Acquisifier window, the file named in the Script entry box is the file the Acquisifier will try to read off disk and load into memory when you press the Load button. Acquisifier scripts are not TCL scripts, although they always contain segments of TCL code. Acquisifier scripts obey a syntax particular to the Acquisifier. Here is a script that measures LWDAQ current consumption on our demonstration stant and stores to the a file on your desktop.

acquire:
name: LWDAQ_Currents
instrument: Diagnostic
post_processing: {
  LWDAQ_print ~/Desktop/Output.txt $result
}
config:
  daq_ip_addr 129.64.37.79
end.

Once the Acquisifier has a script loaded into memory, we run the script with the various control buttons along the top of the Acquisifier window. As the Acquisifier proceeds through a script, it prints step details and data acquisition results to its text window. With Upload_Step_Result checked in the Acquisifier window, the Acquisifier uploads the result of each step to a TCPIP server. With the help of the System Server, a remote client can obtain a copy of the Acquisifier's run_results file. The Acquisifier will store results in this file when instructed to do so by TCL code in the Acquisifier Script.

We designed the Acquisifier to obtain results from LWDAQ instruments such as the BCAM, Rasnik, and Thermometer. When any instrument performs its acquire function, it acquires a block of data, which we call an image, and calculates a result string. We call the data an image regardless of whether it is an array of pixels or a string of numbers. Each acquire step in an Acquisifier script causes an instrument to perform its acquire function. The Acquisifier can modifying this result string as soon as it receives the string. At the end of the acquire step, the Acquisifier stores the result to disk or uploads it over a TCPIP socket.

Example: In ATLAS, the Acquisifier modifies and extends result strings and uploads them to a database. Subsequently, all these results are taken as input by the ARAMYS reconstruction program. The ARAMYS reconstruction program also reads in the calibration constants of all the devices, and uses them to interpret the measurements from each device. The Acquisifier never combines the results obtained from different acquire steps. In the ALICE detector, the Acquisifier stores results to a file, and this file is later read in and analyzed by a reconstruction program. The GME script is a shortened version of the script used in ALICE.

The Acquisifier can combine the results of one or more instruments.

Example: The Demo script illustrates most Acquisifier features, and combines the results of multiple instruments in a single result string, which it stores and displays at the end of the script.

The Acquisifier can combine and analyze the results from one or more instruments.

Example: The BCAM script combines the results from two BCAMs with their calibration constants to obtain a measurement of the separation of the two devices.

We find that the Acquisifier's ability to combine and analyze multiple acquire steps is useful in smaller systems. None of our larger LWDAQ systems use this ability. The ATLAS data acquisition scripts upload the result of each step to a separate server that compiles them together for the end-cap geometry reconstruction program.

Acquisifier Scripts

The Acquisifier's active script is the Acquisifier script it keeps in its internal memory. An acquisifier script is a list of steps defined in a text script. Each step contains a number of fields. The post-processing fields contain short TCL scripts that the Acquisifier will execute after it performs the main functions of the step. Every step produces a step result, which is a string that contains data, an error message, or simply the name of the step to show that the step completed sucessfully.

The format of an acquisifier script simple. You can edit a acquisifier file with any text editor. There three types of Acquisifier step: acquire, default, and acquisifier. Let us start with the acquire step. Here is a script entry that tells the Acquisifier to acquire from the BCAM instrument:

# Acquire from BCAM 1 an image of the two sources on BCAM 2.
# Comment lines like this must begin with a hash character.
acquire:
name: BCAM_1_2
instrument: BCAM
result: "None"
metadata: "12 67"
config:
  daq_flash_seconds "0.000010"
  daq_driver_socket "5"
  daq_device_element "2"
  daq_source_device_element "3 4"
  daq_source_driver_socket "8"
end.

When you press the Load button, the Acquisifer loads the script named in the daq_script variable. If you want to select a script, press the Browse button next to the script name. Once the script is loaded, the Acquisifier maintains the script in memory as its active script. It does not use the script file any more. You can store the active script to disk with the Store button. You can obtain a copy of the active script with the Acquisifier_script_string command. The Load button calls Acquisifier_load_script and the Store button calls Acquisifier_store_script.

You step through a script with the Step button. You execute the previous step once again with Previous Step, and you repeat the previous step over and over again (like Loop in an instrument panel) with Repeat Previous Step. The Run button tells the Acquisifier to execute all steps in a script to the end. The Repeat Run button tells the Acquisifier to run the script to the end, wait until the next execution time as specified by the Acquisifier's cycle period, and then run again, and so on.

If you want to jump to a step, enter its step number minus one in the Step entry box at the top of the window, then press Step. If you want to go back and repeat the last step, press the Previous_Step button. As you step through, you will see the results of each step appearing in green letters in the Acquisifier's text window. If you encounter an error, however, the result will be red. If you would like to see the instrument acquiring the data, you can open the instrument panel before you execute the step. If you try to open the window during the step, LWDAQ will wait until the step is finished before it opens the window.

The results of post-processing instructions appearing in blue in the Acquisifier window. The initial acquisifier step defines a list of TclTk commands and the BCAM default step defines default post-processing for BCAM acquire steps. Each step produces a one-line result. The acquire step results contain data. The other step results contain only the name of the step or its step type if no such name is defined in the script. But any step that encounters an error will return a description of the error in the results string, and this will appear as a red line in the Acquisifier text window. Here are some more demonstration scripts you can study or try out yourself.

The Acquisifier does not know anything about the particular instruments it uses. When it comes to an aquire step, it looks for a field named "instrument:", which gives the exact name of the instrument. The Acquisifier stores this name in its instrument variable. With this name, it calls the instrument's acquisition routine.

LWDAQ_acquire $instrument

All Acquisifier steps produce a step result string. If an acquisfier step has a result field, this field will contain the most recent step result. When the Acquisifier completes the step, it sets the result field to the latest step result. If there is no result field, the Acquisifier does not record the step result in its script. If the Acquisifier has not yet executed the step, the result field will contain "None". You will notice that the result fields in our example scripts all contain "None".

The config field in an acquire step gives the names of any parameters from the Instrument's config or info arrays that you wish to set before acquisition or retain afte acquisition. Each line in the config field gives a parameter name and a value. The script does not specify whether the parameter is in the instrument's config or info arrays. The Acquisifier figures this out for itself.

You will notice that all config values and the result value are enclosed in double-quotes or curly braces. This allows the TclTk interpreter to recognise that values containing spaces are to be considered a single string value, not multiple elements in the script. You don't have to put double-quotes or curly braces around a parameter value unless it contains some type of white space, but we put them around all the parameters just to stop ourselves from getting confused. We recommend that post-processing scripts be enclosed in curly braces.

Some instruments change their own config and info parameters. The BCAM, for example, adjusts daq_flash_seconds when daq_adjust_flash is set to 1. If you would like retain these adjustments, name the parameter you want to retain in the config field and set it to an initial value. At the end of acquisition, the Acquisifier will write the final value of this parameter to the active script in memory. The next time the same acquire step executes, the Acquisifier will use the adjusted value. Here we see one of the ways in which the active script starts to differ from the script file from which it originated.

The acquire steps store evolving information in their config field, and all steps store their evolving results in their result field. But there are times when we need to pass information from one execution of a step to the next execution that are not supported by either the config or result fields. All Acquisifier steps can specify a metadata field. This field is a string that you can refer to in post-processing with the metadata variable. The metadata string is for evolving, step-specific information.

It is likely that all instruments of a particular type will share a set of parameter values. The default step allows you to declare these shared parameters. You change the parameters of an instrument for subsequent acquire steps using a default step. Here is a default command for the BCAM instrument.

default:
name: BCAM_Default
instrument: BCAM
config:
  image_source "daq"
  analysis_enable "1"
  analysis_num_spots "2"
  daq_adjust_flash "1"
  daq_ip_addr "lwdaq.hep.brandeis.edu"
  ambient_exposure_seconds "0.1"
  intensify "exact"
  daq_sensor_mux_socket "1"
  daq_source_mux_socket "1"
end.

You can change the defaults for later acquisitions in the script using further default steps. The next BCAM default step might be named "Another_BCAM_Default". When the Acquisifier loads a new script, we can instruct it to delete all previously-defined default values by checking the Forgetful box before we perform the load. By default, Forgetful is false, so the Acquisifier retains the default values for the next script. We can define defaults with one script, and use them in several subsequent acquisition scripts.

The Acquisifier provides other over-arching controls. Check the Extended_Acquisition box to force extended acquisition in all instruments, wherever the instrument provides such acquisition. The box corresponds to the Acquisifier's extended_acquisition parameter. Check the Upload_Step_Result box to have the Acquisifier upload the result of each step to an IP address or an open TCL channel, as described below. The box corresponds to the upload_step_result parameter. If you want the Acquisifier to restore each instrument's settings after it uses the instrument, check the Restore_Instruments, which corresponds to the restore_instruments parameter. If you want the Acquisifier to apply the Analyzer Tool to the LWDAQ device it uses, check the Analyze box, which corresponds to the analyze parameter. We describe the Acquisifier's use of the Analyzer below.

You may with to run several Acquisifiers simultaneously within the same LWDAQ process. We find this is particularly useful for slow data acquisition projects, where the Acquisifier executes its script infrequently. The Spawn button creates a new Acquisifier by calling Acquisifier_spawn. We devote a special section to the Spawn button below. The new Acquisifier will be independent of the first. It will have its own name, like Acquisifier_2.

If you want to execute your entire script from the current step number to the final step number, press Run. If you want to run continuously, press Repeat Run. If you want to stop at the end of the current step, press Stop. If you want to stop at the end of the current run, press Run. If you want the Acquisifier to run its script and then wait a pre-defined length of time before running it again, and repeat this process indefinitely, use the cycle_period_seconds seconds parameter. You will find it in the Acquisifier's configuration array by pressing Configure. By default, this length of time is set to zero, and the Acquisifier runs its script continuously. Type in another value, like 30, and you will find that the Acquisifier executes the script every thirty seconds.

The cycle_period_seconds parameter is an example of an Acquisifier parameter you may like to set in your script. You could do this with post-processing, but the acquisifier step allows you to set the Acquisifier's own paramters with a config field similar to the acquire and default steps. Here is an example acquisifier step.

acquisifier:
name: Initialize
post_processing: {
	set config(run_result_string) "[clock seconds] "
}
config:
  cycle_period_seconds 30
  run_results run_results.txt
end.

This step sets the run_results file name. It also initializes a new run_result_string parameter with the UNIX time. The Acquisifier does not write to the run_results file unless instructed to do so by post-processing code. But the Acquisifier does provide several routines that manipulate the run_results file. The Acquisifier_run_results routine returns the contents of the run_results file. The Acquisifier_clear_run_results routine clears the file contents. The Acquisifier window provides a text entry box and a browser button for the run_results file name.

The table above lists the field names whose functions are defined by the Acquisifier. You can add your own fields to Acquisifier steps, provided the field names include not white spaces, and use their values in post-processing, as we describe below.

Demonstration Scripts

Below are some example Acquisifier scripts. Download with the link, save to your hard drive. Load the script with the Load button.

Bars.tcl: Exercises the Rasnik instruments buried inside one of our ATLAS End-Cap Alignment bars. We use this script to make sure that all the Rasniks instruments are working.

GMS.tcl: A shortened version of the script used by Raphael Tieulent to read out the ALICE detector's Geometric Monitoring System. Here we see the result of each acquisition being re-arranged by post-processing. It is the re-arranged result string that the Acquisifier stores to disk. The script stores the image obtained by each acquisition, over-writing the previous image.

WPS.tcl: Captures images from multiple wire position sensors and uses their calibration constants to calculate the plane containing the wire that corresponds to each image. The script constains the calibration constants in its initial acquisifier step, and stores them in a configuration parameter for use during execution.

BCAM.tcl: Measures the range between two BCAMs.

HBCAM_Test_Stand.tcl: An extendable script that supports up to eight H-BCAMs arranged in a test stand taking images of one another's lasers. The script contains the calibration constants of the H-BCAMs used in the test stand. The script takes the image positions, combines them with calibration constants and mounting ball locations, and produces error vectors from the actual source positions to the source bearing lines measured by the H-BCAMs.

Demo.tcl: Exercises the BCAM and Rasnik instruments, demonstrates acquisifier and default steps. The script contains plenty of post-processing, with use of meta-data variables and global variables. It tries to demonstrate as many features of the Acquisifier as possible. We include this script with our LWDAQ software distribution.

BCAM_Reflectors.tcl: Reads out two HBCAMs that view retroreflecting glass spheres. The script provides a probability of image storage so we can keep a fraction of the images obtained, saving them for diagnostics. This script was used at FNL to read out their system of H-BCAMs and reflectors.

Configuration

When the Acquisifier starts up, it loads its settings file, if such a file exists. The settings file must be in the Acqusifier tool's data_dir directory. The name of the settings file is derived from the Acquisifier name. The first Acquisifier you open will be called Acquisifier, and its settings file will be Acquisifier_Settings.txt. Other Acquisifiers that you spawn with the Spawn button will be called Acquisifier_n, where n is an integer. Their settings files must be named Acquisifier_n_Settings.tcl.

The data_dir directory will be Tools/Data if you run the Acquisifier form the Tools menu, or LWDAQ.app/Contents/LWDAQ/Startup/Data if you run the Acquisifier automatically from the Configuration directory. See Tools for more information about running the Acquisifier automatically at startup.

Here is an example settings file:

set Acquisifier_config(auto_load) "0"
set Acquisifier_config(title_color) "purple"
set Acquisifier_config(extended_acquisition) "0"
set Acquisifier_config(auto_repeat) "0"
set Acquisifier_config(analyze) "0"
set Acquisifier_config(auto_run) "0"
set Acquisifier_config(run_results) "/Users/kevan/Active/LWDAQ/Tools/Data/Acquisifier_Results.txt"
set Acquisifier_config(run_analysis) "/Users/kevan/Active/LWDAQ/Tools/Data/Acquisifier_Analysis.txt"
set Acquisifier_config(cycle_period_seconds) "0"
set Acquisifier_config(daq_script) "/Users/kevan/Active/LWDAQ/Tools/Data/Acquisifier_Script.tcl"
set Acquisifier_config(analysis_color) "orange"
set Acquisifier_config(upload_target) "stdout"
set Acquisifier_config(auto_quit) "0"
set Acquisifier_config(result_color) "green"
set Acquisifier_config(num_steps_show) "20"
set Acquisifier_config(upload_step_result) "0"
set Acquisifier_config(num_lines_keep) "1000"
set Acquisifier_config(restore_instruments) "0"

You can generate a settings file of your own by running the Acqusifier, pressing the Configure button, assigning values to the configuration parameters in the configuration window, and pressing the Save button in the configuration window. The configuration array will be saved in the ./Tools/Data directory. The values you saved will be loaded automatically the next time you open the Acquisifier. If you want to set up the LWDAQ to run the Acquisifier when it starts up, you can put a copy of Acquisifier.tcl in the LWDAQ Configuration Directory. This copy will use the settings stored in ./Tools/Data.

By means of the the Acquisifier_Settings.tcl file, you can configure the Acquisifier to load its daq script when it opens up, and also to run or to repeat without your pressing the run or repeat button. When the Acquisifier starts up, it checks its auto_load parameter, and if auto_load is set to 1, it loads the script specified by its daq_script parameter, which might also be set by the settings file. If auto_repeat is set, the Acquisifier enters its repeat loop. If auto_run is set instead, the Acquisifier performs one run through the daq script. If auto_quit is set, the Acquisifier will force LWDAQ to quit when the Acquisifier enters the Idle state after executing one or more steps.

Post Processing

The post-processing field of any step in an Acquisifier script contains TclTk code that the Acquisifier will execute immediately after it has performed the primary operations required by the step. The post-processing for a BCAM step, for example, will be executed immediately after the BCAM acqusition. The following BCAM acquire step contains post-processing code that negates the acquired image, analyzes the negated image, and draws the negated image into the BCAM Instrument panel.

acquire:
name: Inverted_BCAM
instrument: BCAM
post_processing: {
	lwdaq_image_manipulate $iconfig(memory_name) negate -replace 1
	set result [LWDAQ_analysis_BCAM $iconfig(memory_name)]
	lwdaq_draw $iconfig(memory_name) $iinfo(photo) \
		-intensify $iconfig(intensify)
}
config:
  analysis_threshold "30 %"
end.

Any step can define its own post-processing with its own post_processing field. The following step initializes the data-recording of our example script.

acquisifier:
name: Initialize
post_processing: {
  set config(run_result) ""
  LWDAQ_print $info(text) "Results will be stored in \"$config(run_results)\"."
}
config:
end.

The post-processing in the following step completes the data recording.

acquisifier:
name: Finalize
post_processing: {
  LWDAQ_print $config(run_results) $config(run_result)
  LWDAQ_print $info(text) "$config(run_result)" blue
}
config:
end.

The post-processing above uses LWDAQ_print to append the run_result string to the run_results file and also to print the string to the screen. The Acquisifier text window name is stored in info(text).

Instrument default steps may have a default_post_processing field, which defines TclTk code that will be performed after every acquire step for a particular instrument. This default code will be executed after the step's own post-processing code. In the following step we define default post-processing for the BCAM Instrument.

default:
instrument: BCAM
default_post_processing: {
  if {![LWDAQ_is_error_result $result]} {
    append config(run_result) " [lrange $result 1 2]"
  } {
    append config(run_result) " -1 -1"
  }
}
config:
end.

We note that, like all Acquisifier steps, a default step can have its own post-processing, which will be executed during the default step but at no other time. The default post-processing is executed only during acquire steps of the instrument specified in the default step.

All post-processing and default post-processing commands are executed within the scope of the Acquisifier_execute routine, not the global scope. The following table lists the local variables available to post-processing scripts.

Any other variables the post-processing needs to reference must be declared with global or upvar commands. Thus if we want to access the BCAM instrument's configuration array from the post-processing of a RASNIK acquire step, we can use the following line.

global LWDAQ_config_BCAM

You can define your own fields in Acquisifier steps and use these fields in your post-processing. The following acquisifier step does nothing except print a message to the screen. The message is defined in a custom field and retrieved from the Acquisfier Script with Acquisifier_get_field.

acquisifier:
screen_text: "This is a custom field value."
post_processing: {
  LWDAQ_print $info(text) [Acquisifier_get_field $info(step) screen_text]
}
config:
end.

We obtain the value of the custom field with the Acquisifier_get_param. We use the step element in the info array to look up the step definition in the active script, and so extract the cutsom field value. Post-processing can set the value of a custom field, or cause the field value to evolve, with the help of the Acquisifier_put_field command.

acquisifier:
counter: 0
post_processing: {
  set counter [Acquisifier_get_field $info(step) counter]
  incr counter
  Acquisifier_put_field $info(step) counter $counter
}
config:
end.

Because post-processing has access to the step number, it can change the order of the step execution, or implement branches and jumps. If the Acquisifier is running through a script, and the post-processing of one of its steps adds one to step, the Acquisifier will skip the next step in the script. A step might add one or two to step, depending upon the result of a test, and so cause conditional execution of steps.

Step Result

Every Acquisfier step generates a result string. The Acquisifier prints the result to its text window after every step. When upload_step_result is set, the Acquisifier transmits the result to a TCPIP server socket or to an open Tcl file channel, as we describe in Step Result Upload. The Acquisifier will store the result to disk if directed to do so by instructions in step post-processing. The step result is available to post-processing as the result variable.

Step results can either be error results or completion results. A completion result begins with the name of the step and is followed by any data generated by the step execution. If the Acquisifier script specifies no name, the Acquisifier will generate a default name. The default name is a combination of the step type and the step number. A default step that is step number 56 in a script will receive the name "default_56".

An error result begins with the phrase "ERROR: ". The Acquisifier prints completion results in green and error results in red. A step returns a completion result if and only if it encountered no errors. No instrument may be named ERROR:, because its completion result would then begin with the error phrase, and be indistinguishable from an error result.

The default completion result from an acquire step is the result of data acquisition by an instrument, with one modification. The Acquisifier replaces the image name in the instrument result with the step name. An acquire step's post-processing can modify the result string. In particular, the post-processing might append additional data to the instrument result. The completion result for default and acquisifier steps is a string beginning with the name of the step followed by "okay".

When a step defines a disable field with "disable: 1", the Acquisifier does not execute the step. It does, however, return a completion result, which will be printed to the Acquisifier text window if it is available. The result string for a disable step begins with the name of the instrument followed by "disabled". But this result string is not uploaded to a remote target when we have set upload_step_result. Thus the disable field causes both data acquisition and result string upload to be skipped.

An error result records the most recent error encountered by the step execution. If the Acquisifier encountered several errors, only the final one will be recorded. Post-processing can generate its own errors, but these must conform to the error result format. They must begin with the error phrase, which is "ERROR" in capital letters followed by a colon and a space.

Metadata

Post-processing in all steps can refer to the step's metadata field with the metadata variable. At the end of the post-processing, the Acquisifier over-writes the old value of metadata with the contents of the variable "metadata".

acquisifier:
metadata: "0"
post_processing: {
  incr metadata
  LWDAQ_print $info(text) "Metadata counter = $metadata" orange
}
config:
end.

Because the metadata field is optional, you can refer to it with the metadata variable even though there is no metadata field in the step's definition in the Acquisifier script. When there is no metadata field, the metadata will be an empty string. When the Acquisifier tries to set the metadata field at the end of your post-processing, it will find that no such field exists in the script, and do nothing. The metadata field must be defined in the step's definition string or else it will not be stored in the active script.

Spawning

The Acquisifier's Spawn button creates a new Acquisifier window. The new Acquisifier is independent of the first. There is no limit to the number of Acquisifiers you can within the same LWDAQ process. Just keep pressing the Spawn button. The first Acquisifier is unique in that its name is just Acquisifier. We refer to it as the Original Acquisifier. The others have names of the form Acquisifier_n, where n is an integer greater than 1. We call them the Spawned Acquisifiers. If you close the Primary Acquisifier, the other Acquisifiers remain unaffected.

The routine that creates a new Acquisifier is called Acquisifier_spawn. This routine is defined the first time you open the Acquisifier Tool. You can call Acquisifier_spawn from the LWDAQ command line. Its result is the name of the new Spawned Acquisifier.

The Primary Acquisifier provides routines like Acquisifier_command, Acquisifier_status, and so on, which are particularly useful for remote control. In Spawned Acquisifiers, these same routines are available, with the name of the Spawned Acquisifier in place of the word Acquisifier. So we might have Acquisifier_3_run_results.

If you want your Acquisifier scripts to be compatible with any Acquisifier, spawned or primary, your post-processing code must refer to Acquisifier routines and parameters indirectly. Instead of referring to Acquisifier_info directly, you refer to the array indirectly as info. To refer to the Acquisifier's text window, use $info(text).

All the spawned Acquisifiers share the same Instruments. They work harmoniously with one another through the LWDAQ event queue. If you open four or five Acquisifiers, and get them all running a script, such as our example Acquisifier script, you can watch them taking turns to use the Instruments in the System Monitor window. This arbitration between the Acquisifiers through the LWDAQ event queue is more stable and efficient than arbitration between two separate LWDAQ processes each using the same data acquisition hardware. In the case of two separate processes, the arbitration is done by checking if the hardware is busy, and waiting a random amount of time before trying again if it is busy. The LWDAQ event queue knows exactly when one data acquisition is finished, and will pass control to the next event in its queue after LWDAQ_Info(queue_ms)

Spawned Acquisifiers are particularly useful when you want to run several slow experiments simultaneously.

Example: You have two Inclinometers on a granite table. You want to measure the inclination of the table every hour, as well as the temperature of the table, and log this to a file. Meanwhile, you have three Rasniks and a BCAM on a test stand, and you want to record measurements from them every ten minutes. A third data acquisition is measuring using the Voltmeter to measure the voltage of a battery that is slowly running down. You want to record the battery voltage every six hours. You open three Acquisifiers and have them run three separate scripts, each with its own repeat period and results file.

If you are running Acquisifiers on slow experiments, you can decrease the processor time used by the LWDAQ by setting LWDAQ_info(queue_ms) to something like 500 ms. By default, it's smaller, perhaps 50 ms. You can change this system parameter in the System Monitor window. We found that the LWDAQ share of the processor's time dropped from 30% to 8% when we increased queue_ms from 50 ms to 500 ms.

Remote Control

You can control the Acquisifier using LWDAQ's System Server. This form of control is best suited to Acquisifier scripts that write their results to a single file, the run results file, whose name is stored in the Acquisifier's run_results parameter. The System Server allows us to open the Acquisfier, load the script, execute the script, and then download the run results file. If you want to control the Acquisifier step-by-step, and get the result of each step as it comes, we recommend you use the Acquisifier's upload step result feature at the same time.

Remote Control can take place when LWDAQ is running with or without graphics. Indeed, the most common application of remote control through the System Server is when LWDAQ is running in --no-console mode. In all cases, we send commands to LWDAQ through the System Server, and these commands start the Acquisifier, load a script, and execute its steps. We describe how to launch LWDAQ without graphics, and to start the System Server using a configuration file, in the Run from Terminal section of the LWDAQ manual.

If LWDAQ is running with graphics, the commands you send through the System Server will cause the Acquisifier window to open and display text lines just as if you opened it with the buttons. If LWDAQ is running in --no-gui mode, no Acquisifier text lines will appear in the console unless you direct such lines to the console. You can send all the Acquisifier text output to the console by setting LWDAQ_Info element default_to_stdout to 1. By default, this element is 0 and window text is lost when the window does not exist. You can send only Acquisifier step results to the console by leaving default_to_sdtout at 0 and instead setting Acquisifier_config element upload_step_result to 1 and upload_target to "stdout". If LWDAQ is running in --no-console mode, you can direct the console output to a file using the ">" operator when you start LWDAQ at your command prompt.

You can launch LWDAQ and start the System Server either from the command line with a configuration file or from the graphical user interface with menus and buttons. To run the Acquisifier through the System Server we must send to the System Server commands that open the Acquisifier, load its script, and execute the script steps. We may also want to return the results of individual steps or the contents of an entire file full of script results.

To illustrate Remote Control, run LWDAQ in graphics mode and open the System Server from the File menu. Set the addr_filter to * so that all clients will be accepted. Set the mode to "execute" so that incoming text lines will be executed in LWDAQ's TclTk interpreter. Set the listening_port to 1090. Press the System Server Start button. Your LWDAQ is now listening for connections by TCPIP.

Make a copy of the LWDAQ program on your machine and run it. This copy is going to act as our client by which we will control the original program, which we will call the host. In the client console window enter the following commands to connect via TCPIP with the System Server.

set sock [socket 127.0.0.1 1090]
fconfigure $sock -buffering line

In the host's server window, you should see something like this:

sock12 listening on port 1090.
sock13 opened by 127.0.0.1:58917.

In the client console enter:

puts $sock "LWDAQ_run_tool Acquisifier.tcl"
gets $sock

The first line asks the host to open the Primary Acquisifier. The Acquisifier window should open in the host. The second line reads back a confirmation that the host did so. The gets line should retun a "1". If it returns a "0" then something went wrong. Now we tell it to load and run the default script.

puts $sock "Acquisifier_load_script"
gets $sock
puts $sock "Acquisifier_command Run"
gets $sock

The Acquisifier should now be running the default script. You will get a "1" back from both commands, to show they are initiated correctly. The "1" from the Run command does not mean that the run is done. To determine if the Acquisifier has finished the run, we use a command provided especially for the System Server.

puts $sock "Acquisifier_status"
gets $sock

You can repeat the above lines until you get a string that begins with the word "Idle". Here's what we saw on in our client console after entering all the commands listed so far. The "%" sign is the command prompt.

% set sock [socket 127.0.0.1 1090]
sock13
% fconfigure $sock -buffering line
% puts $sock "LWDAQ_run_tool Acquisifier.tcl"
% gets $sock
1
% puts $sock "Acquisifier_load_script"
% gets $sock
1
% puts $sock "Acquisifier_command Run"
% gets $sock
1
% puts $sock "Acquisifier_status"
% gets $sock
Run 9 acquire: Rasnik Acquire
% puts $sock "Acquisifier_status"
% gets $sock
Run 11 acquire: Rasnik Acquire
% puts $sock "Acquisifier_status"
% gets $sock
Idle 14 acquisifier: none none

The status command returns the Acquisifier state, the current step number and the steps type. If the step is an acquisition, the status also gives the name of the instrument and the instrument state.

The Acquisifier_run_results command returns the entire contents of the run results file. Thus it is useful with long scripts that clear the run results file when they begin, and create a file with many lines by the time they are done. Our demonstration script merely appends a single line to the run results file, but we'll use it for the purpose of our demonstration anyway.

puts $sock "Acquisifier_run_results"
gets $sock

The host will return the entire contents of the run results file, no matter how long it is. We read the first line of the file with the first "gets" command. But how many more lines are there to read? We can keep reading lines from the socket, but eventually there will be no more lines and our client will freeze up waiting for another line that will never come. Before we start reading the run results file, we first have to find out how long it is. We do this with the following command.

puts $sock "string length \[Acquisifier_run_results\]"

Note the use of backslash escape characters to specify that the puts should send an actual "[" character, followed by the command name, and then a "]" character. This way, the host that will execute Acquisifier_run_results and substitutes its value into the string length command. If we omit the backslashes, then the client interpreter will try to run execute the command and substitute the result into the string it is sending to the host, which is not what we want. Another way of sending the same command would be to use curly brackets to enclose the string we send: in Tcl, curly brackets prevent all substitution. We use double-quotes just to bring up the problem and make it clear to you before you encounter it yourself. With curly brackets the line would be neater.

puts $sock {string length [Acquisifier_run_results]}

Here's how we read the entire run results file.

puts $sock {string length [Acquisifier_run_results]}
set n [gets $sock]
puts $sock "Acquisifier_run_results"
set run_results [read $sock $n]
gets $sock

The client interpreter variable run_results now contains the entire contents of the run results file. The "gets $sock" reads the line break at the end of the System Server's transmission. The System Server always adds a line break to the end of its transmissions.

We can read the Acquisifier Script (that's the active script the Acquisifier holds in memory) with the Acquisifier_script_string command in the same way we read the run results file. First determine the number of characters in the script, then read the script.

You can mimic the effect of any one of the second-row buttons in the Acquisifier window with:

puts $sock "Acquisifier_command Button_Name"

Where Button_Name can be the name of any one of the second-row buttons, like Repeat_Run. Aside from reading out the contents of the daq_results and run_results files, you can also clear the run_results file with Acquisifier_clear_run_results. You can change the name of the run_results and daq_script files by altering the Acquisifier's config array.

puts $sock "set Acquisifier_config(run_results) /Users/kevan/Desktop/results.txt"
gets $sock

It is hard to write a new Acquisifier script to disk on the host with the System Server. We suggest you use SFTP (secure file transfer protocol) to organise daq scripts on the host hard drive instead of the System Server. But it is easy to store the current, memory-resident version of the Acquisifier script to disk on the host system. We use the store script command.

puts $sock "Acquisifier_store_script /Users/kevan/Desktop/current_script.tcl"
gets $sock

If successful, the store script command will return a 1. The current script will be stored to the named file. If we want to over-write the existing disk copy of the script, we can do so like this.

puts $sock "Acquisifier_store_script $Acquisifier_config(daq_script)"
gets $sock

To open a Spawned Acqusifier, call Acquisifier_spawn. The return string will give you the interger, n in the new Acquisifier's name, Acquisifier_n. You use n to contruct subsequent calls to the Acquisifier's routines. To run the new Acquisifier's script, you would send:

puts $sock "Acquisifier_$n\_command Run"

In this command, we assume the Acquisifier number is stored in the variable n. We note that spawned acquisifiers differ from the original Acquisifier in that the original Acquisifier name is just Acquisifier, with no integer following.

Step Result Upload

The upload_step_result variable can be set by your Acquisifier script, in an acquisifier step, or manually with the check-box at the top of the Acquisifier window. With upload_step_result set to 1, the Acquisifier will upload the result of each step over the internet or write it to an open Tcl channel, depending upon the value in upload_target.

If upload_target is an IP address with port number, in the format x.x.x.x:p, the Acquisifier opens a TCPIP socket to this IP address, transmits the step result, and closes the socket.

If upload_target is not an IP address, the Acquisifier assumes it is an open Tcl channel and writes the step result to the channel. By default, upload_target is "stdout", which directs the step results to the console.

You can test the result upload by setting step_result_upload to 1 and upload_target to "stdout". Look at the LWDAQ console output. These values direct the upload to an existing Tcl channel, in this case the standard output channel. You can test TCPIP upload with the System Server. Open the System Server. Set set server_mode to "receive", listening_socket to 1090, and address_filter to 127.0.0.1 (these are the default values). In the Acquisifier, set upload_target to 127.0.0.1:1090. As you run the Acquisifier, you should see the result strings appearing in the System Server text window.

If you using the System Server to control the Acquisifier from a remote system, you may wish to upload the results through the existing server socket. In this case, you must obtain the local name of the server socket, and set upload_target to this name. You obtain the local name of the server socket at the remote system with the LWDAQ_server_info command. The local name will be the first element in the list this command returns. You set upload_target to this local name from the romote system by sending the string "set Acquisifier_config(upload_target) localname". If your remote system is a TCL console, you would enter the following.

puts $sock "LWDAQ_server_info"
set server_info [gets $sock]
puts $sock "set Acquisifier_config(upload_target) [lindex $server_info 0]"
gets sock14

Every Acquisifier step generates a result string, as we describe above. Thus when upload_step_result is set, the Acquisifier uploads a string to the upload target after every step, including steps that merely define default behavior of the Acquisifier.

Device Analysis

The Analyzer Tool attempts to identify a LWDAQ device by looking at its current consumption in response to a selection of LWDAQ command. When used with the Acquisifier, the Analyzer provides an automatic way of looking for hardware failures in a large system.

When the Acquisifier's analyze parameter is set, the Acquisifier applies the Analyzer to all devices involved in any acquire step. The Acquisifier proceeds through its script as usual, but whenever it executes an acquire step, just after it completes the acquisition and just before it executes step post-processing, the Acquisifier calls the Analyzer to analyze all devices involved in the acquisition. The results of device analysis are available to post-processing in the analysis variable. The Acquisifier appends the contents of analysis to a file named by the run_analysis parameter. You can set run_analysis in the Configuration Panel, or you can set it in an Acquisifier step in your data acquisition script.

Some aquire steps use two or more LWDAQ devices. A BCAM step uses a camera and a light source, almost always in separate devices. The Acquisifier detects when more than one device is used in an acquire step, and applies the Analyzer Tool to all devices. Each device receives a separate line in the $analysis string for the results of its analysis. Here is an example two-line analysis result from a Rasnik acquire step.

Rasnik_1 8 129.64.37.79 00000000 6 1 0 0 5.6 "A2048L-B A2048R-B A2051L-S-B A2051R-S-B"
Rasnik_1 8 129.64.37.79 00000000 7 1 0 0 11.1 "A2045L-B A2045R-B A2052A-B"

The first word in each line is the step name. The number (8) is the step number in the script. The IP address, base address, driver socket, and multiplexer socket come next. A binary value (0 or 1) tells us if the Analyzer detected a repeater-multiplexer combination on the driver socket. Another binary value tells us if the Analyzer measured excessive currrent consumption after it turned on the repeater (if any). A real number gives us the current signature error in milliamps. A string lists the matching device types.

Analysis takes a few seconds, while most aquire steps take less than a second. You can expec a thousand-step Acquisifier script to run in twenty minutes without analysis, or one and a half hours with analysis. For more information about the anlyzer, see its manual entry