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.

This page provides details of the internal operation of the adutux driver.

Some characteristics of the ADU devices are described. These details are not necessary to use the adutux driver.

Maybe someone will use the hardware descriptions to build a better driver.

ADU USB Interface Chip

The ADU200 uses a Microchip PIC16C745 processor. (The datasheet is available on the Microchip web site.)

The Microchip PIC16C745 supports only Control and Interrupt end-points. No bulk end-points are available.

The ADU board uses the Control end-points solely for USB chapter 9 control purposes. (see usb.org for the USB specification). All ADU specific communication is transmitted via Interrupt end-points.

Commands to the ADU board are written on the Interrupt Out end-point.
Responses from the ADU board are read on the Interrupt In end-point.

Interrupt Out End-points and Linux

The Interrupt Out end-point was added to the USB specification in Version 1.1. The original 1.0 USB spec defined only Interrupt In end-points.

Most low speed USB devices use Control or Bulk end-points to send data to the peripheral USB device. Accordingly the Linux USB driver core did not make allowance for Interrupt Out end-points. As of this writing (07-Nov-2003) there is no generic Interrupt Out support in the kernel (version 2.6.0-test9). Ergo the adutux driver was created.

The Linux 2.6 kernel lists non-standard Human Interface Devices (HID) in the source file drivers/usb/input/hid-core.c (look for the hid_blacklist). The Ontrak ADU devices appear in the black list because they do not behave like standard HID devices. The ADU behaviour is not wrong, just unusual. The ADU devices conform to the USB specification in a unique way preventing us from using the canned HID drivers.

Device File System

An application finds the ADU device through the file system entries /dev/usb/adutuxN (where N=0, 1, 2, ...)

Because the adutux driver was not accepted into the kernel tree no official minor device number was assigned. The pre-compiled binary uses minor device numbers 179 thru 188.

APIs

The application program uses a standard file interface to communicate with the adutux driver.
open - open a handle to /dev/usb/adutuxN write - writes a command to the ADU device read - reads a response from the ADU device close - close the handle

ADU Message Formats

The ADU board uses the report feature of the USB specification. The first byte in each packet identifies the report. The report id is followed by 7 bytes of data. The ADU board always sends and receives packets that are 8 bytes long.
Report Types 1 - Command Packet 2 - RS232 Packet 3 - Streaming Packet s - requests the serial number from the driver (no physical I/O)

The Microsoft Windows HID driver separates the packets by report id. A Microsoft Windows application opens a file for each report id. Only packets for the selected report id are read through the file descriptor. Ontrak calls these "Pipes". (see the documentation at the Ontrak Control Systems web site).

Linux does not read the Chapter 9 report descriptors that the ADU device contains. (I used a sniffer on the USB cable to verify this). Under Linux all report ids are handled through the same file descriptor. A Linux application must inspect the first data byte to determine the report id of the packet.

Aside: Well the adutux driver _COULD_ separate the packets by report id but only at considerable complication.

ADU USB Chapter 9 Values

Vendor Id = hex 0a07 = Ontrak Control Systems Inc.
Device Id = hex 00c8 = ADU200

Race Conditions

I am sure that some of these exist, however I have only uni-processor systems so they have not become an issue.... for me.... at least not yet.
Feel free to debug any race conditions that you may find.

Limited Binaries

This driver is distributed in source code so that you can build it into your own kernel. Occasionally some binaries for popular distributions may be posted here, but there is no committment to binary releases.