SDK Home
Installation
Application Programming Guide
Internal Details
Licensing

Use at own risk

Use this program at your own risk. No warranty express or implied even as to merchantability. This driver is not supported by Ontrak Control Systems.
This is an experimental driver. Assume that this driver is seriously broken. You are responsible for testing it in your environment.

What is this?

This document describes the application programming interface for the adutux driver.

The examples are all based on the C programming language.

Introduction

The adutux driver operates as a thin layer between the application program and the Linux USB core drivers. It was designed to maximize the utilization of previously implemented (and tested) functionality in Linux.

Once the path to the ADU device has been determined an application uses a standard "open" call to open a file handle to the device.

The application issues standard read and write calls to the device.

The file handle is closed with a standard "close" call.

Packet Formats

All communication with the ADU device is via packets that are 8 bytes long. Short packets are padded out to 8 bytes by the adutux driver.

The first byte of a packet is the report id. It is a hold-over from the Microsoft Windows driver and serves little purpose in Linux. However the ADU firmware requires its presence.

The report id is a binary 1 byte field with a value of 1, 2 or 3. (ie. 0x01, 0x02 or 0x03).

Report Id
1 - Command
2 - RS232
3 - Streaming
s - serial number request

Commands to the ADU device must be prefixed with a report id of 1.
Responses to the commands (if generated) are returned with a report id of 1.

Data to be sent to the RS232 connector must be prefixed with a report id of 2.
Responses from the RS232 connector are returned with a report id of 2.

Data that is being streamed from the ADU device is returned with a report id of 3.
Note: Only selected ADU devices support RS232 ports or streaming of data.

The remaining 7 bytes of a packet are data. The adutux driver treats the data as an opaque block of 7 bytes. The content of the data varies depending upon the model of ADU device. (As of this writing ADU100, ADU200 and ADUMED devices have been tested).

A report id of 's' is a request for the serial number of the ADU device. The adutux driver returns the serial number so that an application can differentiate between multiple ADU devices. During device enumeration an ADU device may appear at different locations in the file tree. (eg /dev/usb/adutux1 instead of /dev/usb/adutux0).

Opening the ADU Device

The sBus and sDevice names are used to create the pathname into the usbfs file system. A file handle is opened to the ADU device using the standard open call of the usbfs file system.

        fd = open("/dev/usb/adutux0", O_RDWR);

Getting the Serial Number

The serial number is useful when multiple ADU devices of the same product id are attached to one computer. It allows the progam to differentiate between the devices.

        char sString[8];
	memset(sString, 0, 8);
	sString[0] = 's';
	status = read(fd, sString, 8);

The character 's' in the first position identifies the read as a request for the serial number. After the read operation the sString field will contain the serial number.

Writing to the ADU Device

A message to the ADU device consists of a 1 byte report id followed by 7 bytes of data. This example shows the command "rpk" being sent to the ADU device.

        int iPipe;
	char sCommand[8];
	char sString[8];
        memset(sString, 0, 8);
        iPipe = 1;
        strcpy(sCommand, "rpk");
	sprintf(sString, "%c%s", iPipe, sCommand);
	status = write(fd, sString, 8);

Reading from the ADU Device

Information is transmitted from the ADU device in 8 byte chunks (1 byte for the report id and 7 bytes of data).

	char sString[8];
	memset(sString, 0, 8);
	status = read(fd, sString, 8);

The 8 bytes retrieved from the ADU are found in sString.

Closing the ADU Device

A standard close function is used the close the file handle.

        close(fd);

Buffers

The adutux driver has no I/O buffers. It relies on the buffers provided by the Linux core USB functions. There appear to be three buffers per device in the USB core. Once they are full the adutux driver cannot write any more until a read operation clears a buffer.

The best approach is to read the response immediately after writing a query command. ie write an "rpk" command and then read the result before writing another command to the ADU.

Murphy's Contribution

Error Code
13 Permission denied - ensure that the user has adequate permissions in the /proc/bus/usb/nnn/ddd tree
38 Function not implemented - ensure that the driver has been loaded (ie use /sbin/insmod).
110 Timeout - Write operation failed. - Make sure that the buffers are not full. Try reading to clear the buffer contents.
110 Timeout - Read operation failed. - Make sure that the application has requested data from the ADU. The ADU will not send data to the host computer unless requested. ie write an "rpk" command before trying to read.

Sample Application - A simple command line application that demonstrates the adutux driver.