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. The portion of a LWDAQ Server that receives and interprets TCPIP messages is a LWDAQ Relay. Each server has only one relay.

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 Message Protocol or the SIAP Message Protocol. We describe both protocols in TCPIP Messages. The server decides on start-up to use the SIAP protocol if its server port number lies in the ranage 30,000 to 40,000. Otherwise it will use the LWDAQ protocol.

Example: The LWDAQ Driver with Ethernet Interface (A2037E) uses an RCM2200 TCPIP Module to implement its LWDAQ 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 LWDAQ Controllers.

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

The Configurator Tool and the Diagnostic Instrument both allow you to determine the hardware id and hardware version of a LWDAQ Relay. 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

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 using the LWDAQ Message Protocol. 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. You will find all the TclTk scripts that define LWDAQ and its instruments at our Sources page. The first script that LWDAQ runs is Init.tcl.

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

You may want to use several instruments in an experiment. You may 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 create your own tool to define your own window with buttons and a display. You create a tool by defining it with a TclTk script. You can run your tool from the Tool Menu, or you can put the tool in the Startup directory and have LWDAQ run the tool automatically at start-up. We describe how to create tools in the Tools section.

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 can call the 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 runs MacOS, 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. You can start LWDAQ by running LWDAQ.bat from a command prompt, or double-clicking on the LWDAQ.bat file. In either case, you should see the LWDAQ main window open up.

Because DOS does not recognise the lwdaq file as an executable, when you enter lwdaq as a command DOS looks for a file called lwdaq.bat. Because DOS is case-insensitive, it runs LWDAQ.bat. Thus we see that the same lwdaq command works on Windows as well as Unix-like platforms, so that the same terminal command can be used to launch LWDAQ on any platform.

Most likely, you will be launching LWDAQ with the mouse. 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. Now you can run LWDAQ by double-clicking on the LWDAQ.bat file.

If you want to launch LWDAQ by running the lwdaq shell script from the MinGW prompt, you must first remove the hash-bang at the top of the lwdaq file. The MinGW installation does not include the bash shell as a command, even though it is itself a Bash Shell. You can, however, run lwdaq without modification from the Cygwin prompt.

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.txt {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 scripts}
    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 lwdaq analysis library}
  {TclTk sources for LWDAQ framework}
  {TclTk sources for LWDAQ Instruments}
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 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 Server, read its configuration parameters from RAM, and write new configuration parameters to EEPROM. 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.

Example: The LWDAQ Driver with Etherenet Interface (A2037E) provides a LWDAQ system with eight driver sockets and one TCPIP interface. The A2037E is a self-contained LWDAQ Server, with both the LWDAQ Relay and LWDAQ Controller in the same enclosure. The Configurator tries to contact the A2037E with contact_ip_addr and contact_ip_port.

Example: A VME crate containg twenty LWDAQ Drivers (A2037A) and a single TCPIP-VME Interface (A2064) provides a LWDAQ Server with 160 driver sockets. Each A2037A provides a LWDAQ Controller. The A2064 provides a LWDAQ Relay that provides TCPIP communication for all twenty controllers. 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 Server with only one LWDAQ Controller. With a non-zero base address, the Configurator assumes a LWDAQ Server with one LWDAQ Relay but multiple LWDAQ Controllers, each of which you select with a unique base address. 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 Identifier Table above.

The first step in the Configuration process is to make contact with your LWDAQ Relay over TCPIP. Let us assume that your LWDAQ Relay is fresh from the factory with our default IP address 10.0.0.37. This is the default IP address for all our LWDAQ Relay assemblies. Apply power to the relay 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 relay 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 relay 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 relay'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 your LWDAQ Relay, try resetting the LWDAQ's EEPROM configuration file with the following procedure. Find the Configuration Switch on your relay. This button is next to the shielded Ethernet jack on the A2037E. It is on the top side of the board on the A2064 and A2101. Press and hold the Configuration Switch. Now press the Reset Switch while still holding down the Configuration Switch. The Reset Switch is on the front side of the A2037E next to the indicator LEDs, on the front panel of the A2064, and on the top side of the A2101. Release the Reset Switch. Keep holding the Configuration Switch for at least three seconds. The relay re-boots. It notices that the Configuration Switch is pressed. It re-writes its configuration file, which is stored in its non-volatile (EEPROM) memory. It loads the newly-written values into RAM and starts its server socket.

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 Relay with the Configurator's Contact button. If you don't succeed, check your cables. Look at the lights on the relay. The two yellow lights nearest to the Reset Switch on an A2037E or A2064A/F are Link and Activity indicators. 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 Driver Sockets. If you don't get a Link light, there is something wrong with your cable, or your computer's Ethernet connection, or you have a broken LWDAQ Relay. 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 your LWDAQ Relay. You can now use our LWDAQ software to exercise your LWDAQ system. Alternatively, you might like to change the relay's IP address. If so, press the Configurator's Read button to read out the relay'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 relay.

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 relay'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 Relay. 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 the password. A simple Ethernet packet sniffer, combined with a knowledge of the LWDAQ or SIAP message protocols, will allow anyone on your local Ethernet to pick your password up immediately. Nor can you protect your LWDAQ Relay 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 can be idle before the LWDAQ Relay 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 Relay 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 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 relay'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 relay's RAM. Your new configuration parameters will not take effect until you re-boot the LWDAQ Relay. Even if you read the relay's configuration, you will not see the values you wrote because the configuration returned by the relay is the configuration running in RAM, not the one stored in EEPROM. You can re-boot the relay by pressing the Reset Switch or by turning the power off and on again. If you use the Reset Switch, be sure not to press the Configuration Switch at the same time, or else the relay will over-write your new parameters with the default values. If your relay is equipped with software version 13 or later and you are running Configurator 20 or later, you can re-boot the relay with the Configurator's Reboot button.

Suppose your LWDAQ Relay 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 contact_ip_addr to match the new relay's new 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 Relay, 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 Relay into your local area network, whose subnet must match your relay'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 new configuration parameters.

The next time you want to change the configuration of your LWDAQ Relay, 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 reboot the LWDAQ Relay and read back the new configuration immediately.

When your LWDAQ Relay contains multiple LWDAQ Controllers, the Configurator can read the hardware identifier, hardware version, and firmware version of individual controllers within the LWDAQ Server 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 LWDAQ Relay and LWDAQ Controller 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
Driver 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. The Configurator uses the word "Interface" instead of "Relay" and "Driver" instead of "Controller".

Analyzer

The Analyzer measures the current consumption signature of a target device. A device's current consumption signature is its response to a sequence of command words, each of which may or may not turn on current-conuming functions inside the device. The Analyzer also makes use of the target device's loop time when it interprets the current consumption signature. The Acquisifier Tool uses the Analyzer to search large systems for faulty devices, repeaters, and multiplexers.

Figure: The Analyzer on MacOS.

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 defined by the Analyzer.tcl in the LWDAQ/Tools directory. Select Analyzer from the Tool menu, and the Analyzer Panel will appear. The Analyzer communicates a target driver at IP address ip_addr. If there is more than one driver at this address, we specify the target driver with base_addr.

The Contact button attempts to read the version numbers and MAC address of a driver. The Power_Off and Power_On buttons turn off and on the power supplies to the driver's devices. The Sleep button puts to sleep the device on each multilexer socket on each driver socket of the target driver. The Repeaters_Off button turns off the repeater on each driver socket of the target driver.

The Analyzer uses driver_start_socket and driver_end_socket to define the range of driver sockets for Repeaters_Off and Sleep. It uses mux_start_socket and mux_end_socket to define the range of multiplexer sockets for Sleep. These parameters, and many others, are available in the window that opens when you press Configure.

When we press Analyze, the Analyzer goes through the following steps to analyze a target device on driver socket driver_socket and multiplexer socket mux_socket.

1. Send to sleep any devices connected to driver_socket.
2. Turn off any repeater connected to driver_socket.
3. Measure voltage and current of power supplies.
4. Turn on any repeater that might be connected to driver_socket.
5. Measure voltage and current of power supplies.
6. Go through list of commands in commands. Send each to the target device and measure voltage and current of power supplies.
7. Download measurements from driver.
8. Measure loop time of target device.
9. Put target device to sleep.
10. If leave_repeater_off is set, turn off any repeater connected to driver_socket.
11. Use the power supply measurements and loop time to try to determine the nature of the target device.

With the verbose flag set, the Analyzer prints the power supply measurements to the screen, and the results of its analysis. You can see an example of the verbose output in the figure above. With the verbose flag cleared, the Analyzer prints a single line only. This line gives the IP address, base address, driver socket, multiplexer socket, and best-guess at the device type.

To analyze a range of branch and driver sockets, we use Analyze_All. The Analyze_All command uses the same ranges of driver sockets and multiplexer sockets as Sleep. Press Configure to change the range limits. If, for example, 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.

The Analyzer script contains a library of current consumption signatures. Open Analyzer.tcl and you will see them at the end of the file. The signatures give the increases in current consumption that occur in response to a selection of command words. The analyzer compares each signature with that of the target device and chooses the device type closest to the target device. If the deviation in milliamps from the signature is greater than max_current_error, the Analyzer marks the device type as unknown_device_name. One of the devices in the Analyzer's library is "none", which is the no-device type.

Most LWDAQ devices have a distinct current signature.

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

The Analyzer uses loop time to check the device type suggested by its signature library. If a device of type "none" loops back with less than the max_loop_time, the Analyzer concludes that there is an unknown device attached.

The Analyzer will work in LWDAQ's no-gui or no-console modes. The following lines start the Analyzer and obtain an analysis of a socket.

% LWDAQ_run_tool Analyzer.tcl
% Analyzer_analyze 129.64.37.79 00E00000 1 1
129.64.37.79 00E00000 1 1 0 0 2.2 "A2056"

The Analyzer_analyze procedure returns the Analyzer's best guess as to the device type, as well as the target address and what it could learn about the repeater and multiplexer. The first four entries in the result string are the IP address, base address, driver socket, and multiplexer socket of the analyzed device. The fifth entry is one (1) if the Analyzer detected a repeater-multiplexer combination on the driver socket, and zero (0) otherwise. The sixth entry is one (1) if the Analyzer measured excessive current consumption after it turned on the repeater, and zero (0) otherwise. The seventh entry is the current signature error in milliamps. The final entry is a list of matching device types.

Run from Terminal

If you are starting LWDAQ from a terminal, we recommend you use our lwdaq Bash Shell script on Linux, Unix, or MacOS. On Windows, use our LWDAQ.bat DOS Shell script. We have already mentioned lwdaq and LWDAQ.bat in our Software Installation instructions. Here we describe their operation detail. You will find both files in the LWDAQ directory.

We will start with lwdaq, and describe LWDAQ.bat later. 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". On Windows, you can run lwdaq from the Cygwin prompt, but you must remove the hash-bang from the top of the script if you want it to run from the MYSIS prompt.

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. The LWDAQ program runs all scripts in its startup directory, just as if you specified them in the lwdaq command.

The LWDQA.bat file attempts to duplicate the behavior of lwdaq, but in a DOS batch file. You can run LWDAQ.bat on any Windows NT, Windows XP, Windows 2000, or Windows Vista machine. Open a Command Prompt and enter lwdaq or LWDAQ.bat from the LWDAQ directory, or give the full path name to LWDAQ.bat when you are in another directory.

You can pass options and a configuration file name to LWDAQ.bat in the same way you would to lwdaq. The --no-console option produces slightly different behavior with LWDAQ.bat. Even in no-console mode, Windows opens a console for LWDAQ that will display its standard output. There is no need for us to re-direct the LWDAQ output away from the terminal that launched it. When LWDAQ quits, the console closes.

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 lines of text from the client. These lines must be delimited by line breaks. The server handles these lines in one of three ways, depending upon the server_mode setting. The default server mode is execute, in which the server passes the line to the TclTk interpreter, executes the line as a command, and returns the result string to the client. The System Server executes commands at the TCL global scope. All of LWDAQ's global variables and commands are available by quoting their full names. In echo mode the server re-transmits the line back to the client. In receive mode, the server receives the line and prints it to its text window, but sends nothing back to the client. and executes these strings as if they were commands typed in at the LWDAQ console.

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

set LWDAQ_Info(server_address_filter) "127.0.0.1"
set LWDAQ_Info(server_listening_port) "1090"
set LWDAQ_Info(server_control) "Stop"
set LWDAQ_Info(server_mode) "execute"

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 127.0.0.1, which accepts connections 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 remote system can obtain the local name of the socket by which it is connected to the System Server by sending the command LWDAQ_server_info to the socket when the System Server is in execute mode. The server will respond by sending back a list of parameters describing itself, as shown in the screen shot 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. Open the System Server. Set address_filter to 127.0.0.1, listening_socket to 1090, and mode to "execute". Press Start. Open a Tcl console in a separate terminal window with tclsh, or run a copy of LWDAQ and use the console it provides. (See Software Installation for availability of the console on your platform and Run from Terminal for how to run a copy of LWDAQ in a terminal window.) In the client console enter the following Tcl commands.

set sock [socket 127.0.0.1 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, the receipt of the LWDAQ_server_info command, and the response sent back to the client. 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. Note that the following commands will generate errors unless you have such a file available for reading.

set sock [socket 127.0.0.1 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. For instructions on using the System Server to receive Acquisifier results, see Step Result Upload.

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 three image formats: DAQ, NDF, and GIF. The DAQ format is the most compact for instruments other than cameras, but works very well for both two-dimensional data and one-dimensional data. For two-dimensional camera images, the GIF format is more convenient. The NDF format is designed for the accumulation of one-dimensional data in a large file.

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 GIF files written by LWDAQ contain the same image data as their equivalent DAQ 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 a DAQ or GIF 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 LWDAQ Instrument uses the results string in its own way, or not at all, to store information about the manner in which the image data was acquired. We call such information Viewer Analysis to the image.

The NDF format is designed to make it easy for us to add one-dimensional data to an existing file. The letters NDF stand for Neuroscience Data Format. The NDF file starts with a header of at least twelve bytes. The first four bytes spell the NDF identifier " ndf".

Two four-byte numbers follow the identifier. Both are big-endian (most significant byte first). The first number is the address of the meta-data string, which is the number of bytes from the start of the file at which we will find the first meta-data byte. This address must be at least 12 to avoid the header. The meta-data string is a null-terminated ASCII character string. The second number is the address of the first data byte. The data extends to the end of the file.

The LWDAQ_write_image_file and LWDAQ_read_image_file commands read and write DAQ, GIF, and NDF files depending upon the extension you pass them in their file_name parameter. Extension ".gif" specifies GIF and ".ndf" specifies NDF. The specification is case-insensitive. Any other extension selects the DAQ format.

As you can see, the NDF data format gives us no information about how its data should be displayed. If we record a sequence of samples in a DAQ image, when we display the samples as a graph, the DAQ image's i_max and j_max fields tell us the dimensions of the rectangle in which we are to plot the graph. The NDF format are not designed to be read into LWDAQ and displayed. Instead, tools like the Neuroarchiver read fragments of a large NDF file's data block into memory for analysis and display. Nevertheless, you can open an NDF file from any LWDAQ Instrument, and the LWDAQ_read_image_file will assign it a display width and height that will be adequate for graphs.

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 its old images from the LWDAQ image list at start of next data acquisition or file analysis.

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 command, where "Instrument" is the name of the instrument. The acquire command 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 command. 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 image, 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.daq", the name of the image will be the instrument name followed by an underscore, 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 command, 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 command, 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 command 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. The BCAM Instrument is defined by BCAM.tcl.

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 set analysis_num_spots to "2" and analysis_enable to "1", the BCAM will display a red square around each separate spot. If there is only one bright 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 

You can specify two numbers in the analysis_num_spots string. The first number is num_spots, the number of spots the BCAM should find for you. The second number is sort_code, and specifies the manner in which the BCAM should sort the num_spots brightest spots in the image. We list the sort_code values below.

spot_decreasing_intensity=1;
spot_increasing_x=2;
spot_increasing_y=3;
spot_decreasing_x=4;
spot_decreasing_y=5;

We specify four spots sorted in order of increasing y-coordinate with analysis_num_spots set to "4 3". Spots closest to the bottom of the image will appear first in the result string. If we omit the sort_code, the BCAM assumes a value of 1, and sorts in order of decreasing brightness. No matter which sort code we specify, the BCAM always picks the num_spots brightest spots to sort. If we have ten spots from left to right, and we set num_spots to "4 4", the BCAM finds the four brightest spots and sorts them in order of decreasing x. The brightest spots are the one with the greatest total intensity above threshold, as opposed to the greatest number of pixels or the brightest centers. A large, dim spot might be brighter than a small bright one.

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. Now set analysis_num_spots to "2 2" and experiment again with flash times. You will see that the left-hand spot comes first in the result string no matter how bright or dim it is.

The BCAM Instrument provides three different ways to calculate the center of a spot. The default is by finding the weighted centroid of the spot's intensity. The weighted centroid calculation is the one we use in all our initial work on BCAMs, as we report in the BCAM User Manual, and it's the calculation we use in the ATLAS End-Cap Alignment. But the BCAM offers two other ways to find the center of the spot: by fitting an ellipse to the border of the spot, and by fitting a near-vertical straight line to the spot. We choose the calculation by setting analysis_enable to one of the following values.

spot_use_centroid=1;
spot_use_ellipse=2;
spot_use_vertical_line=3;

The vertical line calculation is for use when we have a bright stripe from top to bottom of the image, as we would if we looked at the negative version of an x-ray wire shadow, or the gradient version of a black pin image (the latter would have two bright, vertical stripes). The ellipse calculation is for use with large spots with well-defined edges, but within which the intensity varies in a way that does not correlate well with position, as we would see with retro-reflecting tape targets illuminated by laser light.

The BCAM marks each of the spots it finds so we can tell whether it is finding the ones we expect. The markings depend upon the calculation you specified with analysis_enable and the number of spots we requested. With the default centroid calculation and one spot, the BCAM displays 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. When we specify the elliptical calculation of spot position, the BCAM draws an ellipse around the spot that marks the border of the one it fitted to the spot. When we ask the BCAM to fit a vertical line to a spot, we draw the vertical line over the spot, but clip the line to the boundaries of the spot.

We can specify the BCAM analysis threshold in three ways. The first is to specify our threshold intensity as an integer, τ, followed by space and a * character (or by a number, in which case the BCAM Instrument assumes the * character). In this case, the threshold is taken to be the integer we specify. The second way is to enter an integer, p, 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 is to enter an integer, p, followed by a space and a # character. The # tells the BCAM to choose threshold::

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.

The analysis_threshold string allows us to distinguish between spots and noise or background features with further numerical criteria. After the number and character defining the threshold calculation, the next number is the minimum number of pixels a spot must contain to qualify for measurement. The number after that is the maximum eccentricity a spot may have to qualify for measurement. The eccentricity must be a value greater than one. If the ratio of the spot's width to height is greater than the eccentricity or less than the inverse of the eccentricity, the spot will be rejected.

Example: The string "10 # 10 2" for analysis_threshold says that the threshold intensity should be the average image intensity plus 10% of the difference between the maximum and average intensities. The minimum number of pixels in a valid spot is 10. If the width divided by the height is greater than 2 or less than 1/2, a spot will be ignored.

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. The Camera Instrument is defined by Camera.tcl.

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. It is defined by Diagnostic.tcl. The instrument 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 the info array. The maximum acceptable voltage for the +15V supply is max_p15. The minimum is min_p15. The +5V and −15V ranges are defined by max_p5, min_p5, max_n15, and min_n15. Note that we use "max" to mean "most positive acceptable value" and "min" to mean "least positive acceptable value".

Example: The string "off 1000 on 100" cycles the power supplies. With daq_psc = 1 and psc_max_tries = 4, the Diagnostic instrument cycles the power supplies up to four times to try to bring up the power supplies to their correct voltages.

Flowmeter

Before you try the flowmeter, we recommend you read through the help entry on the Thermometer. The Flowmeter Instrument is defined by Flowmeter.tcl. It uses the RTD Head (A2053) to measure gas flow rate with a PT1000 platinum temperature sensor. The A2053 has a heater circuit that runs 15 mA through a PT1000 to heat it up, and then measures the time constant of its cooling to ambient temperature. In theory, the inverse of this time constant is proportional to the gas flow rate in kg/s around the sensor.

Select a sensor for flow measurement in the same way you select a sensor in the Thermometer instrument. There are eleven sensor inputs on the A2053, selected with the daq_sensor_element variable. The flowmeter measurements takes about ten seconds with the default instrument settings. In the first second, it measures the ambient temperature of the gas. In the next two seconds, it heats up the sensor. For the seven seconds after that, it records the temperature of the sensor. When all the data has been transferred to the LWDAQ Driver, the Flowmeter displays it on the screen, and uses the last six seconds of the cool-down to calculate the time constant. The Flowmeter ignores the first second of cool-down after the end of the heating, because secondary time-constants manifest themselves during this first second, and degrate the accuracy of our measurement.

If you change the Scale (s/div), you change all the seconds in the above paragraph to time periods equal to the new value. The only exception is the heating time, which is set independently with the daq_heating_seconds parameter.

After a Flowmeter acquisition, you need to wait a few more time constants before you acquire again: the sensor needs to cool down completely to ambient temperature.

You will see in the display two red graphs. One is a linear plot of the temperature. It is curved. The other is a log-linear plot of temperature, and this plot extends only across the final six divisions of the display. In green is the straight-line fit to the log-linear graph, which we transfer also into the linear plot so you can compare the actual temperature with the fitted-temperature curve.

The Flowmeter output is the inverse time constant (1/s), the rms residual from the fit (C), the ambient temperature (C), the temperature at the start of the measurement fit (C above ambient), and the temperature at the end (C above ambient). We obtain better than 0.03% resolution in inverse time constant with constant laminar flow in a pipe, and we observe that the inverse time constant increases by roughly 1% for a 3% increase in gas flow. The curve of inverse time constant versus flow rate must be measured, because it is not exactly linear. We have an electronically-driven proportional valve connected to our apparatus, and we can calibrate a sensor in five minutes automatically.

You can try out the Flowmeter on the demonstration stand with the help of the Fan_Switch.tcl tool in the /Tools/Demonstration folder. Acquire with the Flowmeter, open the Fan Switch tool, turn on the fan, and wait twenty seconds. Now acquire again. You should see the cool-down is now more rapid. If not, then turn the fan off, wait, and try again. It could be that someone else left the fan on.

Gauge

The Gauge measures physical quantities such as temperature, resistance, or strain using a two-point calibration of a linear measuring device such as the Resistive Sensor Head (A2053). The Gauge Instrument is almost identical to the Thermometer, except it does not assume that the unit of the quantity you are measuring is Centigrade. The Gauge Instrument is defined by Gauge.tcl.

The Gauge measures the bottom and top reference voltages returned from an A2053 or compatible device. You specify values for bottom_ref_y and top_ref_y that correspond to the underlying physical quantities that give rise to the bottom and top reference voltages. Suppose you are using a Strain Gauge Head (A2053S) with bottom reference resistance 115Ω and top reference resistance 125Ω. You enter 115 for ref_bottom_y and 125 for ref_top_y in the Gauge config array. When you acquire data from channels on the A2053S, the Gauge will return the resistance across each channel you acquire from. The Gauge measures the resistance by drawing a straight line through the voltage it reads from the bottom and top reference resistors, and using this straight line to determine the resistance corresponding to the voltage it reads back from other channels.

The Gauge takes daq_image_width samples of each voltage it measures. By this means, it obtains daq_image_width measurements of an underlying physical quantity. With analysis_enable > 0, the Gauge plots these individual measurements in its display rectangle. With analysis_enable = 1, the Gauge result string contains the average of these daq_image_width measurements for each channel you specify. With analysis_enable = 2 , the Gauge returns the average and the standard deviation of the measurements.

If you want to measure temperature with a 100-Ω RTD using the A2053S, and you want the Gauge to convert RTD resistance into temperature, enter the RTD temperature that corresponds to an RTD resistance of 115Ω in the ref_bottom_y box, and the resistance that corresponds to 125Ω in the ref_top_y box. These temperatures are 38.96°C and 64.94°C respectively. Now the Gauge will convert resistance into temperature for you in its results line.

If you want to measure strain with a 120-Ω strain Gauge using the A2053S, and the Gauge factor of the strain Gauge is 2.0, enter -20800 for ref_bottom_y, indicating -20800 ppm strain, and +20800 for ref_top_y, indicating +20800 ppm strain. The Gauge will convert the strain Gauge's resistance into ppm strain in its results line.

You can, of course, connect both RTDs and strain Gauges to the same A2053S, and you can read them all out in one acquisition. The Gauge will not convert some channels into temperature and others into strain. It does either temperature or strain or resistance or some other units. We leave it to you to decide if you want to convert resistance to temperature and strain yourself, or if you want to configure and acquire from the Gauge Instrument once for your temperature sensors and a second time for your strain Gauges.

We also note that the Gauge will work equally well with the RTD Head (A2053A) and 1000-Ω RTDs. The A2053A uses 1060 Ω and 1100 Ω for its bottom and top reference resistances. You enter 15.38°C for ref_bottom_y, and 25.69°C for top_ref_y, and the Gauge will convert your 1000-Ω RTD measurements into degrees centigrade.

The Gauge's measurement method is accurate so long as the voltage returned by the measuring device is linear with the physical quantity it measures. All versions of the A2053 are designed so that thei are linear to within 100 ppm of their dynamic range.

Inclinometer

The Inclinometer, also called a tilt sensor, measures inclination in two directions using a liquid level sensor with five electrodes. The Inclinometer Instrument is defined by Inclinometer.tcl.

Figure: The Inclinometer Instrument on MacOS.

The Inclinometer Instrument works with the Inclinometer Head (A2065) and Inclinometer Sensor Head (A2066). The A2065 is a LWDAQ Device with programmable logic and analog circuits to drive the liquid level sensor. The A2066 holds the liquid level sensor and connects to the A2065 via a six-way flex cable. For a picture of the two of them in a box, see here.

The sensor has five electrodes. Four lie upon the corners of a square. The fifth lies in the center of the square. We call that one CTR in the circuit diagram. Two electrodes on opposide corners we call X+ and X−. The other two we call Y+ and Y−. In the Operation section of the Inclinometer Head Manual we describe how we measure the tilt of the sensor in the X and Y directions. There you will also find a description of the elements returned in the Inclinometer Instrument result.

Rasnik

A Rasnik Instrument takes an image of a chessboard pattern and determines the point in the chessboard projected onto a reference point in the image sensor. Our Rasnik Instrument is defined by Rasnik.tcl. The NIKHEF laboratory in the Netherlands invented the Rasnik Mask, which is a chessboard with some squares switched from black to white, and other switched from white to black in such a way as to indicate to a camera which part of the mask it is looking at, even though the camera sees only a small protion of the mask. Here is an example Rasnik image with the results of our analysis routine overlayed.

Figure: The Rasnik Instrument on MacOS. The Rasnik analysis routine draws green, red, and yellow lines and squares on the chess-board pattern. The green lines should lie exactly upon the edges of the squares in the pattern. The yellow squares should mark out-of-parity squares in the pattern, and the red squares also, but the red ones are at the intersections of rows and columns in the pattern that carry out-of-parity squares.

We distinguish between the magnification of the mask in the x (horizontal) and y (vertical) directions. You can see a Rasnik result in the figure above. The name at the beginning of the result is the name of the image file we analyzed, or if we captured the image from the LWDAQ, it is the name of the image in the LWDAQ image list. We have lwdaq_rasnik as a command-line routine in TclTk, lwdaq_image_create, and so on. If we specify an image in the LWDAQ image list, then the name of this image is the name at the beginning of the rasnik result.

The first and second numbers are the coordinates in the rasnik mask of the point in the mask that is projected by the rasnik lens onto the reference point in the CCD. The reference point does not strictly speaking have to lie within the CCD. It is a point in "image coordinates". Unlike the mask coordinates, which are right-handed, and proceed from the bottom-left corner of the mask, the image coordinates are left-handed, and proceed from the top-left corner of the top-left pixel in the image. Postive x is left to right, and positive y is top to bottom. We can specify image coordinates in microns, or in pixels. Within the analysis library, we use pixels for the most part, but when you specify the reference point yourself, as you can in the LWDAQ_info_Rasnik array, you do so in microns.

The third and fourth numbers are the x and y direction magnifications. The x and y directions we refer to here are not those of the image coordinates, but rather of what we call "pattern coordinates". The pattern coordinates are parallel to the mask squares. The x-direction is roughly left-to-right along the squares, and the y-direction is roughly top-to-bottom.

rasnik_image  91334.14  42632.84 1.189374 1.362885  13.412  0.2 120 10.0 3 2 1720.0 1220.0

The fifth number is the rotation of the pattern coordinates with respect to the image coordinates, and so we can refer to it as the mask rotation. Positive rotation is anti-clockwise rotation of the image with respect to the CCD, or clockwise rotation of the mask when we look from behind the mask towards the CCD through the lens.

The sixth number is an estimate of the accuracy of the mask x and y measurement. We have improved this error estimate so that it now includes the error we get from using a reference point that is displaced from the center of the area in the image we use to determine the rasnik measurement. We call this area the "analysis_bounds". When we use the top-left corner of the image as our reference point (coordinates 0, 0), our measurement is less accurate than if we use the center of the analysis bounds. This is because there is a stochastic error in our measurement of the rotation of the mask, and we must multiply this error by the distance from the center of the analysis bounds to the reference point to obtain the additional error caused by this displacement. That is not to say, however, that we lose anything by using the top-left corner. We provide a TclTk command line routine lwdaq_rasnik_shift which allows you to convert a rasnik measurement from one reference point to another, and in doing so you can remove the rotation error.

The next number, the seventh so far, is the size in microns of the squares in the rasnik mask.

rasnik_image  91334.14  42632.84 1.189374 1.362885  13.412  0.2 120 10.0 3 2 1720.0 1220.0

The eighth number is the pixel size in microns.

The ninth number is the orientation code. Here's what it means, as defined in Pascal:

rasnik_mask_orientation_nominal=1;
rasnik_mask_orientation_rotated_y=2;
rasnik_mask_orientation_rotated_x=3;
rasnik_mask_orientation_rotated_z=4;

The x, y, and z axese we refer to in the names above are the axese in the mask coordinates, with z being out of the mask. We have another orientation code:

rasnik_try_all_orientations=0;

This orientation code never appears in the rasnik output, but you can specify it as an input to the rasnik analysis, in which case the analysis will try all orientations and pick what it thinks is the best one.

The tenth number is the reference code. This tells the rasnik analysis what point it should use in the image as the reference point. Here are the reference codes as defined in Pascal:

rasnik_reference_top_left_corner=0;
rasnik_reference_center_analysis_bounds=1;
rasnik_reference_center_ccd=2;
rasnik_reference_image_point=3;

The last one, 3, requires you to specify a point in the ccd using the reference_x_um and reference_y_um parameters. At the moment, these are in the LWDAQ_info_Rasnik array, accessible with the Info button in the Rasnik instrument.

The last two numbers are the reference point the rasnik analysis used, specified in microns from the top-left corner of the top-left pixel.

The analysis boundaries are not included in the Rasnik output. Your DAQ script can get the analysis bounds from the lwdaq_image_characteristics command.

Here's how you use lwdaq_rasnik_shift to shift a rasnik reading to coordinates (1, 2) in millimeters.

set result [LWDAQ_acquire Rasnik]
lwdaq_rasnik_shift $result -reference_x_um 1000 -reference_y_um 2000

The result will give the Rasnik measurement with respect to the new reference coordinates in the CCD.

The Rasnik provides automatic flash time adjustement and background subtraction, just like the BCAM, and controlled by daq_adjust_flash in the Rasnik window.

The Rasnik extended acquisition adjusts the exposure time in the same way as the BCAM's extended acquisition. But the Rasnik's extended acquisition does not adjust its analysis boundaries.

The Rasnik allows you to specify a separate IP address for the source device LWDAQ, through the daq_source_driver_addr parameter, just like the BCAM.

As you select different reference codes, we mark the reference point in the Rasnik window different ways. If you set show_fitting to 1 you will see the steps of our rasnik analysis in the derivative images. If you set show_fitting to 1000 the program waits for 1000 ms between its displays of intermediate steps. If you set show_fitting to -1, the program will put up a little window with an OK button, right over the main window, and you press the button to continue. If you perform live capture with the -1 option, you can get a bit stuck trying to get to the Stop button after the OK button. Use the apple-t key on MacOS X, or control-t on Linux, to stop all instruments.

By setting analysis_enable to 0, you can disable the Rasnik's image analysis. This stops the Rasnik drawing its colored lines over the image. By setting analysis_enable to numbers greater than 1, you enable enhanced versions of the image analysis. In particular, you enable the Rasnik Instrument's boundry adjustment process.

With analysis_enable set to 2, the Rasnik tries to analyze a portion of the original analysis bounds. It selects a smaller analysis rectangle at random within the original rectangle. The minimum width and height of this new rectangle is analysis_min_width, in units of pixels. If this alternate rectangle produces a valid rasnik result, the analysis terminates and returns this result. Otherwise, the analysis routine writes one or two lines of red error messages to the instrument panel and then tries another rectangle. It keeps trying until it reaches analysis_max_tries or it meets with success. If it is successful, the analysis draws the rasnik measurement on the image.

At the end of the bounds-adjusting anlysis, the analysis boundaries in the analyzed image will be set equal to the rectangle within which the analysis obtained a valid result. If it did not obtain a valid result, it leaves the original boundaries of the image intact. You can find out what the final analysis boundaries were with the help of lwdaq_image_characteristics applied to image memory_name.

When analysis_enable is 3, the analysis also tries alternate rectangles, and displays each rectangle on the screen as it goes. This display is entertaining when you are working directly on the machine performing the analysis, but if you are connected to this machine via X-Windows or some other remote access, you will find the rectangle-drawing slows the Rasnik Instrument down.

Recorder

The Recorder Instrument is defined by Recorder.tcl.

The Recorder Instrument operates with the Data Recorder (A3007). The Neuroarchiver Tool uses the Recorder to obtain data from implanted telemetric devices such as the Subcutaneous Transmitter (A3013). Both the software and the hardware were developed by Open Source Instruments Inc. For more information, see the Recorder Instrument User Manual.

RFPM

The RFPM Instrument is defined by RFPM.tcl.

The RFPM (Radio Frequency Power Meter) Instrument operates with the RF Spectrometer (A3008). Both the software and the hardware were developed by Open Source Instruments Inc. The Spectrometer Tool uses the RFPM to obtain power measurements for its radio-frequency spectra.

Terminal

The Terminal Instrument is defined by Terminal.tcl.

Figure: The Terminal Instrument on MacOS.

The Terminal Instrument provides a terminal-like interface with a LWDAQ data device. During a data acquisition cycle, the Terminal sends a string of bytes to the device and downloads a string of bytes that it expects to receive in return. We use the Terminal with the RS232 Interface (A2060C) and the ADC Tester (A2100).

The Terminal transmits bytes obtained from four different sources. You specify bytes in tx_ascii by entering their ASCII characters. If you type "A", you specify the byte with hexadecimal value 41 and decimal value 65. You specify bytes in tx_decimal by entering their decimal values separated by spaces. If you type "65" you specify the byte with ASCII value A and hex value 41. If you enter "65 66", you specify "AB". If you enter "10 13", you get line-feed (LF) followed by a carriage-return (CR). You specify bytes in tx_hex by entering two-digit hexadecimal numbers separated by spaces. If you type "41" you specify the byte with ASCII value A and decimal value 65. You can use tx_decimal and tx_hex to send terminator characters at the end of a character string, as we might when communicating with an RS232 terminal using the RS232 Head (A2060C). Here are some likely terminator characters and their decimal and hexadecimal values.

The Terminal concatinates strings defined by tx_ascii, tx_decimal, tx_file_name, and tx_hex to form a single string called tx_string. The concatination takes place in the order we just listed the strings, which is also the order in which the string names appear from top to bottom in the Terminal Insturment window.

The Terminal sends tx_string to the target device one byte at a time. For each character, the Terminal sends a command word with the upper byte containing the character value and DRX (DC6) set to 1, as required by data devices during read jobs.

Example: The RS232 Interface (A2060C) transmits each character it receives over its RS232 interface.

Example: The ADC Tester (A2100) receives each byte as an instruction, which it executes immediately.

After sending tx_string to the target device, the Terminal downloads a response string from the target device. It obtains the response string by consecutive byte transfers. The string will be rx_size bytes long, and will be stored in rx_string. If rx_size is zero, the Terminal skips the download, sets rx_string to an empty string, and ends its acquisition. The consecutive byte transfers cease when rx_size bytes have been received, or when the transfers from the target device end with the receive terminator character, whichever occurs first. We define the receive terminator character with rx_last_decimal. We set rx_last_decimal equal to the decimal value of an ASCII character. The value 0, which indicates the NULL character, has a special meaning: the Terminal does not look for a terminator character, but instead waits until the driver has received rx_size bytes from the target device.

Example: You connect a PC to the LWDAQ through an RS232 Head (A2060C). You transmit text lines to the PC terminated by FF characters, and a receive text lines terminated by FF charcters also. The longest answer you expect to receive is a few thousand characters, so you set the rx_size to 10000. You put your text instructions in tx_ascii. You set tx_hex to "0C". You leave tx_file_name and tx_decimal empty. You set rx_last_decimal to "0C". Suppose the PC is asking the questions. Set tx_ascii to the empty string and acquire. Wait until you have receive a string from the PC. The string should appear in the Terminal text window. Type your answer to the PC in tx_ascii. Acquire again, and so on. You could equally well set up the communication so that the Terminal was asking the questions. You send a query string and wait for the PC to answer.

The Terminal allows you to set a time-out for reading from the target device. The timeout applies only when waiting for a receive terminator character from the target device. The Terminal will give up waiting for the terminator after rx_timeout_ms and download rx_size bytes from the driver.

Once it obtains its rx_size bytes from the driver, the Terminal displays them in its image display area. Each byte appears as the gray-scale intensity of one pixel. The first byte is the first pixel in the second row (not the first row). With zoom set to 1, the pixels will be small. The default value of zoom for the Terminal is 2.

After it displays the data as gray-scale pixels, the Terminal analyzes the data and creates its result string. The result string depends upon the value of analysis_enable.

If the block of received bytes is large, or contains many non-standard ASCII values, you can work with the data in the Terminal image, using routines like lwdaq_data_manipulate.

Thermometer

The Thermometer instrument allows you to measure temperatures from either a Bar Head (A2044) or an RTD Head (A2053). Both these LWDAQ Devices are equipped with platinum RTDs (resistance temperature devices). We tend to use the 1000-Ohm variety, with reference resistors 1060 Ohms and 1100 Ohms on the board to act as references for temperatures 15.38 C and 25.69 C respectively. The Thermometer Instrument is defined by Thermometer.tcl.

Figure: The Thermometer Instrument on MacOS.

You tell the Thermometer which device you are using with the daq_sensor_name variable in the config array, which you can set to "A2053" or "A2044" (no spaces on either side of your entry). The A2044 provides four RTD inputs, and the A2053 provides eleven. You specify which sensors you want to read, and the order in which you want to read them, using daq_sensor_element. In our default setup, the Thermometer reads out all eleven channels from our demonstration stand's A2053, as well as the on-board bottom temperature reference and top temperature reference. We use numbers to select the sensors, the letter "B" to select the bottom reference resistor, and "T" to select the top reference resistor.

Connector P1 on both the A2044 and A2053 carries sensor elements 1 through 4. The connector has eight pins, with pin 1 being marked on the silk screen. The first two pins are for sensor 1, and so on. On the A2053, connector P2 carries sensors 5 through 8 in the same way. Connector P3 is a four-way connector and carries sensors 9 and 10. Sensor 11 is on P4, which is a two-way header that we usually leave out, so you can solder wires into the board if you want to.

The Thermometer measures temperature by comparing the resistance of every sensor you tell it to look at to the resistances of the bottom and top reference resistors. If you tell the Thermometer to measure the temperature of the bottom reference resistor, it goes through the same procedure, but instead of selecting an external sensor, it selects the bottom reference resistor. The bottom reference resistor should give you a temperature equal to ref_bottom_C in the info array.

For each sensor element, the Thermometer selects the bottom reference resistor, the sensor resistor, and the top reference resistor in turn. For each of these three resistors, if records a series of sixteen-bit ADC samples. The number of samples it records is equal to daq_image_width. When the Thermometer calculates the sensor temperature, it does so using the average of each of the three series of samples. The Thermometer writes the temperatures it measures to its results string, in the order you specify in daq_sensor_element.

The Thermometer takes daq_image_width samples of each voltage it measures. By this means, it obtains daq_image_width measurements of temperature. With analysis_enable > 0, the Thermometer plots these individual measurements in its display rectangle. With analysis_enable = 1, the Thermometer result string contains the average of these daq_image_width measurements for each channel you specify. With analysis_enable = 2 , the Thermometer returns the average and the standard deviation of the measurements.

The Thermometer display looks like an oscilloscope. It displays the individual temperature measurements that go into making the average measurement that the Thermometer writes to its result string. Each point displayed in the oscilloscope graphs is a sixteen-bit measurement of sensor resistance combined with the average bottom and top temperature measurements taken immediately before and after the sensor samples. You can zoom in on individual sensors, and expand the time scale using the numerical text entries below the display.

When the Thermometer acquires a new measurment, it determines its sixteen-bit ADC sample rate by looking at the "Scale (s/div)" entry below the oscilloscope, which is equal to display_s_per_div. The thermometer knows how many columns there are in the display per display division, and divides display_s_per_div by the number of columns per division to obtain the sample period. If the sample period required to conform to this rule is less than the smallest sample period possible with the driver's sixteen-bit ADC, then the Thermometer simply sets the period equal to this smallest value. Either way, the Thermometer knows the actual sample period, and displays the samples accurately along the time scale.

The demonstration stand provides an A2053 with the following sensor elements:

1. A 0.01% 1060-Ohm TC < 10 ppm/C (should give 15.38 C)
2. A 0.01% 1060-Ohm TC < 10 ppm/C (should give 25.69 C)
3. Wire link (gives bottom of dynamic range)
4. Open circuit (gives top of dynamic range)
5. PT1000 glued to metal base of rasnik mask
6. PT100 glued to back side of rasnik LED array
7. PT100 suspended above LED array
8. PT1000 glued to metal base of Rasnik mask
9. Open circuit
10. Open circuit
11. PT1000 suspended in front of a fan

Try the following script. Cut and paste the script into the console to run it.

LWDAQ_open Thermometer
set LWDAQ_config_Thermometer(daq_sensor_element) "5 6 7 8"
set LWDAQ_config_Rasnik(daq_flash_seconds) 0.2
while {[winfo exists $LWDAQ_info_Thermometer(window)]} {
  LWDAQ_acquire Thermometer
  LWDAQ_acquire Rasnik
}

The script will read the temperature of the sensors on glued to the rasnik mask and then flash the LEDs for one second and measure the temperature again, and so on in a loop until you close the Thermometer instrument panel. The heat dissipated by the LEDs warms up sensors 5 and 6.

Viewer

The Viewer allows you to open image files and analyze them with any of the other instruments installed in your LWDAQ program. The Viewer's own analysis routine returns the image header information: height and width, left, top, right, and bottom boundaries, and the image results string. The Viewer is defined by Viewer.tcl.

Figure: The Viewer Instrument on MacOS.

The Viewer has no data acquisition parameters of its own. If you enter "daq" for image_source you will receive an error message. You invoke the analysis procedures of other instruments by pressing the buttons below the image display. The Viewer will apply the analysis to the currently-displayed image. It will not acquire a new image.

Example: Suppose you want to analyze an image with the BCAM and the Camera instruments. The image already exists in memory, having just been captured. You see that the name of the image is BCAM_7. Enter BCAM_7 for the memory_name in the Viewer, and "memory" for image_source. Press the Acquire button. The image shows up in the viewer display. Now press the BCAM button, and you will see the results of BCAM analysis overlayed upon the image (unless your BCAM Instrument has analysis_enable set to 0), and the BCAM results string will show up in the Viewer text window. Press the Rasnik button to do the same with Rasnik analysis.

If you want to acquire a new image from another instrument, write the name of this other instrument as the Viewer's image_source parameter. The viewer will acquire an image using this other instrument and display the image in its own window.

The Viewer allows you to change the dimensions, analysis bounds, and results string of an image using the buttons and entry boxes. Enter your new values in the entry boxes and press the appropriate button. The "−1" default values for analysis boundaries tell the Viewer to leave pre-existing boundaries as they are.

The Viewer converts multiple image files on disk between DAQ and GIF image formats using the DAQ to GIF and GIF to DAQ buttons.

Voltmeter

The Voltmeter uses the Input-Output Head (A2057) to measure analog inputs. The A2057 provides two analog inputs, a 5-V reference input, a 0-V reference input, four open-drain digital outputs, and two 8-bit analog DAC outputs. The Voltmeter is defined by Voltmeter.tcl.

Figure: The Voltmeter Instrument on MacOS. On the oscilloscope-like display is the triangle wave you can obtain from the Brandeis demonstration stand.

The Voltmeter uses the LWDAQ Driver's sixteen-bit ADC and 10 kHz low-pass filter to measure voltages returned from the Input-Output Head. You select one or more of the A2057 analog inputs using the Voltmeter's daq_device_element. The Voltmeter takes daq_image_width samples of each analog input you specify in daq_device_element and calculates its average value and standard deviation. When you set analysis_auto_calib to 1, the Voltmeter compares analog inputs to 5-V and 0-V references, and so obtains a more accurate measurement of the analog input voltages. If you set analysis_auto_calib to 0, the Voltmeter relies upon the nominal gain in the Input-Ouput Head, and the LWDAQ Driver, to translate sixteen-bit ADC values into analog input voltages.

The Voltmeter plots the samples on its oscilloscope screen. You can adjust the display and sample frequency used by the Voltmeter in the same way you would those of an oscilloscope. The Voltmeter provides you with a trigger as well, with slope and threshold.

When you set daq_x11_gain to one, you turn on the ×11 amplifier on the Input-Output Head for all inputs you specify in daq_device_element. The Voltmeter analysis will account for the gain by dividing its measurment of the analog voltages.

We have an A2057 connected to our demonstration stand. One analog input is connected to a triangle wave generator. Try acquiring from it. You should see a 1 kHz 5-V amplitude triangle wave. Try changing the Scale (s/div) and Trigger Level (V). You can do both during live capture, just as you would with an oscilloscope.

The Voltmeter allows you to set the four digital outputs on the A2057 with the daq_logic_outputs string, which represents the state of the binary outputs as the low-order hexadecimal digit in a hexadecimal number up to four digits long.

The oscillator attached to our demonstration stand's A2057 responds to the first two digital outputs so that the daq_logic_outputs string has the following correspondance to oscillator outputs:

• 0000: Triangle wave, amplitude 0.5 V, frequency 10 kHz
• 0001: Triangle wave, amplitude 0.5 V, frequency 1 kHz
• 0002: Triangle wave, amplitude 5 V, frequency 10 kHz
• 0003: Triangle wave, amplitude 5 V, frequency 1 kHz

At the moment, the Voltmeter does not allow you to set the two DAC outputs on the A2057, although you can do this with the A2057.tcl tool in the Tools/Circuit_Testers sub-folder.

WPS

The WPS Instrument works with an optical wire position sensor such as the WPS1. The WPS Instrument is defined by WPS.tcl.

The WPS1 consists of two cameras, a light source, and a background screen. The cameras view the wire from two angles against a background of white paper. An array of infra-red LEDs illuminate the paper so that the camera sees the wires in silhouette. In the WPS screen shot you see the silhouette of a wire with the results of analysis marked upon it. The red lines are the edges found by the analysis. The green and yellow lines are the intensity and row derivative intensity graphs. The blue line marks the height at which we calculate the horizontal position of the wire.

The WPS result gives us the results of analysis applied to both edges of the wire silhouette. The first six numbers correspond to the left edge, the last six to the right edge.

WPS_380 718.69 -6.93 1859 69 0.432 11 888.37 -4.53 1878 69 0.437 11 

The first number is the horizontal position of the left edge where it crosses the reference line. We set the reference line with analysis_reference_um. We specify the number of microns from the top edge of the top row in the image. The WPS Instrument convertes micrometers to pixels with analysis_pixel_size_um. The horizontal position of the edge is the number of microns from the left edge of the leftmost row in the image to the intersection of the edge and the reference line. The second number is the rotation of the edge counter-clockwise in the image, in milliradians. The third number is the number of pixels found in the edge. The fourth number is the maximum intensity of the edge pixels in the derivative image we use to find the edges (see Derivative Analysis). The fifth number is the change in edge position per unit increase in threshold. The sixth number is the threshold used to discriminate between edge pixels and non-edge pixels in the derivative image. The next six wires correspond to the right edge in the same way. As you can see, the threshold is the same for both wires.

The WPS Instrument is similar in many ways to the BCAM Instrument. Indeed, the WPS1 uses BCAM electronics to read out its cameras and drive its light source. Unlike a BCAM, however, the WPS light source and cameras are always contained within the same device. We have a separate daq_source_device_element for the source and daq_device_element for the camera, but the source and camera share the same daq_driver_socket, daq_mux_socket, and daq_ip_addr.

With analysis_enable set to 1, we differentiate and apply a threshold to the raw image. With analysis_enable set to 2, we smooth the image with a 3×3 box filter and enhance contrast before we differentiate and discriminate. We describe the analysis in more detail in WPS Performance. Look at the Derivative Analysis section and the Derivatives Again section. For details of pre-smoothing see the Wire Types section.

You can ask the WPS to show you the pixels it uses for each edge by setting analysis_show_edges to 1 in the Info array. The green and yellow graphs will disappear, and the edges will be marked in bright colors.

The threshold the WPS applies to the gradient image in the same way that BCAM thresholds apply to raw BCAM images. The "%" and "#" characters have the same meaning we describe in detail for the BCAM. The WPS analysis is a straight-line fit to the two bright lines in the horizontal derivative image. You could obtain the same analysis with the BCAM Instrument with the following script in the toolmaker, after first setting up the WPS Instrument to take images from a wire position sensor.

upvar #0 LWDAQ_config_BCAM config
set config(image_source) WPS
set config(analysis_enable) 0
set config(analysis_num_spots) 2
LWDAQ_acquire BCAM
lwdaq_image_manipulate $config(memory_name) smooth -replace 1
lwdaq_image_manipulate $config(memory_name) grad_i -replace 1
set config(analysis_enable) 3
LWDAQ_instrument_analyze BCAM

In the script, we smooth the image, take its derivative, and then apply the BCAM's straight-line spot finder routine for two spots. The BCAM fits two red lines to the edges that appear in the derivative image.

Commands

You can get a list of all LWDAQ commands by typing the following at the console:

LWDAQ_list_commands

You will find all commands listed and described in the LWDAQ Command Reference. You can generate this HTML document from the LWDAQ console with:

LWDAQ_command_reference

Commands whose names begin with lwdaq_ are implemented in the analysis library, and we call these the library commands. Those whose names begin with LWDAQ_ are implemented in TclTk scripts stored in the LWDAQ.app directory, and we call these script commands. You can get the descriptions of script commands at the console by typing "help" or "man" followed by the procedure name.

help LWDAQ_socket_write

If you want to see the TclTk definition of a script command, add the word "definition" at the end of the help command.

help LWDAQ_socket_write definition

Try the following command at your console. We include a likely output in blue letters.

(LWDAQ_OSX) 1 % LWDAQ_read_image_file Images/blurred
lwdaq_image_1

LWDAQ_read_image_file reads an image file from disk and puts it in the LWDAQ image list. The routine returns the name of the image in the LWDAQ image list. The file name you specify is with respect to the current TCL default directory, which we set to the program at start-up.

(LWDAQ_OSX) 2 % lwdaq_image_charactheristics lwdaq_image_1
20 2 342 242 58.5 14.1 226.0 40.0

Command lwdaq_image_characteristics returns information about an image. The first four numbers give the left, top, bottom, and right borders of the analysis boundries. These numbers are row and column numbers. For example, left is the number of the left-most column. Then there are four real numbers giving the average of intensity, the standard deviation of the intensity, the maximum intensity, and the minimum intensity. All four numbers we calculate within the analysis boundries. You can treat the result as a string or a list in TclTk.

(LWDAQ_OSX) 3 % lwdaq_image_exists lwdaq_image_1
lwdaq_image_1

lwdaq_image_exists returns the names of all images that match the string you pass as a parameter. You can use a "*" as a wildcard string, or "?" as a wildcard letter. If no image with a matching name exists, then the routine returns an empty string.

(LWDAQ_OSX) 4 % LWDAQ_write_image_file lwdaq_image_1 images/new_image

LWDAQ_write_image_file takes an image from the LWDAQ image list, which you specify by name, and writes it to the file you specify.

lwdaq_image_destroy lwdaq_image_1

lwdaq_image_destroy removes all images in the image list whose name matches the string you pass in the first parameter. You can use "*" as a string wild card, and "?" as a character wild card.

All the lwdaq routines will return a list of parameters they take if you enter the command name at the console with no parameters. We specify parameters to lwdaq routines with an option name and then a value for each option, as shown for lwdaq_image_destroy. The LWDAQ routines, on the other hand, take their parameters directly with no option name to identify them. We use option names in the lwdaq commands because it simplifies our Pascal code.

Startup Scripts

The LWDAQ Startup Directory is LWDAQ.app/Contents/LWDAQ/Startup. When LWDAQ starts up, it attempts to run every file with extension ".tcl" as a TclTk script. It runs the scripts in alphabetical order. Try putting a file called Example.tcl in the startup directory, with the following line.

LWDAQ_open Rasnik
LWDAQ_run_tool Acquisifier.tcl

When LWDAQ starts up, it will open the Rasnik Panel and the Acquisifier Panel. You can open any tool or instrument like this. Here's another startup script. It opens the console on Windows and MacOS, and prints the startup script name to the console.

console show
puts "Hello from inside [info script]"

Startup scripts are run in the same was as configuration scripts, which we discuss above. The only difference between them is the way in which they are called. A configuration script is one whose name you pass with the lwdaq command at your terminal. A startup script is any script in the Startup Directory.

Tools

A LWDAQ Tool is a TclTk script that calls commands in our LWDAQ libraries and makes use of the LWDAQ instruments. We provide example LWDAQ Tools in the Tools directory. You can run a tool using the Run Tool option in the Tool menu.

One of the scripts in the Tools directory is the Configurator. We use the Configurator to set the IP address of new drivers. If you put a script in the Startup directory, LWDAQ will run it automatically when it starts up.

When you write a tool, you can use the TCL console to check individual lines in the tool for their syntax and functionality. One way to create a new tool is to open a new text file in a text editor, enter TclTk commands, save it to disk, and run it from LWDAQ with Run Tool from the Tool menu. Another way, which we prefer for quick and simple jobs, is to use our Toolmaker. To open the Toolmaker, select select it in the Tool menu.

Toolmaker

The Toolmaker provides a text window into which you type a TclTk script. Whenever you press the Execute button, the Toolmaker adds your script to a list, saves the list to disk, and executes the script. The Toolmaker opens a text window to record the script execution. This window is distinct from any previous or subsequent Toolmaker windows. It is the Output Window for this particular script execution.

The Output Window displays the script lines, error messages, and text output. The script can refer to this text window with the local t variable.

LWDAQ_print $t "Output from a script." blue

The above line, in a Toolmaker script, will print "Output from script." in blue in the Output Window.

You can save, edit, and load lists of scripts with buttons in the Toolmaker window. See LWDAQ_Toolmaker and LWDAQ_Toolmaker_execute for more details.

The only Instrument commands you are likely to need in a LWDAQ tool are LWDAQ_aquire, LWDAQ_open, and LWDAQ_close. Each one takes an instrument name as a parameter. The following script opens the Rasnik instrument panel, adjusts the daq parameters, acquires an image and returns the results of Rasnik analysis, and then closes the Rasnik instrument panel. Try running it in the Toolmaker.

LWDAQ_open Rasnik
set LWDAQ_config_Rasnik(daq_source_branch) 
set LWDAQ_config_Rasnik(daq_sensor_branch) 
set result [LWDAQ_acquire Rasnik]
LWDAQ_close Rasnik
LWDAQ_print $t $result purple

You don't have to open the Rasnik instrument panel in order to adjust its configuration array and acquire data. The only reason you might want to open the instrument panel is to see what is going on. The above script leaves result equal to something like this:

Rasnik_1 8088.21 9160.74 0.742465 0.741196 -2.407 0.9 120 10.0 2 2 1720.0 1220.0

When you execute the above script in the Toolmaker, you will see the result value printed in the execution window in purple.

Basic Tools

A basic tool is a TclTk script we can run with Run Tool from the Tool menu. We can also run it with LWDAQ_run_tool at the Tcl command prompt. Toolmaker scripts can refer to an execution window with the t variable. But a basic tool must declare an execution window of its own. A basic tool can call any LWDAQ command. It can reside in any directory and have any file name.

Standard Tools

A standard tool is a basic tool with the following features.

• The tool name, Tool, contains no spaces or periods.
• The tool script is either Tools/Tool.tcl or Tools/More/Tool.tcl.
• The tool declares commands Tool_init and Tool_open.
• Command Tool_init calls LWDAQ_tool_init.
• Command Tool_init sets at least one element of global array Tool_config.
• Command Tool_open opens the tool's window.
• The tool's window is .tool, where tool is the lower-case version of Tool.
• The tool's user-adjustable parameters are elements in an array called Tool_config.
• Re-selecting the tool from the Tool menu does not re-initialize the tool.
• The tool script embeds help text according to the format described below.
• The tool script embeds data according to the format described below.
• The tool provides a Configure button that calls "LWDAQ_tool_configure Tool".
• The tool provides a Help button that calls "LWDAQ_tool_help Tool".

The Tool_init command creates two global arrays called Tool_config and Tool_info. The distinction between the info and config arrays for standard tools is different from the distinction between the info and config arrays for LWDAQ instruments. In the case of Tools, the config array is for parameters the user should be able to change and save, and the info array is for all other parameters. When you select Save Settings from the File menu, Tool_save saves only the Tool's config array. The info array never gets saved.

We provide the LWDAQ_tool_init to make it easy for you to initialize a standard tool, and all standard tools must call this command (or its predecessor LWDAQ_tool_startup).

upvar #0 Configurator_info info
upvar #0 Configurator_config config

LWDAQ_tool_init "Tool" "1"
if {[winfo exists $info(window)]} {return 0}

These lines declare two global arrays for use in initialization. We pass the tool name and the tool version number to LWDAQ_tool_init. The LWDAQ_tool_init command saves the name of the tool window in the info(window) element. We test this element to see if the window exists already, and if it does, we abort the config and info arrays.

At the end of Tool_init, we have the following lines to read in and execute the settings file:

if {[file exists $info(settings_file_name)]} {
  uplevel #0 [list source $info(settings_file_name)]
} 

The Tool_open command creates the tool's display window. This window can have Help, Save, and Configure buttons that call the tool's help, save, and configure commands. Here is one way to create these buttons in a tool window.

The Configure button will call LWDAQ_tool_configure. This command opens a configuration panel that shows all the elements of the global Tool_config array. The window provides a button that saves the config array to a file called ./Tools/Data/Tool_Settings.tcl. If you want to implement additional configuration buttons in the configuration panel, create a custom configuration command for you tool.

proc Tool_configure {} {
  upvar #0 Tool_info info
  set f [LWDAQ_tool_configure $info(name)]
  button $f.custom -text "Custom Config" -command Tool_custom_config
}

The LWDAQ_tool_configure command returns the name of the frame it packs in the configuration panel below the Save button. In the script above, we use this frame to hold a custom configuration button.

The LWDAQ_tool_help command extracts help text from the tool's scropt file. We embed help text by placing it after a "return" command in the script that guarantees TclTk will never proceed farther down the file. If the Tool_help command encounters the word "return" alone on a line, with no white spaces before or after, it assumes that everything following this line is the Help text. If, on the other hand, Tool_help encounters a return with other characters, as in the following example, it will proceed until it finds the special begin help line.

return 1

----------Begin Help----------

The begin help line must be exactly as shown above: ten dashes followed by "Begin Help" and ten more dashes, then a line break. Don't put any spaces after the last dash. You end the help text with the following line:

 ----------End Help----------

You can embed data in a tool script by enclosing it between the following two lines. Once again: the lines must be exactly as shown, with ten dashes before and after the words.

 ----------Begin Data----------

 ----------End Data---------- 

You use LWDAQ_tool_data to extract the data lines from the tool script file:

set data [LWDAQ_tool_data Tool]

If your tool requires a scrolling text window, you create one with the following lines in its Tool_open command.

set info(text) [LWDAQ_text_widget $w 80 15]

The LWDAQ_print command implements color-coding for errors and warnings. You can specify a color to print in as well. We support the following text colors: black, red, green, blue, orange, yellow, brown, purple. If the string you want to print contains the keyword "error:" (case insensitive), the text appears in red. Otherwise, if the string containes "warning:", the text appears in blue. Otherwise, the text appears in your specified color. If you don't specify a color, the text is black. By default, LWDAQ_print adds a line break at the end of the string it prints, but you can suppress the line break with the -nonewline option.

LWDAQ_print -nonewline $info(text) "Title Without Line Break" $config(title_color)

Standard tools like the BCAM Saturator capture images using the LWDAQ instruments and display the images in their own windows without ever opening the instrument panel itself. To display images in your tool window, you start by creating a label widget in Tool_open. Here are the lines from the BCAM Saturator that create such a label:

set info(photo) [image create photo -width 344 -height 244]
label $f1.image -image $info(photo)
pack $f1.image -side left

As you can see, you associate a TK photo with the label widget, and you store the name of this photo in the Tool_info array. Later, the BCAM Saturator captures an image with the BCAM and displays it using the following lines:

LWDAQ_acquire BCAM
lwdaq_draw $iconfig(memory_name) $info(photo)

We use the following line to get access to the global array (which has a long name) through the name "info" (a short name).

upvar #0 BCAM_Saturator_info info

As we have said, the Standard LWDAQ Tool provides two commands with names constructed out of the name of the tool. These procedurs and all others unique to the tool are defined by the Tool's script file. In that file, after all the command declarations, there are at least the following lines:

Tool_init
Tool_open
return

If we don't want to use the "return" line to mark the beginning of our help text we add an empty-string specifier or a "1" to say that our tool script executed properly:

Tool_init
Tool_open
return 1

When we write new Standard LWDAQ Tools, we start with an empty text file, open a couple of pre-existing standard tool scripts, and copy sections from the pre-existing scripts into our new script. We replace the old tool names with our new tool name.

Polite Tools

A Polite LWDAQ Tool obeys the following restrictions.

1. The tool never intentionally disables itself to wait for user input.
2. The tool recovers gracefully from all TclTk errors.
3. The tool creates its own window, and when you close this window, all activity related to the tool aborts within ten seconds.
4. The tool always allows you to abort whatever activity it is engaged upon by pressing a button on the screen, even if this button is the tool window's close button.
5. The tool does not call TCL's vwait command directly, but instead calles vwait through LWDAQ_vwait. This allows LWDAQ's reset button to stop all process by setting their timeout variables.
6. The tool's buttons post their actions to the LWDAQ event queue if those actions call LWDAQ_vwait. This avoids vwait deadlock in the TCL event loop.
7. The tool checks the global LWDAQ_Info(reset) variable to see if it should abort its data acquisitions.

Most of the tools we provide with LWDAQ are standard and polite. In particular, BCAM Calibrator manages to be polite even though its function is complex and passes through multiple states. The Chamber Checker tool is not polite, because it opens up with a dialog box and enters a TCL while loop waiting for you to enter an operator name.

Making a polite tool takes a lot more effort than making a standard tool, so we recommend that you start by making a standard tool and telling your users that it is not polite. This will warn them that they cannot perform Loop capture from six open instruments, and expect to fire up your tool and have no TCPIP conflicts or vwait deadlocks. If your tool gets enough use, and your users ask you to make it more compatible with the LWDAQ instruments, then you can decide for yourself if it is worth the effort of making it polite.

Acquisifier

The Acquisifer allows you to define a LWDAQ acquisition cycle through many LWDAQ Instruments and record their results and images to disk. It is an example of a LWDAQ Tool. Select Acquisifier from the Tools menu to open the Acquisifier Panel. You define the acquisition cycle with an Acquisifier Script. We describe the Acquisifier in detail in the Acquisifier User Manual.

Readme

New

We list new features in order newest to oldest.

7.2

1. The LWDAQ.bat file has been greatly enhanced to support passing options and a script file to the batch process. Now we can launch LWDAQ and have it run a script for us in the background simply by naming LWDAQ.bat and the script file in a single command.
2. The command-w combination closes windows on MacOS, and alt-w on windows, and ctrl-w on Linux.
3. The analysis_threshold parameter in the BCAM Instrument and WPS Instrument now allows you to specify the minimum number of pixels a valid spot must contain. Pixels above threshold that are not part of a valid spot are marked on the overlay in white when you set analysis_show_pixels or analysis_show_edges. The same analysis_threshold
allows you to specify a maximum eccentricity for a spot. If the ratio of width to height, or of height to width, is greater than this maximum, the spot will be ignored, and its pixels will be marked white in the overlay.
4. Add pre-smoothing option with analysis_enable set to 2 in the WPS Instrument. Improve the resolution and contrast in the images created by the smooth option of lwdaq_image_manipulate.
5. The BCAM Instrument now allows us to sort results in order of increasing or decreasing x or y using the a sort_code that we append to analysis_num_wires. Spots may now be analyzed in three different ways: weighted centroid, vertical line fit, or elliptical fit, using different values of analysis_enable. With the new analysis_show_pixels parameter set to 1, the BCAM will mark the pixels of the various spots it finds in the image with different colors so we can see the results of its recursive spot-construction algorithm.
6. The BCAM calibration constant print-out routines check to see if the calibration constants obtained are within an acceptable range of their nominal values, and if not, the routines append warnings to the print-out string. These warnings automatically notify the BCAM Calibrator and the BCAM Calculator tools of the range errors. The calibration print-out will be blue in both cases when a range error occurs, and in the BCAM Calibrator, the calibration will be marked as a failure. You will find the ranges accepted by the BCAM analysis in the interface section of bcam.pas. We consolidated the old calibration.pas file into bcam.pas, so calibration.pas no longer exists.
7. With zoom not equal to 1, the Rasnik Instrument will now display the progress of its random boundary analysis with the correct image size. Previously, the intermediate steps would always be displayed with zoom=1. The result with zoom=2 and analysis_enable=3 acting upon a large block of images opened with the Read button is most gratifying.
8. All Instruments now perform better when analyzing long lists of files. In the Rasnik Instrument, for example, we press Read and select 4909 images taken from the ATLAS Barrel Alignment System, and analyze these. After an initial freeze while TCL obtains the list of file names, LWDAQ proceeds with analysis. We can move windows, change instrument settings and work in the console whiel analysis is taking place. We can abort the analysis at any time with the Stop button. The LWDAQ event queue, however, remains stuck on the analysis of the image list. We still cannot run the Acquisifier at the same time as the batch analysis started by the Read button. (But please note that multiple-file selection with the file browser does not work on Linux in TclTk 8.5.1. To get the same effect, enter the directory name and a "/*" for glob matching in file_name and set image_source to "file".)
9. In the rasnik analysis, we relaxed one constraint that previously led to failure. In the past, if rasnik_refine_pattern in rasnik.pas found more than line_data_size pixels (20,000 with current code) along one chessboard edge in a rasnik image, it would abort. In some 400k-pixel images with large squares, poor focus, and poor illumination, the number of pixels in an edge was exceeding 20,000. We hesitate to increase line_data_size because we encountered problems whith the Windows version of the code when we did so. But now the analysis will fit a line to the existing 20,000 points and do its best to find the rasnik pattern.
10. Added append_errors option to lwdaq_config. When set, new errors are appended to the existing global error_string in the analysis library. This addition was a product of work we did upon the rasnik routines to fix our analysis.a static version of our analysis library, which was not working properly for the ATLAS barrel alignment team.
11. Added simplex fitting routine to utils.pas, which we will export to TCL command line in near future. We first used the simplex fitter for wire position sensor calibration. We will replace the far less efficient gradiant-descent routine used in shadow.pas, and we will use it to fit ellipses to large BCAM spots.
12. When downloading a large block of data, the LWDAQ Client now re-sets its timeout variable every time it receives a new fragment of data from the LWDAQ Server. We now have only one TCP timeout variable, tcp_timeout_ms, which is by default set to 10000 (ten seconds). The result is better performance over slow networks with small data blocks and over fast networks with large data blocks.