3 Software

Top

3.1 Compatibility

Overview

The Aardvark software is offered as a 32-bit or 64-bit Dynamic Linked Library (or shared object). The specific compatibility for each operating system is discussed below. Be sure the device driver has been installed before plugging in the Aardvark adapter.

Windows Compatibility

The Aardvark software is compatible with Windows XP (SP2 or later, 32-bit and 64-bit), Windows Vista (32-bit and 64-bit), and Windows 7 (32-bit and 64-bit). Windows 2000 and legacy 16-bit Windows 95/98/ME operating systems are not supported.

Linux Compatibility

The Aardvark software is compatible with all standard 32-bit and 64-bit distributions of Linux with kernel 2.6 and integrated USB support. When using the 32-bit library on a 64-bit distribution, the appropriate 32-bit system libraries are also required.

Mac OS X Compatibility

The Aardvark software is compatible with Intel versions of Mac OS X 10.4 Tiger, 10.5 Leopard, and 10.6 Snow Leopard. Installation of the latest available update is recommended.

Top

3.2 Windows USB Driver

Driver Installation

As of version 3.0, the Aardvark communications layer under Windows no longer uses a virtual serial port driver. The switch to a more direct USB driver should improve the installation and performance of PC and Aardvark adapter communication.

To install the appropriate USB communication driver under Windows, use the Total Phase USB Driver Installer before plugging in any device. The driver installer can be found either on the CD-ROM (use the HTML based guide that is opened when the CD is first loaded to locate the Windows installer), or in the Downloads section of the Aardvark adapter product page on the Total Phase website.

After the driver has been installed, plugging in an Aardvark adapter for the first time will cause the adapter to be installed and associated with the correct driver. The following steps describe the feedback the user should receive from Windows after an Aardvark adapter is plugged into a system for the first time:

Windows 2000:

1. The Found New Hardware dialog window will appear during installation and will disappear when the installation completes.

Windows XP:

1. The Found New Hardware notification bubble will pop up from the system tray and state that the “Total Phase Aardvark I2C/SPI Host Adapter” has been detected.

2. When the installation is complete, the Found New Hardware notification bubble will again pop up and state that “your new hardware is installed and ready to use.”

Windows Vista:

1. A notification bubble will pop up from the system tray and state that Windows is “installing device driver software.”

2. When the installation is complete, the notification bubble will again pop up and state that the “device driver software installed successfully.”

To confirm that the device was correctly installed, check that the device appears in the “Device Manager.” To navigate to the “Device Manager” screen, select “Control Panel | System Properties | Hardware | Device Manager” for Windows 2000/XP or select “Control Panel | Hardware and Sound | Device Manager” for Windows Vista. The Aardvark device should appear under the “Universal Serial Bus Controllers” section.

Driver Removal

The USB communication driver can be removed from the operating system by using the Windows program removal utility. Instructions for using this utility can be found below. Alternatively, the Uninstall option found in the driver installer can also be used to remove the driver from the system. It is critical that all Total Phase devices have been removed from your system before removing the USB drivers.

Windows 2000/XP:

1. Select “Control Panel | Add or Remove Programs”

2. Select “Total Phase USB Driver” and select “Change/Remove”

3. Follow the instructions in the uninstaller

Windows Vista:

1. Select “Control Panel | Uninstall a program”

2. Right click on “Total Phase USB Driver” and select “Uninstall/Change”

3. Follow the instructions in the uninstaller

Top

3.3 Linux USB Driver

As of version 3.0, the Aardvark communications layer under Linux no longer requires a specific kernel driver to operate. However, the user must ensure independently that the libusb library is installed on the system since the Aardvark library is dynamically linked to libusb.

Most modern Linux distributions use the udev subsystem to help manipulate the permissions of various system devices. This is the preferred way to support access to the Aardvark adapter such that the device is accessible by all of the users on the system upon device plug-in.

For legacy systems, there are two different ways to access the Aardvark adapter, through USB hotplug or by mounting the entire USB filesystem as world writable. Both require that /proc/bus/usb is mounted on the system which is the case on most standard distributions.

UDEV

Support for udev requires a single configuration file that is available on the software CD, and also listed on the Total Phase website for download. This file is 99-totalphase.rules. Please follow the following steps to enable the appropriate permissions for the Aardvark adapter.

1. As superuser, unpack 99-totalphase.rules to /etc/udev/rules.d

2. chmod 644 /etc/udev/rules.d/99-totalphase.rules

3. Unplug and replug your Aardvark adapter(s)

USB Hotplug

USB hotplug requires two configuration files which are available on the software CD, and also listed on the Total Phase website for download. These files are: aardvark and aardvark.usermap. Please follow the following steps to enable hotplugging.

1. As superuser, unpack aardvark and aardvark.usermap to /etc/hotplug/usb

2. chmod 755 /etc/hotplug/usb/aardvark

3. chmod 644 /etc/hotplug/usb/aardvark.usermap

4. Unplug and replug your Aardvark adapter(s)

5. Set the environment variable USB_DEVFS_PATH to /proc/bus/usb

World-Writable USB Filesystem

Finally, here is a last-ditch method for configuring your Linux system in the event that your distribution does not have udev or hotplug capabilities. The following procedure is not necessary if you were able to exercise the steps in the previous subsections.

Often, the /proc/bus/usb directory is mounted with read-write permissions for root and read-only permissions for all other users. If an non-privileged user wishes to use the Aardvark adapter and software, one must ensure that /proc/bus/usb is mounted with read-write permissions for all users. The following steps can help setup the correct permissions. Please note that these steps will make the entire USB filesystem world writable.

1. Check the current permissions by executing the following command:
   “ls -al /proc/bus/usb/001”

2. If the contents of that directory are only writable by root, proceed with the remaining steps outlined below.

3. Add the following line to the /etc/fstab file:

        none /proc/bus/usb usbfs defaults,devmode=0666 0 0
   

4. Unmount the /proc/bus/usb directory using “umount”

5. Remount the /proc/bus/usb directory using “mount”

6. Repeat step 1. Now the contents of that directory should be writable by all users.

7. Set the environment variable USB_DEVFS_PATH to /proc/bus/usb

Top

3.4 Mac OS X USB Driver

The Aardvark communications layer under Mac OS X does not require a specific kernel driver to operate. Both Mac OS X 10.4 Tiger and 10.5 Leopard are supported. It is typically necessary to ensure that the user running the software is currently logged into the desktop. No further user configuration should be necessary.

Top

3.5 USB Port Assignment

The Aardvark adapter is assigned a port on a sequential basis. The first adapter is assigned to port 0, the second is assigned to port 1, and so on. If an Aardvark adapter is subsequently removed from the system, the remaining adapters shift their port numbers accordingly. With n Aardvark adapters attached, the allocated ports will be numbered from 0 to n−1.

Detecting Ports

To determine the ports to which the Aardvark adapters have been assigned, use the aa_find_devices routine as described in following API documentation.

Top

3.6 Aardvark Dynamically Linked Library

DLL Philosophy

The Aardvark DLL provides a robust approach to allow present-day Aardvark-enabled applications to interoperate with future versions of the device interface software without recompilation. For example, take the case of a graphical application that is written to communicate I2C or SPI through an Aardvark device. At the time the program is built, the Aardvark software is released as version 1.2. The Aardvark interface software may be improved many months later resulting in increased performance and/or reliability; it is now released as version 1.3. The original application need not be altered or recompiled. The user can simply replace the old Aardvark DLL with the newer one. How does this work? The application contains only a stub which in turn dynamically loads the DLL on the first invocation of any Aardvark API function. If the DLL is replaced, the application simply loads the new one, thereby utilizing all of the improvements present in the replaced DLL.

On Linux and Mac OS X, the DLL is technically known as a shared object (SO).

DLL Location

Total Phase provides language bindings that can be integrated into any custom application. The default behavior of locating the Aardvark DLL is dependent on the operating system platform and specific programming language environment. For example, for a C or C++ application, the following rules apply:

On a Windows system, this is as follows:

1. The directory from which the application binary was loaded.

2. The application’s current directory.

3. 32-bit system directory. Examples:

   • c:\Windows\System32 [Windows 2000/XP/Vista 32-bit]

   • c:\Windows\SysWow64 [Windows Vista 64-bit]

4. The windows directory. (Ex: c:\Windows)

5. The directories listed in the PATH environment variable.

On a Linux system this is as follows:

1. First, search for the shared object in the application binary path. If the /proc filesystem is not present, this step is skipped.

2. Next, search in the application’s current working directory.

3. Search the paths explicitly specified in LD_LIBRARY_PATH.

4. Finally, check any system library paths as specified in /etc/ld.so.conf and cached in /etc/ld.so.cache.

On a Mac OS X system this is as follows:

1. First, search for the shared object in the application binary path.

2. Next, search in the application’s current working directory.

3. Search the paths explicitly specified in DYLD_LIBRARY_PATH.

4. Finally, check the /usr/lib and /usr/local/lib system library paths.

If the DLL is still not found, an error will be returned by the binding function. The error code is AA_UNABLE_TO_LOAD_LIBRARY.

DLL Versioning

The Aardvark DLL checks to ensure that the firmware of a given Aardvark device is compatible. Each DLL revision is tagged as being compatible with firmware revisions greater than or equal to a certain version number. Likewise, each firmware version is tagged as being compatible with DLL revisions greater than or equal to a specific version number.

Here is an example.

     DLL v1.20: compatible with Firmware >= v1.15
     Firmware v1.30: compatible with DLL >= v1.20

Hence, the DLL is not compatible with any firmware less than version 1.15 and the firmware is not compatible with any DLL less than version 1.20. In this example, the version number constraints are satisfied and the DLL can safely connect to the target firmware without error. If there is a version mismatch, the API calls to open the device will fail. See the API documentation for further details.

Top

3.7 Rosetta Language Bindings: API Integration into Custom Applications

Overview

The Aardvark Rosetta language bindings make integration of the Aardvark API into custom applications simple. Accessing Aardvark functionality simply requires function calls to the Aardvark API. This API is easy to understand, much like the ANSI C library functions, (e.g., there is no unnecessary entanglement with the Windows messaging subsystem like development kits for some other embedded tools).

First, choose the Rosetta bindings appropriate for the programming language. Different Rosetta bindings are included with the software distribution on the distribution CD. They can also be found in the software download package available on the Total Phase website. Currently the following languages are supported: C/C++, Python, Visual Basic 6, Visual Basic .NET, and C#. Next, follow the instructions for each language binding on how to integrate the bindings with your application build setup. As an example, the integration for the C language bindings is described below. (For information on how to integrate the bindings for other languages, please see the example code included on the distribution CD and also available for download on the Total Phase website.)

1. Include the aardvark.h file included with the API software package in any C or C++ source module. The module may now use any Aardvark API call listed in aardvark.h.

2. Compile and link aardvark.c with your application. Ensure that the include path for compilation also lists the directory in which aardvark.h is located if the two files are not placed in the same directory.

3. Place the Aardvark DLL, included with the API software package, in the same directory as the application executable or in another directory such that it will be found by the previously described search rules.

Versioning

Since a new Aardvark DLL can be made available to an already compiled application, it is essential to ensure the compatibility of the Rosetta binding used by the application (e.g., aardvark.c) against the DLL loaded by the system. A system similar to the one employed for the DLL-Firmware cross-validation is used for the binding and DLL compatibility check.

Here is an example.

     DLL v1.20: compatible with Binding >= v1.10
     Binding v1.15: compatible with DLL >= v1.15

The above situation will pass the appropriate version checks. The compatibility check is performed within the binding. If there is a version mismatch, the API function will return an error code, AA_INCOMPATIBLE_LIBRARY.

Customizations

While provided language bindings stubs are fully functional, it is possible to modify the code found within this file according to specific requirements imposed by the application designer.

For example, in the C bindings one can modify the DLL search and loading behavior to conform to a specific paradigm. See the comments in aardvark.c for more details.

Top

3.8 Application Notes

Asynchronous Messages

There is buffering within the Aardvark DLL, on a per-device basis, to help capture asynchronous messages. Take the case of the Aardvark adapter receiving I2C messages asynchronously. If the application calls the function to change the SPI bitrate while some unprocessed asynchronous messages are pending, the Aardvark adapter will transact the bitrate change but also save any pending I2C messages internally. The messages will be held until the appropriate API function is called.

The size of the I2C and SPI buffers are 16 KiB each and they can hold many separate transactions. The buffers are only used when an Aardvark API call is invoked. The buffer size is adequate since the overall limitation for asynchronous messages is fundamentally determined by the operating system’s internal buffer size. This concept is explained below.

Receive Saturation

The Aardvark adapter can be configured as an I2C or SPI slave. A slave can receive messages asynchronously with respect to the host PC software. Between calls to the Aardvark API, these messages must be buffered somewhere in memory. This is accomplished on the PC host, courtesy of the operating system. Naturally the buffer is limited in size and once this buffer is full, bytes will be dropped.

An overflow can occur when the Aardvark device receives asynchronous messages faster than the rate that they are processed — the receive link is “saturated.” This condition can affect other synchronous communication with the Aardvark adapter. For example, if the SPI slave is receiving many unserviced messages (messages left pending in the operating systems buffer), a subsequent call to change the bitrate of I2C could fail in the following manner.

1. The software sends a command to the Aardvark adapter to change the bitrate.

2. The Aardvark adapter responds that the bitrate was set to a given value.

3. The response is lost since the operating system’s receive buffer was full.

The requested bitrate has most likely been set by the Aardvark device, but the response was lost. A similar problem can happen when one attempts to disable the very slave that is saturating the incoming receive buffer! The API function sends a command to disable the slave, but the acknowledgment from the Aardvark adapter is lost. The API call will treat this as a communication error, but if the slave was actually disabled, a subsequent call to disable the slave should complete without errors.

The receive saturation problem can be improved in two ways. The obvious solution is to reduce the amount of traffic that is sent by the master between calls to the Aardvark API. This will require the ability to reconfigure the offending master device. The other option is to more regularly poll the slave to obtain any pending asynchronous messages. Keep in mind that each call to capture pending asynchronous data can have a timeout of up to 500 ms. If there is other time critical code that must be executed simultaneously, it is best to use the asynchronous polling function found in the API which allows for variable timeout values.

Threading

The Aardvark DLL is designed for single-threaded environments so as to allow for maximum cross-platform compatibility. If the application design requires multi-threaded use of the Aardvark functionality, each Aardvark API call can be wrapped with a thread-safe locking mechanism before and after invocation. A call to any Aardvark API function that communicates with the host synchronously will also fetch any pending asynchronous messages, buffering them for subsequent calls to the asynchronous (slave) receive functions.

USB Scheduling Delays

Each API call that is used to send data to and from the Aardvark adapter can incur up to 1 ms in delay on the PC host. This is caused by the inherent design of the USB architecture. The operating system will queue any outgoing USB transfer request on the host until the next USB frame period. The frame period is 1 ms. Thus, if the application attempts to execute several transactions in rapid sequence there can be 1–2 ms delay between each transaction plus any additional process scheduling delays introduced by the operating system. The best throughput can be achieved for single transactions that transfer a large number of bytes at a time.