LWDAQ User Manual

Contents

Introduction

This manual tells you how to use our LWDAQ software in combination with our TCPIP-based LWDAQ hardware. We describe the LWDAQ drivers, multiplexers, and devices. We show how our TCPIP-based LWDAQ creates a stand-alone data acquisition system connected to the rest of the world through a single Ethernet socket. We explain how our data acquisition software runs on Windows, Linux, Unix, and MacOS, and describe how you can download and run the software on your own computer in a matter of minutes, and to configure it so that it transmits and stores your acquired data in a form convenient to you.

Figure: LWDAQ System with Driver and Computer Connected Directly. A lap-top computer (1) running our data acquisition software connects via a cross-over ethernet cable (7) to a driver (2). The driver connects via a a root cable (8) to a multiplexer (3). The multiplexer connects via branch cables (9) to devices (4, 5). In this case the devices are a Black Azimuthal BCAM (View) and a Blue Azimuthal BCAM (View). Another device (6), this being a Camera (A2056), connects directly to the driver via another root cable. Power comes from a 24-V wall adaptor cable (10).

Once we have introduced you to the hardware and software, we describe the details of the software, and its relationships with each of our most popular LWDAQ Devices. We tell you how to use the Configurator Tool to set the IP address and other configuration parameters for your LWDAQ's TCPIP interface. We show you how the Acquisifier Tool makes it easy for you to build a data acquisition system out of dozens or even thousands of devices, retrieve data from each in a cycle, and save the data to disk.

To help you understand what the LWDAQ is, and how our software lets you use the hardware, we recommend that you begin by downloading our data acquisition software. The Software Installation section below tells you how to install the software and test it with the help of our demonstration stand. Our demonstration stand is a selection of LWDAQ devices connected to an A2037E and available to everyone via the Internet.

Hardware Description

A Long-Wire Data Acquisition (LWDAQ) system conforms to the LWDAQ Specification. The term long-wire refers to the long cables you can use to connect devices, multiplexers and repeaters to drivers. The following figure shows how these four elements can connect together.

Figure: LWDAQ Architechture, showing Driver, Repeaters, Multiplexers, and Devices. Devices may be connected directly to drivers, or to multiplexers, with the same cables.

The cable that connects a driver to a device or multiplexer is a root cable. A cable that connects a multiplexer to a device is a branch cable. All sockets are RJ-45. Cables can be shielded or unshielded. Despite their different names, all LWDAQ cables are interchangeable. The same cable can connect a multiplexer to a driver, a device to a driver, or a device to a multiplexer. Devices and multiplexers can be plugged in and unplugged at any time without damage.

We describe the making and testing of LWDAQ Cables in our Cable-Making Manual. If your LWDAQ cables are less than ten meters long, you can use standard CAT-5 Ethernet patch cables. For longer cables, the slight differences between the LWDAQ and Ethernet connector pinout become significant, and you must use true LWDAQ cables.

Here are some example LWDAQ Devices. Each device contains an electronic circuit. Each electronic circuit is called a head to distinguish it from the device that contains it. Each device is controlled by an Instruments. The Instrument is a component of our LWDAQ Software.

• Polar BCAM Head (A2051). Use with BCAM Instrument.
• Bar Head (A2044). Use with Rasnik and Thermometer Instruments.
• Proximity Mask Head (A2045). Use with Rasnik Instrument.
• Proximity Camera Head (A2047). Use with Rasnik Instrument.
• Camera Head (A2056). Use with Camera Instrument.
• Resistive Sensor Head (A2053). Use with Thermometer, Flowmeter, and Gauge Instruments.
• Input-Output Head (A2057). Use with Voltmeter Instrument.
• RS232 Head (A2060C). Use with Console Instrument.
• RF Spectrometer (A3008). Use with RFPM Instrument.
• Data Receiver (A3018). Use with Recorder Instrument.

Example: The BCAM is an optical surveying instrument that contains up to two digital cameras and four laser diode light sources. As used in the ATLAS End-Cap Muon Spectrometer, BCAMs connect through ten-meter cables to multiplexers, through another twenty-meter cable to repeaters, and along a hundred-meter cable to drivers in the service chamber besice the ATLAS cavern. Individual pixel intensities travel as analog voltages from the BCAMs, through the multiplexers, cables and repeaters to the driver, where they are digitized and stored in memory.

Multiplexers allow use to connect up to fifteen devices to a driver with only one root cable. We use multiplexers in large systems, but only rarely in the laboratory. Multiplexer branch sockets are identified by their multiplexer socket number. Socket number zero is reserved for multiplexer and repeater internal control. Socket numbers one to fifteen are available for data acquisition.

Example: The Ten-Slot Multiplexer (A2046) provides ten sockets for branch cables and a single socket for a root cable.

The driver provides power to its multiplexers and devices. It transmits control signals down its root cables and receives analog and digital data in the other direction. One twisted pair of wires carries a serial digital signal from the driver. Another twisted pair carries a serial analog or digital signal back to the driver. For details of the LWDAQ serial communication protocol, see the Transmit Signals and Receive Signals sections of the LWDAQ Specification.

Figure: Front and Rear Views of the LWDAQ Driver with Ethernet Interface (A2037E). The Ethernet socket and Configuration Switch are on the back side. The 24-V DC power input is also on the back side. The Hardware Reset switch is on the front, along with indicator lights and eight sockets for LWDAQ Devices or Multiplexers.

A driver provides one or more driver sockets for root cables. These sockets are unshielded RJ-45. The sockets at the other end of the root cables are always shielded. The driver sockets are identified by their driver socket number. Socket number zero is reserved for internal current and voltage monitoring. Socket numbers one to fifteen are for data acquisition.

Example: The A2037E gets its power from a power adaptor that you plug into an AC wall socket. It communicates with the outside world via TCPIP over Ethernet. There is an RJ-45 socket on the back side of the driver for 10-Base-T Ethernet. On the front side are eight RJ-45 sockets for root cables. The sockets are numbered one through eight, with number one next to the indicator LEDs and number eight farthest from the LEDs.

Example: The LWDAQ Driver with VME Interface (A2037A) is a 6U VME board for use in large LWDAQ systems. The A2037A provides eight driver sockets and occupies 512 KBytes of address space.

Figure: A2037As in VME Crates in the ATLAS USA15 Service Chamber. These crates run the End-Cap Muon Alignment System. On the left is Christoph Amelung of Brandeis. On the right is Jim Bensinger of Brandeis. Photo taken Jun 2008.

A LWDAQ Server is the combination of a TCPIP connection and one or more LWDAQ Drivers.

Example: We use the A2037A in conjunction with the VME-TCPIP Interface (A2064). The A2064 provides communication with all drivers in its VME crate through a single Ethernet connection. We select a driver socket by specifying the driver's base address and the socket number. In the figure above, each VME crate is a LWDAQ Server. Each crate contains a single TCPIP-VME Interface (A2064F) and twenty LWDAQ Drivers (A2037A). Each server provides 160 driver sockets. Each driver socket connects to a multiplexer at the end of roughly 100 m of root cable. Each multiplexer is connected to an average of eight devices. Each of these servers therefore provides access to roughly one thousand devices.

A LWDAQ Server accepts TCPIP connections to its IP address on a user-configurable port number. It responds to TCPIP messages that conform to the LWDAQ TCPIP Message Protocol. We describe this protocol in detail in the TCPIP Messages section of the LWDAQ Specification. The portion of a LWDAQ Server that receives and interprets TCPIP messages is a LWDAQ Relay. Each server has only one relay.

Example: The LWDAQ Driver with Ethernet Interface (A2037E) uses an RCM2200 TCPIP Module to implement its relay. The VME-TCPIP Interface (A2064A) does the same. The faster VME-TCPIP Interface (A2064F) uses an RCM3200.

The part of a LWDAQ Server that transmits and receives electrical signals to and from LWDAQ Devices is called a LWDAQ Controller. A single server can contain many controllers.

Example: The LWDAQ Driver with Ethernet Interface (A2037E) is a self-contained LWDAQ Server with a single relay and a single controller with eight driver sockets. The VME crate LWDAQ Servers shown in the figure above each contain a single relay and twenty controllers.

The Configurator Tool and the Diagnostic Instrument both allow you to determine the hardware id and hardware version of a relay, which tell you what type of relay it is. We list the relationship between the hardware id, hardware version and assembly name in the table below.

We connect to a LWDAQ Server with a LWDAQ Client. The client runs on a computer somewhere on the same TCPIP network as the server. Our client software runs on Windows, MacOS, and Linux. We describe our LWDAQ Software in the next section.

Software Description

You can read this description without loading our software on your machine, but if you would rather have the software loaded, so you can type in the examples at the LWDAQ console, we invite you to jump to the Software Installation section and follow the installation instruction for your platform before you proceed.

It is possible for you to write your own software to send and receive messages to and from the LWDAQ over TCPIP. We know of at least one lab that has a direct interface from LabView to LWDAQ. Nevertheless, we have done our best to provide you with a program communicates with the LWDAQ hardware and analyzes the acquired data. Our LWDAQ software is a combination of analysis routines written in Pascal and communication routines written in TclTk.

The core of our LWDAQ Software is a TclTk interpreter. This interpreter executes the TclTk scripts that control the LWDAQ over TCPIP and creates our graphical user interface. It loads our analysis library and makes its routins available to our scripts as TclTk commands.

Image analysis and drawing are computationally intensive. We do both in Pascal. We compile our Pascal code for all platforms with GPC, the GNU Pascal Compiler. We create a shared library called lwdaq.so on Linux, lwdaq.dll on Windows, and lwdaq.dylib on MacOS. This is our analysis library. Our analysis library is for use with our LWDAQ software only. If you want to use our analysis routines in another context, we recommend you compile analysis.a, our static analysis library. You will find instructions for mixing Pascal and C code in our Mixing Manual. You will find instructions on compiling our static analysis library in Rasnik Manual.

The GPC compiler and TclTk are open source programs freely available over the internet and well-documented on the web. There are many good books available on TclTk. We use Practical Programming in TclTk by Brent Welch. TclTk is a scripting language understood by TclTk interpreter programs, in the same way that UNIX is a scripting language understood by a UNIX shell. The TclTk interpreter, called the Wish Shell, exists for almost every computer operating system. The Wish Shell is usually installed automatically with Linux and Unix, and you can download it yourself for Windows and Linux and for MacOS. Once you install and run the interpreter on your computer, and it will run any TclTk script. For example, the following script opens a socket to IP address lwdaq.hep.brandeis.edu port 90, and then closes the socket.

set sock [socket lwdaq.hep.brandeis.edu 90]
close $sock

You can, of course, send and receive data from the socket. It does not matter what platform you are on, the same script works because all the platform-dependence of opening and using a TCPIP socket has been taken care of and hidden from you by the TclTk interpreter. The following script creates a button that writes Hello World to the console every time you click on the button with the mouse.

button .helloworld -text "Hello World" -command "puts {Hello World}"

When you start our LWDAQ program, you start a TclTk interpreter (a Wish Shell). We have changed its appearance, but it is still a Wish Shell. You will come across the name Wish and the TclTk feather icon in odd places as you use the program. When the LWDAQ program starts up, it runs our initialization scripts, loads the analysis library, and creates our LWDAQ user interface. The File, Instrument and Tool menus appear in the LWDAQ menu bar. The Instrument menu opens windows that control the various LWDAQ instruments. Each instrument performs a particular type of data acquisition and analysis.

Example: The BCAM Instrument acquires images from BCAM devices.

The windows opened by the Instrument Menu are the instrument panels. Each instrument panel allows you to control one of the instruments. We can control the instruments from the command line also, without using the panels. The non-graphical version of LWDAQ runs with only a terminal interface, and the no-console version runs in the background without even a terminal.

Example: Open the Camera Instrument and press Acquire. If you are on the Internet, you will obtain data from our demonstration stand at Brandeis University Physics Department in Boston, USA. The picture should be of our hallway.

If you have your own Driver with Ethernet Interface (A2037E), connect it to your laptop directly with a cross-over Ethernet cable and confifure its TCPIP interface to suit your local area network with the help of the Configurator tool in the Tool menu. Once you have your devices connected to your driver, and the driver connected to the Internet, you can display and record measurements from your LWDAQ Devices (hardware objects) using the LWDAQ Instruments (software routines).

Ultimately, you will want to use several instruments together in an experiment. You will want record measurements to disk and take data in a continuous cycle. You can combine instruments and record data with our Acquisifier Tool. You can also write your own tool to define your own window with buttons and a display. You create such a tool by defining it with a TclTk script. You can either run your TclTk script from the LWDAQ Tool Menu, or you can create a version of LWDAQ that runs your script automatically at startup. We describe how you can make your own tools to work with LWDAQ in the Tools section of this manual. There are several such tools available in the Tools Menu.

Example: The Spectrometer Tool uses the Radio-Frequency Power Meter Tool to plot a graph of power density versus frequency. The BCAM Calculator calls no instruments, but analyzes calibration data on disk. The BCAM Calibrator obtains BCAM calibration data.

In your scripts, you will have at your disposal our LWDAQ Script Commands, the names of which all start with the letters LWDAQ, and our LWDAQ Library Commands the names of which all start with the letters lwdaq. The script commands are defined by the TclTk scripts executed by the LWDAQ program at start-up, or when you select Re-Initialize from the File menu. The library commands are contained in a shared library called lwdaq.so that we pre-compile for you from our Pascal source code. The LWDAQ program loads lwdaq.so at start-up, and calls its initialization routine. The lwdaq.so initialization routine installs the lwdaq.so routines in the TclTk interpreter, so that they are available at the TclTk command line, and may be called in our TclTk scripts, and your own TclTk tools. We describe our LWDAQ procedures in the Commands section of this manual, and in the LWDAQ Command Reference.

When the LWDAQ program connects to a LWDAQ Driver, it does so over TCPIP. All our instruments and tools use the LWDAQ_socket_open routine declared in the Driver.tcl script file to open the TCPIP connection to a driver. To open a TCPIP socket, we must specify an IP address and a port number. The LWDAQ_socket_open routine will accept either a numerical address or a host name. You specify the port number by adding it to the end of the IP address, separated from the address itself by a colon, like so:

LWDAQ_socket_open lwdaq.hep.brandeis.edu:90

By default, we use port number 90 on the LWDAQ Driver with Ethernet Interface (A2037E) and the VME-TCPIP Interface (A2064). If you do not specify a port number, LWDAQ assumes you are trying to connect to port 90. The LWDAQ's TCPIP can be re-programmed, however, to accept connections on different port number.

You specify the driver socket you want to use to communicate with your target device using the LWDAQ_set_driver_mux routine. Sometimes there is more than one LWDAQ Driver associated with the TCPIP socket you have opened. For example, if you have a VME-TCPIP Interface (A2064) plugged into a VME crate, you might have twenty LWDAQ Driver with VME Interface (A2037A) in the crate, and to select one of them you need to specify its base address to the VME-TCPIP interface. The LWDAQ software combines the act of selecting a drivers socket with the act of selecting a driver. You specify the base address of the driver with an eight-digit hex number.

LWDAQ_set_driver_mux $sock 00E00000:1 3

The above command selects the driver at base address hexadecimal "00E00000". It selects socket 1 on that driver, and transmits an address word down this socket to direct a multiplexer, if there is one connected, to select branch socket 3. In the following command, we have left out the base address, and select driver socket 1 and branch socket 3.

LWDAQ_set_driver_mux $sock 1 3

The The LWDAQ program stores all its measurments as two-dimensional arrays of bytes, which we call images. The measurement received from a camera really is an image, and we have found that the same format will accomodate any instrument we care to invent. All images are maintained by the compiled Pascal procedures. Here's the TclTk script command that draws an image with name an_image in a TK photo (drawing area in a window) with name a_tk_photo:

lwdaq_draw an_image a_tk_photo

If you want to intensify the image, you can do so:

lwdaq_draw an_image a_tk_photo -intensify strong

Look at the Camera instrument below for a description of the intensification options. Open the Camera instrument, acquire an image from our demonstration stand, and then let the Camera sit in its Idle state. Now open the console (if it is available on your platform, see Software Installation). Type the following and press return:

LWDAQ_acquire Camera

You will see the Camera capture a new image. The console will show the result returned by your TclTk command. The result is a the name of the image you captured and a string of numbers giving characteristics of the image. You can do the same for any of the instruments defined in the Instrument menu, and each of them will return a string with an image name and results. The data acquisition will take place whether the instrument panel is open or not. To understand what the results are, look at the section in this manual that describes the instrument, or set verbose_result to 1 in the instrument panel, and acquire again.

We call custom scripts tools. Tools are simply text files containing TclTk commands that you can execute from LWDAQ. We provide a number of them in the Tools menu, written by ourselves and other LWDAQ users. You can write your own to manage your own data acquisition system, and run them on any computer upon which you have installed the LWDAQ software. If your desktop computer runs windows, but your lap-top is an iBook, you will use the same tool on both computers. The LWDAQ is not tied to any computer or any operating system. You can access your data acquisition system from anywhere in the world, or you can keep it private on a local area network.

Software Installation

We distribute our LWDAQ software as a ZIP archive and a DMG archive. You will find the latest version of our software at our Software page. The DMG archive suits MacOS users because it preserves file icons. The ZIP archive works on all platforms.

Although the contents of the archive you download are the same for all platforms, the installation procedure varies from one platform to the next. The archives contain three versions of the TclTk interpreter, one each for Linux, Windows, and MacOS. We do not provide TclTk interpreters for Unix machines.

Linux

Download the ZIP archive from our website. Extract the entire contents of the archive and place them in a directory of your choice. In a Linux terminal run the lwdaq shell script you will find in the LWDAQ directory.

./lwdaq

The terminal window acts as a TclTk console. Open the Camera instrument from the Instrument menu and press Acquire. You should get an image from our demonstration stand. Everything you need to run LWDAQ is contained in the LWDAQ application bundle. The other files and directories contain example Tools, of which the Configurator is the one you are most likely to need, example images, and the Pascal source code.

The lwdaq command calls the TclTk or Tcl interpreter included with our LWDAQ distrubution, depending upon the options you pass it. You can also run LWDAQ in your own TclTk or Tcl interpreter, although we cannot guarantee compatibility between our scripts and your interpreters.

To compile our Pascal source code, download and install GPC 20030830 or later. You will find binary distributions of GPC for Linux at the here. The most recent binary available is 20041218. We use the standard Linux version, here. These binary GPC distrubutions come with their own GCC libraries. They do not affect your own installation of GCC. But you will need GCC to compile the lwdaq.so shared library. We use GCC to perform the final link. So make sure you have GCC installed on your system as well.

Once you have GCC and GPC installed, go to the LWDAQ/Build directory and type "make". The Makefile will direct GPC to compile all the Pascal source code and install the lwdaq.so library in the LWDAQ.app directory tree, ready for loading at run-time.

We obtain the Linux versions of our embedded Tcl and TclTk interpreters from ActiveState.

MacOS

Download the LWDAQ dmg archive. Copy all files from the read-only virtual hard drive the DMG creates. You can download and use the zip archive instead, but the LWDAQ application icon will not be installed automatically from the zip archive. If you are running Mac OS 10.2, the analysis libraries we distribute with LWDAQ may not run on your machine. If you get an error telling you that Wish could not find libmx.A.dylib, you are running MacOS 10.2 or earlier, which we do not support.

You can launch LWDAQ with the Finder or from a Terminal window. The easiest is to double-click on the LWDAQ icon. The LWDAQ icon is actually a folder called LWDAQ.app. The extension .app is hidden by the Finder. Nevertheless, LWDAQ.app is a directory and you can see what's inside by control-clicking on the icon and selecting Show Package Contents.

If you run LWDAQ from the terminal, the terminal acts as a primitive TclTk console. If you double-click on the LWDAQ icon, you have available a more sophisticated TclTk console by selecting Show Console from the File menu.

Once you have LWDAQ running, and assuming you are connected to the Internet, open the Camera instrument from the Instrument menu and press Acquire. You should get an image from our demonstration stand. Everything you need to run LWDAQ is contained in the LWDAQ application bundle. The other files and directories contain example Tools, of which the Configurator is the one you are most likely to need, example images, and the Pascal source code.

When you select Show Console on MacOS X, you get a new application window with a new menu. To get back to the menu, click on one of the LWDAQ windows. The console has a Source and Quit option, but otherwise its menus differ from those of LWDAQ.

When LWDAQ opens up with graphics, it presents you with a main window and a menu. The main window has only one button it it: Quit. If you close the main window, the program quits. We thought about getting rid of the TclTk main window, but TclTk uses it in two ways. First, when you open the console, you get a new set of menus. How do you get back to the LWDAQ set of menus? You have to click on an instrument or the main window. If you have no instruments open, you have to click on the program icon in the dock, or select Hide Console from the console's menu. Second, when we put up standard TclTk dialog boxes, they appear on top of the main window. If we hide the main window, they don't show up on the screen. So, we have been forced to keep the TclTk main window, with its redundant Quit button.

If you would need to re-compile our image analysis libraries, install a version of the GPC (GNU Pascal Compiler) that works with your version of MacOS and your computer architecture. The latest versions of the compiler are available from Microbizz. Open the Terminal program and navigate to LWDAQ/Build. Enter make at the command prompt. The compilation will proceed through the Pascal source files, and finally create the lwdaq.dylib library for MacOS.

We build our embedded versions of the Tcl and Tk interpreters from sources, which we obtain from the Tcl Developer Exchange. First we compile the Tcl interpreter, with make embedded and name it tclsh. We make its reference to its own libraries relative to its own location with the install_name_tool as follows (for Tcl 8.5).

install_name_tool -change \
  /Library/Frameworks/Tcl.framework/Versions/8.5/Tcl \
  @executable_path/../Frameworks/Tcl.framework/Versions/8.5/Tcl \
  tclsh

We compile the TclTk intepreter with make embedded also, and we use the resulting Wish.app as the starting-point for our LWDAQ directory structure.

Unix

We do not include a Unix analysis library in our LWDAQ distribution, nor a TclTk interpreter. You must download and install GPC (the GNU Pascal Compiler) for your Unix platorm. Check that your system has TclTk installed. If not, download the TclTk source code and compile it with GCC. Start your search here.

Once you have TclTk and GPC installed, download and decompress our LWDAQ zip archive. Go to the LWDAQ/Build directory and type make. You should see GPC compiling our Pascal files into object code. The final step is to link the object code to the GCC, GPC, TCL, and TK libraries with GCC. This step will most likely fail. You must modify the Makefile to direct the complier to the TclTk and GCC libraries.

Once you have modified the Makefile to refer to all the necessary libraries in the final link of lwdaq.so, type make again. The compilation should proceed through the final step, and create lwdaq.so. Now you can run LWDAQ from the terminal in any of the following ways.

In all cases, LWDAQ runs inside the TclTk or Tcl interpreters you installed in your system. There are no Unix TclTk interpreters bundled with LWDAQ.

Windows

We have tested LWDAQ on Windows NT, 2000, and XP. Download the LWDAQ ZIP archive and extract all files into a directory of your choice. Double-click on LWDAQ.bat. You should see the LWDAQ main window open up.

You can make a shortcut to LWDAQ.bat and associate the LWDAQ icon with the shortcut. The shortcut can be anywhere on your computer. Right-click on the shortcut file and select Properties. Click Change Icon... Browse to lwdaq.ico in LWDAQ\LWDAQ.app\Windows. Click OK twice.

You can re-compile our Pascal analysis library by installing a minimal Unix shell called MinGW. Go to the MinGW Download Page. Download and run the Automated MinGW Installer. Install the bare minimum files of MinGW. Go back to the same download page and download the most recent version of the MYSIS shell program for MinGW. You will end up with an icon on your desktop for the MYSIS shell. When you double-click on the icon, a Unix terminal opens up.

The MYSIS terminal has the GCC compiler available to you. We use this compiler to compile the TclTk source code for Windows. To compile our analysis code, you must install GPC for MinGW. Download the latest version with GCC support files and save it in your MinGW parent directory. If you put MinGW in C:\MinGW, put the archive in C:\. The download file is a g-zipped tarball with extension .tar.gz. Run MYSIS, go to the directory containing the archive and enter the following command.

tar xzvf archive.tar.gz

The tar decompression takes files in the tarball and places them in the correct location in the MinGW directory tree. The decompression may take a minute. When it's done, at your MYSIS prompt, enter gpc. You should see the version number of the GNU Pascal Compiler you just installed, and other information.

In MYSIS, go to the LWDAQ_Dir/Build directory and type make. Make will use GPC to compile all the Pascal files in the LWDAQ_Dir/Sources folder. It uses GCC to link the object code to the TclTk libraries in the LWDAQ budle. The result is a new lwdaq.dll analysis library, which Make installs in the LWDAQ directory tree.

At this point, you can run LWDAQ by double-clicking on the LWDAQ.bat file.

When you run lwdaq from the MinGW prompt, you must first remove the hash-bang at the top of the lwdaq script file. The MinGW installation is so minimal that it does not include the bash shell as a command, even though it is itself a Bash Shell. You can run lwdaq from the Cygwin prompt without modification.

We obtain the Windows versions of our embedded Tcl and TclTk interpreters from ActiveState.

Hardware Installation

To set up a LWDAQ that uses the A2037E or A2064, you must connect power to the driver and configure its IP address, subnet mask, and gateway address to suit your local network. Connect the LWDAQ directly to your computer with a cross-over ethernet cable and run our LWDAQ software. You will have to change your computer's TCPIP settings so that it can talk to the LWDAQ over the isolated TCPIP network created by your single cross-over cable. See the Configurator section below for more detailed instructions. Use the Configurator tool first to contact your LWDAQ, and then to configure its TCPIP interface.

Once the LWDAQ has an IP address, gateway address, and subnet mask that matches your local network, you can plug it into your local network network with a straight-through ethernet cable and communicate with it from anywhere on the Internet. We almost always communicate with our LWDAQ systems over our wireless network from our laptop computers, as shown in the following figure.

Figure: LWDAQ System with Driver Connected to Local Ethernet. We can use the LWDAQ System from the lap-top sitting on the same table, via our wireless network. The driver in this figure connects to many instruments in our laboratory. The lap-top is near one sets of instruments.

The LWDAQ TCPIP interface provides some primitive password protection to restrict access if you wish to do so. If you access the LWDAQ only from your local network, then our primitive password protection will be secure, because you will never transmit the password across the Internet. Alternatively, you can connect the LWDAQ directly to a lap-top and run it on an isolated IP network, in which case it will be completely secure.

You can test your LWDAQ Driver power supplies and internal logic with the Diagnostic instrument. If your are testing a driver in a VME crate, you must specify its base address in the daq_target_driver_socket parameter.

Directory Tree

Here is the directory tree of our LWDAQ software distrubution archives. Each archive contains all the files and directories needed for all supported platforms.

lwdaq     {Call from terminal to start LWDAQ}
LWDAQ.bat {Double-click to start LWDAQ on Windows}
LWDAQ.app {Double-click to start LWDAQ on MacOS X}
  Contents
    LWDAQ
      Info.plist {MacOS}
      PkgInfo {MacOS}
      Resources
        Scripts
          AppMain.tcl {MacOS startup script}
      MacOS
        {MacOS TclTk interpreter}
        {MacOS Tcl interpreter}
      Frameworks
        {MacOS TclTk libraries}
      Windows
        {Windows TclTk interpreter}
        {Windows Tcl interpreter}
        {Windows TclTk libraries}
        {Windows icon}
      Linux
        {Linux TclTk interpreter}
        {Linux Tcl interpreter}
        {Windows TclTk libraries}
        {Linux icon}
      LWDAQ
        License.txt
        CRT.html {command reference template HTML file}
        Init.tcl {initializes global arrays and calls other scripts}
        Utils.tcl {utility routines}
        Driver.tcl {tcpip communication with driver}
        Interface.tcl {graphical user interface}
        Instruments.tcl {instrument management routines}
        Tools.tcl {tool routines}
        Toolmaker.tcl {saved toolmaker scripts}
        Settings.tcl {if present, lwdaq will load it}
        Instruments
          BCAM.tcl
          Camera.tcl
          Diagnostic.tcl
          Flowmeter.tcl
          Gauge.tcl
          Inclinometer.tcl
          Rasnik.tcl
          Recorder.tcl
          RFPM.tcl
          Console.tcl
          Thermometer.tcl
          Viewer.tcl
          Voltmeter.tcl
          WPS.tcl
        Startup
          {startup tool scripts}
          Data 
            {data files for startup tools}
    lwdaq.dylib {MacOS analysis library}
    lwdaq.so {Linux or Unix analysis library}
    lwdaq.dll {Windows analysis library}
Tools
  Acquisifier.tcl
  BCAM_Calculator.tcl
  BCAM_Calibrator.tcl
  Configurator.tcl
  Image_Browser.tcl
  Motion_Sensor.tcl
  Neuroarchiver.tcl
  Spectrometer.tcl
  More
    {more tools}
  Data
    {data files for tools}
Sources
  {pascal sources for analysis library}
Images
  {sample images}
Build
    Makefile {compile from terminal on all platforms}
    c.c {example c program}
    p.pas {example pascal program}
    cpp.cpp {example c++ program}

Note that on MacOS, the Finder hides the .app extension of LWDAQ.app. Instead of a called LWDAQ.app, the Finder shows you an icon called LWDAQ. Double-click on the icon, and LWDAQ opens up. Windows also hides file name extensions, but the manner in which it does this varies from one version of the operating system to the next, and depends upon your own preferences. The same thing might happen on Linux, but we have very little experience with Linux.

Demonstration Stand

We have a LWDAQ driver demonstration stand connected to the internet at the address lwdaq.hep.brandeis.edu. When you open LWDAQ for the first time after a fresh installation, you will find that the daq_driver_addr is set to this address in all the instruments. You can open any instrument and acquire measurements with each. The Camera instrument should give you a picture of the hallway of the Brandeis University High Energy Physics Laboratory.

Figure: Demonstration Stand in the Brandeis University High Energy Physics Laboratory (Boston, USA), showing LWDAQ Driver with Ethernet Interface (A2037E) at IP address lwdaq.hep.brandeis.edu (1), local ethernet connection (2), root cable to hallway camera (3), Input-Ouput Head (4), Inplane Mask Head with Rasnik mask (5), short-range BCAM looking at Rasnik mask (6), Blue Azimuthal BCAM (7), Inplane Mask Head that drives the cooling fan (8), indicator LED that tells us the fan is on (9), cooling fan (10), flowmeter sensor (11), RTD Head (12), RTD sensor cables (13), Black Azimuthal BCAM (14).

Users of LWDAQ can access the demonstration driver simultaneously. When two users are using the driver at the same time, you will see the state label in your instrument panel turning red to show that the instrument is waiting for an opportunity to connect.

Windows and Menus

The main window has a quit button. You can quit the program by pressing the quit button, closing the main window, selecting Quit from the LWDAQ menu, or pressing apple-q on MacOS and control-q on Linux. The LWDAQ main window has the following menus on all platforms: LWDAQ, File, Tool, Instrument.

The File menu provides you with with up to seven options: Show Console, Hide Console, Re-Initialize, Save Settings, Load Settings, System Server, System Monitor, and System Reset. Show Consol and Hide Consol open and close the TclTk console. These may or may not appear in your menu, depending upon how you launched TclTk, and upon your operating system. Re-Initialize resets LWDAQ to its default state, just as if you had started LWDAQ without your own settings file.

Save Settings saves your current LWDAQ settings, including all Instrument settings (see below) to a file you specify in with a file browser window. Load Settings loads previously-saved settings from a file you specify with a file browser window. You can force LWDAQ to load your own settings on start-up by putting your settings file (which you created with the Save Settings menu option) in the LWDAQ.app/Contents/LWDAQ directory, and naming it Settings.tcl.

The Reset command stops all instruments, and should result in the event queue emptying and all TCPIP communication stopping. The reset takes a few seconds, as determined by the global reset_duration_ms variable.

The Tool menu provides at least one option, Run Tool. Run Tool, lets you select a TclTk script file with your platform's file browser. LWDAQ will execute the script file at the global TclTk scope, and the script will have access to all LWDAQ's procedures, both those defined in LWDAQ's TclTk scripts and its Pascal library. In addition to the Run Tool option, The Tool menu contains a menu item for each tool LWDAQ finds in the Tools folder at start-up. You can run the tool by selecting its menu item, which saves you a few mouse-clicks compared to running the tool with the Run Tool option.

The Instrument menu has one entry for each instrument defined by your version of LWDAQ. To open an instrument, select it from the menu. Alternatively, you can type LWDAQ_open in the console, or execute the same command in a script, followed by the instrument name (case-sensitive). The following line opens the instrument.

LWDAQ_open Diagnostic

We talk more about instruments in the Instruments section below.

Configurator

The Configurator allows you to communicate with a LWDAQ, read the configuration parameters of its TCPIP interface, and write a new list of configuration parameters to its EEPROM memory. After the next hardware reset or power cycle, the new configuration parameters will be come active. The Configurator is a LWDAQ tool defined by the Configurator.tcl script in the Tools directory. Select Configurator from the Tool menu, and the Configurator Panel will appear.

One example of a LWDAQ is a single LWDAQ Driver with Etherenet Interface (A2037E). The A2037E has eight driver sockets and one TCPIP interface. The Configurator contacts the A2037E using contact_ip_addr and contact_ip_port. Another example of a LWDAQ is a VME crate containg 20 LWDAQ Drivers with VME Interface (A2037A). Each A2037A provides eight driver sockets, but has no TCPIP interface. A single TCPIP-VME Interface (A2064) in the same crate provides a TCPIP interface for all the drivers in the crate. The Configurator contacts the A2064 using contact_ip_addr and contact_ip_port. It identifies an individual A2037A in the crate with contact_base_addr.

The contact_base_addr parameter contains the thirty-two bit hexadecimal base address of an individual driver in a LWDAQ. When contact_base_addr is 00000000, the Configurator assumes a LWDAQ with one TCPIP interface and only one. Otherwise the Configurator assumes a LWDAQ with one TCPIP interface and multiple drivers. The Configurator reads out a variety of identifiers and version numbers. These allow you to confirm the kind of hardware the Configurator is talking too, as shown in the following table. For now, we assume that we are configuring a single-driver LWDAQ. At the end of this section we'll talk about multiple-driver LWDAQs.

The first step in the Configuration process is to make contact with the LWDAQ over TCPIP. Let us assume that our TCPIP interface is fresh from the factory with our default IP address 10.0.0.37. Apply power to the LWDAQ and connect it directly to a computer with a cross-over ethernet cable. (You don't need the crossover with an Apple computer or the newer PCs because they auto-negotiate the polarity of the Ethernet connection.) The computer and the LWDAQ now form an isolated two-node Internet. Set your computer to use gateway address (or router address or subnet address) 10.0.0.1, and assign your computer its own IP address on the 10.0.0 subnet. You could pick 10.0.0.2. Don't pick 10.0.0.1 or 10.0.0.37.

On MacOS, create a new location with the Network Locations panel. We call ours LWDAQ. If you want simultaneous access to the Internet via your wireless card, turn on the Ethernet and Airport adaptors, and move the Airport adaptor to the top of the list, so your computer tries it first. If you work on Windows, follow these instructions. If you work on Linux, we will leave it to you to find out how you can perform the switch, and the subsequent switch back again to your normal IP configuration. If you are willing to e-mail us instructions, we'll link to them from here.

Now that your computer and the LWDAQ are connected together, and, we assume, operating on the 10.0.0 subnet, enter 10.0.0.37 in the contact_ip_addr box in the Configurator. Make sure that contact_password, contact_ip_port, and contact_base_addr are LWDAQ, 90, and 00000000 respectively. Press the Contact button. The Configurator will tell you whether it can contact the driver. If it makes contact, it will report the LWDAQ's MAC address and version numbers.

Attempting to open socket...success.
Attempting login...success.
Relay Software Version: 12
Relay MAC Address: 0090c2c1905f
Controller Hardware ID: 37
Controller Hardware Version: 1
Controller Firmware Version: 11
Closing socket...closed.

If the Configurator cannot make contact with the LWDAQ, try resetting the LWDAQ's EEPROM configuration file. Hold down the Configuration Reset button. This button is next to the shielded Ethernet jack on the A2037E, and on the top side of the board on the A2064. Press and release the Hardware Reset button. This one is on the front side of the A2037E next to the indicator LEDs, and on the front panel of the A2064. Keep holding the Configuration Reset button for at least three seconds after you release the Hardware Reset button. You have reset the configuration parameters stored in the non-volatile (EEPROM) memory of the LWDAQ to their default values.

ip_addr: 10.0.0.37
gateway_addr: 10.0.0.1
subnet_mask: 255.255.255.0 
ip_port: 90
password: LWDAQ
operator: relay_version_X (X is your relay software version)
security_level: 1
tcp_timeout: 0
configuration_time: 00000000000000
driver_id: none_assigned

Configuration parameters must not contain any white-space characters, colons (:), semi-colons (;), or commas (,). They may contain periods (.) and dashes (-) and underscores (_).

Try again to contact the LWDAQ with the Configurator. If you don't succeed, check your cables. Look at the lights on the front of the LWDAQ. The two yellow ones nearest to the Hardware Reset button are its Link and Activity lights. One should be on permanently when your cable is plugged into the shielded Ethernet socket. Don't be distracted by the eight unshielded RJ-45 sockets on the front of the A2037E. These are not Ethernet sockets. They are the LWDAQ sockets. If you don't get a Link light, then there is something wrong with your cable, or your computer's Ethernet connection, or you have a broken LWDAQ TCPIP interface. If the Link light is on, the Activity light should be flashing occasionally. If it is not flashing, then your computer is probably set to communicate over a modem or wireless network, and is ignoring its 10-Base-T Ethernet connection.

Let us assume that you have now made contact with the LWDAQ. You can now run the LWDAQ program and use the driver. Alternatively, you might like to change the LWDAQ's IP address. If so, press the Configurator's Read button to read out the LWDAQ's active configuration parameters from RAM. You should see values for each of the parameters we listed above appear in the read_* parameter boxes. Press Copy to copy these parameters into the write_* parameter boxes. You will notice that the configuration_time parameter does not get copied. Leave it blank and the Configurator will fill it in with a current time stamp when you write a new configuration file to the LWDAQ.

Set the IP address, gatweay address, and subnet mask to match your local area network, if that is what you want to do. Enter your name for "operator".

You might also like to change the LWDAQ password, security level, and TCP timeout. Depending on the LWDAQ's security level, the LWDAQ software may or may not have to transmit the correct password in order to perform data acquisition or read and write the configuration file. Here are the restrictions enforced by the ascending security levels:

All the LWDAQ instruments have an daq_password parameter. If you set this parameter to anything other than "no_password", the instrument will always attempt to log into the LWDAQ before it performs any data acquisition function.

The LWDAQ program does not encrypt the password when it logs into the LWDAQ. The password offers no real security, and we hope that you will not use it to safeguard your data acquisition system. The purpose of the password is to give you a way of telling other users that they are not welcome to use this particular driver, or to alert them to the fact that they are connecting to your driver, and not their own driver. You will not be able to protect your data acquisition system from hackers with this password system. A simple Ethernet packet sniffer, combined with a knowledge of the publicly-available LWDAQ message protocol, will allow anyone on your local Ethernet to pick your password up immediately. Nor can you protect your LWDAQ by setting the ip_port to some unpredictable value, because it is a simple matter for a TCPIP sniffer program to determine which IP ports on your driver are active.

The tcp_timeout parameter determines the length of time for which a TCPIP connection to the LWDAQ can be idle before the LWDAQ closes the connection. By default, the tcp_timeout is 0, which is a special value indicating that the timeout is infinite. But if you have a LWDAQ available on the Internet, consider setting the timeout to thirty seconds so that the LWDAQ will not hang up when a connection breaks because of a hardware failure or catastrophic system crash on the computer at the other end of a TCPIP connection. The LWDAQ software never leaves a connection open to a driver for longer than it takes to acquire data.

Now that you have filled in all the values in the write_* boxes of the Configurator window, you are ready to write the new configuration to the LWDAQ's non-volatile (EEPROM) configuration file. Press the Write button. The EEPROM has been re-written. Press the Read button. You get the same values as before: you have re-written the EEPROM, but you have not loaded the new EEPROM values into the LWDAQ's RAM. Your new configuration parameters will have absolutely no effect on the operation of the LWDAQ until you press and release the Hardware Reset button on the front of the LWDAQ next to the LEDs. Don't press the Configuration Reset button this time, or you will over-write your new parameters with the factory default values, and be forced to go through the Configurator procedure again.

The LWDAQ has re-started with ints new configuration parameters. Press the Read button in the Configurator. If you changed the LWDAQ's IP address, you won't be able to make contact any more. Change the IP address in the contact_ip_addr box to match the new LWDAQ IP address. Press the Contact button. If the new IP address is not on the 10.0.0.x subnet, you still won't be able to make contact.

Suppose you changed contact_ip_addr to 129.64.37.79. If your computer tries to send your contact request to address 129.64.37.79 across the cable that leads to the LWDAQ driver, your computer will not send the request to address 129.64.37.79 directly. You set up your computer with address 10.0.0.20, and told it that the gateway was at 10.0.0.1. When it sees that you want to send a message to 129.64.37.79, it transmits the message to the gatewy, at 10.0.0.1, so that the gateway can forward your message to a router and so through the Internet to 129.64.37.79. But there is no gateway at 10.0.0.1, so your contact request fails.

If you have a second active TCPIP connection, such as a wireless card, your computer will try to send your contact request out over the Internet through the wireless card. But 129.64.37.79 is not available on the Internet. It is sitting on a two-node network made of one cable joining it to your computer. So even this communication through the wireless card will fail to reach the driver.

Your next step, therefore, is to plug your LWDAQ into your local area network, whose subnet must match your LWDAQ's subnet. Make sure your computer is connected to the same local area network. Press Contact. You should not get a contact confirmation. Press Read. You should see your configuration parameters.

The next time you want to change the configuration of your LWDAQ, you can run the Configurator and connect to the driver over your local area network using its existing IP address. Make your changes and save. So long as you don't change the gateway address, and your new IP address is still on the same subnet, you can reset the LWDAQ with the Hardware Reset button, and read back the new configuration immediately.

You will note that it is impossible for anyone to change the current configuration of an LWDAQ over the network. You must press the Hardware Reset button to implement the new configuration. Noone can connect to your driver and re-configure it so it will no longer respond to you. All they can do is run interference with continuous data acquisition of their own.

When your LWDAQ contains multiple drivers, the Configurator can read the hardware identifier, hardware version, and firmware version of individual drivers within the LWDAQ by means of its contact_base_addr parameter. Set this to the hexadecimal base address of the driver you want to examine. Once you set contact_base_addr to a non-zero value, the Configurator extends its contact queries to include separate interrogations of the TCPIP interface hardware and the driver hardware.

Attempting to open socket...success.
Attempting login...success.
Interface Software Version: 12
Interface MAC Address: 0090c2d295fb
Interface Hardware ID: 64
Interface Hardware Version: 1
Interface Firmware Version: 3
Driver Hardware ID: 37
Driver Hardware Version: 0
Driverr Firmware Version: 10
Closing socket...closed.

The above lines are an example text output from the Configurator when it contacts an A2064 in a VME crate with an A2037.

Analyzer

The Analyzer measures the power consumption of a device in response to a sequence of command words. All LWDAQ drivers allow us to measure the voltage and current of the LWDAQ power supplies. These supplies are nominally +15V, +5V, and −15V. By examining the way in which current consumption varies with command word, we can go a long way towards identifying a device and assessing its condition.

The Analyzer is a LWDAQ tool defined by the Analyzer.tcl script in the Tools directory. Select Analyzer from the Tool menu, and the Analyzer Panel will appear. The panel provides a top row of buttons to contact and manipulate a LWDAQ, and a bottom row of buttons to control device analysis. An array of labels and entry boxes gives easy access to the most frequently-changed Analyzer parameters. A text window displays the results of analysis.

Analyzer communicates with the TCPIP interface at address ip_addr. If there is more than one driver at this address, we specify which driver the Analyzer is to work with using driver_base_addr. When we press Analyze, the Analyzer goes through the following steps.

1. Turn off any repeater that might be connected to driver driver_socket.
2. Measure the voltage and total current consumption from the driver power supplies. Print these to the Analyzer text window.
3. Turn on any repeater that might be connected to driver socket number driver_socket.
4. Measure the voltage and total current consumption from the driver power supplies. Print these to the Analyzer text window.
5. Go through the list of sixteen-bit commands by four-digit hex strings in commands. For each command, send the command to the target device, which is at branch socket number branch_socket on driver socket number driver_socket. Measure the increase in voltage and current compared to step (4). Print to text window.
6. Measure loop time of target device and print to text window.
7. Send target device to sleep.
8. Select branch socket zero, which turns off any repeater connected to the driver.

To analyze a range of branch and driver sockets, we use Analyze_All. The Analyze_All command will start with the current values of branch_socket and driver_socket, and proceed through a range defined by driver_start_socket, driver_end_socket, branch_start_socket, and branch_end_socket. If you want to analyzer all the sockets on a particular multiplexer, you can set the driver start and end sockets to the multiplexer's driver socket number, and use Analyze_All.

Perhaps a future version of the Analyzer will go through its own table of results and suggest to the user the nature and condition of the target device. For now, the we must examine the table of results ourselves. In the following paragraphs we give examples of signature current consumptions for existing devices.

Example: The Proximity Mask Head (A2045) and Inplane Mask Head (A2052) respond to command 0001 by consuming roughly 80 mA from ±15V.

The wake command for all LWDAQ Devices is 0080. This command sets the wake bit, which is DC8, and leaves all other bits clear. Some devices do not change their current consumption when awake, but most do. We call the current consumption after receiving the wake command the waking current consumption.

Example: The Proximity Mask Head (A2045) waking current consumption is 0 mA from ±15V.

Current consumptions vary by 10% from one device of the same type to the next. Whenever we specify current consumptions, keep this variation in mind.

Example: The Proximity Camera Head (A2047) and Inplane Sensor Head (A2036) respond to command 0080 by consuming roughly 40 mA from +15V and 37 mA from −15V. The asymmetry between the +15V and −15V consumption is due to the image sensor, which is powered from only +15V, and consumes roughly 3 mA. If the device's image sensor is unplugged, waking power consumption becomes symmetric. If the image sensor flex cable is plugged in the wrong way, ±15V waking current consumption jumps to 80 mA.

Example: The Polar BCAM Head (A2051) has waking current consumption 55 mA from ±15V. The Azimuthal BCAM Head (A2048) has waking current consumption 50 mA. These two are close enough that we cannot use waking current consumption to distinguish with certainty between an azimuthal and polar BCAM. When we send command 1080 or 0880, we turn on one of the front lasers. Both devices will consume 80 mA from +15V while −15V consumption remains unchanged. When we send command 0480 or 0280, we turn on the rear lasers of a double-ended polar BCAM. By measuring current consumption in response to these commands, we can distinguish between single-ended and double-ended BCAMs, and we can distinguish BCAMs from image sensor devices that have no lasers, such as the Proximity Camera Head (A2047).

Example: The Bar Head (A2044) has waking current consumption 65 mA from +15V and 50 mA from −15V. The asymmetry is due to image sensors, an instrumentation amplifier, two current sources, and asymmetric loading of op-amps. Waking and sleeping current consumption from +5V for the A2044 is 6 mA. Until we first applied the Analyzer to an A2044, we had been convinced that the sleeping current consumption from +5V was only 2 mA. Now we see that the A2044 exceeds the LWDAQ Specification +5V sleeping current consumption by 1 mA. When we send command 0480 or 0280 to the A2044, its +15V consumption jumps up to 130 mA while −15V consumption jumps to 125 mA. Both commands turn on one of the two LED arrays that can be connected to an A2044.

The loop time of the target device is the time it takes a signal to propagate from the driver to the device and back again. Signals propagate down LWDAQ cables at 20 cm/ns. Multiplexers add 25 ns to the loop time. Repeaters add less than 5 ns. To the first approximation, therefore, the total cable length between the driver and a device is the loop time divided by 10 ns.

L = t ÷ 10 ns/m

The loop time gives us more information about a device and its cable. In particular, a large loop time indicates the absence of a device. The maximum loop time the LWDAQ Driver (A2037) can measure is 3125 ns, which would correspond to a cable length of 312 m. The LWDAQ does not function well for cable lengths over 200 m, so we can assume that a loop time of 3125 ns indicates either a faulty device that is not responding to the loop command, or no device at all.

Example: The Resistive Sensor Head (A2053) fails to respond to the Loop command properly, and always returns a loop time of 0 ns.

Example: We disconnect a device. To check we have disconnected the right one, we measure its loop time with a LWDAQ Driver (A2037). We expect the loop time to be 3125 ns, but we find it to be 900 ns. We have disconnected the wrong device.

Run from Terminal

If you are starting LWDAQ from a terminal, we recommend you use our lwdaq Bash Shell script. You will find lwdaq in the LWDAQ directory. The script accepts several options and a script file as parameters. We have already mentioned the lwdaq file in our Software Installation instructions. Here we describe its operation detail.

Because lwdaq is a Bash Shell script, you must have the Bash Shell installed on your machine, and available in your default search path. The lwdaq script begins with a shebang call to the Bash Shell. If the shebang call fails, you will get an error like, "cannot find file".

Suppose you want LWDAQ to start and run a configuration script of your own. Here is an example of such a script, which we will refer to as config.tcl.

set LWDAQ_Info(server_listening_port) 1234
set LWDAQ_Info(server_address_filter) *
LWDAQ_server_start

The script configures and starts the LWDAQ System Server. The following command launches LWDAQ, and runs the TclTk commands in config.tcl after LWDAQ has finished its own initialization.

lwdaq config.tcl

The lwdaq command takes the following options.

The following command is equivalent to our first example.

lwdaq --gui config.tcl

The following command starts the non-graphical version of LWDAQ. All graphical activity of the instruments is suppressed. The LWDAQ process uses the terminal as a console and as a destination for its standard output (stdout).

lwdaq --no-gui config.tcl

The following command starts the non-graphical version of LWDAQ and runs it as a background process. There is no LWDAQ console. The lwdaq command terminates, making the terminal available for more shell commands.

lwdaq --no-console config.tcl

Even with the console disabled, writing by LWDAQ to standard output still goes to the terminal. If we close the terminal window while the LWDAQ process is still active in the background, the process will freeze when it next attempts to write to stdout. To make the LWDAQ process independent of the terminal window, we must divert its standard output to a file or a null device.

lwdaq --no-console config.tcl > output.txt

The above command diverts standard output to the file "output.txt". Now we can close our terminal window and LWDAQ will run independently. If we don't want to save the standard output, we can direct it to the null device.

lwdaq --no-console config.tcl > /dev/null

Output sent to the null device is discarded.

You don't have to specify a configuration file for the lwdaq command. But if LWDAQ is running in the background, you must tell it how it is to receive instructions from the outside world. You can do this with the config.tcl file in the lwdaq command, or you can place your configuration script in the LWDAQ startup directory. The LWDAQ program runs all scripts in its startup directory, just as if you specified them in the lwdaq command.

System Server

The System Server allows you to control LWDAQ over TCPIP and transfer results. To open the System Server window, select System Server in the File menu, or call LWDAQ_server_open. You will see a window like the one shown below.

Figure: System Server on MacOS.

To start the server, press Start in the server window, or call LWDAQ_server_start. Once it starts, the System Server listens for TCPIP connections from potential clients. When a client connects, the server accepts text strings delimited by line breaks from the client, and executes these strings as if they were commands typed in at the LWDAQ console. The System Server executes these commands at the TCL global scope. All of LWDAQ's global variables and procedures are available by quoting their full names in commands you pass to the System Server. After the server executes a command, it transmits the result of the command back to the client.

The following lines are taken from LWDAQ_interface_init, which initializes the System Server configuration.

set LWDAQ_Info(server_address_filter) "0.0.0.0"
set LWDAQ_Info(server_listening_port) "1090"
set LWDAQ_Info(server_listening_sock) "none"
set LWDAQ_Info(server_control) "Stop"
set LWDAQ_Info(server_command_filters) "?*"

Each of these variables appears in the System Server window, but with the suffix "server_" dropped for brevity. If you want to change the System Server configuration from the console, or in a script, use commands just like the ones from the initialization.

The listening_port specifies the port at which the System Server will listen for TCPIP connection requests. By default, we use port 1090. You must set the listening port before you start the System Server, or else your value will not take effect.

The address_filter must match the IP address of a client, or else the System Server will refuse the client's request for a connection. By default, this address filter is 0.0.0.0, which will accept connections only from the local host. The filter matching uses an asterisk as a string wild-card, and a question mark as a character wild-card.

The command_filters can include any number of separate filters, each enclosed in double quotation marks. The filters can use an asterisk as a string wild-card, and a quotation mark as a charcter wild-card. Our default command filter is "?*", which accepts any command with at least one character. If the text line transmitted by the client matches any or all of the filters, the server will execute the line as a command. Otherwise it rejects the command. Regardless of the filters you choose, the System Server will never accept a command line containing a semi-colon. If the command contains a semi-colon, the server returns an error to the client. If we were to allow semi-colons, the client could concatinate commands on a single line, and so circumvent command filters designed to restrict the actions the client can take.

The remote system can obtain the local name of the socket by sending the command LWDAQ_server_info. The server will respond by sending back a list of parameters describing itself, as shown above. The first element in this list is the local name of the socket, which will be something like sock16. The subsequent elements are the local time in seconds, the platform name, program version, and TCL version.

You can try out the System Server on your own machine by making a copy of LWDAQ and running both the original and the copy. You use the copy to connect to the original. In the original, open the System Server and press Start. Leave the address filter, the listening port, and the command filters at their default values. We will refer to the original as the server. In the copy, which we will call the client, open the Consol and enter the following commands.

set sock [socket 0.0.0.0 1090]
fconfigure $sock -buffering line
puts $sock "LWDAQ_server_info"
gets $sock
close $sock

You should see the result of LWDAQ_server_info in the client console. In the server window, you will see acknowledgment of the connection, and the receipt of the LWDAQ_server_info command. Now let's suppose you have a large text file on your desktop named Data.txt, and you want to read this through the server to the client.

set sock [socket 0.0.0.0 1090]
fconfigure $sock -buffering line
puts $sock "open ~/Desktop/Data.txt"
set f [gets $sock]
puts $sock "read $f"
while {[gets $sock line]} {puts $line}
puts $sock "close $f"
close $sock

The System Server receives the command "open ~/Desktop/Data.txt" and returns to the client the name of the file channel, let us say it is file16. The client reads the channel name into variable f. It sends the command "read file16". Note that the client refers to the value of f in the string that it sends to the System Server. The client interpreter substitutes the value of f, which is file16, for "$f" before it writes the string to the socket. The server executes the read command and returns the contents of Data.txt to the client. The client reads all available lines using the while loop. The gets command will put each line in the line variable and return a value greater than zero so long as there are more lines to be read from the socket. But when there are no more lines, it returns a value less than zero. Finally, the client directs the server to close the file, and then it closes the socket.

For a tutorial on using the System Server to control the Acquisifier, see Remote Control below.

System Monitor

To open the System Monitor window, select System Monitor in the File menu, or call LWDAQ_monitor_open.

Figure: System Monitor on MacOS. Several instruments are looping simultaneously and the System Server is listening for connctions.

The System Monitor shows you the events awaiting execution in the LWDAQ event queue, the state of all outstanding timeout variables (those generated by LWDAQ_vwait), and lists all open TCPIP sockets (those opened and closed by LWDAQ_socket_open and LWDAQ_socket_close). The monitor provides buttons that stop the event queue, start it, and clear it. The Reset button stops all instruments and polite tools, and results in the event queue emptying itself. the Info button displays the contents of LWDAQ's global information array, and allows you to edit all of its elements.

You should never see more than one LWDAQ vwait operation in the list of vwaits. If there are two, then something has gone wrong with LWDAQ. Somehow, an event executing in the LWDAQ event queue was interrupted and another event that required a vwait was begun. It may be that two LWDAQ event queues are operating simultaneously, although we have made every effort to stop this from happening. If your LWDAQ is not behaving properly, open the System Monitor window and look at what is going on. By reporting to us what you see, you may help us fix a bug in the code.

Image Formats

The LWDAQ Instruments store acquired data as byte arrays in memory and in files. We refer to blocks of acquired data as images, regardless of whether they represent two-dimensional arrays of pixels or one-dimensional arrays of data samples. The LWDAQ program supports its own simple DAQ image format, as well as the GIF format. The DAQ format is more compact for instruments other than cameras, and we recommend its use to you. But the GIF format is just as compact, but far more convenient, for camera images. You can view a GIF file with a web browser. In this section, we describe how LWDAQ stores its header and data blocks in disk files.

We first introduced our simple image format here. We call our image format the DAQ format. We will repeat the definition for your convenience, and describe an addition we made since the first definition: the image format allows you to store a results string as well. Our simple image format assumes that we don't need the pixels in the first row of the image, and that the row will always be longer than twenty or thirty pixels. We over-write the first dozen or more pixels with the dimensions of the image, its analysis boundaries, and a results string, as shown in the table below. After over-writing the first row with our header information, we store the image pixels to disk as a block, with the first row of pixels followed by the second row, and so on. But if we find that all remaining pixels in the image are zero, we don't write them to disk at all. When we later read back the file, we will fill in all thre missing pixels with zeros.

All the numbers are two-byte integers. We store them on disk with the high-byte (most significant byte) first, which is big-endian byte ordering. The results string can be up to j_max - 12 bytes long. If it is any longer, it will start to over-write pixels in the second row of the image, which is forbidden by our image format rules. The results string must be terminated with a null characters, which is the character with decimal ASCII value zero.

The LWDAQ program will read and write images as DAQ files or as GIF files. The GIF file image data is the same as that of the DAQ-format files, including the embedded header information in the first line. If you open a GIF file written by LWDAQ, you won't see blue lines marking the analysis boundaries, but the analysis boundaries will be embedded in the pixels of the first line. When LWDAQ reads back one of its own GIF files, it looks for the analysis boundaries and a results string in the first line of image pixels.

When we write an image to disk, we store the result string starting at byte twelve in the pixel array, after the twelve-byte image header. The string is a sequence of ASCII characters terminated by a null character. If the result string plus twelve bytes is longer than the image row, the string will continue into the second row of the image. Each instrument uses the results string in its own way, or not at all. The results string is reserved for use by the LWDAQ instruments. You can view an image's results string in the Viewer.

Instruments

The LWDAQ instruments are available in the Instrument menu. Each acquires data from any compatible data acquisition hardware. You set the instrument parameters to point to and configure the hardware for acquisition. If you have a thousand BCAM cameras, you acquire data from them one after another by changing the BCAM instrument parameters for each acquisition.

Each instrument has two arrays of parameters that govern its operation. If the instrument is called "Instrument" then these two arrays are LWDAQ_config_Instrument and LWDAQ_info_Instrument. We refer to them as the "config" and "info" arrays for brevity, and to show that we refer to the arrays for each instrument. Every element of the config array is visible in the instrument panel, and you can change them by entering new values with the keyboard. You should be able to modify the values even during live image capture. Every element of the info array appears in a new window when you press the Info button in the instrument panel. Be careful changing the info array elements. Some of them, such as the instrument name, you should not change.

Here are some common instrument parameters and their functions:

• daq_driver_socket: In the config array. Selects a driver socket for data acquisition. If we are acquiring from a driver like the A2037E, we specify one number only: the number of the socket on the driver. But if we are acquiring through an TCPIP-VME Interface (A2064A or A2064F), we must specify not only the socket on the driver, but the driver within the VME crate. We specify the driver with its base address. We combine the base address and the driver socket number like this: "00E00000:3", where "00E00000" is a hexadecimal string giving the 32-bit base address of the driver, and "3" gives the driver socket number.
• daq_source_driver_socket: In the config array. When data acquisition requires the cooperation of two devices, one is the "source" device, which might flash a light source or send some other kind of signal or stimulus to the acquiring device. We specify the source device's driver socket in the same way we would the acquiring device's socket.
• image_source: In the config array. The source of the instrument's data, which we call its image. This can be "daq" to indicate the LWDAQ hardware as the source of data, or "file" to indicate a file on disk, or "memory" to indicate an image in the LWDAQ image list. If you name another instrument as the image source, the first instrument will set the second instrument's image_source to "daq" temporarily, and capture an image using its data acquisition parameters. The instrument names are case-sensitive, so be sure to enter them exactly as they appear in the Instrument menu.
• memory_name: In the config array. The name of the image in the LWDAQ image list that the instrument should use if the image_source is "memory".
• file_name: In the config array. The name of the file that the instrument should use if the image_source is "file".
• delete_old_images: In the info array. Instructs the instrument to delete old images from the LWDAQ image list at start of next acquisition from any source other than the list itself.

For each instrument, the LWDAQ_init_Name (where Name is the name of the instrument) creates the config and info arrays by assigning default values to each element. These values will be over-ridden by values you read in from a settings file (see File Menu).

If you want to acquire data with an instrument using its window, select the instrument from the Instrument meny, adjust its parameters, and press the Acquire button. If you don't adjust the parameters at all, but use the default values, you will acquire something from a test stand that has been left on the internet as an example of the instrument.

If you want to acquire data with an instrument in a script, use the LWDAQ_acquire Instrument procedure, where "Instrument" is the name of the instrument. The acquire procedure will analyze the data it obtains provided that analysis_enable is 1. If you want to analyze data that already exists in memory, you can pass the data to the LWDAQ_acquire_Instrument procedure. Suppose the data is in the LWDAQ image list in an image called lwdaq_image_4.

set LWDAQ_config_Rasnik(image_source) memory
set LWDAQ_config_Rasnik(memory_name) lwdaq_image_4
set result [LWDAQ_acquire Rasnik]

If you have the Rasnik instrument panel open at the time you run the above script, you will see the lwdaq_image_4 image displayed along with the results of analysis. In your script, the results variable now contains the result string produced by Rasnik analysis.

Instruments distinguish between data and results. They acquire data and analyze it to obtain results. The source of data can be the computer memory, a file on disk, or the data acquisition system. All instrument data either exists in memory as an image in the LWDAQ image list, or as an image file on disk. Instrument data exists in the format of an image even though the data itself may not be an image in the strict sense of the word. The image's intensity array serves as a space in which to store data. This data might be an array of sixteen-bit words from the Voltmeter, a sequence of four-byte messages from the Recorder, or a gray-scale image from the Rasnik. The image's overlay array is a space in which to display the results of analysis in graphical form, as in the Voltmeter, or to overlay the results on the gray-scale image itself, as in the Rasnik.

The result of analysis is always a string. If the instrument panel is open during analysis, the result may be represented graphically in the image display area. But the result itself is always a string. The first entry in the string is the name of the source of the data. If the source was a file, it is the name of the file. If the source was data acquisition, name of the source is the name of the image the instrument created to accomodate the data. If the source was a pre-existing image, then the name of the source is the name of this pre-existing image. Following the data source name in the results string are the results of analysis. If the result of analysis is another iamge, the name of this image will be in the results string.

Whenever an instrument creates a new image, it gives the image a name that begins with the name of the instrument. When the instrument reads data out of a file called "directory/file.txt", the name of the image will be the instrument name followed by an underscorre, then "file", then another underscore, and then the value of the instrument's counter parameter. When the instrument reads data directly from the DAQ, the name of the data image will be the instrument name followed by an underscore and the current value of counter. For example, the fifth acquisition by the BCAM will produce an image called BCAM_file_5 from a file called "file.img" regardless of where the file resides, or BCAM_5 if the data comes from the DAQ.

Each instrument has a Save and an Open button. The Save button allows you to save the current image to disk. The Open button allows you to open an image file, display it, and analyze it. The Open button is equivalent to entering the file name for file_name, entering "file" for image_source and pressing Acquire. The only difference between these two procedures is that the Open button allows you to use the operating system's diretory-browser to find the file you want to open, and you can perform the entire operation with the mouse alone. If you want to open multiple files, you must still use the keyboard procedure, and enter a wild-card in the file_name.

When you store an image to disk, you store all the data acquired from the LWDAQ Driver. When you open the image again, and analyze it, you will obtain exactly the same results you obtained with the same analysis when you captured the image. When you save from the Diagnostic instrument, for example, all the 16-bit ADC samples it retrieved to plot graphs of the power supplies are saved in the image, as well as the version numbers read directly from the Driver. When you re-open the Diagnostic image, you can re-analyze to produce the same graph, and recall the version numbers of the Driver hardware and software. For a description of the image file formats supported by LWDAQ, see the Image Formats section above.

As we acquire repeatedly with an instrument, we will accumulate more an more images unless we purge them from the image list. At the beginning of each acquisition from file or daq, an instrument deletes every image in the LWDAQ image list whose name begins with the name of the instrument. If you don't want the instrument to purge its image from the image list, set its delete_old_images variable to 0. Our system works well provided that you do not create your own images and give them names that start with the name of one of your instruments. If you do, then you will find that these images disappear at the beginning of an acquisition by that instrument.

Each instrument provides a verbose_result variable. If set to 0, the instrument displays in its text window a single-line string result at the end of every acquisition. But if verbose_result is set to 1, the instrument displays each element of its result on a separate line with a description of the element. By this means, you can check that you remember which elements are which without referring to this manual. Regardless of the setting of verbose_result, the instrument acquire procedure always returns a single-line result to a calling script. The calling script can obtain a list of phrases describing the data by retrieving the verbose_description list.

The instruments can share a driver with another computer. The way the instruments share the Driver is by repeatedly trying to connect to it. When the Driver is busy with another instrument, it refuses the connection immediately. The refused instrument waits a random length of time and then tries again, and again, until it succeeds. The maximum number of times they are allowed to try is stored in LWDAQ_Info(max_daq_attempts). All instruments in your LWDAQ program will wait until the refused instrument succeeds in completing its data acquisition, or gives up after the maximum number of attempts (about ten seconds with the current default settings). If you want to interrupt an instrument during its repeated attempts to contact its driver, you can press the instrument's Stop button. After a few seconds, you will see a red error message telling you what went wrong.

After an instrument receives its first connection refusal during an acquisition, it lets you know that it is having some problems by printing its internal state in red instead of black on the top-left of the screen. As soon as it connects, it prints the state in black again.

Instrument results show up in the instrument's text window. So to error messages. These will be displayed in red. If you want to clear the text window, click on it, and then press command-b (MacOS X) control-b (Linux) or alt-b (Windows).

Each instrument can obtain its data from one of four sources: memory, file, daq, or another instrument. Each instrument has the image_source parameter that you set to memory, file, daq, or the name of another instrument (case-sensitive), depending upon your choice. A data acquisition script can make the same choice before it calls the instrument's acquire procedure, by setting the same variable. When we get data from memory, we get it from the the analysis library's internal list of images. To specify an image, we specify its name. When we get data from a file, we specify the file name. It you want to analyze multiple files, you can specify * and ? in the file name. To specify data acquisition from a LWDAQ, you specify the driver address, and other parameters beginning with daq_ in the instrument panel.

When and instrument obtains an image from disk, by default it uses the analysis boundaries stored with the image on disk. But you can instruct any instrument to over-write the stored analysis boundaries, and instead use the boundaries defined in its daq_image_left, daq_image_top, daq_image_right, and daq_image_bottom parameters by setting the file_use_daq_bounds parameter to 1. By this means, you can read in an entire list of files from disk (specified in file_name with the help of an asterisk), and analyze them with different bounds than those encoded in the images on disk.

If you want to view the script that defines the instrument's data acquisition procedure, you can press the Info button in the instrument panel, and then the Script button in the new Info window. If you want to modify the instrument scripts, you must use your own text editor. In the long run, we do not expect you to need to modify the instrument scripts often, although you will develop your own DAQ scripts.

After you have adjusted your instrument settings, you may wish to save them to disk, so that the next time you open LWDAQ you get the same settings back again. If you want to save the settings, select Save Settings from the File menu. You can load them again later with the Load Settings option.

You can press the space bar to provoke the acquire button in any instrument panel. You can break the connection between the space bar and the acquire button by clicking on any other button or entry in the window, and restore the connection by once again clicking on the acquire button.

All instruments provide an daq_extended parameter, which may be set to 0 or 1. If set to 1, and the image source is daq, the instrument will perform extended acquisition, if such acquisition is defined for the instrument in a procedure called LWDAQ_extended_$instrument. Extra parameters required by the extended acquisition are stored in extended_parameters. Extended acquisition can allow the instrument to optimise its own acquisition parameters or test itself for problems.

BCAM

A BCAM takes images of the point sources on other BCAMS in its field of view and determines the location of each point source image relative to one corner of its image sensor.

Figure: The BCAM Instrument on MacOS. The black square with two white spots is a BCAM image of two laser light sources. The red squares around the spots show the extent of each spot as determined by our BCAM multiple-spot analysis routine.

You can see the BCAM string output in the BCAM window shown above. The first two numbers are the x and y position in microns of the brightest spot in the image, measured from the top-left corner of the top-left pixel in the image. The third number is the number of pixels in the same spot. We count all pixels above the threshold in a small box that just encloses the spot and is clipped to the image's analysis bounds. The fourth number is the maximum image intensity in the spot. The fifth number is the gradient of spot position with analysis threshold. The sixth number is the threshold intensity. The next six numbers describe the second-brightest spot in the image in the same way.

You specify the number of spots the BCAM should find with analysis_num_spots. If you specify more than one spot, the BCAM will display a red square around each separate spot. If you ask for two spots but there is only one spot in the image, you get something like this:

BCAM_3 3049.79 1480.92 22 191 0.002 57 -1 -1 0 0 0 0 

When the BCAM finds several spots, the brightest spot comes first in the list. You do not necessarily have the leftmost or rightmost spot first every time you capture an image. You may find the spots changing order in the list if they are very close to the same intensity. The brightest spot is the one with the greatest total intensity above threshold.

Example: Open the BCAM instrument and use it to obtain an image from our demonstration stand. With the default instrument settings, you will see two spots displayed, each with a red square around it. Change analysis_num_spots to 1. Acquire another image. You will see a red cross centered upon one of the spots. Change daq_source_device_element to "3 4 4". One of the spots gets twice as bright because it is flashed twice. If it's the source that had the cross on before, the cross remains where it was. Now try "3 3 4". The cross will move from one spot to the other. By this means, you can tell which spot corresponds to source element number 3, and which corresponds to number 4. You also see how the BCAM analysis picks the brightest spot.

When analysis_num_spots is 1, the BCAM will display a red cross at the center of the brightest spot it finds. We use a red cross instead of a square because we use the BCAM with instruments that have spots covering most of the image, and in these cases, we like to see where the BCAM has placed the center of the spot.

You can specify the BCAM analysis threshold in three ways. The first is to specify your threshold intensity as an integer, τ. The second is to enter an integer, p, between zero and a hundred, followed by a space and a % character. The % character tells the BCAM analysis to set the threshold equal to an intensity that is p% of the way from the minimum intensity to the maximum intensity. To be exact, the threshold is:

(min + (max-min)*p/100),

where max and min are the maximum and minimum intensities in the image analysis boundary. We find that with the threshold set to "10 %" we can vary the brightness of the spot in the image by a factor of ten and see less than 0.5-μm (5% of a pixel) change in measured spot position.

The third way of specifying the analysis threshold is to enter an integer, p between zero and a hundred, followed by a space and a # character. The # tells the BCAM to choose a threshold equal to:

(ave + (max-ave)*p/100),

where ave is the average intensity in the BCAM analysis boundaries, and max is the maximum intensity.

The "#" option is more reliable when your image contains small spots. The average intensity is close to the background intensity. Black spots caused by unusual noise or defects in the image sensor do not disturb the average intensity, and the threshold is well-placed relative to the spot intensity and the background. The "%" option is more reliable when your image contains large spots. When a spot takes up half the width of the image, the average intensity is raised significantly above the background intensity by the intensity of the large spot. In this case, we use the minimum intensity as our estimage of the background intensity, and we allow ourselves to be vulnerable to black spots and image sensor defects.

The BCAM is accurate only so long as the laser image is bright enough to be undisturbed by the prevailing image noise, and yet not so bright as to saturate the CCD. If you set daq_adjust_flash to 1, the BCAM will take consecutive images, measure the maximum intensity in each image, and adjust the daq_flash_seconds until the maximum intensity lies between peak_min and peak_max, or until the flash time is zero or exceeds flash_seconds_max. You can use the automatic exposure adjustment along with background subtraction. When you are using background subtraction, the BCAM adds peak_background to the maximum intensity of the background-subtracted image and compares the sum with peak_max and peak_min. The BCAM Saturator tool allows you to check the saturation intensity and exposure time of your BCAM.

There are rare cases where the flash-adjustment algorithm does not converge. The flash_max_tries parameter limits the number of adjustments the BCAM can make before it gives up and accepts whatever image it has most-recently obtained.

The BCAM allows you to flash multiple lasers on the same LWDAQ Device. You can use the multiple-spot analysis to find all the spots in your image. To flash multiple elements of the same LWDAQ Device, enter the element numbers into the daq_source_element variable separated by single spaces. If you want one element to be flashed for a period longer or shorter than daq_flash_seconds, follow the element number immediately with a "*" character and multiple or fraction of daq_flash_seconds for which you would like the element to flash.

set LWDAQ_config_BCAM(daq_device_element) "1*2.0 2*10 3*0.5 4*1.0"
set LWDAQ_config_BCAM(daq_flash_seconds) 0.001

The above line will instruct the BCAM to flash elements 1 through 4 for 2 ms, 10 ms, 0.5 ms, and 1 ms respectively. Be warned: with factors greater than one (1.0), the BCAM's automatic flash adjustment will get stuck in a loop when the flash time drops to zero seconds. That's because the smallest increment in flash time is daq_flash_seconds_step (by default, 1 μs). In the above example, if the ideal flash time for element 2 is 5 μs, the BCAM will try 0*10 = 0 μs and find that the image is too dim. It will try 1*10 = 10 μs and find that the image is too bright. After that, it will try 0 μs again, and so on.

The BCAM will subtract a background image from the image of the laser or lasers. Set daq_subtract_background to one. The BCAM takes one image with the laser flashing, and another with the laser turned off. Both images have the same exposure to ambient light. We call the first image the forefround image, and the second the background image. The BCAM subtracts the background from the foreground to obtain the background-subtracted image. Negative intensities in the background-subtracted image are set to zero. If a pixel in the background image is brighter than a pixel in the foreground image, the pixel in the background-subtracted image will be zero.

We use background subtraction when we have ambient light that varies across the image sensor, or when we have significant dark current in the image caused by long exposures or by radiation damage. Provided that neither the foreground nor background image saturates, and provided that the ambient light or dark current does not change significantly between the two images, the background-subtraction will contain only the laser images.

In its extended acquisition, the BCAM tries to find effective values for peak_min, peak_max, daq_flash_seconds, and its analysis boundaries. You control these adjustments with extended_parameters, which should give values for min_frac, max_frac, border, and adjust_individual. If the parameter string is "0.6 0.9 20 1", then min_frac, max_frac, border, and adjust_individual are respectively 60%, 90%, 20 pixels, and 1 for "yes".

The extended acquisition begins by capturing a camera image while flashing the BCAM sources for flash_seconds_max. We assume that this image will contain saturated pixels, so that its maximum intensity is the saturation intensity. Then it obtains another image while flashing non-existent lasers. We assume that the average intensity of this image is the background intensity. The BCAM sets peak_max and min_frac and max_frac. These might be 0.6 and 0.9, in which case peak_max is 90% of the way from the background to the saturation intensity, and peak_min is 60% of the way. If daq_source_device_element specifies only one light source, the extended acquisition captures a third image, and adjusts daq_flash_seconds until the peak intensity in the image lies between min_peak and max_peak.

If daq_source_device_element specifies more than one light source, and you have set adjust_individual greater than zero (for "yes"), the extended acquisition flashes each source in turn, and determines a suitable daq_flash_seconds for each one. It then sorts the light sources in order of decreasing daq_flash_seconds, and modifies the entries for each light source in daq_source_device_element using the * operator we describe above. It captures one more image, and at this point, you should see all the light sources appearing in the image with roughly the same intensity. If adjust_individual is zero (for "no"), the extended acquisition skips this step.

The third parameter in extended_parameters tells the extended acquisition how to set the BCAM analysis boundaries. Some BCAM users don't like to perform background subtraction, because it slows down data acquisition. Ambient light reflected from a ball bearing in the field of view might be at certain times of day be bright enough to be mistaken for a flashing laser. Even with background subtraction, sunlight passing through a ventilation fan might be bright during the foreground image, but dim in the background image. In such cases, you can use extended acquisition to set the analysis boundaries automatically. The analysis boundaries define the area in the image the analysis program considers when looking for spots. Before adjusting the boundaries, however, you must obtain a BCAM image in which the lasers you flash are the brightest spots of light. You may have to pick a cloudy day, or work at night. You may have to cover up shiny ball bearings in the field of view. Once you have an image that the BCAM can analyze correctly, edit the extended_parameter string so that the third element is equal to the border you would like around your light spots. If this border is set to 0, then the analysis boundary adjustment is disabled. By default, its value is zero. Try setting it to 20. Perform the extended acquisition. You should see a new blue rectangle around your spots. Open the Info window and you will see that daq_image_left, _right, _top, and _bottom have been changed. Subsequent acquisitions from the BCAM will impose these bondaries upon the image as it comes in.

If you are using the BCAM with the Acquisifier, you can go through all your BCAMs with one run through your Acquisifier script, and get them to set their flash times and analysis boundaries. But you must be sure to include in your Acquisifier script a mention of all four of the analysis boundaries, and the flash time. If you don't mention these parameters, they will not be remembered by the script, and so they will not be put into place again the next time you capture from the same BCAM.

If you want to obtain an ambient-light image with the lasers flashing, try setting ambient_exposure_seconds in the info array to 0.1 or 0.2, and switch intensify to strong.

By default, the BCAM assumes that both the source and sensor devices are controlled through the same TCPIP socket. The daq_source_driver_addr parameter is set to * (wild card). The sensor and sources share a TCPIP connection to the address given by daq_driver_addr. But if the sources are connected to another LWDAQ, and must be controlled through a separate TCPIP socket, you can instruct the BCAM to do this by setting daq_source_driver_addr to the IP address at which the sources are available. The BCAM will use daq_driver_addr for the sensor, and daq_source_driver_addr for the sources. If the two addresses are the same, then the BCAM will recognise that they are the same, and share a single socket between the sources and sensor.

When both the sensor and source are connected to the same IP address, the LWDAQ program sends a string of instructions to the LWDAQ and allows them to be executed sequentially in the hardware associated with the single IP address. But when the sensor and source are connected to separate IP addresses, the LWDAQ program must receive confirmation from the sensor socket that the sensor is ready for exposure before it sends the instructions to flash the laser to the source socket. It must receive confirmation from the source socket that the flash is complete before it sends instructions to retrieve the image to the sensor socket. These delays for confirmation are round-trip delays across your TCPIP connection. They will be a matter of millisconds in a local area network, but could be hundreds of milliseconds across the global Internet.

Camera

The Camera Instrument captures images from an image sensor device, displays the image on the screen with your choice of intensification, and prints the image's dimensions, analysis boundaries, and intensity characteristics in the instrument panel.

Figure: The Camera Instrument on MacOS. The picture is a view of our laboratory corridor, after applying the grad manipulation.

Unlike the BCAM and Rasnik instruments, the Camera does not flash light sources. It takes pictures using ambient light only. To accommodate large differences in ambient light intensity, the Camera supports anti-blooming as well as a more rapid form of image handling we call fast-move. We enable anti-blooming with daq_anti_blooming, and we enable fast-move with daq_fast_move. Most image sensor devices provide anti-blooming, but only a few provide fast-move. By default, anti-blooming is enabled and fast-move is disabled. When we use anti-blooming with a device that does not provide anti-blooming, the anti-blooming has no effect. But when we use fast-move with a device that does not support fast-move, the result is a streaky, white image. When we use fast-move with the Camera Head (A2056), the fast-move works for most of the image, but garbles the first two lines. That's why the default Camera analysis boundary top is greater than 1.

The Camera allows you to read images from the daq, memory, or file, just like any other instrument. The Camera allows you to manipulate these images before you display and analyze them. You specify these manipulations with manipulation codes in the analysis_manipulation string. You can specify multiple manipulations by listing their codes separated by spaces. The Camera will perform the manipulations consecutively. The original image will be replaced by the final product. For a list of the manipulation codes and their functions, see lwdaq_image_manipulate. The Camera supports all manipulations available to lwdaq_image_manipulate that operate on only one image. The subtract and combine manipulations, for example, are not supported by the Camera.

After performing whatever manipulations you specify, or after no manipulations at all, the Camera performs a simple analysis of the image by calling lwdaq_image_characteristics. The Camera result contains ten numers.

Camera_1 20 3 343 243 73.3 15.5 121.0 48.0 244 344

The first four numbers are always integers, and they give the left, top, right, and bottom edges of the analysis boundaries. The next four numbers are real-valued. They are the average, standard deviation, maximum, and minimum intenity of the image within the analysis boundaries. The last two inumbers are always integers. They give the height and width of the image.

As with all instruments, the Camera will display images with one of our four varieties of intensification: exact, mild, strong, or none, and it will capture and display images through another instrument when you name that instrument in image_source.

Diagnostic

The Diagnostic instrument provides an oscilloscope-like display of the power supply voltages on the driver board, and calculates the average current running out through each of them. The Diagnostic instrument also provides extra buttons that allow you manipulate and test devices directly. When it acquires, the Diagnostic instrument reads the hardware, firmware, and softare version numbers from the driver. As with any instrument, set verbose_result to 1 to get a description of the result numbers.

If you want to change the voltage scale, offset, or coupling for the oscilloscope display, you can do so by entering in new values in the entries dedicated to each of these variables. When you press return while in one of these entries, the display will refresh with the existing data.

You can change also the seconds per division in the oscilloscope display, and the offset of the left edge from time zero (the time of the first sample). You can change the number of seconds per division for the display as well.

Figure: The Diagnostic Instrument on MacOS, set up to acquire from an A2037A in a VME crate with the help of a VME-TCPIP Interface (A2064). Before acquiring data from the driver, the instrument performs actions "off 1000 on 100".

The A2037E and A2037A allow you to turn on and off the data acquisition power supplies. The Head Power On and Head Power Off buttons turn on and off the +5 V and ±15V power supplies to all multiplexers and devices connected to the driver you specify in the configuration entries. If you turn the head power off on our demonstration stand, everyone else will get no data from it until they realize what you have done, and turn the power back on again. If you want to turn the power off and then on again, wait for several seconds after turning the power off, to let the circuits settle in preparation for power-on reset. The Reset button resets the driver state machines, but not the devices. Some drivers turn off their data acquisition power supplies when you reset them, and others turn on their data acquisition power supplies. The behavior of your driver will depend upon its firmware version number.

The Sleep button sends to sleep the target device you specify with the config array entries. The Wake button wakes it up again. Because waking and sleeping are done automatically by all data acquisition instruments, you don't do any harm by sending a device to sleep. But you might bring down the demonstration stand power supplies if you wake up too many devices and forget to put them to sleep again. One way to put all devices attached to a driver to sleep is to use the Sleep All button. Another way to send all devices to sleep is to press the Head Power Off button, count to ten, and press the Head Power On button.

The Loop button executes a loop job and returns the total propagation time for an electrical signal travelling to the target device and back again. The loop time for a working cableis 5.0 ns per meter of cable between the driver and the device, as shown in this graph.

The Transmit button transmits the commands you specify in hexadecimal to the target device. Enter a command, or a list of commands separated by spaces, in the command entry box next to the Transmit button, and press transmit. If you want the same single command transmitted multiple times in succession, enter a non-zero number in the repeat entry box. If you combine a list of commands with a non-zero repeat value, each command will be transmitted multiple times before the next command is transmitted multiple times.

The maximum value accepted by your driver's repeat counter depends upon the driver's firmware version. You can be confident, however, that you can go up to 65535 with any A2037E or A2037A.

Example: You want to turn on the front left laser on a Blue Azimuthal BCAM. Go to the Blue Azimuthal BCAM Head (A2048) Manual and look at its command bit allocation. You turn on the left laser with command 1080 hexadecimal. Enter "1080" in the box next to the Transmit button, select your BCAM with daq_target_driver_socket and daq_target_mux_socket and daq_driver_addr. Press the Transmit button. You should see your laser turn on and stay on. To turn it off and send the BCAM to sleep, transmit 0000.

The Diagnostic instrument allows you to execute any of its special button commands before it aquires power supply measurements, through the daq_actions parameter. You may also specify delays in milliseconds by adding an integer to this string. The following table relates the button you want to execute to the code word you include in the daq_actions string. You separate the code words with one or more spaces.

Specify any number of the above code words in the daq_actions string, combined with any number of delays in milliseconds, and the Diagnostic instrument will execute them before it measures the driver power supplies.

Example: The string "reset off 1000 on 100" resets the controller, turns off the head power supplies, waits one second, turns on the power supplies, and waits for a hundred milliseconds.

By means of the daq_actions string, you can use the Diagnostic instrument to cycle the driver power supplies and check for devices that remain awake after the cycle. The delays allow you to make sure that the power supplies have a chance to turn off fully, and to turn on again.

In large LWDAQ systems containing devices with unreliable power-up reset, power supply cycling is essential to guarantee that all devices are in their sleep state and the power supplies are stable. We describe the power supply problems experienced by large LWDAQ systems in the Large Systems section of the LWDAQ Specification. To help us deal with these problems, the Diagnostic instrument can turn off and on the power supplies automatically, check the power supply voltages, and repeat the same cycle until it sees the power supplies turning on properly.

With daq_psc set to 1, the Diagnostic Instrument checks the power supply voltages before it completes data acquisition. The letters "psc" stand for "power supply check". If the power supplies lie within the ranges specified by the info array, acquisition ends. But if the supplies are out of range, the instrument acquires again. Acquisition will end when the power supplies are within range, or after psc_max_tries attempts. The power supply ranges are defined by elements in