USBTMC Kernel Driver Documentation

Contents

Copyright Notice
Versions
Introduction
Driver Installation
Using the Driver
Reference: usbtmc_ioctl
Reference: I/O Programming Using the USBTMC Driver
Reference: Attributes
Reference: usbtmc_load
Driver Limitations
Example Programs
Feedback
GNU Free Documentation License

Copyright Notice

Copyright (c) 2007 Stefan Kopp, Gechingen, Germany

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Back to Contents

Versions

1.0 / 03.12.2007 / Initial version.
1.1 / 08.12.2007 / Minor changes and clarifications.

Back to Contents

Introduction

About the driver

The prevalent approach to writing test automation software (especially under Windows) is to use VISA, a vendor-independent library and API for T&M I/O programming. Several commercial VISA implementations are available for Windows (e. g. from Agilent, see http://www.agilent.com/find/iolib) and Linux (e. g. from TAMS, see http://www.tamsinc.com/). For more details about VISA, see http://ivifoundation.org/.

Commercial VISA implementations are shipped in binary format. The drawback with that approach is that the supplier needs to make a choice with regards to distributions supported. Usually, only a very limited number of distributions and kernel versions is supported. Consequently, if you are using a less common distribution (or if you desire portability) you might decide to refrain from using a commercial VISA implementation and do your I/O programming using direct system calls.

While TCP/IP programming is relatively straightforward, controlling USB-based instruments is a bit more challenging. It usually requires creating a kernel driver that controls your USB instruments through the kernel's USB core services layer.

This document describes a free, open-source driver for USBTMC instruments, licensed under the GNU GPL. Being available in source code format, the driver can be compiled under (or ported to) any given distribution.

About USBTMC

USBTMC, introduced in 2002, is a vendor-independent standard for programmatic control of USB-based test instruments. The standard defines protocols that are used to send instrument command messages to an instrument and read back response messages. It does not define the instrument messages themselves.

Most USB-based instruments available today adhere to the USBTMC standard. Furthermore, most are programmed via SCPI or similar text messages, very similar (often identical) to what you would expect from a GPIB instrument.

For details about USBTMC, see http://www.usb.org/developers/devclass_docs#approved.

About the driver architecture

The classic method of implementation for text-based I/O on UNIX and Linux is through a character device driver. A character device file allows the end user to use basic file I/O mechanisms to communicate with the instrument or device behind the driver. In other words, no special API is needed to communicate with the device.

The USBTMC driver described in this document is a character device driver for USBTMC instruments. It uses the special file names /dev/usbtmc0 through /dev/usbtmc16 (or higher). /dev/usbtmc0 is reserved for communication with the driver itself (e. g. to read driver configuration data). /dev/usbtmc1 is used for the first USBTMC instrument attached, /dev/usbtmc2 is the second instrument, and so on.

Using a character device model as a window to the user offers several key benefits:

Use models

There are two obvious use models for the driver.

In the interactive (shell) use model, you communicate with your instrument directly by redirecting the standard input/output to/from the corresponding device file. For example, you can typically reset an instrument by sending a *RST command. You can use echo and output redirection to send that command to your instrument:

echo *RST>/dev/usbtmc1

Note that echo will also add a \n (newline) character (which is required by most instruments).

Similarly, you can read an instrument response using the cat command. For example, the following commands query an instrument's ID string:

echo *IDN?>/dev/usbtmc1
cat /dev/usbtmc1

In the programmatic use model, you will use system calls such as open(2), read(2), write(2), close(2) and ioctl(2) to communicate with the instrument from your automated test application. For example, you could reset your instrument using the following C statements:

int my_inst;
my_inst=open(“/dev/usbtmc1”,O_RDWR);
write(my_inst,”*RST\n”,5);
close(my_inst);

Back to Contents

Driver Installation

The driver is available from Agilent's web site at http://www.agilent.com/find/linux.

Copy the driver's TAR archive (usbtmc.tar) to an empty directory, change to that directory and extract the files using:

tar -x usbtmc.tar

This will extract a number of files in the directory, including the driver source files and a makefile. Compile the driver using that makefile:

make

Note: As a prerequisite, you need the kernel sources directory tree to be installed on your system. It is usually available on your distribution's media but often not installed by default. Look for a package named kernel-source.

make will create a kernel object file, usbtmc.ko. This kernel module can be installed dynamically (in the running kernel) using the insmod(8) command (with root privilege):

insmod ./usbtmc.ko

Next, the device files under /dev need to be created. You can do that manually if you prefer, but the usbtmc_load script does it for you. Run it as follows:

./usbtmc_load

If you don't need the driver anymore, you can unload it from the running kernel with the rmmod(8) command:

rmmod usbtmc

There is an additional utility named usbtmc_ioctl for special instrument operations such as device clear (see below for more information). Compile is using the command:

gcc usbtmc_ioctl.c -o usbtmc_ioctl

Back to Contents

Using the Driver

Finding out which devices are attached

After installation via insmod(8), the driver registers with the kernel's USB core services. The USB core, in turn, will notify the driver of any USBTMC-compatible devices attached to the system. The driver is notified in the order in which the instruments are connected to the system. If several devices are connected simultaneously (or if they are already attached when loading the USBTMC driver), the order of notification is unknown. Consequently, as a first step, you need to be able to find out which devices are attached and which special files they are using. This information is available by reading from /dev/usbtmc0 (special file 0 is reserved for communication with the driver itself). For example:

cat /dev/usbtmc0
Minor Number Manufacturer Product Serial Number
001 Agilent Technologies 34411A Digital Multimeter MY45000181
002 Agilent Technologies 33220A Function Generator MY12345678

In this example, the Agilent 34411A multimeter is shown as being the first device attached (using minor number 1), so communication with this device is done through /dev/usbtmc1. Note that the individual fields shown are separated by \t (tab) characters.

Special operations: ioctl(2) or usbtmc_ioctl

As mentioned earlier, message-based I/O with the instruments is possible through the echo and cat shell commands (or through system calls for file I/O). However, some I/O operations go beyond basic message I/O, such as reset, instrument clear etc. Such special operations can be invoked from C via the ioctl(2) system call. In the shell, the usbtmc_ioctl utility can be used to call the driver's ioctl entry point. For example, the following command clears the instrument behind /dev/usbtmc1 (to be more exact, its input and output buffers):

usbtmc_ioctl 1 clear

read(2) and fread(2)

Here's another aspect you need to be aware of. The kernel offers two sets of system calls for file I/O, and their behavior is slightly different, especially when it comes to reading data. The read(2) system call requests a given maximum number of bytes from the file (instrument), but it is happy if the call returns less than the maximum number. The fread(2) system call, on the other hand, has the habit of retrying until the total number requested bytes is reached (or until the call returns 0 bytes, which indicates the end of the file). This works well for real files, but it doesn't work well for instruments because the second read transaction will usually cause a timeout.

If you use C or another language that gives you the choice, it is recommended to use read(2) etc. instead of fread(2) etc. However, if you use echo/cat and shell output redirection, the shell will use fread(2). In order to avoid the issues associated with automatic retries, the driver simply ignores every second call to its read entry point (assuming that call is a retry) unless the first call returned the maximum number of bytes requested (in which case there is no retry).

It is important to note that if you are using read(2) – which is recommended – you need to deactivate the driver's default behavior of ignoring every second call to its read entry point! This can be done by setting a driver attribute through a call to the driver's ioctl entry point:

int my_inst;
struct usbtmc_attribute attr;
my_inst=open(“/dev/usbtmc1”,O_RDWR);
attr.attribute=USBTMC_ATTRIB_READ_MODE;
attr.value=USBTMC_ATTRIB_VAL_READ; // using read, not fread
ioctl(my_inst,USBTMC_IOCTL_SET_ATTRIBUTE,&attr);

See Reference: Attributes for details about this and other driver attributes.

Back to Contents

Reference: usbtmc_ioctl

Use usbtmc_ioctl to make calls to the driver's ioctl entry point. If you are using C or another language that can call ioctl(2) directly, do that. usbtmc_ioctl is useful when controlling instruments from the shell or if your language can't do direct ioctl(2) calls.

Usage:

usbtmc_ioctl m request [ attribute [ value ] ]

where
m = minor number, e. g. 1 for /dev/usbtmc1
request = { clear , getcaps , indpulse , abortout , abortin , setattr , clearouthalt , clearinhalt , getattr , reset }
attribute = { autoabort , readmode , timeout , numinst , numminor , buffsize , deftimeout , debug , version , termcharenab , termchar , addnlread , remnlwrite }

Requests:

clear: Device clear (clears the instrument's input and output buffer)
getcaps: Prints the device's capability values.
indpulse: Flashes the device's activity indicator (for identification purposes).
abortout: Aborts the last output (write) operation.
abortin: Aborts the last input (read) operation.
setattr: Sets a driver attribute. Requires additional parameters for name and value of attribute to be set.
clearouthalt: Clears a halt condition on the BULK OUT endpoint.
clearinhalt: Clears a halt condition on the BULK IN endpoint.
getattr: Reads a driver attribute. Requires additional parameter for name of attribute to be read.
reset: Resets the USB configuration.

Attributes:

autoabort: If active (on), aborts the last read or write transaction automatically when an I/O error occurs.
Possible values: { on , off }.
readmode: If set to fread, causes the driver to ignore a subsequent call to its read entry point – see above for background information.
Possible values: { fread , read }.
timeout: Sets or reads the timeout value for USB transactions. Timeout value is in ms. Use 0 for no timeout.
numinst: Read-only. Returns the number of instruments currently serviced by the USBTMC driver.
numminor: Read-only. Returns the number of instruments the driver can service at the same time.
buffsize: Read-only. Returns the size of the driver-internal I/O buffer.
deftimeout: Read-only. Returns the default timeout value.
debug: Read-only. Returns the state of the debug mode.
version: Read-only. Returns an integer representation of the driver version.
termcharenab: Enables or disables automatic termination of read operations if the instrument data stream contains a certain termination character.
Possible values: { on , off }.
termchar: Termination character to be used of automatic termination of read operations is enabled.
Possible values: An integer between 0 and 255, representing the character's ASCII value.
addnlread: If active (on), the driver will add a newline character to the instrument's response string. This is mainly for use through the shell because cat assumes that the response is terminated by a newline character.
Possible values: { on , off }.
remnlwrite: If active (on), the driver will remove the newline character at the end of the command message. This is mainly for use through the shell because echo automatically adds a newline character.

Most calls just require two parameters (instrument number and request). Here are some examples:

usbtmc_ioctl 1 clear

Clears the instrument's input and output buffers. Use this to reset the instrument to a known state, e.g. after an error condition. This is comparable to a GPIB device clear.

usbtmc_ioctl 1 abortin

Use this to abort the last read operation after a read timeout has occurred.

usbtmc_ioctl 1 reset

Sends a request to the USB core services to reset the device's USB configuration. This will not reset the device itself (as a *RST command does), but it might help recover from low-level USB issues by resetting some of the USB core data structures associated with the device.

The setattr (set attribute) request requires two additional parameters (name and value of the attribute to be set). For example:

usbtmc_ioctl 1 setattr readmode read

This instructs the driver not to ignore subsequent calls to its read entry point. See Using the Driver for background information.

Back to Contents

Reference: I/O Programming Using the USBTMC Driver

Include the driver's header file at the beginning of your program:

#include “usbtmc.h”

The following code demonstrates a basic example of message-based I/O. Note that, first of all, the attribute USBTMC_ATTRIB_READ_MODE is set to USBTMC_ATTRIB_VAL_READ because we are using read(2), not fread(2). Always use read(2) instead of fread(2) if you have the choice – see Using the Driver for background information.

int myfile;
char buffer[4000];
int actual;
int retval;
int en;
struct usbtmc_attribute attr;

myfile=open("/dev/usbtmc1",O_RDWR);
attr.attribute=USBTMC_ATTRIB_READ_MODE;
attr.value=USBTMC_ATTRIB_VAL_READ;
ioctl(myfile,USBTMC_IOCTL_SET_ATTRIBUTE,&attr);

retval=write(myfile,"*IDN?\n",6);
if(retval==-1) {
en=errno;
printf("Error during write: %s\n",strerror(en));
}
actual=read(myfile,buffer,4000);
if(actual==-1) {
en=errno;
printf("Error during read: %s\n",strerror(en));
}
else {
buffer[actual]=0;
printf("ID: %s\n",buffer);
}
close(myfile);

The following code example shows how to handle a read timeout by aborting the last read transaction.

ioctl(myfile,USBTMC_IOCTL_ABORT_BULK_IN,0);

Similarly, the following line would abort the last output operation.

ioctl(myfile,USBTMC_IOCTL_ABORT_BULK_OUT,0);

The following code demonstrates how you can find out which devices are attached. You can also read that information from /dev/usbtmc0, but the ioctl(2) call shown below fills a C structure which is easier to process in C, compared to a text buffer. Before calling ioctl(2), you need to set the minor_number field to the instrument number you want to read the details for.

struct usbtmc_instrument inst;
inst.minor_number=1;
if(ioctl(myfile,USBTMC_IOCTL_INSTRUMENT_DATA,&inst)!=-1) {
printf("MANUFACTURER: %s\n",inst.manufacturer);
printf("PRODUCT: %s\n",inst.product);
printf("S/N: %s\n",inst.serial_number);
}

Note that ioctl will return -1 if the given minor number is not in use.

ioctl(2): Special operations

As show in the above examples, ioctl(2) is used for special operations (everything that goes beyond text-based communication). The second parameter to ioctl(2) is a request code which indicates what kind of special operation you want the driver to perform. Valid request codes are defined in usbtmc.h. They are:

USBTMC_IOCTL_GET_CAPABILITIES

This request is used to get information about the device's capabilities. In this case, the third parameter to ioctl(2) is a pointer to a structure of type struct usbtmc_dev_capabilities (defined in usbtmc.h). This structure is filled by ioctl. See usbtmc.h and the USBTMC specification for details.

USBTMC_IOCTL_INDICATOR_PULSE

This request asks the device to light its activity indicator for identification purposes. This is an optional capability and may not be available with your device. Inspect the device's capability values when in doubt. In this case, the third parameter to ioctl(2) is not used.

USBTMC_IOCTL_CLEAR

This request is used to clear the device's input and output buffers. It is roughly equivalent to a GPIB device clear. In this case, the third parameter to ioctl(2) is not used.

USBTMC_IOCTL_ABORT_BULK_OUT

This requests aborts the last USBTMC BULK OUT operation, i.e. the last write operation to the device's command buffer. It is used to recover from I/O errors that occur during a write operation. Note that you can instruct the driver to do the abort automatically if an I/O error occurs. See Reference: Attributes for details. In this case, the third parameter to ioctl(2) is not used.

USBTMC_IOCTL_ABORT_BULK_IN

This request aborts the last USBTMC BULK IN operation, i.e. the last read operation from the device's output buffer. It is used to recover from I/O errors (such as a timeout) that occur during a read operation. Note that you can instruct the driver to do the abort automatically if an I/O error occurs. See Reference: Attributes for details. In this case, the third parameter to ioctl(2) is not used.

USBTMC_IOCTL_SET_ATTRIBUTE

This request is used to set a driver attribute (see Reference: Attributes). In this case, the third parameter to ioctl(2) is a pointer to a structure of type struct usbtmc_attribute (defined in usbtmc.h). This structure needs to be filled with the attribute code and the desired value before calling ioctl(2). Valid attribute codes are defined in usbtmc.h.

USBTMC_IOCTL_CLEAR_OUT_HALT

This request is used to clear a halt condition on the device's BULK OUT endpoint. In most situations, you should rather use USBTMC_IOCTL_ABORT_BULK_OUT since that request clears the command buffer and the halt condition. See the USBTMC specification for details. In this case, the third parameter to ioctl(2) is not used.

USBTMC_IOCTL_CLEAR_IN_HALT

This request is used to clear a halt condition on the device's BULK IN endpoint. In most situations, you should rather use USBTMC_IOCTL_ABORT_BULK_IN since that request clears the output buffer and the halt condition. See the USBTMC specification for details. In this case, the third parameter to ioctl(2) is not used.

USBTMC_IOCTL_GET_ATTRIBUTE

This request is used to read a driver attribute (see Reference: Attributes). In this case, the third parameter to ioctl(2) is a pointer to a structure of type struct usbtmc_attribute (defined in usbtmc.h). This structure needs to be filled with the attribute code before calling ioctl(2). After the call returns, you can read the attribute value from the structure. Valid attribute codes are defined in usbtmc.h.

USBTMC_IOCTL_INSTRUMENT_DATA

This request is used to read information about the devices currently being serviced by the USBTMC driver. In this case, the third parameter to ioctl(2) is a pointer to a structure of type struct usbtmc_instrument (defined in usbtmc.h). Set the minor number field to the number of the device you are interested in (e. g. 1 for /dev/usbtmc1 or minor number 1). After the call returns, the structure is filled with the device's manufacturer, product and serial number string. Note that this call will return -1 if the minor number given is not in use.

USBTMC_IOCTL_RESET_CONF

This request instructs the USB core to reset the device's USB configuration. This doesn't send any command messages to the instrument (such as a *RST). Rather, it reinitializes the USB core data structures for the device. Normally, you should not have to use this request unless something is really wrong...

See Example Programs for further programming examples.

Back to Contents

Reference: Attributes

Driver attributes are used to modify the behavior of the driver (e. g. to a activate optional functionality). The attributes are set/read using ioctl(2) or through the usbtmc_ioctl command line utility (see above). The following attributes are available:

USBTMC_ATTRIB_AUTO_ABORT_ON_ERROR

Defines if the driver should automatically abort the last read/write USBTMC operation if an I/O error (e. g. timeout) occurs. You should always abort the last USBTMC operation if an error occurs. You can chose to do the abort automatically or you can do it explicitly via ioctl(2) or the usbtmc_ioctl command line utility. Especially if you are using the driver from the shell (using echo/cat) you might want to use the automatic abort. This setting is local to the current device.
Values: { USBTMC_ATTRIB_VAL_ON (abort automatically) , USBTMC_ATTRIB_VAL_OFF (handle I/O errors manually) }. Default value: USBTMC_ATTRIB_VAL_ON

USBTMC_ATTRIB_READ_MODE

Defines if the driver should ignore subsequent calls to its read entry point. This should be set to USBTMC_ATTRIB_VAL_FREAD if you are using fread(2) or if you are using echo and output redirection (i.e. using fread(2) behind the scenes). fread(2) retries the read operation until the driver returns the number of bytes requested (or until it returns 0 for EOF). The retries would cause a timeout with instruments, so the driver simply returns 0 (EOF) when called for the second time. Set the attribute to USBTMC_ATTRIB_VAL_READ if you are using read(2). The setting is local to the current device.
Values: { USBTMC_ATTRIB_VAL_FREAD (ignore second call to read entry point) , USBTMC_ATTRIB_VAL_READ (handle every call) }. Default value: USBTMC_ATTRIB_VAL_FREAD

USBTMC_ATTRIB_TIMEOUT

Timeout value for USB I/O operations. The value is local to the current device.
Value specified in ms. 0 means no timeout but should not be used in order to avoid driver hangs (use a larger timeout value instead). Default value: 10s.

USBTMC_ATTRIB_NUM_INSTRUMENTS

This is a read-only attribute and returns the number of USB instruments currently being serviced by the USBTMC driver. You can read this value in order to verify that your instruments are attached properly or when automatically detecting the attached instruments. You can modify this value by changing the corresponding #define in usbtmc.h and recompiling the driver.

USBTMC_ATTRIB_MINOR_NUMBERS

This is a read-only attribute that returns the maximum number of USB instruments the driver can service at the same time. You can modify this value by changing the corresponding #define in usbtmc.h and recompiling the driver.

USBTMC_ATTRIB_SIZE_IO_BUFFER

This is a read-only attribute that returns the size of the driver-internal I/O buffer (in bytes). Note that you can do larger transfers since the driver will split large transactions into several smaller ones. You can modify this value by changing the corresponding #define in usbtmc.h and recompiling the driver.

USBTMC_ATTRIB_DEFAULT_TIMEOUT

This is a read-only attribute that returns the default timeout value (in ms). This timeout value will be used unless you change an individual instrument's timeout value by setting the attribute USBTMC_ATTRIB_TIMEOUT. You can modify this value by changing the corresponding #define in usbtmc.h and recompiling the driver.

USBTMC_ATTRIB_DEBUG_MODE

This is a read-only attribute that returns a number indicating if the debug mode of the driver is active. If set to USBTMC_ATTRIB_VAL_ON, the driver will log debugging messages to the kernel log.
Values: { USBTMC_ATTRIB_VAL_ON (logging debug messages) , USBTMC_ATTRIB_VAL_OFF (not logging debug messages) }. You can modify this value by changing the corresponding #define in usbtmc.h and recompiling the driver.

USBTMC_ATTRIB_VERSION

This is a read-only attribute that returns an integer representation of the driver version (e. g. 101 for version 1.0.1). This allows your software to verify if it is running with the driver version it has been tested with. See the corresponding #define in usbtmc.h.

USBTMC_ATTRIB_TERM_CHAR_ENABLED

This attribute tells the driver to use the termination character feature, i. e. to terminate a read operation automatically if a given termination character is encountered in the device's output buffer. Note that not all instruments support this feature. Inspect the device's capabilities via ioctl(2) or the usbmc_ioctl command line utility if you are not sure about your device's features.

USBTMC_ATTRIB_TERM_CHAR

This attribute sets the termination character to be used if the termination character mode is enabled. Note that not all instruments support this feature. Inspect the device's capabilities via ioctl(2) or the usbmc_ioctl command line utility if you are not sure about your device's features.
Value: Any 8 bit character value. Default: '\n' (newline).

USBTMC_ATTRIB_ADD_NL_ON_READ

This attribute instructs the driver to append a newline character when reading data from the instrument. You will typically activate this feature if you have an instrument that does not terminate it's response with a newline character (as most instruments do) and when you are using the driver from the shell (using echo/cat). cat will not work properly unless the instrument response ends with a newline character.
Values: { USBTMC_ATTRIB_VAL_ON (add newline character) , USBTMC_ATTRIB_VAL_OFF (leave response as is) }. Default value: USBTMC_ATTRIB_VAL_OFF

USBTMC_ATTRIB_REM_NL_ON_WRITE

This attribute instructs the driver to remove the newline character at the end of the instrument command message. If you are using the driver from the shell (i. e. you are sending data via echo and output redirection), a newline character will be appended to the instrument command automatically. Most instruments expect that, anyway. However, if your instrument doesn't want to see a newline character in the command string, activate this feature to remove the newline character.
Values: { USBTMC_ATTRIB_VAL_ON (remove newline character) , USBTMC_ATTRIB_VAL_OFF (leave command string as is) }. Default value: USBTMC_ATTRIB_VAL_OFF

Back to Contents

Reference: usbtmc_load

The usbtmc_load shell script automates the steps of loading the USBTMC driver kernel module and creating the device files.

Note that the major number used by the driver is allocated dynamically in the driver initialization routine. Install the driver first, then find the major number and create the device files using that major number. The easiest way to find the major number is to inspect the output of cat /proc/devices. Another option is to inspect the kernel log, since the driver logs a kernel message with the major number.

usbtmc_load shell script

#!/bin/sh

module="usbtmc"

# Remove module from kernel (just in case it is still running)
/sbin/rmmod $module

# Install module
/sbin/insmod ./$module.ko

# Find major number used
major=$(cat /proc/devices | grep USBTMCCHR | awk '{print $1}')
echo Using major number $major

# Remove old device files
rm -f /dev/${module}[0-9]

# Ceate new device files
mknod /dev/${module}0 c $major 0
mknod /dev/${module}1 c $major 1
mknod /dev/${module}2 c $major 2
mknod /dev/${module}3 c $major 3
mknod /dev/${module}4 c $major 4
mknod /dev/${module}5 c $major 5
mknod /dev/${module}6 c $major 6
mknod /dev/${module}7 c $major 7
mknod /dev/${module}8 c $major 8
mknod /dev/${module}9 c $major 9

# Change access mode
chmod 666 /dev/${module}0
chmod 666 /dev/${module}1
chmod 666 /dev/${module}2
chmod 666 /dev/${module}3
chmod 666 /dev/${module}4
chmod 666 /dev/${module}5
chmod 666 /dev/${module}6
chmod 666 /dev/${module}7
chmod 666 /dev/${module}8
chmod 666 /dev/${module}9

Back to Contents

Driver Limitations

The USBTMC driver has been written and tested under openSUSE 10.2. It should compile and run without changes on most actual distributions.

If the driver doesn't perform as expected, make sure the line
#define USBTMC_DEBUG
is active at the beginning of the usbtmc.c file. This define will tell the driver to log status messages in the kernel log. This information might be helpful in understanding the driver's behaviour.

Known limitations

Back to Contents

Example Programs

The following program is an example of basic instrument I/O.

int myfile;
char buffer[4000];
int actual;
int retval;
int en;
struct usbtmc_instrument inst;
struct usbtmc_attribute attr;

myfile=open("/dev/usbtmc1",O_RDWR); // Open instrument #1 for reading and writing
if(myfile==-1) exit(1);

// Tell the driver we are using read(2), not fread(2)
attr.attribute=USBTMC_ATTRIB_READ_MODE;
attr.value=USBTMC_ATTRIB_VAL_READ;
ioctl(myfile,USBTMC_IOCTL_SET_ATTRIBUTE,&attr);

attr.attribute=USBTMC_ATTRIB_NUM_INSTRUMENTS;
ioctl(myfile,USBTMC_IOCTL_GET_ATTRIBUTE,&attr);
printf("Number of instruments active: %d\n",attr.value);

retval=write(myfile,"*IDN?\n",6); // Send *IDN? command
if(retval==-1) {
en=errno;
printf("Error during write: %s\n",strerror(en));
}
actual=read(myfile,buffer,4000); // Read response
if(actual==-1) {
en=errno;
printf("Error during read: %s\n",strerror(en));
}
else {
buffer[actual]=0;
printf("ID: %s\n",buffer);
}

// Get info about instrument #1
inst.minor_number=1;
if(ioctl(myfile,USBTMC_IOCTL_INSTRUMENT_DATA,&inst)!=-1) {
printf("MANUFACTURER: %s\n",inst.manufacturer);
printf("PRODUCT: %s\n",inst.product);
printf("S/N: %s\n",inst.serial_number);
}

// Demonstrate timeout handling
actual=read(myfile,buffer,4000); // Provoke timeout
if(actual==-1) {
en=errno;
printf("Error during read: %s\n",strerror(en));
printf("Recover from timeout using ABORT_BULK_IN\n");
ioctl(myfile,USBTMC_IOCTL_ABORT_BULK_IN,0);
}

close(myfile); // Done using the instrument

Back to Contents

Feedback

This driver is provided as is, without any kind of warranty or support. Nevertheless, we hope that the driver is useful and we are interested in your feedback. Feel free to contact us with your enhancement ideas and problem reports (or just to tell us how you are using this driver).

To contact us, send an email to: stefan_kopp@agilent.com

Back to Contents

GNU Free Documentation License

GNU Free Documentation License

Version 1.2, November 2002

Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Back to Contents