Aardvark I2C/SPI Host Adapter User Manual

1 General Overview

Top

1.1 I²C Background

1.1.1 I²C History

When connecting multiple devices to a microcontroller, the address and data lines of each devices were conventionally connected individually. This would take up precious pins on the microcontroller, result in a lot of traces on the PCB, and require more components to connect everything together. This made these systems expensive to produce and susceptible to interference and noise.

To solve this problem, Philips developed Inter-IC bus, or I²C, in the 1980s. I²C is a low-bandwidth, short distance protocol for on board communications. All devices are connected through two wires: serial data (SDA) and serial clock (SCL).

Figure 1 : Sample I²C Implementation. – Regardless of how many slave units are attached to the I²C bus, there are only two signals connected to all of them. Consequently, there is additional overhead because an addressing mechanism is required for the master device to communicate with a specific slave device.

Because all communication takes place on only two wires, all devices must have a unique address to identify it on the bus. Slave devices have a predefined address, but the lower bits of the address can be assigned to allow for multiples of the same devices on the bus.

1.1.2 I²C Theory of Operation

I²C has a master/slave protocol. The master initiates the communication. Here is a simplified description of the protocol. For precise details, please refer to the Philips I²C specification. The sequence of events are as follows:

1. The master device issues a start condition. This condition informs all the slave devices to listen on the serial data line for their respective address.
2. The master device sends the address of the target slave device and a read/write flag.
3. The slave device with the matching address responds with an acknowledgment signal.
4. Communication proceeds between the master and the slave on the data bus. Both the master and slave can receive or transmit data depending on whether the communication is a read or write. The transmitter sends 8 bits of data to the receiver, which replies with a 1 bit acknowledgment.
5. When the communication is complete, the master issues a stop condition indicating that everything is done.

Figure 2 shows a sample bitstream of the I²C protocol.

Figure 2 : I²C Protocol. – Since there are only two wires, this protocol includes the extra overhead of the addressing and acknowledgement mechanisms.

1.1.3 I²C Features

I²C has many features other important features worth mentioning. It supports multiple data speeds: standard (100 kbps), fast (400 kbps), and high speed (3.4 Mbps) communications.

Other features include:

• Built-in collision detection,
• 10-bit Addressing,
• Multi-master support,
• Data broadcast (general call).

For more information about other features, see the references at the end of this section.

1.1.4 I²C Benefits and Drawbacks

Since only two wires are required, I²C is well suited for boards with many devices connected on the bus. This helps reduce the cost and complexity of the circuit as additional devices are added to the system.

Due to the presence of only two wires, there is additional complexity in handling the overhead of addressing and acknowledgments. This can be inefficient in simple configurations and a direct-link interface such as SPI might be preferred.

1.1.5 I²C References

• I²C bus – NXP (Philips) Semiconductors Official I²C website
• I²C (Inter-Integrated Circuit) Bus Technical Overview and Frequently Asked Questions – Embedded Systems Academy
• Introduction to I²C – Embedded.com
• I²C – Open Directory Project Listing

Top

1.2 SPI Background

1.2.1 SPI History

SPI is a serial communication bus developed by Motorola. It is a full-duplex protocol which functions on a master-slave paradigm that is ideally suited to data streaming applications.

1.2.2 SPI Theory of Operation

SPI requires four signals: clock (SCLK), master output/slave input (MOSI), master input/slave output (MISO), slave select (SS).

Figure 3 : Sample SPI Implementation. – Each slave device requires a separate slave select signal (SS). This means that as devices are added, the circuit increases in complexity.

Three signals are shared by all devices on the SPI bus: SCLK, MOSI and MISO. SCLK is generated by the master device and is used for synchronization. MOSI and MISO are the data lines. The direction of transfer is indicated by their names. Data is always transferred in both directions in SPI, but an SPI device interested in only transmitting data can choose to ignore the receive bytes. Likewise, a device only interested in the incoming bytes can transmit dummy bytes.

Each device has its own SS line. The master pulls low on a slaves SS line to select a device for communication.

The exchange itself has no pre-defined protocol. This makes it ideal for data-streaming applications. Data can be transferred at high speed, often into the range of the tens of megahertz. The flipside is that there is no acknowledgment, no flow control, and the master may not even be aware of the slave's presence.

1.2.3 SPI Modes

Although there is no protocol, the master and slave need to agree about the data frame for the exchange. The data frame is described by two parameters: clock polarity (CPOL) and clock phase (CPHA). Both parameters have two states which results in four possible combinations. These combinations are shown in figure 4.

Figure 4 : SPI Modes – The frame of the data exchange is described by two parameters, the clock polarity (CPOL) and the clock phase (CPHA). This diagram shows the four possible states for these parameters and the corresponding mode in SPI.

1.2.4 SPI Benefits and Drawbacks

SPI is a very simple communication protocol. It does not have a specific high-level protocol which means that there is almost no overhead. Data can be shifted at very high rates in full duplex. This makes it very simple and efficient in a single-master single-slave scenario.

Because each slave needs its own SS, the number of traces required is n+3, where n is the number of SPI devices. This means increased board complexity when the number of slaves is increased.

1.2.5 SPI References

• Introduction to Serial Peripheral Interface – Embedded.com
• SPI – Serial Peripheral Interface

2 Hardware Specifications

The specifications defined in this section are for the Aardvark I²C/SPI Host Adapter. The Aardvark OEM adapters have a subset of these features. The Aardvark OEM I²C Host Adapter is an I²C master capable of speeds up to 125 kbps. The Aardvark OEM SPI Host Adapter is an SPI master capable of speeds up to 1 Mbps. Neither OEM adapter provides slave capabilities.

Top

2.1 Pinouts

2.1.1 Connector Specification

The ribbon cable is a standard 10-wire 0.050″ (1.25 mm) pitch cable that is 5.125″ (131mm) long.

The ribbon cable connector is a standard 0.100″ (2.54 mm) pitch IDC type connector. This connector will mate with a standard keyed boxed header.

Alternatively, a split cable is available which connects to the ribbon cable and provides individual leads for each pin.

2.1.2 Orientation

The ribbon cable pin order follows the standard convention. The red line indicates the first position. When looking at your Aardvark adapter in the upright position (figure 5 ), pin 1 is in the top left corner and pin 10 is in the bottom right corner.

Figure 5 : The Aardvark I²C/SPI Host Adapter in the upright position. – Pin 1 is located in the upper left corner of the connector and Pin 10 is located in the lower right corner of the connector.

If you flip your Aardvark adapter over (figure 6 ) such that the text on the serial number label is in the proper upright position, the pin order is as shown in the following diagram.

Figure 6 : The Aardvark I²C/SPI Host Adapter in the upside down position. – Pin 1 is located in the lower left corner of the connector and Pin 10 is located in the upper right corner of the connector.

2.1.3 Order of Leads

1. SCL
2. GND
3. SDA
4. NC/+5V
5. MISO
6. NC/+5V
7. SCLK
8. MOSI
9. SS
10. GND

2.1.4 Ground

GND (Pin 2):
GND (Pin 10):

It is imperative that the Aardvark adapter be on a common ground with the target system. If the grounds are not connected, the signaling is entirely unpredictable and communication will likely be corrupted. Two pins are connected to provide a solid ground path.

2.1.5 I²C Pins

SCL (Pin 1):

Serial Clock line – the signal used to synchronize communication between the master and the slave.

SDA (Pin 3):

Serial Data line – the signal used to transfer data between the transmitter and the receiver.

2.1.6 SPI Pins

SCLK (Pin 7):

Serial Clock – control line that is driven by the master and regulates the flow of the data bits.

MOSI (Pin 8):

Master Out Slave In – this data line supplies output data from the master which is shifted into the slave.

MISO (Pin 5):

Master In Slave Out – this data line supplies the output data from the slave to the input of the master.

SS (Pin 9):

Slave Select – control line that allows slaves to be turned on and off via hardware control.

2.1.7 Powering Downstream Devices

It is possible to power a downstream target, such as an I²C or SPI EEPROM with the Aardvark adapters power (which is provided by the USB port). It is ideal if the downstream device does not consume more than 25 mA per pin. The Aardvark adapter is compatible with USB hubs as well as USB host controllers (see section below on USB compliance). USB hubs are technically only rated to provide 100 mA per USB device. If the Aardvark adapter is directly plugged into a USB host controller, it can theoretically draw up to 500 mA total, leaving approximately 400 mA for any downstream target. However, the Aardvark adapter always reports itself to the host as a low-power device (<100 mA). Therefore, drawing large amounts of current from the host is not advisable.

NC/+5V (Pin 4): I²C Power
NC/+5V (Pin 6): SPI Power

By default, these pins are left unconnected at the time of shipping. For hardware versions 2.00 and greater, these pins are switched through the software API. A maximum of 25 mA may be drawn from each pin.

For hardware versions prior to 2.00, power cannot be supplied unless the appropriate jumpers are connected inside the Aardvark unit. To connect VDD to pins 4 and 6, connect jumpers J301 and J302.

Opening your Aardvark unit will void any hardware warranty. Any modifications are at the user's own risk.

Top

2.2 Signal Levels/Voltage Ratings

2.2.1 Logic High Levels

All signal levels are nominally 3.3 volts (+/- 10%) logic high. This allows the Aardvark adapter to be used with both TTL and CMOS logic level devices. A logic high of 3.3 volts will be adequate for TTL-compliant devices since such devices are ordinarily specified to accept logic high inputs above approximately 3 volts.

2.2.2 ESD protection

The Aardvark adapter has built-in electrostatic discharge protection to prevent damage to the unit from high voltage static electricity.

2.2.3 Input Current

All inputs are high-impedance so the input current is approximately 1 µA.

2.2.4 Drive Current

The Aardvark adapter can drive all output signals with a maximum of 10 mA current source or sink. It may be possible to exceed this for short periods of time, but drawing more than 20mA may damage the I/O buffers.

Top

2.3 I²C Signaling Characteristics

2.3.1 Speed

As of hardware version 3.00, the Aardvark I²C master can operate at a maximum bitrate of 800 kbps and supports many intermediate bitrates between 1 kHz and the maximum. The power-on default bitrate is for the I²C master unit is 100 kbps.

For slave functionality, the Aardvark adapter can operate at any rate less than the maximum bitrate of 800 kbps.

For hardware versions before 3.00, the maximum I²C master bitrate is 663 kbps and the maximum I²C slave bitrate is 595 kbps.

It is not possible to send bytes at a throughput of exactly 1/8 times the bitrate. The I²C protocol requires that 9 bits are sent for every 8 bits of data. There is also a finite time required to set up a byte transmission. In the development of the Aardvark adapter, many optimizations have been employed to decrease this setup time. This allows byte throughputs within each transaction to be very close to the theoretical maximum byte throughput of 1/9 the bitrate.

There can be extra overhead introduced by the operating system between calls to the Aardvark API. These delays will further reduce the overall throughput across multiple transactions. To achieve the fastest throughput, it is advisable to send as many bytes as possible in a single transaction (i.e., a single call to the Aardvark API).

2.3.2 Pull-up Resistors

There is a 2.2K resistor on each I²C line (SCL, SDA). The lines are effectively pulled up to 3.3V, resulting in approximately 1.5 mA of pull-up current. If the Aardvark adapter is connected to an I²C bus that also includes pull-up resistors, the total pull-up current could be potentially larger. The I²C specification allows for a maximum of 3 mA pull-up current on each I²C line.

A good rule of thumb is that if a downstream I²C device can sink more than 5 mA of current, the protocol should operate properly. Stronger pull-up resistors and larger sink currents may be required for fast bitrates, especially if there is a large amount of capacitance on the bus. The Aardvark device is able to sink approximately 10 mA, so it is possible to have two Aardvark devices communicate with each other as master and slave, with both devices pull-up resistors enabled.

Hardware versions 2.00 and later have the ability to switch the pull-up resistors by through the software. Refer to the API section for more details.

2.3.3 I²C Clock Stretching

When the Aardvark adapter is configured as an I²C master, it supports both inter-bit and inter-byte slave clock-stretching. If a slave device pulls SCL low during a transaction, the adapter will wait until SCL has been released before continuing with the transaction.

2.3.4 Known I²C Limitations

Since firmware version 2.00, the Aardvark adapter supports the repeated start, 10-bit addressing, and combined format features of the I²C protocol.

Since firmware version 3.00, the Aardvark adapter can keep the slave functions enabled even while master operations are executed through the same adapter. The Aardvark adapter can even respond to slave requests immediately after losing bus arbitration during the slave addressing phase of a master transaction.

Multi-master is also supported with the following features:

1. If there is a bus collision during data transmission and the Aardvark adapter loses the bus, the transaction will be be cut short and the host API will report that fewer bytes were transmitted than the requested number. This condition can be distinguished from the case in which the downstream slave cuts short the transmission by sending a NACK by using the function aa_i2c_read_ext.
2. Collisions are not detected in the following situations:
   • Between a REPEATED START condition and a data bit
   • Between a STOP condition and a data bit
   • Between a REPEATED START and a STOP condition

This constraint can be phrased in a different manner. Say that I²C master device A has a packet length of X bytes. If there is a second I²C master device, B, that sends packets of length greater than X bytes, the first X bytes should never contain exactly the same data as the data sent by device A. Otherwise the results of the arbitration will be undefined.

This is a constraint found with most I²C master devices used in a multi-master environment.

Top

2.4 SPI Signaling Characteristics

2.4.1 SPI Waveforms

The SPI signaling is characterized by the waveforms in Figures 7 and 8.

Figure 7 : SPI Waveform – Three different times are of note: t  ₁ , time from the assertion of SS# to the first clock cycle; t  ₂ , time from the last clock cycle and the deassertion of SS#; t  _p , clock period.

Figure 8 : SPI Byte Timing – t  _d is the setup time between SPI bytes and t  _b is the total byte-to-byte time.

2.4.2 Speeds

The Aardvark SPI master can operate at bitrates between 125 kHz and 8 MHz, including, but not limited to the following frequencies: 125 kHz, 250 kHz, 500 kHz, 1 MHz, 2 MHz, 4 MHz, and 8 MHz. The power-on default bitrate is 1 MHz. The quoted bitrates are only achievable within each individual byte and does not extend across bytes. There is approximately 9 µs of setup time required in between each byte which results in a total transmission period of the byte transmission time plus 9 µs.

The Aardvark SPI slave can operate at any bitrate up to 4 Mbps. However, for correct transmission from slave to master there must be at least 4 µs delay between the end of byte n and start of byte n+1 for the MISO data to be setup properly for byte n+1. Otherwise, the Aardvark adapter will simply return the data it just received. Likewise, for correct reception of data by the slave, there must be at least 10 µs between the start of byte n and the start of byte n+1.

Similarly, when the Aardvark adapter is configured to act as an SPI slave, and the slave select is pulled high to indicate the end of a transaction, there is a data processing overhead of sending the transaction to the PC host. As such, if the SPI master sends a subsequent transaction in rapid succession to the Aardvark slave, the data received by the Aardvark slave may be corrupted. There is no precise value for this minimum inter-transaction time, but a suggested spacing is approximately 100-200 µs.

2.4.3 Pin Driving

When the SPI interface is activated as a master, the slave select line (SS) is actively driven low. The MOSI and SCK lines are driven as appropriate for the SPI mode. After each transmission is complete, these lines are returned to a high impedance state. This feature allows the Aardvark adapter, following a transaction as a master SPI device, to be then reconnected to another SPI environment as a slave. The Aardvark adapter will not fight the master lines in the new environment.

Consequently, any SPI slave target to which the Aardvark adapter is interfaced must have a pull-up resistor on its slave select line, preventing fluttering of the voltage when the Aardvark adapter stops driving the signal. It is also advisable that every slave also have passive pull-ups on the MOSI and SCK lines. These pull-up resistors can be relatively weak – 100k should be adequate.

As a slave, the MOSI, SCK, and SS lines are configured as an input and the MISO line is configured as an output. This configuration is held as long as the slave mode is enabled (see the API documentation later in the manual).

2.4.4 Known SPI Limitations

There is currently an issue with SPI mode 2 (clock idles high, and sampling of MOSI is on the leading edge) that induces periodic bit corruptions in the most significant bit of certain bytes. The bug has been noted for SPI slave devices and there may also be corruptions when using this mode for sending or receiving messages as an SPI master. Unfortunately there is no fix for this problem and the best solution is to use another mode. If you have any questions regarding this issue please contact Total Phase support.

It is only possible to reliably send and receive transactions of 4 KiB or less as an SPI master or slave. This is due to operating system issues and the full-duplex nature of the SPI signaling.

2.4.5 Aardvark Device Power Consumption

The Aardvark adapter consumes less than 100 mA of current. This is within the USB 1.1 current specification for devices powered from a USB host adapter (500 mA maximum per device) or a USB hub (100 mA maximum per device).

Top

2.5 USB 1.1 Compliance

The Aardvark adapter is USB 1.1 compliant and will also operate as a full speed (12 Mbps) device on a USB 2.0 hub or host controller

Top

2.6 Physical Specifications

• Dimensions: W x D x L: 55.6 mm x 22.2 mm x 89 mm (2.19" x 0.87" x 3.5")
• Weight: 64 g (0.14 lbs)

Top

2.7 Temperature Specifications

The Aardvark device is designed to be operated at room temperature (10-35 C). The electronic components are rated for standard commercial specifications (0-70 C). However, the plastic housing, along with the ribbon and USB cables, may not withstand the higher end of this range. Any use of the Aardvark device outside the room temperature specification will void the hardware warranty.

3 Software

Top

3.1 Compatibility

3.1.1 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.

3.1.2 Windows Compatibility

The Aardvark software is compatible with 32-bit and 64-bit versions of Windows XP (SP2 or later), Windows Vista, Windows 7, Windows 8/8.1, and Windows 10.

Windows 2000 and legacy 16-bit Windows 95/98/ME operating systems are not supported.

3.1.3 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.

3.1.4 Mac OS X Compatibility

The Aardvark software is compatible with Intel versions of Mac OS X 10.5 Leopard, 10.6 Snow Leopard, 10.7 Lion, 10.8 Mountain Lion, and 10.9 Mavericks. Installation of the latest available update is recommended.

Top

3.2 Windows USB Driver

3.2.1 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 XP:

1. The Found New Hardware notification bubble will pop up from the system tray and state that the Total Phase Aardvark I²C/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/7/8:

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 XP, or select "Control Panel | Hardware and Sound | Device Manager" for Windows Vista/7/8. The Aardvark device should appear under the Universal Serial Bus Controllers section.

3.2.2 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.

NOTE: It is critical to remove all Total Phase devices from your system before you remove the USB drivers.

Windows 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/7/8:

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 5.15, the Aardvark communications layer under Linux no longer requires a specific kernel mode or user mode driver to operate. This differs from previous versions that required the user to ensure independently that the libusb library was installed on the system. See the README.txt in the API package for more details.

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.

3.3.1 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)

3.3.2 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

3.3.3 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.

3.5.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

3.6.1 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 I²C 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).

3.6.2 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 applications current directory.
3. 32-bit system directory (for a 32-bit application). Examples:
   • c:\Windows\System32 [Windows XP/Vista/7/8 32-bit]
   • C:\Windows\System64 [Windows XP 64-bit]
   • c:\Windows\SysWow64 [Windows Vista/7/8 64-bit]
4. 64-bit system directory (for a 64-bit application). Examples:
   • C:\Windows\System32 [Windows XP/Vista/7/8 64-bit]
5. The Windows directory. (Ex: c:\Windows )
6. 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 applications 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 applications 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.

3.6.3 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

3.7.1 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.

3.7.2 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.

3.7.3 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

3.8.1 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 I²C 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 I²C messages internally. The messages will be held until the appropriate API function is called.

The size of the I²C 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 systems internal buffer size. This concept is explained below.

3.8.2 Receive Saturation

The Aardvark adapter can be configured as an I²C 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 I²C 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 systems 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.

3.8.3 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.

3.8.4 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.

4 Firmware

Top

4.1 Field Upgrades

4.1.1 Upgrade Philosophy

The Aardvark adapter is designed so that its internal firmware can be upgraded by the user, thereby allowing the inclusion of any performance enhancements or critical fixes available after the purchase of the device. The upgrade procedure is performed via USB and has several error checking facilities to ensure that the Aardvark adapter is not rendered permanently unusable by a bad firmware update. In the worst case scenario, a corruption can cause the Aardvark adapter to be locked until a subsequent clean update is executed.

The upgrade utility is also compatible with older devices that use the legacy virtual serial port communications drivers (pre-3.00 firmware revisions). The older serial port driver must be installed on your operating system. When listing such devices, the upgrade utility will report these devices with port numbers starting at 128. The devices will also be marked as "serial" as opposed to the "direct" identifier. Upgrading the legacy firmware will cause the Aardvark unit to automatically switch to using the new communications driver interface. If the host PC does not have the appropriate driver installed, the operating system may prompt the user for the new driver upon completion of the firmware upgrade. Please refer to the section on USB driver installation above for more information on how to install the new driver.

The Aardvark OEM I²C Host Adapter and the Aardvark OEM SPI Host Adapter do not support field upgrades.

4.1.2 Upgrade Procedure

Here is the simple procedure by which the Aardvark firmware is upgraded.

1. Download the latest firmware from the Total Phase website.
2. Unzip the downloaded file. It should contain the aaflash utility. This utility contains the necessary information to perform the entire firmware update.
3. Run the appropriate version of aaflash :
   • aaflash-win32.exe on Windows
   • aaflash-linux on Linux
   • aaflash-darwin on Mac OS X

   It will first display the firmware version contained in the utility along with the required hardware version to run this firmware version.

4. It will list all of the detected devices along with their current firmware and hardware versions.
5. Select a device to upgrade. Note the firmware and hardware version of the device before proceeding. If the selected devices hardware is not suitable to accept the new firmware, an error will be printed and the utility will be reinvoked.
6. If the chosen device is acceptable, the aaflash utility will update the device with the new firmware. The process should take about 3 seconds, with a progress bar displayed during the procedure.
7. The upgraded Aardvark adapter should now be usable by any Aardvark-enabled application.
8. In the event that there was a malfunction in the firmware update, the Aardvark adapter may not be recognizable by an Aardvark-enabled application. Try the update again, since the Aardvark adapter has most likely become locked due to a corruption in the upgrade process. If the update still does not take effect, it is best to revert back to the previous firmware. This can be done by running a previous version of aaflash that contains an earlier firmware version. Check the Total Phase website or the distribution CD that was included with your Aardvark adapter for previous versions of the firmware.

5 API Documentation

Top

5.1 Introduction

The API documentation that follows is oriented toward the Aardvark Rosetta C bindings. The set of API functions and their functionality is identical regardless of which Rosetta language binding is utilized. The only differences will be found in the calling convention of the functions. For further information on such differences please refer to the documentation that accompanies each language bindings in the Aardvark software distribution.

The Aardvark OEM I²C Host Adapter and the Aardvark OEM SPI Host Adapter have a subset of these features. Attempting to use a feature that is not supported will result in an error.

Top

5.2 General Data Types

The following definitions are provided for convenience. All Aardvark data types are unsigned.

      typedef unsigned char  aa_u08;       typedef unsigned short aa_u16;       typedef unsigned int   aa_u32;     

Top

5.3 Notes on Status Codes

Most of the Aardvark API functions can return a status or error code back to the caller. The complete list of status codes is provided at the end of this chapter. All of the error codes are assigned values less than 0, separating these responses from any numerical values returned by certain API functions.

Each API function can return one of two error codes with regard to the loading of the underlying Aardvark DLL, AA_UNABLE_TO_LOAD_LIBRARY and AA_INCOMPATIBLE_LIBRARY. If these status codes are received, refer to the previous sections in this manual that discuss the DLL and API integration of the Aardvark software. Furthermore, all API calls can potentially return the error AA_UNABLE_TO_LOAD_FUNCTION. If this error is encountered, there is likely a serious version incompatibility that was not caught by the automatic version checking system. Where appropriate, compare the language binding versions (e.g., AA_HEADER_VERSION found in aardvark.h and AA_CFILE_VERSION found in aardvark.c ) to verify that there are no mismatches. Next, ensure that the Rosetta language binding (e.g., aardvark.c and aardvark.h ) are from the same release as the Aardvark DLL. If all of these versions are synchronized and there are still problems, please contact Total Phase support for assistance.

Any API function that accepts an Aardvark handle can return the error AA_INVALID_HANDLE if the handle does not correspond to a valid Aardvark device that has already been opened. If this error is received, check the application code to ensure that the aa_open command returned a valid handle and that this handle is not corrupted before being passed to the offending API function.

Finally, any I²C or SPI API call that communicates with an Aardvark device can return the error AA_COMMUNICATION_ERROR. This means that while the Aardvark handle is valid and the communication channel is open, there was an error receiving the acknowledgment response from the Aardvark adapter. This can occur in situations where the incoming data stream has been saturated by asynchronously received messages an outgoing message is sent to the Aardvark adapter, but the incoming acknowledgment is dropped by the operating system as a result of the incoming USB receive buffer being full. The error signifies that it was not possible to guarantee that the connected Aardvark device has processed the host PC request, though it is likely that the requested action has been communicated to the Aardvark adapter and the response was simply lost. For example, if the slave functions are enabled and the incoming communication buffer is saturated, an API call to disable the slave may return AA_COMMUNICATION_ERROR even though the slave has actually been disabled.

If either the I²C or SPI subsystems have been disabled by aa_configure, all other API functions that interact with I²C or SPI will return AA_I2C_NOT_ENABLED or AA_SPI_NOT_ENABLED, respectively.

These common status responses are not reiterated for each function. Only the error codes that are specific to each API function are described below.

All of the possible error codes, along with their values and status strings, are listed following the API documentation.

Top

5.4 General

5.4.1 Interface

Top

Find Devices (aa_find_devices)

      int aa_find_devices (int      nelem,                            aa_u16 * devices);     

Get a list of ports to which Aardvark devices are attached.

Top

Find Devices (aa_find_devices_ext)

      int aa_find_devices_ext (int       num_devices,                                aa_u16 * devices,                                int      num_ids,                                aa_u32 * unique_ids);     

Get a list of ports and unique IDs to which Aardvark devices are attached.

Top

Open an Aardvark device (aa_open)

      Aardvark aa_open (int port_number);     

Open the Aardvark port.

Top

Open an Aardvark device (aa_open_ext)

      Aardvark aa_open_ext (int port_number, AardvarkExt *aa_ext);     

Open the Aardvark port, returning extended information in the supplied structure.

  struct AardvarkExt {     AardvarkVersion  version;     /* Features of this device. */     int              features;   }           

  struct AardvarkVersion {     /* Software, firmware, and     hardware versions. */     aa_u16 software;     aa_u16 firmware;     aa_u16 hardware;     /* FW requires that SW must be >= this version. */     aa_u16 sw_req_by_fw;     /* SW requires that FW must be >= this version. */     aa_u16 fw_req_by_sw;     /* API requires that SW must be >= this version. */     aa_u16 api_req_by_sw;   };           

Top

Close an Aardvark (aa_close)

      int aa_close (Aardvark aardvark);     

Close the Aardvark port.

Top

Get Port (aa_port)

      int aa_port (Aardvark aardvark);     

Return the port number for this Aardvark handle.

Top

Get Features (aa_features)

      int aa_features (Aardvark aardvark);     

Return the device features as a bit-mask of values, or an error code if the handle is not valid.

    #define AA_FEATURE_SPI     (1<<0)     #define AA_FEATURE_I2C     (1<<1)     #define AA_FEATURE_GPIO    (1<<3)         

Top

Get Unique ID (aa_unique_id)

      aa_u32 aa_unique_id (Aardvark aardvark);     

Return the unique ID of the given Aardvark device.

Top

Status String (aa_status_string)

      const char *aa_status_string (int status);     

Return the status string for the given status code.

Top

Logging (aa_log)

      int aa_log (Aardvark aardvark, int level, int handle);     

Enable logging to a file.

Top

Version (aa_version)

      int aa_version (Aardvark aardvark, AardvarkVersion *version);     

Return the version matrix for the device attached to the given handle.

Top

Configure (aa_configure)

      int aa_configure (Aardvark aardvark, AardvarkConfig config);     

Activate/deactivate individual subsystems (I²C, SPI, GPIO).

Top

Target Power (aa_target_power)

      int aa_target_power (Aardvark aardvark, aa_u08 power_mask);     

Activate/deactivate target power pins 4 and 6.

Top

Asynchronous Polling (aa_async_poll)

      int aa_async_poll (Aardvark aardvark, int timeout);     

Check if there is any asynchronous data pending from the Aardvark adapter.

Top

Sleep (aa_sleep_ms)

      u32 aa_sleep_ms (u32 milliseconds);     

Sleep for given amount of time.

Top

5.5 I²C Interface

5.5.1 I²C Notes

1. It is not necessary to set the bitrate for the Aardvark I²C slave.
2. An I²C master operation read or write operation can be transacted while leaving the I²C slave functionality enabled. In a multi-master situation it is possible for the Aardvark adapter to lose the bus during the slave addressing portion of the transaction. If the other master that wins the bus subsequently addresses this Aardvark adapters slave address, the Aardvark adapter will respond appropriately to the request using its slave mode capabilities.
3. It is always advisable to set the slave response before first enabling the slave. This ensures that valid data is sent to any requesting master.
4. It is not possible to receive messages larger than approximately 4 KiB as a slave due to operating system limitations on the asynchronous incoming buffer. As such, one should not queue up more than 4 KiB of total slave data between calls to the Aardvark API.
5. Since firmware revision 2.00 it is possible for the Aardvark I²C master to employ some of the advanced features of I²C. This is accomplished by the AardvarkI2cFlags argument type that is included in the aa_i2c_read and aa_i2c_write argument lists. The options in Table 5 are available can be logically ORed together to combine them for one operation.
   
   
   Table 5 : I²C Advanced Feature Options

   AA_I2C_NO_FLAGS	Request no options.
   AA_I2C_10_BIT_ADDR	Request that the provided address is treated as a 10-bit address. The Aardvark I2C subsystem will follow the Philips I2C specification when transmitting the address.
   AA_I2C_COMBINED_FMT	Request that the Philips combined format is followed during a I2C read operation. Please see the Philips specification for more details. This flag does not have any effect unless a master read operation is requested and the AA_I2C_10_BIT_ADDR is also set.
   AA_I2C_NO_STOP	Request that no stop condition is issued on the I2C bus after the transaction completes. It is expected that the PC will follow up with a subsequent transaction at which point a repeated start will be issued on the bus. Eventually an I2C transaction must be issued without the "no stop" option so that a stop condition is issued and the bus is freed.
   AA_I2C_SIZED_READ	See aa_i2c_read below.
   AA_I2C_SIZED_READ_EXTRA1	See aa_i2c_read below.

6. Since firmware revision 3.00 it is possible for the Aardvark I²C master to return an extended status code for master read and master write transactions. These codes are described in Table 6 and are returned by the aa_i2c_read_ext and aa_i2c_write_ext functions, as well as the analogous slave API functions.
   
   
   Table 6 : I²C Extended Status Code

   AA_I2C_STATUS_BUS_ERROR	A bus error has occurred. Transaction was aborted.
   AA_I2C_STATUS_SLA_ACK	Bus arbitration was lost during master transaction; another master on the bus has successfully addressed this Aardvark adapters slave address. As a result, this Aardvark adapter has automatically switched to slave mode and is responding.
   AA_I2C_STATUS_SLA_NACK	The Aardvark adapter failed to receive acknowledgment for the requested slave address during a master operation.
   AA_I2C_STATUS_DATA_NACK	The last data byte in the transaction was not acknowledged by the slave.
   AA_I2C_STATUS_ARB_LOST	Another master device on the bus was accessing the bus simultaneously with this Aardvark adapter. That device won arbitration of the bus as per the I2Cspecification.
   AA_I2C_STATUS_BUS_LOCKED	An I2C packet is in progress, and the time since the last I2C event executed or received on the bus has exceeded the bus lock timeout. This is most likely due to the clock line of the bus being held low by some other device, or due to the data line held low such that a start condition cannot be executed by the Aardvark. The bus lock timeout can be configured using the aa_i2c_bus_timeout function. The Aardvark adapter resets its own I2C interface when a timeout is observed and no further action is taken on the bus.
   AA_I2C_STATUS_LAST_DATA_ACK	When the Aardvark slave is configured with a fixed length transmit buffer, it will detach itself from the I2C bus after the buffer is fully transmitted. The Aardvark slave also expects that the last byte sent from this buffer is NACKed by the opposing master device. This status code is returned by the Aardvark slave (see Slave Write Statistics API) if the master device instead ACKs the last byte. The notification can be useful when debugging a third-party master device.

   These codes can provide hints as to why an impartial transaction was executed by the Aardvark adapter. In the event that a bus error occurs while the Aardvark adapter is idle and enabled as a slave (but not currently receiving a message), the adapter will return the bus error through the aa_i2c_slave_read function. The length of the message will be 0 bytes but the status code will reflect the bus error.

5.5.2 General I²C

Top

I²C Pullup (aa_i2c_pullup)

      int aa_i2c_pullup (Aardvark aardvark, aa_u08 pullup_mask);     

Activate/deactivate I²C pull-up resistors on SCL and SDA.

Top

Free bus (aa_i2c_free_bus)

      int aa_i2c_free_bus (Aardvark aardvark);     

Free the Aardvark I²C subsystem from a held bus condition (e.g., "no stop").

Top

Set Bus Lock Timeout (aa_i2c_bus_timeout)

      int aa_i2c_bus_timeout (Aardvark aardvark, aa_u16 timeout_ms);     

Set the I²C bus lock timeout in milliseconds.

5.5.3 I²C Master

Top

Set Bitrate (aa_i2c_bitrate)

      int aa_i2c_bitrate (Aardvark aardvark, int bitrate_khz);     

Set the I²C bitrate in kilohertz.

Top

Master Read (aa_i2c_read)

      int aa_i2c_read (Aardvark            aardvark,                        aa_u16              slave_addr,                        AardvarkI2cFlags    flags,                        aa_u16              num_bytes,                        aa_u08 *            data_in);     

Read a stream of bytes from the I²C slave device.

Top

Master Read Extended (aa_i2c_read_ext)

      int aa_i2c_read_ext (Aardvark            aardvark,                            aa_u16              slave_addr,                            AardvarkI2cFlags    flags,                            aa_u16              num_bytes,                            aa_u08 *            data_in,                            aa_u16 *            num_read);     

Read a stream of bytes from the I²C slave device with extended status information.

Top

Master Write (aa_i2c_write)

      int aa_i2c_write (Aardvark         aardvark,                         aa_u16           slave_addr,                         AardvarkI2cFlags flags,                         aa_u16           num_bytes,                         const aa_u08 *   data_out);     

Write a stream of bytes to the I²C slave device.

Top

Master Write Extended (aa_i2c_write_ext)

      int aa_i2c_write_ext (Aardvark            aardvark,                             aa_u16              slave_addr,                             AardvarkI2cFlags    flags,                             aa_u16              num_bytes,                             const aa_u08 *      data_out,                             aa_u16 *            num_written);     

Write a stream of bytes to the I²C slave device with extended status information.

Top

Master Write-Read (aa_i2c_write_read)

      int aa_i2c_write_read (Aardvark           aardvark,                              aa_u16             slave_addr,                              AardvarkI2cFlags   flags,                              aa_u16             out_num_bytes,                              const aa_u08 *     out_data,                              aa_u16 *           num_written,                              aa_u16             in_num_bytes,                              aa_u08 *           in_data,                              aa_u16 *           num_read);     

Write a stream of bytes to the I²C slave device followed by a read from the same slave device.

5.5.4 I²C Slave

Top

Slave Enable (aa_i2c_slave_enable)

      int aa_i2c_slave_enable (Aardvark      aardvark,                                aa_u08        addr,                                aa_u16        maxTxBytes,                                aa_u16        maxRxBytes);     

Enable the Aardvark adapter as an I²C slave device.

Top

Slave Disable (aa_i2c_slave_disable)

      int aa_i2c_slave_disable (Aardvark aardvark);     

Disable the Aardvark adapter as an I²C slave device.

Top

Slave Set Response (aa_i2c_slave_set_response)

      int aa_i2c_slave_set_response (Aardvark         aardvark,                                      aa_u08           num_bytes,                                      const aa_u08 *   data_out);     

Set the slave response in the event the Aardvark adapter is put into slave mode and contacted by a master.

Top

Slave Write Statistics (aa_i2c_slave_write_stats)

      int aa_i2c_slave_write_stats (Aardvark aardvark);     

Return number of bytes written from a previous Aardvark I²C slave to I²C master transmission.

Top

Slave Write Statistics Extended (aa_i2c_slave_write_stats_ext)

      int aa_i2c_slave_write_stats_ext (Aardvark    aardvark,                                         aa_u16 *    num_written);     

Return number of bytes written from a previous Aardvark I²C slave to I²C master transmission with extended status information.

Top

Slave Read (aa_i2c_slave_read)

      int aa_i2c_slave_read (Aardvark     aardvark,                              aa_u08 *     addr,                              aa_u16       num_bytes,                              aa_u08 *     data_out);     

Read the bytes from an I²C slave reception.

Top

Slave Read Extended (aa_i2c_slave_read_ext)

      int aa_i2c_slave_read_ext (Aardvark    aardvark,                                  aa_u08 *    addr,                                  aa_u16      num_bytes,                                  aa_u08 *    data_out                                  aa_u16 *    num_read);     

Read the bytes from an I²C slave reception with extended status information.

Top

5.6 SPI Interface

5.6.1 SPI Notes

1. The SPI master and slave must both be configured to use the same bit protocol (mode).
2. It is not necessary to set the bitrate for the Aardvark SPI slave.
3. An SPI master operation read or write operation can be transacted while leaving the SPI slave functionality enabled. During the master transaction, the slave will be temporarily deactivated. Once the master transaction is complete, the slave will be automatically reactivated.
4. It is always advisable to set the slave response before first enabling the slave. This ensures that valid data is sent to any requesting master.
5. It is not possible to receive messages larger than approximately 4 KiB as a slave due to operating system limitations on the asynchronous incoming buffer. As such, one should not queue up more than 4 KiB of total slave data between calls to the Aardvark API.
6. It is not possible to send messages larger than approximately 4 KiB as a master due to operating system limitations on the asynchronous incoming buffer. The SPI is full-duplex so there must be enough buffer space to accommodate the slave response when sending as a master.
7. Sending zero bytes as an SPI master will simply toggle the slave select line for 5-10 µs.

5.6.2 General SPI

Top

Configure (aa_spi_configure)

      int aa_spi_configure (Aardvark                aardvark,                             AardvarkSpiPolarity     polarity,                             AardvarkSpiPhase        phase,                             AardvarkSpiBitorder     bitorder);     

Configure the SPI master or slave interface.

5.6.3 SPI Master

Top

Set Bitrate (aa_spi_bitrate)

      int aa_spi_bitrate (Aardvark aardvark, int bitrate_khz);     

Set the SPI bitrate in kilohertz.

Top

Set Slave Select Polarity (aa_spi_master_ss_polarity)

      int aa_spi_master_ss_polarity (Aardvark                aardvark,                                      AardvarkSpiSSPolarity   polarity);     

Change the output polarity on the SS line.

Top

Master Write/Read (aa_spi_write)

      int aa_spi_write (Aardvark         aardvark,                         aa_u16           out_num_bytes,                         const aa_u08 *   data_out,                         aa_u16           in_num_bytes,                         aa_u08 *         data_in);     

Write a stream of bytes to the downstream SPI slave device and read back the full-duplex response.

5.6.4 SPI Slave

Top

Slave Enable (aa_spi_slave_enable)

      int aa_spi_slave_enable (Aardvark aardvark);     

Enable the Aardvark as an SPI slave device.

Top

Slave Disable (aa_spi_slave_disable)

      int aa_spi_slave_disable (Aardvark aardvark);     

Disable the Aardvark as an SPI slave device.

Top

Slave Set Response (aa_spi_slave_set_response)

      int aa_spi_slave_set_response (Aardvark         aardvark,                                      aa_u08           num_bytes,                                      const aa_u08 *   data_out);     

Set the slave response in the event the Aardvark adapter is put into slave mode and contacted by a master.

Top

Slave Read (aa_spi_slave_read)

      int aa_spi_slave_read (Aardvark     aardvark,                              aa_u16       num_bytes,                              aa_u08 *     data_in);     

Read the bytes from an SPI slave reception.

Top

5.7 GPIO Interface

5.7.1 GPIO Notes

1. The following enumerated type maps the named lines on the Aardvark I²C/SPI output cable to bit positions in the GPIO API. All GPIO API functions will index these lines through a single 8-bit masked value. Thus, each bit position in the mask can be referred back its corresponding line through the mapping described below.
   Table 8 : AardvarkGpioBits : enumerated type of line locations in bit mask

   AA_GPIO_SCL	Pin 1	0x01	I2C SCL line
   AA_GPIO_SDA	Pin 3	0x02	I2C SDA line
   AA_GPIO_MISO	Pin 5	0x04	SPI MISO line
   AA_GPIO_SCK	Pin 7	0x08	SPI SCK line
   AA_GPIO_MOSI	Pin 8	0x10	SPI MOSI line
   AA_GPIO_SS	Pin 9	0x20	SPI SS line

2. There is no check in the GPIO API calls to see if a particular GPIO line is enabled in the current configuration. If a line is not enabled for GPIO, the get function will simply return 0 for those bits. Another example is if one changes the GPIO directions for I²C lines while the I²C subsystem is still active. These new direction values will be cached and will automatically be activate if a later call to aa_configure disables the I²C subsystem and enables GPIO for the I²C lines. The same type of behavior holds for aa_gpio_pullup and aa_gpio_set.
3. Additionally, for lines that are not configured as inputs, a change in the pullup configuration using aa_gpio_pullup will be cached and will take effect the next time the line is active and configured as an input. The same behavior holds for aa_gpio_set when a line is configured as an input instead of an output.
4. On Aardvark adapter power-up, directions default to all input, pullups default to disabled and outputs default to logic low. Also the GPIO subsystem is off by default. It must be activated by using aa_configure.
5. Note: For hardware version 1.02, it is not possible to have high-Z inputs on the I²C lines since that hardware has 2.2K pullups on the I²C bus.

5.7.2 GPIO Interface

Top

Direction (aa_gpio_direction)

      int aa_gpio_direction (Aardvark     aardvark,                              aa_u08       direction_mask);     

Change the direction of the GPIO lines between input and output directions.

Top

Pullup (aa_gpio_pullup)

      int aa_gpio_pullup (Aardvark      aardvark,                           aa_u08        pullup_mask);     

Change the pullup configuration of the GPIO lines.

Top

Get (aa_gpio_get)

      int aa_gpio_get (Aardvark aardvark);     

Get the value of current GPIO inputs.

Top

Set (aa_gpio_set)

      int aa_gpio_set (Aardvark     aardvark,                        aa_u08       value);     

Set the value of current GPIO outputs.

Top

Change (aa_gpio_change)

      int aa_gpio_change (Aardvark     aardvark,                           aa_u16       timeout);     

Block until there is a change on the GPIO input lines.

Top

5.8 Error Codes

6 Legal / Contact

Top

6.1 Disclaimer

All of the software and documentation provided in this manual, is copyright Total Phase, Inc. ("Total Phase"). License is granted to the user to freely use and distribute the software and documentation in complete and unaltered form, provided that the purpose is to use or evaluate Total Phase products. Distribution rights do not include public posting or mirroring on Internet websites. Only a link to the Total Phase download area can be provided on such public websites.

Total Phase shall in no event be liable to any party for direct, indirect, special, general, incidental, or consequential damages arising from the use of its site, the software or documentation downloaded from its site, or any derivative works thereof, even if Total Phase or distributors have been advised of the possibility of such damage. The software, its documentation, and any derivative works is provided on an "as-is" basis, and thus comes with absolutely no warranty, either express or implied. This disclaimer includes, but is not limited to, implied warranties of merchantability, fitness for any particular purpose, and non-infringement. Total Phase and distributors have no obligation to provide maintenance, support, or updates.

Information in this document is subject to change without notice and should not be construed as a commitment by Total Phase. While the information contained herein is believed to be accurate, Total Phase assumes no responsibility for any errors and/or omissions that may appear in this document.

Top

6.2 Life Support Equipment Policy

Total Phase products are not authorized for use in life support devices or systems. Life support devices or systems include, but are not limited to, surgical implants, medical systems, and other safety-critical systems in which failure of a Total Phase product could cause personal injury or loss of life. Should a Total Phase product be used in such an unauthorized manner, Buyer agrees to indemnify and hold harmless Total Phase, its officers, employees, affiliates, and distributors from any and all claims arising from such use, even if such claim alleges that Total Phase was negligent in the design or manufacture of its product.

Top

6.3 Contact Information

Total Phase can be found on the Internet at http://www.totalphase.com/. If you have support-related questions, please go to the Total Phase website. For sales inquiries, please contact [email protected] .