Aardvark I2C/SPI Host Adapter Data Sheet v5.00
| Prev: Hardware Specifications | Table of Contents | Next: Firmware |
3 Software
3.1 Compatibility
Windows Compatibility
The Aardvark software is also compatible with Windows 2000 and Windows XP. The software’s compatibility with Windows 98 and Windows ME has not been tested. Theoretically, the Aardvark software is compatible with these legacy operating systems, but there will be no support provided by Total Phase for these environments.
Linux Compatibility
The Aardvark software is compatible with all standard distributions of Linux with integrated USB support. Kernel 2.6 is required.
Mac OS X Compatibility
The Aardvark software is compatible with Intel versions of Mac OS X 10.4 Tiger and 10.5 Leopard. Installation of the latest available update is recommended.
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, step through the following instructions. This is only necessary for the very first Aardvark adapter that is plugged into the PC. Subsequent plugs and unplugs are automatically handled by the operating system.
Windows 2000:
When you plug in the Aardvark adapter into your PC for the first time, Windows will present the “Found New Hardware Wizard.” Select “Next.”
On the next dialog window, select “Search for a suitable driver for my device (recommended)” and click “Next.”
On the third screen, uncheck all settings and check “Specify a location” and click “Next.”
Click “Browse…”, navigate to either the CD-ROM (\usb-drivers\windows directory), or temporary directory where the driver files have been unpacked (for downloaded updates).
Select “ftd2xx.inf” and click “Open”, then click “Ok.”
Click “Next” on the subsequent screen, followed by “Finish” to complete the installation. This completes the installation of the USB driver.
Windows XP:
When you plug in the Aardvark adapter into your PC for the first time, Windows will present the “Found New Hardware Wizard.”
Select “Install from a list or specific location (Advanced)” and click “Next.”
Select “Search for best driver in these locations:”, uncheck “Search removable media”, check “Include this location in the search.”
Click “Browse…”, expand My Computer and then navigate to either the CD-ROM (\usb-drivers\windows directory), or temporary directory where the driver files have been unpacked (for downloaded updates).
Click “OK”, then click “Next.”
A dialog will inform the user that the USB driver has been installed. Click “Finish.”
Both Windows 2000 and Windows XP:
Once the installation is complete, confirm that the installation was successful by checking that the device appears in the “Device Manager.” To navigate to the “Device Manager” screen select “Control Panel | System Properties | Hardware | Device Manager.”
The Aardvark device should appear under the “Universal Serial Bus Controllers” section.
Driver Removal
Here are instructions to remove the USB communication driver from the operating system. It is critical that all Aardvark adapters have been removed from your system before proceeding with this process.
Navigate to either the CD-ROM (\usb-drivers\windows directory), or temporary directory where the driver files have been unpacked (for downloaded updates).
Run FTD2XXUN.EXE and follow the instructions.
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.
As superuser, unpack 99-totalphase.rules to /etc/udev/rules.d
chmod 644 /etc/udev/rules.d/99-totalphase.rules
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.
As superuser, unpack aardvark and aardvark.usermap to /etc/hotplug/usb
chmod 755 /etc/hotplug/usb/aardvark
chmod 644 /etc/hotplug/usb/aardvark.usermap
Unplug and replug your Aardvark adapter(s)
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.
Check the current permissions by executing the following command:
“ls -al /proc/bus/usb/001”If the contents of that directory are only writable by root, proceed with the remaining steps outlined below.
Add the following line to the /etc/fstab file:
none /proc/bus/usb usbfs defaults,devmode=0666 0 0Unmount the /proc/bus/usb directory using “umount”
Remount the /proc/bus/usb directory using “mount”
Repeat step 1. Now the contents of that directory should be writable by all users.
Set the environment variable USB_DEVFS_PATH to /proc/bus/usb
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.
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.
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:
The directory from which the application binary was loaded.
The application’s current directory.
32-bit system directory. (Ex: c:\winnt\System32) [Windows NT/2000/XP only]
16-bit system directory. (Ex: c:\winnt\System or c:\windows\system)
The windows directory. (Ex: c:\winnt or c:\windows)
The directories listed in the PATH environment variable.
On a Linux system this is as follows:
First, search for the shared object in the application binary path. If the /proc filesystem is not present, this step is skipped.
Next, search in the application’s current working directory.
Search the paths explicitly specified in LD_LIBRARY_PATH.
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:
First, search for the shared object in the application binary path.
Next, search in the application’s current working directory.
Search the paths explicitly specified in DYLD_LIBRARY_PATH.
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.
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.)
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.
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.
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.
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.
The software sends a command to the Aardvark adapter to change the bitrate.
The Aardvark adapter responds that the bitrate was set to a given value.
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.
| Prev: Hardware Specifications | Table of Contents | Next: Firmware |