Aardvark v3.30
Uploaded by
Agustín RamírezAardvark v3.30
Uploaded by
Agustín RamírezAardvark I2C/SPI Embedded Systems Interface
Features
2
I C Two wire interface
Standard mode (100 kbps) and fast mode (400 kbps)
Variable bitrate (1-800 kbps)
Byte throughput rates are near theoretical maximums
Master transmit and receive
Asynchronous slave transmit and receive
Repeated start, 10-bit addressing, and combined format
SPI 4 wire serial communication protocol A ARDVARK
I 2C/SPI
Up to 8 Mbps master signaling rate
Up to 4 Mbps slave signaling rate
Full duplex master transmit/receive Aardvark I2C/SPI
Asynchronous slave transmit/receive Embedded Systems Interface
Con gurable slave select polarity for master mode
GPIO General Purpose Input/Output
General purpose signaling on I2C and/or SPI pins
Internal caching of GPIO con guration Data Sheet v3.30
2
I C Monitor August 31, 2006
Unobtrusively record tra c on an I2C bus
Supports bus speeds up to 125 kHz
USB host communication
Up to 3 Mbps transfer to host PC
Powered from USB, eliminating power adapters
Reports as a full-speed device (12 Mbps) to USB 2.0 hosts
Software API
Linux and Windows compatible
Easy to integrate application interface
Upgradeable Firmware
Field upgradeable over USB
Error checking prevents upgrade disasters
Summary
2
The Aardvark I C/SPI Embedded Systems Interface is a host adapter through
USB. It allows a developer to interface a host PC to a downstream embed-
2
ded system environment and transfer serial messages using the I C and SPI
2
protocols. I C and SPI functionality can be used concurrently. Additionally,
2
the I C and/or SPI pins can be used for general purpose signaling when the
2
respective subsystem is not in use. An I C monitoring feature is also available
2
to unobtrusively record tra c on an I C bus.
www.totalphase.com © 2006 Total Phase, Inc.
Aardvark I2C/SPI Embedded Systems Interface
1 General Overview
1.1 I2C Background
I2C 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.
2 2
To solve this problem, Philips developed InterIC 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).
Master SDA
SCL
Slave Slave Slave
Figure 1: Sample I2C Implementation.
Regardless of how many slave units are attached to the I2C 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 speci c slave device.
Because all commnication takes place on only two wires, all devices must have a unique
address to identify it on the bus. Slave devices have a prede ned address, but the lower bits
of the address can be assigned to allow for multiples of the same devices on the bus.
I2C Theory of Operation
2
I C has a master/slave protocol. The master initiates the communication. Here is a simpli ed
2
description of the protocol. For precise details, please refer to the Philips I C speci cation.
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 ag.
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.
www.totalphase.com 2
Aardvark I2C/SPI Embedded Systems Interface
5. When the communication is complete, the master issues a stop condition indicating
that everything is done.
2
Figure 2 shows a sample bitstream of the I C protocol.
Figure 2: I2C Protocol.
Since there are only two wires, this protocol includes the extra overhead of the addressing and
acknowledgement mechanisms.
I2C Features
2
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,
10bit Addressing,
Multimaster support,
Data broadcast (general call).
For more information about other features, see the references at the end of this section.
I2C Bene ts and Drawbacks
2
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 ine cient in simple con gurations and a
directlink interface such as SPI might be preferred.
I2C References
2
I C bus NXP (Philips) Semiconductors O cial I2C website
2
I C (Inter-Integrated Circuit) Bus Technical Overview and Frequently Asked Questions
Embedded Systems Academy
Introduction to I C Embedded.com
2
I C Open Directory Project Listing
2
www.totalphase.com 3
Aardvark I2C/SPI Embedded Systems Interface
1.2 SPI Background
SPI History
SPI is a serial communication bus developed by Motorola. It is a fullduplex protocol which
functions on a masterslave paradigm that is ideally suited to data streaming applications.
SPI Theory of Operation
SPI requires four signals: clock (SCLK), master output/slave input (MOSI), master in-
put/slave output (MISO), slave select (SS).
Master Slave 1
SCLK SCLK
MOSI MOSI
MISO MISO
SS1 SS
SS2
SS3
Slave 2
SCLK
MOSI
MISO
SS
Slave 3
SCLK
MOSI
MISO
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 slave's SS line to select a device
for communication.
The exchange itself has no prede ned protocol. This makes it ideal for datastreaming
applications. Data can be transferred at high speed, often into the range of the tens of
megahertz. The ipside is that there is no acknowledgment, no ow control, and the master
may not even be aware of the slave's presence.
www.totalphase.com 4
Aardvark I2C/SPI Embedded Systems Interface
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 gure 4.
Clock Phase (CPHA)
CPHA = 0 CPHA = 1
sample sample
Clock Polarity (CPOL)
CPOL = 0
MODE 0 MODE 1
CPOL = 1
MODE 2 MODE 3
sample sample
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.
SPI Bene ts and Drawbacks
SPI is a very simple communication protocol. It does not have a speci c highlevel 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 e cient 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.
SPI References
Introduction to Serial Peripheral Interface Embedded.com
SPI Serial Peripheral Interface
www.totalphase.com 5
Aardvark I2C/SPI Embedded Systems Interface
2 Hardware Speci cations
2.1 Pinouts
Connector Speci cation
The ribbon cable connector is a standard 0.100 (2.54mm) 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.
Orientation
The ribbon cable pin order follows the standard convention. The red line indicates the rst
position. When looking at your Aardvark adapter in the upright position ( gure 5), pin 1 is
in the top left corner and pin 10 is in the bottom right corner.
Figure 5: The Aardvark I2C/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 ip your Aardvark adapter over ( gure 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 I2C/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.
Order of Leads
1. SCL
2. GND
3. SDA
4. NC/+5V
5. MISO
6. NC/+5V
7. SCLK
www.totalphase.com 6
Aardvark I2C/SPI Embedded Systems Interface
8. MOSI
9. SS
10. GND
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.
I2C 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.
SPI Pins
SCLK (Pin 7):
Serial Clock control line that is driven by the master and regulates the ow 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 o via hardware control.
Powering Downstream Devices
2
It is possible to power a downstream target, such as an I C or SPI EEPROM with the
Aardvark adapter's power (which is provided by the USB port). It is ideal if the downstream
device does not consume more than 2030 mA. 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,
www.totalphase.com 7
Aardvark I2C/SPI Embedded Systems Interface
leaving approximately 400 mA for any downstream target. However, the Aardvark adapter
always reports itself to the host as a lowpower device (≤ 100 mA). Therefore, drawing large
amounts of current from the host is not advisable.
NC/+5V (Pin 4): I2C 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 50 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 modi cations are at the
user's own risk.
2.2 Signal Levels/Voltage Ratings
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 TTLcompliant devices since such devices are ordinarily speci ed to
accept logic high inputs above approximately 3 volts.
ESD protection
The Aardvark adapter has builtin electrostatic discharge protection to prevent damage to
the unit from high voltage static electricity.
Drive Current
The Aardvark adapter can drive all output signals with a maximum of 10 mA current source
or sink.
2.3 I2C Signaling Characteristics
Speed
2
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
2
poweron 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.
2
For hardware versions before 3.00, the maximum I C master bitrate is 663 kbps and the
2
maximum I C slave bitrate is 595 kbps.
www.totalphase.com 8
Aardvark I2C/SPI Embedded Systems Interface
It is not possible to send bytes at a throughput of exactly 1/8 times the bitrate. The
2
I C protocol requires that 9 bits are sent for every 8 bits of data. There is also a nite time
required to setup 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).
Pullup Resistors
2
There is a 2.2K resistor on each I C line (SCL, SDA). The lines are eectively pulled up
to 3.3V, resulting in approximately 1.5 mA of pullup current. If the Aardvark adapter is
2
connected to an I C bus that also includes pullup resisters, the total pullup current could
2
be potentially larger. The I C speci cation allows for a maximum of 3 mA pullup current
2
on each I C line.
2
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 pullup resistors and larger sink currents may
be required for fast bit rates, 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'
pullup resistors enabled.
Hardware versions 2.00 and later have the ability to switch the pullup resistors by through
the software API. Refer to the API section for more details.
I2C Clock Stretching
2
When the Aardvark adapter is con gured as an I C master, it supports both interbit and
interbyte slave clockstretching. If a slave device pulls SCL low during a transaction, the
adapter will wait until SCL has been released before continuing with the transaction.
Known I2C Limitations
Since rmware version 2.00, the Aardvark adapter supports the repeated start, 10bit ad-
2
dressing, and combined format features of the I C protocol.
Since rmware 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.
Multimaster 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
www.totalphase.com 9
Aardvark I2C/SPI Embedded Systems Interface
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
2
This constraint can be phrased in a dierent manner. Say that I C master device A has a
packet length of X 2
bytes. If there is a second I C master device, B, that sends packets of
length greater than X bytes, the rst X bytes should never contain exactly the same data as
the data sent by device A. Otherwise the results of the arbitration will be unde ned.
2
This is a constraint found with most I C master devices used in a multimaster environment.
2.4 SPI Signaling Characteristics
SPI Waveforms
The SPI signaling is characterized by the waveforms in Figures 7 and 8.
SS
t1 t2
SCLK
tp
MISO MISO
MOSI MOSI
Figure 7: SPI Waveform
Three dierent times are of note: t1 , time from the assertion of SS# to the rst clock cycle; t2 ,
time from the last clock cycle and the deassertion of SS#; tp , clock period.
Table 1: SPI Timing Parameters
Symbol Parameter Min Max Units
t1 SS# assertion to rst clock 10 20 µs
t2 Last clock to SS# deassertion 5 10 µs
tp Clock period 125 8000 ns
td Setup time (Master) 7 9 µs
td Setup time (Slave) 4 n/a µs
tb Time between start of bytes (Slave) 10 n/a µs
www.totalphase.com 10
Aardvark I2C/SPI Embedded Systems Interface
Figure 8: SPI Byte Timing
td is the setup time between SPI bytes and tb is the total byte-to-byte time.
Speeds
The Aardvark SPI master can operate at bitrates of 125 kHz, 250 kHz, 500 kHz, 1 MHz, 2
MHz, 4 MHz, and 8 MHz. The poweron default bitrate is 1000 kHz. 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 con gured 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 intertransaction time, but a
suggested spacing is approximately 100200 µs.
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 ght the
master lines in the new environment.
Consequently, any SPI slave target to which the Aardvark adapter is interfaced must have a
pullup resistor on its slave select line, preventing uttering of the voltage when the Aardvark
adapter stops driving the signal. It is also advisable that every slave also have passive pullups
on the MOSI and SCK lines. These pullup resistors can be relatively weak 100k should
be adequate.
www.totalphase.com 11
Aardvark I2C/SPI Embedded Systems Interface
As a slave, the MOSI, SCK, and SS lines are con gured as an input and the MISO line is
con gured as an output. This con guration is held as long as the slave mode is enabled (see
the API documentation later in the datasheet).
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 signi cant 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 x 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 fullduplex nature of the SPI signaling.
Aardvark Device Power Consumption
The Aardvark adapter consumes less than 100 mA of current. This is within the USB 1.1
current speci cation for devices powered from a USB host adapter (500 mA maximum per
device) or a USB hub (100 mA maximum per device).
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
2.6 Temperature Speci cations
The Aardvark device is designed to be operated at room temperature (1035
◦ C). The
◦
electronic components are rated for standard commercial speci cations (070 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 speci cation
will void the hardware warranty.
www.totalphase.com 12
Aardvark I2C/SPI Embedded Systems Interface
3 Software
3.1 Compatibility
Linux Compatibility
The Aardvark software is compatible with all standard distributions of Linux with integrated
USB support. Kernel 2.4.18 or greater is recommended.
Windows Compatibility
The Aardvark software is also compatible with Windows 2000 and Windows XP. The soft-
ware'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.
3.2 Linux USB Driver
As of version 3.0, the Aardvark communications layer under Linux no longer requires a speci c
kernel driver to operate. It does however require that /proc/bus/usb is mounted on the
system which is the case on most standard distributions.
There are two dierent ways to access the Aardvark adapter, through USB hotplug or by
mounting the entire USB lesystem as world writable. The hotplug method is the preferred
method because only the Aardvark adapter would be world writable and hence more secure.
USB Hotplug
USB hotplug requires two con guration les which are available for download from the Total
Phase web site. These les 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).
Driver Installation/Uninstallation
Here is an alternative method of con guring your Linux system in the event that your dis-
tribution does not have hotplug capabilities. The following procedure is not necessary if you
were able to exercise the steps in the previous subsection.
Often, the /proc/bus/usb directory is mounted with readwrite permissions for root and
readonly permissions for all other users. If an nonprivileged user wishes to use the Aardvark
adapter and software, one must ensure that /proc/bus/usb is mounted with readwrite
www.totalphase.com 13
Aardvark I2C/SPI Embedded Systems Interface
permissions for all users. The following steps can help setup the correct permissions. Please
note that these steps will make the entire USB lesystem 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 le:
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.
3.3 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 rst Aardvark adapter that is plugged into the PC. Subsequent plugs
and unplugs are automatically handled by the operating system.
Windows 2000:
1. When you plug in the Aardvark adapter into your PC for the rst time, Windows will
present the Found New Hardware Wizard. Select Next.
2. On the next dialog window, select Search for a suitable driver for my device (recom-
mended) and click Next.
3. On the third screen, uncheck all settings and check Specify a location and click
Next.
4. Click Browse. . . , navigate to either the CDROM ( \usb-drivers\windows directory),
or temporary directory where the driver les have been unpacked (for downloaded
updates).
5. Select ftd2xx.inf and click Open, then click Ok.
6. Click Next on the subsequent screen, followed by Finish to complete the installation.
This completes the installation of the USB driver.
Windows XP:
www.totalphase.com 14
Aardvark I2C/SPI Embedded Systems Interface
1. When you plug in the Aardvark adapter into your PC for the rst time, Windows will
present the Found New Hardware Wizard.
2. Select Install from a list or speci c location (Advanced) and click Next.
3. Select Search for best driver in these locations:, uncheck Search removable media,
check Include this location in the search.
4. Click Browse. . . , expand My Computer and navigate to either the CDROM ( \usb-
drivers\windows directory), or temporary directory where the driver les have been
unpacked (for downloaded updates).
5. Click OK, then click Next.
6. A dialog will inform the user that the USB driver has been installed. Click Finish.
Both Windows 2000 and Windows XP:
7. Once the installation is complete, con rm that the installation was successful by check-
ing that the device appears in the Device Manager. To navigate to the Device Man-
ager screen select Control Panel | System Properties | Hardware | Device Manager.
8. 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.
1. Navigate to either the CDROM ( \usb-drivers\windows directory), or temporary
directory where the driver les have been unpacked (for downloaded updates).
2. Run FTD2XXUN.EXE and follow the instructions.
3.4 USB Port Assignment
The Aardvark adapter is assigned a port on a sequential basis. The rst 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.
www.totalphase.com 15
Aardvark I2C/SPI Embedded Systems Interface
3.5 Aardvark Dynamically Linked Library
DLL Philosophy
The Aardvark DLL provides a robust approach to allow presentday Aardvarkenabled appli-
cations to interoperate with future versions of the device interface software without recompi-
lation. For example, take the case of a graphical application that is written to communicate
2
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 ver-
sion 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 rst 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, 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 speci c programming language environment. For example, for a C or C++
application, the following rules apply:
On a Linux system this is as follows:
1. First, search for the shared object in the application binary path. Note, that this step
requires /proc lesystem support, which is standard in 2.4.x kernels. If the /proc
lesystem is not present, this step is skipped.
2. Next, search in the application's current working directory.
3. Search the paths explicitly speci ed in LD_LIBRARY_PATH.
4. Finally, check any system library paths as speci ed in /etc/ld.so.conf and cached
in /etc/ld.so.cache.
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. 32bit system directory. (Ex: c:\winnt\System32) [Windows NT/2000/XP only]
4. 16bit system directory. (Ex: c:\winnt\System or c:\windows\system)
5. The windows directory. (Ex: c:\winnt or c:\windows)
6. The directories listed in the PATH environment variable.
www.totalphase.com 16
Aardvark I2C/SPI Embedded Systems Interface
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 rmware of a given Aardvark device is compat-
ible. Each DLL revision is tagged as being compatible with rmware revisions greater than
or equal to a certain version number. Likewise, each rmware version is tagged as being
compatible with DLL revisions greater than or equal to a speci c 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 rmware less than version 1.15 and the rmware
is not compatible with any DLL less than version 1.20. In this example, the version number
constraints are satis ed and the DLL can safely connect to the target rmware 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.6 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. Dierent
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, and Visual Basic. 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.
1. Include the aardvark.h le 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 les 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.
www.totalphase.com 17
Aardvark I2C/SPI Embedded Systems Interface
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 DLLFirmware crossvalidation 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 le according to speci c 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 speci c paradigm. See the comments in aardvark.c for more details.
3.7 Application Notes
Asynchronous Messages
There is buering within the Aardvark DLL, on a perdevice basis, to help capture asyn-
chronous messages.
2
Take the case of the Aardvark adapter receiving I C messages asyn-
chronously. If the application calls the function to change the SPI bitrate while some unpro-
cessed asynchronous messages are pending, the Aardvark adapter will transact the bitrate
2
change but also save any pending I C messages internally. The messages will be held until
the appropriate API function is called.
2
The size of the I C and SPI buers are 16 KiB each and they can hold many separate
transactions. The buers are only used when an Aardvark API call is invoked. The buer
size is adequate since the overall limitation for asynchronous messages is fundamentally
determined by the operating system's internal buer size. This concept is explained below.
Receive Saturation
2
The Aardvark adapter can be con gured 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 buered somewhere in memory. This is accomplished on the PC
host, courtesy of the operating system. Naturally the buer is limited in size and once this
buer is full, bytes will be dropped.
An over ow 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 aect
www.totalphase.com 18
Aardvark I2C/SPI Embedded Systems Interface
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 buer),
2
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 system's receive buer 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 buer! 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 tra c that is sent by the master between calls to the Aardvark API.
This will require the ability to recon gure the oending 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 singlethreaded environments so as to allow for maximum
crossplatform compatibility. If the application design requires multithreaded use of the
Aardvark functionality, each Aardvark API call can be wrapped with a threadsafe locking
mechanism before and after invocation. A call to any Aardvark API function that com-
municates with the host synchronously will also fetch any pending asynchronous messages,
buering 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 12 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.
www.totalphase.com 19
Aardvark I2C/SPI Embedded Systems Interface
4 Firmware
4.1 Field Upgrades
Upgrade Philosophy
The Aardvark adapter is designed so that its internal rmware can be upgraded by the user,
thereby allowing the inclusion of any performance enhancements or critical xes 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 rmware 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 (pre3.00 rmware 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 identi er. Upgrading the legacy rmware 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 rmware upgrade. Please refer to the section on
USB driver installation above for more information on how to install the new driver.
Upgrade Procedure
Here is the simple procedure by which the Aardvark rmware is upgraded.
1. Download the latest rmware from the Total Phase website.
2. Unzip the downloaded le. It should contain the aaflash utility. This utility contains
the necessary information to perform the entire rmware update.
3. Run aaflash (aaflash.exe on Windows or aaflash on Linux). It will rst display
the rmware version contained in the utility along with the required hardware version
to run this rmware version.
4. It will list all of the detected devices along with their current rmware and hardware
versions.
5. Select a device to upgrade. Note the rmware and hardware version of the device
before proceeding. If the selected device's hardware is not suitable to accept the new
rmware, 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 rmware. 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 Aardvarkenabled appli-
cation.
www.totalphase.com 20
Aardvark I2C/SPI Embedded Systems Interface
8. In the event that there was a malfunction in the rmware update, the Aardvark adapter
may not be recognizable by an Aardvarkenabled 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 eect, it is best to revert back to the
previous rmware. This can be done by running a previous version of aaflash that
contains an earlier rmware version. Check the Total Phase website or the distribution
CD that was included with your Aardvark adapter for previous versions of the rmware.
www.totalphase.com 21
Aardvark I2C/SPI Embedded Systems Interface
5 API Documentation
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 dierences will be found in the calling convention of
the functions. For further information on such dierences please refer to the documentation
that accompanies each language bindings in the Aardvark software distribution.
5.2 General Data Types
The following de nitions 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;
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 un-
derlying Aardvark DLL, AA_UNABLE_TO_LOAD_LIBRARY and AA_INCOMPATIBLE_LIBRARY. If
these status codes are received, refer to the previous sections in this datasheet 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 sys-
tem. 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
oending API function.
2
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
www.totalphase.com 22
Aardvark I2C/SPI Embedded Systems Interface
as a result of the incoming USB receive buer being full. The error signi es 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 buer is saturated, an API call to disable the slave may
return AA_COMMUNICATION_ERROR even though the slave has actually been disabled.
2
If either the I C or SPI subsystems have been disabled by aa_con gure, all other API functions
2
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 speci c 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.
www.totalphase.com 23
Aardvark I2C/SPI Embedded Systems Interface
5.4 General
Interface
Find Devices (aa_ nd_devices)
int aa_find_devices (int nelem,
aa_u16 * devices);
Get a list of ports to which Aardvark devices are attached.
Arguments
nelem: Maximum size of the array
devices: array into which the port numbers are returned
Return Value
This function returns the number of devices found, regardless of the array size.
Speci c Error Codes
None.
Details
Each element of the array is written with the port number.
Devices that are in use are OR'ed with AA_PORT_NOT_FREE (0x8000). Under Linux, such
devices correspond to Aardvark adapters that are currently in use. Under Windows, such
devices are currently in use, but it is not known if the device is an Aardvark adapter.
Example:
Devices are attached to port 0, 1, 2
ports 0 and 2 are available, and port 1 is inuse.
array => 0x0000, 0x8001, 0x0002;
If the input array is NULL, it is not lled with any values.
If there are more devices than the array size (as speci ed by nelem), only the rst nelem
port numbers will be written into the array.
Find Devices (aa_ nd_devices_ext)
int aa_find_devices_ext (int nelem,
aa_u16 * devices,
aa_u32 * unique_ids);
Get a list of ports and unique IDs to which Aardvark devices are attached.
Arguments
nelem: Maximum size of the array
devices: array into which the port numbers are returned
unique_ids: array into which the unique IDs are returned
Return Value
www.totalphase.com 24
Aardvark I2C/SPI Embedded Systems Interface
This function returns the number of devices found, regardless of the array size.
Speci c Error Codes
None.
Details
This function is the same as aa_find_devices() except that is also returns the unique IDs
of each Aardvark device. The IDs are guaranteed to be nonzero if valid.
The IDs are the unsigned integer representation of the 10digit serial numbers.
Open an Aardvark device (aa_open)
Aardvark aa_open (int port_number);
Open the Aardvark port.
Arguments
port_number: The port number is the the same as the one obtained from function
aa_find_devices. It is a zerobased number.
Return Value
This function returns an Aardvark handle, which is guaranteed to be greater than zero if
valid.
Speci c Error Codes
AA_UNABLE_TO_OPEN: The speci ed port is not connected to an Aardvark device or the port
is already in use.
AA_INCOMPATIBLE_DEVICE: There is a version mismatch between the DLL and the rmware.
The DLL is not of a su cient version for interoperability with the rmware version or
vice versa. See aa_open_ext() for more information.
Details
This function is recommended for use in simple applications where extended information is
not required. For more complex applications, the use of aa_open_ext() is recommended.
The open function also deactivates all slave functionality. An Aardvark device could have
potentially been opened, enabled as a slave, and con gured to send asynchronous responses
to a thirdparty master. If the controlling application quits without calling aa_close(), the
port is freed but the slave functions can still be active. The open function deactivates slave
functionality to ensure that the new application has access to an Aardvark device that is in
2
a knownstate. Also the I C bus is freed, in the event that it was held inde nitely from a
previous AA_I2C_NO_STOP transaction.
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.
Arguments
port_number: same as aa_open
www.totalphase.com 25
Aardvark I2C/SPI Embedded Systems Interface
aa_ext: pointer to preallocated structure for extended version information available on
open
Return Value
This function returns an Aardvark handle, which is guaranteed to be greater than zero if
valid.
Speci c Error Codes
AA_UNABLE_TO_OPEN: The speci ed port is not connected to an Aardvark device or the port
is already in use.
AA_INCOMPATIBLE_DEVICE: There is a version mismatch between the DLL and the rmware.
The DLL is not of a su cient version for interoperability with the rmware version or vice
versa. The version information will be available in the memory pointed to by aa_ext.
Details
If 0 is passed as the pointer to the structure, this function will behave exactly like aa_open().
The AardvarkExt structure is described below:
struct AardvarkExt {
AardvarkVersion version;
/* Features of this device. */
int features;
}
The features eld denotes the capabilities of the Aardvark device. See the API function
aa_features for more information.
The AardvarkVersion structure describes the various version dependencies of Aardvark
components. It can be used to determine which component caused an incompatibility error.
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;
};
All version numbers are of the format:
(major 8) | minor
example: v1.20 would be encoded as 0x0114.
www.totalphase.com 26
Aardvark I2C/SPI Embedded Systems Interface
The structure is zeroed before the open is attempted. It is lled with whatever information
is available. For example, if the rmware version is not lled, then the device could not be
queried for its version number.
This function is recommended for use in complex applications where extended information is
required. For simpler applications, the use of aa_open() is recommended.
This open function also terminates all slave functionality as described for the aa_open()
call.
Close an Aardvark (aa_close)
int aa_close (Aardvark aardvark);
Close the Aardvark port.
Arguments
aardvark: handle of an Aardvark adapter to be closed
Return Value
An Aardvark status code is returned with AA_OK on success.
Speci c Error Codes
None.
Details
An Aardvark adapter could have potentially been opened, enabled as a slave, and con gured
to send and receive asynchronous responses to and from a thirdparty master. A call to
aa_close() will deactivate all slave functionality. Also the I2C bus is freed, in the event that
it was held inde nitely from a previous AA_I2C_NO_STOP transaction.
Get Port (aa_port)
int aa_port (Aardvark aardvark);
Return the port number for this Aardvark handle.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
The port number corresponding to the given handle is returned. It is a zerobased number.
Speci c Error Codes
None.
Details
None.
www.totalphase.com 27
Aardvark I2C/SPI Embedded Systems Interface
Get Features (aa_features)
int aa_features (Aardvark aardvark);
Return the device features as a bitmask of values, or an error code if the handle is not valid.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
The features of the Aardvark device are returned. These are a bitmask of the following
values.
#define AA_FEATURE_SPI (1<<0)
#define AA_FEATURE_I2C (1<<1)
#define AA_FEATURE_GPIO (1<<3)
#define AA_FEATURE_I2C_MONITOR (1<<4)
Speci c Error Codes
None.
Details
None.
Get Unique ID (aa_unique_id)
aa_u32 aa_unique_id (Aardvark aardvark);
Return the unique ID of the given Aardvark device.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
This function returns the unique ID for this Aardvark adapter. The IDs are guaranteed to
be nonzero if valid. The ID is the unsigned integer representation of the 10digit serial
number.
Speci c Error Codes
None.
Details
None.
Status String (aa_status_string)
const char *aa_status_string (int status);
Return the status string for the given status code.
Arguments
status: status code returned by an Aardvark API function
Return Value
www.totalphase.com 28
Aardvark I2C/SPI Embedded Systems Interface
This function returns a human readable string that corresponds to status. If the code is not
valid, it returns a NULL string.
Speci c Error Codes
None.
Details
None.
Logging (aa_log)
int aa_log (Aardvark aardvark, int level, int handle);
Enable logging to a le.
Arguments
aardvark: handle of an Aardvark adapter
level: the logging detail level as described below
handle: a le descriptor
Return Value
An Aardvark status code is returned with AA_OK on success.
Speci c Error Codes
None.
Details
The handle must be standard le descriptor. In C, a le descriptor can be obtained by using
the ANSI C function "open" or by using the function " leno" on a FILE* stream. A FILE*
stream obtained using fopen or can correspond to the common stdout or stderr available
when including stdlib.h.
The logging detail level can be one of the following options.
0 none
1 error
2 warning
3 info
4 debug
Note that if the handle is invalid, the application can crash during a logging operation.
Version (aa_version)
int aa_version (Aardvark aardvark, AardvarkVersion *version);
Return the version matrix for the device attached to the given handle.
Arguments
aardvark: handle of an Aardvark adapter
version: pointer to preallocated structure
www.totalphase.com 29
Aardvark I2C/SPI Embedded Systems Interface
Return Value
An Aardvark status code is returned with AA_OK on success.
Speci c Error Codes
None.
Details
If the handle is 0 or invalid, only the software version is set.
See the details of aa_open_ext for the de nition of AardvarkVersion.
Con gure (aa_con gure)
int aa_configure (Aardvark aardvark, AA_CONFIG config);
IC
Activate/deactivate individual subsystems ( 2 , SPI, GPIO).
Arguments
aardvark: handle of an Aardvark adapter
config: enumerated type specifying con guration. See Table 2
Table 2: config enumerated types
AA_CONFIG_GPIO_ONLY 2
Con gure all pins as GPIO. Disable both I C and SPI.
AA_CONFIG_SPI_GPIO 2
Con gure I C pins as GPIO. Enable SPI.
AA_CONFIG_GPIO_I2C 2
Con gure SPI pins as GPIO. Enable I C .
AA_CONFIG_SPI_I2C 2
Disable GPIO. Enable both I C and SPI.
AA_CONFIG_QUERY Queries existing con guration (does not modify).
Return Value
The current con guration on the Aardvark adapter will be returned. The con guration will
be described by the same values in AA_CONFIG.
Speci c Error Codes
AA_CONFIG_ERROR: 2
The I C or SPI subsystem is currently active and the new con guration
requires the subsystem to be deactivated.
Details
2
If either the I C or SPI subsystems have been disabled by this API call, all other API functions
2
that interact with I C or SPI will return AA_CONFIG_ERROR.
If con gurations are switched, the subsystem speci c parameters will be preserved. For
example if the SPI bitrate is set to 500 kHz and the SPI system is disabled and then enabled,
the bitrate will remain at 500 kHz. This also holds for other parameters such as the SPI
2 2
mode, SPI slave response, I C bitrate, I C slave response, etc.
However, if a subsystem is shut o, it will be restarted in a quiescent mode. That is to say,
2 2
the I C slave function will not be reactivated after reenabling the I C subsystem, even if the
2 2
I C slave function was active before rst disabling the I C subsystem.
Note: Whenever the con gure command is executed and GPIO lines are enabled, the GPIO
lines will be momentarily switched to highZ before their direction and pullup con gurations
are executed.
www.totalphase.com 30
Aardvark I2C/SPI Embedded Systems Interface
Target Power (aa_target_power)
int aa_target_power (Aardvark aardvark, aa_u08 power_mask);
Activate/deactivate target power pins 4 and 6.
Arguments
aardvark: handle of an Aardvark adapter
power_mask: enumerated values specifying power pin state. See Table 3.
Table 3: power_mask enumerated types
AA_TARGET_POWER_NONE Disable target power pins
AA_TARGET_POWER_BOTH Enable target power pins
AA_TARGET_POWER_QUERY Queries the target power pin state
Return Value
The current state of the target power pins on the Aardvark adapter will be returned. The
con guration will be described by the same values as in the table above.
Speci c Error Codes
AA_INCOMPATIBLE_DEVICE: The hardware version is not compatible with this feature. Only
hardware versions 2.00 or greater support switchable target power pins.
Details
Both target power pins are controlled together. Independent control is not supported. This
function may be executed in any operation mode.
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.
Arguments
aardvark: handle of an Aardvark adapter
timeout: timeout in milliseconds
Return Value
A status code indicating which types of asynchronous messages are available for processing.
See Table 4.
These codes can be bitwise OR'ed together if there are multiple types of data available.
Speci c Error Codes
None.
Details
Recall that, like all other Aardvark functions, this function is not threadsafe.
If the timeout value is negative, the function will block inde nitely until data arrives. If the
timeout value is 0, the function will perform a nonblocking check for pending asynchronous
data.
www.totalphase.com 31
Aardvark I2C/SPI Embedded Systems Interface
Table 4: Status code enumerated types
AA_ASYNC_NO_DATA No asynchronous data is available.
AA_ASYNC_I2C_READ 2
I C slave read data is available. Use
aa_i2c_slave_read to get data.
AA_ASYNC_I2C_WRITE 2
I C slave write stats are available. Use
aa_i2c_slave_write_stats to get data.
AA_ASYNC_SPI SPI slave read data is available. Use
aa_spi_slave_read to get data.
AA_ASYNC_I2C_MONITOR 2
I C monitor data is available. Use
aa_i2c_monitor_read to get data.
As described before, the Aardvark software contains asynchronous queues that can be lled
during synchronous operations on the Aardvark adapter. If data is already in one or more
asynchronous queues, it will immediately return with all of the types of asynchronous data
that are currently available. Further data may be pending in the operating system's incoming
receive buer, but the function will not examine that data. Hence any pending data in the
operating system's incoming buer will not be reported to the user until the Aardvark's
software queues have been fully serviced.
If there is no data already available, this function will check the operating system's receive
buer for the presence of asynchronous data. The function will block for the speci ed
timeout. It will then only report the type of the very rst data that has been received. The
function will not examine the remainder of the operating system's receive buer to see what
other asynchronous messages are pending.
One can employ the following technique to guarantee that all pending asynchronous data
have been captured during each service cycle:
1. Call the polling function with a speci ed timeout.
2. If the polling function indicates that there is data available, call the appropriate service
function once for each type of data that is available.
3. Next, call the polling function with a 0 timeout.
4. Call the appropriate service function once for each type of data that is available.
5. Repeat steps 3 and 4 until the polling function reports that there is no data available.
www.totalphase.com 32
Aardvark I2C/SPI Embedded Systems Interface
5.5 I2C Interface
I2C Notes
2
1. It is not necessary to set the bitrate for the Aardvark I C slave.
2
2. An I C master operation read or write operation can be transacted while leaving the
2
I C slave functionality enabled. In a multimaster situation it is possible for the Aard-
vark 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 adapter's
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 rst 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 buer. As such, one
should not queue up more than 4 KiB of total slave data between calls to the Aardvark
API.
2
5. Since rmware revision 2.00 it is possible for the Aardvark I C master to employ some
2
of the advanced features of I C . This is accomplished by the AA_I2C_FLAGS 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 OR'ed together to combine them for
one operation.
Table 5: I2C Advanced Feature Options
AA_I2C_NO_FLAGS Request no options.
AA_I2C_10_BIT_ADDR Request that the provided address is treated as a 10bit
2
address. The Aardvark I C subsystem will follow the
2
Philips I C speci cation when transmitting the address.
AA_I2C_COMBINED_FMT Request that the Philips combined format is followed
2
during a I C read operation. Please see the Philips
speci cation for more details. This ag does not have
any eect unless a master read operation is requested
and the AA_I2C_10_BIT_ADDR is also set.
AA_I2C_NO_STOP 2
Request that no stop condition is issued on the I C 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.
2
Eventually an I C transaction must be issued without
the "no stop" option so that a stop condition is issued
and the bus is freed.
2
6. Since rmware revision 3.00 it is possible for the Aardvark I C master to return an ex-
tended status code for master read and master write transactions. These codes are de-
scribed in Table 6 and are returned by the aa_i2c_read_ext and aa_i2c_write_ext
functions.
www.totalphase.com 33
Aardvark I2C/SPI Embedded Systems Interface
Table 6: I2C 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
adapter's 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
2
I C speci cation.
AA_I2C_STATUS_LAST_DATA_ACK When the Aardvark slave is con gured with
a xed length transmit buer, it will detach
itself from the I2C bus after the buer is
fully transmitted. The Aardvark slave also
expects that the last byte sent from this
buer is NACK'ed 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 noti cation 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 re ect the bus error.
General I2C
I2C Pullup (aa_i2c_pullup)
int aa_i2c_pullup (Aardvark aardvark, aa_u08 pullup_mask);
Activate/deactivate I2C pullup resistors on SCL and SDA.
Arguments
aardvark: handle of an Aardvark adapter
www.totalphase.com 34
Aardvark I2C/SPI Embedded Systems Interface
pullup_mask: enumerated values specifying pullup state. See Table 7.
Table 7: pullup_mask enumerated types
AA_I2C_PULLUP_NONE Disable SCL/SDA pullup resistors
AA_I2C_PULLUP_BOTH Enable SCL/SDA pullup resistors
AA_I2C_PULLUP_QUERY Queries the pullup resistor state
Return Value
2
The current state of the I C pullup resistors on the Aardvark adapter will be returned. The
con guration will be described by the same values as in the table above.
Speci c Error Codes
AA_INCOMPATIBLE_DEVICE: The hardware version is not compatible with this feature. Only
hardware versions 2.00 or greater support switchable pullup resistors pins.
Details
Both pullup resistors are controlled together. Independent control is not supported. This
function may be performed in any operation mode.
Free bus (aa_i2c_free_bus)
int aa_i2c_free_bus (Aardvark aardvark);
Free the Aardvark I2C subsystem from a held bus condition (e.g., "no stop").
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
AA_I2C_ALREADY_FREE_BUS: The bus was already free and no action was taken.
Details
2
If the Aardvark I C subsystem had executed a master transaction and is holding the bus due
to a previous AA_I2C_NO_STOP ag, this function will issue the stop command and free the
bus. If the bus is already free, it will return the status code AA_I2C_BUS_ALREADY_FREE.
2
Similarly, if the Aardvark I C subsystem was placed into slave mode and in the middle of a
slave transaction, this command will disconnect the slave from the bus, ush the last transfer,
and reenable the slave. Such a feature is useful if the Aardvark adapter was receiving bytes
but then was forced to wait inde nitely on the bus because of the absence of the terminating
stop command. After disabling the slave, any pending slave reception will be available to the
host through the usual aa_i2c_slave_write_stats and aa_i2c_slave_read API calls.
The bus is always freed (i.e., a stop command is executed if necessary) and the slave functions
are disabled at software opening and closing of the device.
www.totalphase.com 35
Aardvark I2C/SPI Embedded Systems Interface
I2C Master
Set Bitrate (aa_i2c_bitrate)
int aa_i2c_bitrate (Aardvark aardvark, int bitrate_khz);
Set the I2C bitrate in kilohertz.
Arguments
aardvark: handle of an Aardvark adapter
bitrate_khz: the requested bitrate in khz.
Return Value
This function returns the actual bitrate set.
Speci c Error Codes
None.
Details
The poweron default bitrate is 100 kHz.
2
Only certain discrete bitrates are supported by the Aardvark I C master interface. As such,
this actual bitrate set will be less than or equal to the requested bitrate.
If bitrate_khz is 0, the function will return the bitrate presently set on the Aardvark adapter
and the bitrate will be left unmodi ed.
Master Read (aa_i2c_read)
int aa_i2c_read (Aardvark aardvark,
aa_u16 slave_addr,
AA_I2C_FLAGS flags,
aa_u16 num_bytes,
aa_u08 * data_in);
Read a stream of bytes from the I2C slave device.
Arguments
aardvark: handle of an Aardvark adapter
slave_addr: the slave from which to read
flags: special operations as described in "Notes" section
num_bytes: the number of bytes to read (maximum 65535)
data_in: pointer to data
Return Value
Number of bytes read.
Speci c Error Codes
AA_I2C_READ_ERROR: There was an error reading from the Aardvark adapter. This is most
likely a result of a communication error.
Details
www.totalphase.com 36
Aardvark I2C/SPI Embedded Systems Interface
For ordinary 7bit addressing, the lower 7 bits of slave_addr should correspond to the slave
2
address. The topmost bits are ignored. The Aardvark I C subsystem will assemble the address
along with the R/W bit after grabbing the bus. For 10bit addressing, the lower 10 bits of
addr should correspond to the slave address. The Aardvark adapter will then assemble the
address into the proper format as described in the Philips speci cation, namely by rst issuing
an write transaction on the bus to specify the 10bit slave and then a read transaction to read
the requested number of bytes. The initial write transaction can be skipped if the "Combined
Format" feature is requested in conjunction with the 10bit addressing functionality.
The data pointer should be allocated at least as large as num_bytes.
It is possible to read zero bytes from the slave. In this case, num_bytes is set to 0 and the
data argument is ignored (i.e., it can be 0 or point to invalid memory). However, due to the
2
nature of the I C protocol, it is not possible to address the slave and not request at least one
byte. Therefore, one byte is actually received by the host, but is subsequently thrown away.
If the number of bytes read is zero, the following conditions are possible.
The requested slave was not found.
The requested slave is on the bus but refuses to acknowledge its address.
The Aardvark adapter was unable to seize the bus due to the presence of another
2
I C master. Here, the arbitration was lost during the slave addressing phase
results can be unpredictable.
Zero bytes were requested from a slave. The slave acknowledged its address and re-
turned 1 byte. That byte was dropped.
Ordinarily the number of bytes read, if not 0, will equal the requested number of bytes. One
special scenario in which this will not happen is if the Aardvark adapter loses the bus during
2
the data transmission due to the presence of another I C master.
If the slave has fewer bytes to transmit than the number requested by the master, the slave
will simply stop transmitting and the master will receive 0xff for each remaining byte in the
2
transmission. This behavior is in accordance with the I C protocol.
Master Read Extended (aa_i2c_read_ext)
int aa_i2c_read_ext (Aardvark aardvark,
aa_u16 slave_addr,
AA_I2C_FLAGS flags,
aa_u16 num_bytes,
aa_u08 * data_in
aa_u16 * num_read);
Read a stream of bytes from the I2C slave device with extended status information.
Arguments
aardvark: handle of an Aardvark adapter
slave_addr: the slave from which to read
flags: special operations as described in "Notes" section
num_bytes: the number of bytes to read (maximum 65535)
www.totalphase.com 37
Aardvark I2C/SPI Embedded Systems Interface
data_in: pointer to data
num_read: the actual number of bytes read
Return Value
Status code (see "Notes" section).
Speci c Error Codes
None.
Details
This function operates exactly like aa_i2c_read, except that the return value now speci es
a status code. The number of bytes read is returned through an additional pointer argument
at the tail of the parameter list.
2
The status code allows the user to discover speci c events on the I C bus that would otherwise
be transparent given only the number of bytes transacted. The "Notes" section describes
the status codes.
For a master read operation, the AA_I2C_STATUS_DATA_NACK ag is not used since the
2
acknowledgment of data bytes is predetermined by the master and the I C speci cation.
Master Write (aa_i2c_write)
int aa_i2c_write (Aardvark aardvark,
aa_u16 slave_addr,
AA_I2C_FLAGS flags,
aa_u16 num_bytes,
const aa_u08 * data_out);
Write a stream of bytes to the I2C slave device.
Arguments
aardvark: handle of an Aardvark adapter
slave_addr: the slave from which to read
flags: special operations as described in "Notes" section
num_bytes: the number of bytes to write (maximum 65535)
data_out: pointer to data
Return Value
Number of bytes written.
Speci c Error Codes
AA_I2C_WRITE_ERROR: There was an error reading the acknowledgment from the Aardvark
adapter. This is most likely a result of a communication error.
Details
For ordinary 7bit addressing, the lower 7 bits of slave_addr should correspond to the
slave address. The topmost bits are ignored.
2
The Aardvark I C subsystem will assemble
the address along with the R/W bit after grabbing the bus. For 10bit addressing, the lower
10 bits of addr should correspond to the slave address. The Aardvark adapter will then
assemble the address into the proper format as described in the Philips speci cation. There
www.totalphase.com 38
Aardvark I2C/SPI Embedded Systems Interface
is a limitation that a maximum of only 65534 bytes can be written in a single transaction if
the 10bit addressing mode is used.
The slave_addr 0x00 2
has been reserved in the I C protocol speci cation for general call
2
addressing. I C slaves that are enabled to respond to a general call will acknowledge this
2
address. The general call is not treated specially in the Aardvark I C master. The user of this
API can manually assemble the rst data byte if the hardware address programming feature
with general call is required.
It is actually possible to write 0 bytes to the slave. The slave will be addressed and then the
stop condition will be immediately transmitted by the Aardvark adapter. No bytes are sent
to the slave, so the data argument is ignored (i.e., it can be 0 or point to invalid memory).
If the number of bytes written is zero, the following conditions are possible.
The requested slave was not found.
The requested slave is on the bus but refuses to acknowledge its address.
The Aardvark adapter was unable to seize the bus due to the presence of another
2
I C master. Here, the arbitration was lost during the slave addressing phase
results can be unpredictable.
The slave was addressed and no bytes were written to it because num_bytes was set
to 0.
The number of bytes written can be less than the requested number of bytes in the transaction
due to the following possibilities.
The Aardvark adapter loses the bus during the data transmission due to the presence
2
of another I C master.
The slave refuses the reception of any more bytes.
Master Write Extended (aa_i2c_write_ext)
int aa_i2c_write_ext (Aardvark aardvark,
aa_u16 slave_addr,
AA_I2C_FLAGS flags,
aa_u16 num_bytes,
const aa_u08 * data_out
aa_u16 * num_written);
Write a stream of bytes to the I2C slave device with extended status information.
Arguments
aardvark: handle of an Aardvark adapter
slave_addr: the slave from which to read
flags: special operations as described in "Notes" section
num_bytes: the number of bytes to write (maximum 65535)
data_out: pointer to data
num_written: the actual number of bytes written
Return Value
www.totalphase.com 39
Aardvark I2C/SPI Embedded Systems Interface
Status code (see "Notes" section).
Speci c Error Codes
None.
Details
This function operates exactly like aa_i2c_write, except that the return value now spec-
i es a status code. The number of bytes written is returned through an additional pointer
argument at the tail of the parameter list.
2
The status code allows the user to discover speci c events on the I C bus that would otherwise
be transparent given only the number of bytes transacted. The "Notes" section describes
the status codes.
For a master write operation, the AA_I2C_STATUS_DATA_NACK ag can be useful in the
following situation:
2
Normally the I C master will write to the slave until the slave issues a NACK or the
requested number of bytes have been written.
2
If the master has wishes to write 10 bytes, the I C slave issues either an ACK or NACK
on the tenth byte without aecting the total number of bytes transferred. Hence, the
aa_i2c_write function cannot provide the caller with the information that the 10th
byte was ACK'ed or NACK'ed.
On the other hand, if the aa_i2c_write_ext is used, the status code will distinguish
the two scenarios. This status information could be useful for further communications
with that particular slave device.
I2C Slave
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 I2C slave device.
Arguments
aardvark: handle of an Aardvark adapter
addr: address of this slave
maxTxBytes: max number of bytes to transmit per transaction
maxRxBytes: max number of bytes to receive per transaction
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
www.totalphase.com 40
Aardvark I2C/SPI Embedded Systems Interface
The lower 7 bits of addr should correspond to the slave address of this Aardvark adapter.
If the topmost bit of addr is set, the slave will respond to a general call transmission by an
2 2
I C master. After having been addressed by a general call, the Aardvark I C slave treats the
transaction no dierently than a single slave communication. There is no support for the
2
hardware address programming feature of the general call that is described in the I C protocol
speci cation since that capability is not needed for Aardvark devices.
If maxTxBytes is 0, there is no limit on the number of bytes that this slave will transmit per
transaction. If it is nonzero, then the slave will stop transmitting bytes at the speci ed limit
and subsequent bytes received by the master will be 0xff due to the bus pullup resistors. The
response that is transmitted by the slave is set through the aa_i2c_slave_set_response
function described below. If the maximum is greater than the response (as set through
aa_i2c_slave_set_response) the Aardvark slave will wrap the response string as many
times as necessary to send the requested number of bytes.
If maxRxBytes is 0, the slave can receive an unlimited number of bytes from the master.
However, if it is nonzero, the slave will send a notacknowledge bit after the last byte
that it accepts. The master should then release the bus. Even if the master does not stop
transmitting, the slave will return the received data back to the host PC and then transition
to a idle state, waiting to be addressed in a subsequent transaction.
It is never possible to restrict a transmit or receive to 0 bytes. Furthermore, once the slave
is addressed by a master read operation it is always guaranteed to transmit at least 1 byte.
If a master transaction is executed after the slave features have been enabled, the slave
features will remain enabled after the master transaction completes.
Slave Disable (aa_i2c_slave_disable)
int aa_i2c_slave_disable (Aardvark aardvark);
Disable the Aardvark adapter as an I2C slave device.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
None.
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.
www.totalphase.com 41
Aardvark I2C/SPI Embedded Systems Interface
Arguments
aardvark: handle of an Aardvark adapter
num_bytes: number of bytes for the slave response
data_out: pointer to the slave response
Return Value
The number of bytes accepted by the Aardvark slave for the response.
Speci c Error Codes
None.
Details
The value of num_bytes must be greater than zero. If it is zero, the response string is
unde ned until this function is called with the correct parameters.
Due to limited buer space on the Aardvark slave, the device may only accept a portion of
the intended response. If the value returned by this function is less than num_bytes the
Aardvark slave has dropped the remainder of the bytes.
If more bytes are requested in a transaction, the response string will be wrapped as many
times as necessary to complete the transaction.
The buer space will nominally be 64 bytes but can change depending on rmware revision.
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 I2C slave to I2C master transmission.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
The number of bytes written asynchronously.
Speci c Error Codes
AA_I2C_SLAVE_TIMEOUT: There was no recent slave transmission.
Details
2
The transmission of bytes from the Aardvark slave, when it is con gured as an I C slave, is
asynchronous with respect to the PC host software. Hence, there could be multiple responses
queued up from previous write transactions.
This function will wait 500 milliseconds before timing out. See the aa_async_poll function
if a variable timeout is required.
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 I2C slave to I2C master transmission
with extended status information.
www.totalphase.com 42
Aardvark I2C/SPI Embedded Systems Interface
Arguments
aardvark: handle of an Aardvark adapter
num_written: : the number of bytes written by the slave
Return Value
Status code (see "Notes" section).
Speci c Error Codes
None.
Details
This function operates exactly like aa_i2c_slave_write_stats, except that the return
value now speci es a status code. The number of bytes written is returned through an
additional pointer argument at the tail of the parameter list.
The only possible status code is AA_I2C_STATUS_BUS_ERROR which can occur when an illegal
START, STOP, or RESTART condition appears on the bus during a transaction. In this case
the num_written may not exactly re ect the number of bytes written by the slave. It can
be o by 1.
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 I2C slave reception.
Arguments
aardvark: handle of an Aardvark adapter
addr: the address to which the received message was sent
num_bytes: the maximum size of the data buer
data_out: pointer to data buer
Return Value
This function returns the number of bytes read asynchronously.
Speci c Error Codes
AA_I2C_SLAVE_TIMEOUT: There was no recent slave transmission.
AA_I2C_DROPPED_EXCESS_BYTES: The msg was larger than num_bytes.
Details
If the message was directed to this speci c slave, *addr will be set to the value of this
slave's address. However, this slave may have received this message through a general call
addressing. In this case, *addr will be 0x80 instead of its own address.
The num_bytes parameter speci es the size of the memory pointed to by data. It is pos-
sible, however, that the received slave message exceeds this length. In such a situation,
AA_I2C_DROPPED_EXCESS_BYTES is returned, meaning that num_bytes was placed into data
but the remaining bytes were discarded.
www.totalphase.com 43
Aardvark I2C/SPI Embedded Systems Interface
There is no cause for alarm if the number of bytes read is less than num_bytes. This simply
indicates that the incoming message was short.
2
The reception of bytes by the Aardvark slave, when it is con gured as an I C slave, is
asynchronous with respect to the PC host software. Hence, there could be multiple responses
queued up from previous transactions.
This function will wait 500 milliseconds before timing out. See the aa_async_poll function
if a variable timeout is required.
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 I2C slave reception with extended status information.
Arguments
aardvark: handle of an Aardvark adapter
addr: the address to which the received message was sent
num_bytes: the maximum size of the data buer
data_out: pointer to data buer
num_read: the actual number of bytes read by the slave
Return Value
Status code (see "Notes" section).
Speci c Error Codes
None.
Details
This function operates exactly like aa_i2c_slave_read, except that the return value now
speci es a status code. The number of bytes read is returned through an additional pointer
argument at the tail of the parameter list.
The only possible status code is AA_I2C_STATUS_BUS_ERROR which can occur when an illegal
START, STOP, or RESTART condition appears on the bus during a transaction.
www.totalphase.com 44
Aardvark I2C/SPI Embedded Systems Interface
5.6 SPI Interface
SPI Notes
1. The SPI master and slave must both be con gured 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 rst 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 buer. 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 buer. The SPI is full
duplex so there must be enough buer 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 510
µs.
General SPI
Con gure (aa_spi_con gure)
int aa_spi_configure (Aardvark aardvark,
AA_SPI_POLARITY polarity,
AA_SPI_PHASE phase,
AA_SPI_BITORDER bitorder);
Con gure the SPI master or slave interface.
Arguments
aardvark: handle of an Aardvark adapter
polarity: AA_SPI_POL_RISING_FALLING or AA_SPI_POL_FALLING_RISING
phase: AA_SPI_PHASE_SAMPLE_SETUP or AA_SPI_PHASE_SETUP_SAMPLE
bitorder: AA_SPI_BITORDER_MSB or AA_SPI_BITORDER_LSB
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
www.totalphase.com 45
Aardvark I2C/SPI Embedded Systems Interface
Details
These con guration parameters specify how to clock the bits that are sent and received on
the Aardvark SPI interface.
The polarity option speci es which transition constitutes the leading edge and which tran-
sition is the falling edge. For example, AA_SPI_POL_RISING_FALLING would con gure the
SPI to idle the SCLK clock line low. The clock would then transition lowtohigh on the
leading edge and hightolow on the trailing edge.
The phase option determines whether to sample or setup on the leading edge. For example,
AA_SPI_PHASE_SAMPLE_SETUP would con gure the SPI to sample on the leading edge and
setup on the trailing edge.
The bitorder option is used to indicate whether LSB or MSB is shifted rst.
The pair (AA_SPI_POL_FALLING_RISING, AA_SPI_PHASE_SETUP_SAMPLE) would corre-
spond to mode 3 in the gure found in the "SPI Background" chapter.
SPI Master
Set Bitrate (aa_spi_bitrate)
int aa_spi_bitrate (Aardvark aardvark, int bitrate_khz);
Set the SPI bitrate in kilohertz.
Arguments
aardvark: handle of an Aardvark adapter
bitrate_khz: the requested bitrate in khz.
Return Value
This function returns the actual bitrate set.
Speci c Error Codes
None.
Details
The poweron default bitrate is 1000 kHz.
Only certain discrete bitrates are supported by the Aardvark adapter. As such, this actual
bitrate set will be less than or equal to the requested bitrate unless the requested value is
less than 125 kHz, in which case the Aardvark adapter will default to 125 kHz.
If bitrate_khz is 0, the function will return the bitrate presently set on the Aardvark adapter
and the bitrate will be left unmodi ed.
Set Slave Select Polarity (aa_spi_master_ss_polarity)
int aa_spi_master_ss_polarity (Aardvark aardvark,
AA_SPI_SS_POLARITY polarity);
Change the output polarity on the SS line.
Arguments
aardvark: handle of an Aardvark adapter
www.totalphase.com 46
Aardvark I2C/SPI Embedded Systems Interface
polarity: AA_SPI_SS_ACTIVE_LOW or AA_SPI_SS_ACTIVE_HIGH
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
This function only aects the SPI master functions on the Aardvark adapter. When con g-
ured as an SPI slave, the Aardvark adapter will always be setup with SS as active low.
Master Write/Read (aa_spi_write)
int aa_spi_write (Aardvark aardvark,
aa_u16 num_bytes,
const aa_u08 * data_out,
aa_u08 * data_in);
Write a stream of bytes to the downstream SPI slave device and read back the fullduplex
response.
Arguments
aardvark: handle of an Aardvark adapter
num_bytes: number of bytes to send
data_out: pointer to the bytes to transmit out
data_in: pointer to memory that will hold the received data
Return Value
This function returns the total number of bytes read from the slave which normally will be
the same as the number of bytes written to the slave.
Speci c Error Codes
AA_SPI_WRITE_ERROR: There was an error writing to the Aardvark adapter. This is most
likely a result of a communication error. Make sure that num_bytes is less than 4 KiB.
Details
The data_in pointer should reference memory that is at least allocated to the size speci ed
by num_bytes. Otherwise there will be a memory access violation in the program.
If num_bytes is 0, no bytes will be written to the slave. However, the slave select line will
be dropped for 510 µs. This can be useful in sending a signal to a downstream SPI slave
without actually sending any bytes. For example, if an SPI slave has tied the slave select
to an interrupt line and it sees the line is toggled without any bytes sent, it can interpret
the action as a command to prepare its rmware for an subsequent reception of bytes. If
num_bytes is 0, data_out and data_in are completely ignored by this function and can be
set to 0.
If the return value of this function is less than num_bytes, there was an error. SPI is a
bitblasting scheme where the master does not even know if there is a slave on the other
end of the transmission. Therefore, it is always expected that the master will send the entire
length of the transaction.
www.totalphase.com 47
Aardvark I2C/SPI Embedded Systems Interface
An error will likely occur if the number of bytes sent is signi cantly greater than 4 KiB. This
function cannot reliably execute larger transfers due to the buering issues explained in the
"Software | Application Notes" section. Only a partial number of bytes will be sent to the
slave and only a partial number will be received from the slave; it is quite possible that these
numbers will not be equal. The size of the partial response is returned by this function and
the data will be in the memory pointed to by data_in. Note that the last few bytes of the
response may be corrupted as well.
SPI Slave
Slave Enable (aa_spi_slave_enable)
int aa_spi_slave_enable (Aardvark aardvark);
Enable the Aardvark as an SPI slave device.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
None.
Slave Disable (aa_spi_slave_disable)
int aa_spi_slave_disable (Aardvark aardvark);
Disable the Aardvark as an SPI slave device.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
None.
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);
www.totalphase.com 48
Aardvark I2C/SPI Embedded Systems Interface
Set the slave response in the event the Aardvark adapter is put into slave mode and contacted
by a master.
Arguments
aardvark: handle of an Aardvark adapter
num_bytes: number of bytes for the slave response
data_out: pointer to the slave response
Return Value
The number of bytes accepted by the Aardvark for the response.
Speci c Error Codes
None.
Details
The value of num_bytes must be greater than zero. If it is zero, the response string is
unde ned until this function is called with the correct parameters.
Due to limited buer space on the Aardvark slave, the device may only accept a portion of
the intended response. If the value returned by this function is less than num_bytes the
Aardvark slave has dropped the remainder of the bytes.
If more bytes are requested in a transaction, the response string will be wrapped as many
times as necessary to complete the transaction.
The buer space will nominally be 64 bytes but may change depending on rmware revision.
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.
Arguments
aardvark: handle of an Aardvark adapter
num_bytes: the maximum size of the data buer
data_in: pointer to data buer
Return Value
This function returns the number of bytes read asynchronously.
Speci c Error Codes
AA_SPI_SLAVE_TIMEOUT: There was no recent slave transmission.
AA_SPI_DROPPED_EXCESS_BYTES: The msg was larger than num_bytes.
Details
The num_bytes parameter speci es the size of the memory pointed to by data. It is pos-
sible, however, that the received slave message exceeds this length. In such a situation,
AA_SPI_DROPPED_EXCESS_BYTES is returned, meaning that num_bytes was placed into data
but the remaining bytes were discarded.
www.totalphase.com 49
Aardvark I2C/SPI Embedded Systems Interface
There is no cause for alarm if the number of bytes read is less than num_bytes. This simply
indicates that the incoming message was short.
The reception of bytes by the Aardvark adapter, when it is con gured as an SPI slave, is
asynchronous with respect to the PC host software. Hence, there could be multiple responses
queued up from previous write transactions.
This function will wait 500 milliseconds before timing out. See the aa_async_poll function
if a variable timeout is required.
2
The SPI API does not include a function that is analogous to the I C function
aa_i2c_slave_write_stats. Since SPI is a fullduplex standard, the slave writes to
the master whenever it receives bytes from the master. Hence, a received message from
aa_i2c_slave_read implies that an equal number of bytes were sent to the master.
www.totalphase.com 50
Aardvark I2C/SPI Embedded Systems Interface
5.7 GPIO Interface
GPIO Notes
2
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 8bit masked value. Thus, each bit position in the mask can be
referred back its corresponding line through the mapping described below.
Table 8: AA_GPIO_BITS: enumerated type of line locations in bit mask
AA_GPIO_SCL Pin 1 0x01 2
I C SCL line
AA_GPIO_SDA Pin 3 0x02 2
I C 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 con guration. 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
2 2
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_con gure disables the
2 2
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 con gured as inputs, a change in the pullup con g-
uration using aa_gpio_pullup will be cached and will take eect the next time the
line is active and con gured as an input. The same behavior holds for aa_gpio_set
when a line is con gured as an input instead of an output.
4. On Aardvark adapter powerup, directions default to all input, pullups default to dis-
abled and outputs default to logic low. Also the GPIO subsystem is o by default. It
must be activated by using aa_configure.
2
5. Note: For hardware version 1.02, it is not possible to have highZ inputs on the I C lines
2
since that hardware has 2.2K pullups on the I C bus.
GPIO Interface
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.
Arguments
aardvark: handle of an Aardvark adapter
www.totalphase.com 51
Aardvark I2C/SPI Embedded Systems Interface
direction_mask: each bit corresponds to the physical line as given by AA_GPIO_BITS. If a
line's bit is 0, the line is con gured as an input. Otherwise it will be an output.
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
None.
Pullup (aa_gpio_pullup)
int aa_gpio_pullup (Aardvark aardvark,
aa_u08 pullup_mask);
Change the pullup con guration of the GPIO lines.
Arguments
aardvark: handle of an Aardvark adapter
pullup_mask: each bit corresponds to the physical line as given by AA_GPIO_BITS. If a
line's bit is 1, the line's pullup is active whenever the line is con gured as an input.
Otherwise the pullup will be deactivated.
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
None.
Get (aa_gpio_get)
int aa_gpio_get (Aardvark aardvark);
Get the value of current GPIO inputs.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An integer value, organized as a bitmask in the fashion described by AA_GPIO_BITS. Any
line that is logic high will have a its corresponding bit active. If the line is logic low the bit
will not be active in the bit mask.
Speci c Error Codes
None.
Details
A line's bit position in the mask will be 0 if it is con gured as an output or if it corresponds
to a subsystem that is still active.
www.totalphase.com 52
Aardvark I2C/SPI Embedded Systems Interface
Set (aa_gpio_set)
int aa_gpio_set (Aardvark aardvark,
aa_u08 value);
Set the value of current GPIO outputs.
Arguments
aardvark: handle of an Aardvark adapter
value: a bitmask specifying which outputs should be set to logic high and which should be
set to logic low.
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
If a line is con gured as an input or not activated for GPIO, the output value will be cached.
The next time the line is an output and activated for GPIO, the output value previously set
will automatically take eect.
Change (aa_gpio_change)
int aa_gpio_change (Aardvark aardvark,
aa_u16 timeout);
Block until there is a change on the GPIO input lines.
Arguments
aardvark: handle of an Aardvark adapter
timeout: time to wait for a change in milliseconds
Return Value
The current state of the GPIO input lines.
Speci c Error Codes
None.
Details
The function will return either when a change has occurred or the timeout expires. Pins
con gured as outputs will be ignored. The timeout, speci ed in milliseconds, has a precision
of approximately 16 ms. The maximum allowable timeout is approximately 4 seconds. If
the timeout expires, this function will return the current state of the GPIO lines. It is the
application's responsibility to save the old value of the lines and determine if there is a change
based on the return value of this function.
The function aa_gpio_change will return immediately with the current value of the GPIO
lines for the rst invocation after any of the following functions are called: aa_configure,
aa_gpio_direction, or aa_gpio_pullup. If the function aa_gpio_get is called before
calling aa_gpio_change, aa_gpio_change will only register any changes from the value
last returned by aa_gpio_get.
www.totalphase.com 53
Aardvark I2C/SPI Embedded Systems Interface
5.8 I2C Bus Monitor
Monitor Notes
2
1. The Aardvark adapter can continuously monitor I C tra c up to 125 khz. It may
be possible to monitor higher bitrates for small transactions, but the reliability is not
guaranteed.
2. Activating the bus monitor will disable all other functions on the Aardvark adapter and
ush all pending asynchronous messages. The Aardvark adapter will be placed into the
AA_CONFIG_GPIO_ONLY mode by default. Once the bus monitor is disabled, the user
2
must use aa_configure to reenable either I C or SPI functions if these operations
are required.
3. Once the bus monitor is enabled, the execution of any other communication function
on the Aardvark adapter will disable the bus monitor.
2 2
4. The I C pullup resistors can be enabled or disabled during I C monitor use. Simply use
the aa_i2c_pullup function before enabling the bus monitor.
2 2
5. Once enabled, the I C monitor automatically monitors the attached I C bus and returns
data back to the host asynchronously. Due to operating system limitations on the
asynchronous incoming buer, one must ensure that the asynchronous data is serviced
regularly. As such, one should not queue up more than 4 KiB of total monitor data
between calls to the Aardvark API. For example, problems can arise when there is a
high ow of tra c on the bus that is being monitored.
I2C Bus Monitor Interface
Monitor Enable (aa_i2c_monitor_enable)
int aa_i2c_monitor_enable (Aardvark aardvark);
Enable the Aardvark adapter as an I2C monitoring device.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
This function has a 100 ms delay to ush all communications buers.
www.totalphase.com 54
Aardvark I2C/SPI Embedded Systems Interface
Monitor Disable (aa_i2c_monitor_disable)
int aa_monitor_slave_disable (Aardvark aardvark);
Disable the Aardvark adapter as an I2C monitoring device.
Arguments
aardvark: handle of an Aardvark adapter
Return Value
An Aardvark status code is returned that is AA_OK on success.
Speci c Error Codes
None.
Details
This function has a 100 ms delay to ush all communications buers.
Monitor Read (aa_i2c_monitor_read)
int aa_i2c_monitor_read (Aardvark aardvark,
aa_u16 num_bytes,
aa_u16 * data);
Read the bytes from an I2C monitor operation.
Arguments
aardvark: handle of an Aardvark adapter
num_bytes: the maximum size of the data buer
data: pointer to data buer
Return Value
This function returns the number of monitor bytes read.
Speci c Error Codes
AA_I2C_MONITOR_NOT_ENABLED: The monitor functionality was not enabled.
Details
2 2
Once enabled, the I C monitor automatically monitors the attached I C bus and returns data
back to the host asynchronously. This function allows the PC to retrieve the asynchronous
data into a buer for analysis.
The monitored data is returned in a semiraw format. The returned data buer contains all
information about bitlevel signaling on the bus. Parsing this information is simple and the
user is referred to the examples that are included with the Aardvark software distribution.
Furthermore, the Control Center application demonstrates a GUI that uses this monitoring
function.
The information in each element of the returned buer is marked as follows:
1. Element is equal to the constant AA_I2C_MONITOR_CMD_START (0xff00) if a start bit
has been encountered.
www.totalphase.com 55
Aardvark I2C/SPI Embedded Systems Interface
2. Element is equal to the constant AA_I2C_MONITOR_CMD_STOP (0xff01) if a start bit
has been encountered.
3. If the element is neither a start or stop bit, the bottom 8bits are equal to the 8 data
2
bits of the I C transaction.
4. The element can have the 9th bit equal to 1 if the data byte was not acknowledged
2
by the I C receiving device. One can test for this condition by bitwise AND'ing the
element with AA_I2C_MONITOR_NACK (0x100).
2
The monitor function returns one I C transaction at a time. It expects that every transaction
2
starts with an I C START bus signal. The function returns when encountering a STOP
command. The application can then process the transaction and call the monitor function
again to process a subsequent transaction.
In the event of a repeated start on the bus, the incoming buer will contain a START code
without a prior STOP code. All tra c between the initial START command and the nal
STOP command will be returned in one call to this function.
2
As per the I C protocol, the slave address is the rst byte transmitted after the START com-
mand. The user can analyze this byte to determine the slave address for the bus transaction
as well as the direction of the transaction (i.e., master read versus master write). The top
7 bits of the byte correspond to the slave address and the least signi cant bit denotes the
2
transfer direction. See the Philips I C protocol de nition for more details.
There can be bit alignment issues if the monitor is plugged into a bus that is already in the
2
middle of an I C transaction. The data will most likely be corrupted. Likewise, there can be
corruption if there is an over ow of the operating system's receive buer.
This function will wait 500 milliseconds before timing out. See the aa_async_poll function
if a variable timeout is required.
www.totalphase.com 56
Aardvark I2C/SPI Embedded Systems Interface
5.9 Error Codes
Table 9: Aardvark API Error Codes
Literal Name Value aa_status_string() return value
AA_OK 0 ok
AA_UNABLE_TO_LOAD_LIBRARY -1 unable to load library
AA_UNABLE_TO_LOAD_DRIVER -2 unable to load USB driver
AA_UNABLE_TO_LOAD_FUNCTION -3 unable to load binding function
AA_INCOMPATIBLE_LIBRARY -4 incompatible library version
AA_INCOMPATIBLE_DEVICE -5 incompatible device version
AA_COMMUNICATION_ERROR -6 communication error
AA_UNABLE_TO_OPEN -7 unable to open device
AA_UNABLE_TO_CLOSE -8 unable to close device
AA_INVALID_HANDLE -9 invalid device handle
AA_CONFIG_ERROR -10 con guration error
AA_I2C_NOT_AVAILABLE -100 i2c feature not available
AA_I2C_NOT_ENABLED -101 i2c not enabled
AA_I2C_READ_ERROR -102 i2c read error
AA_I2C_WRITE_ERROR -103 i2c write error
AA_I2C_SLAVE_BAD_CONFIG -104 i2c slave enable bad con g
AA_I2C_SLAVE_READ_ERROR -105 i2c slave read error
AA_I2C_SLAVE_TIMEOUT -106 i2c slave timeout
AA_I2C_DROPPED_EXCESS_BYTES -107 i2c slave dropped excess bytes
AA_I2C_BUS_ALREADY_FREE -108 i2c bus already free
AA_SPI_NOT_AVAILBLE -200 spi feature not available
AA_SPI_NOT_ENABLED -201 spi not enabled
AA_SPI_WRITE_ERROR -202 spi write error
AA_SPI_SLAVE_READ_ERROR -203 spi slave read error
AA_SPI_SLAVE_TIMEOUT -204 spi slave timeout
AA_SPI_DROPPED_EXCESS_BYTES -205 spi slave dropped excess bytes
AA_GPIO_NOT_AVAILABLE -400 gpio feature not available
AA_I2C_MONITOR_NOT_AVAILABLE -500 i2c bus monitor feature not available
AA_I2C_MONITOR_NOT_ENABLED -501 i2c bus monitor not enabled
www.totalphase.com 57
Aardvark I2C/SPI Embedded Systems Interface
6 Legal / Contact
6.1 Disclaimer
All of the software and documentation provided in this datasheet, 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 docu-
mentation 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 documenta-
tion, and any derivative works is provided on an asis basis, and thus comes with absolutely
no warranty, either express or implied. This disclaimer includes, but is not limited to, implied
warranties of merchantability, tness for any particular purpose, and noninfringement. 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.
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 safetycritical 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 o cers, employees, a liates,
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.
6.3 Contact Information
Total Phase can be found on the Internet at http://www.totalphase.com/. If you
have Aardvark supportrelated questions, please email the product engineers at sup-
[email protected]. For questions about Total Phase's corporate services, please send
inquiries to [email protected].
©20022006 Total Phase, Inc.
All rights reserved.
www.totalphase.com 58
Aardvark I2C/SPI Embedded Systems Interface
List of Figures
1 Sample I2C Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 I2C Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3 Sample SPI Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4 SPI Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5 The Aardvark I2C/SPI Host Adapter in the upright position . . . . . . . . . 6
6 The Aardvark I2C/SPI Host Adapter in the upside down position . . . . . . 6
7 SPI Waveform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8 SPI Byte Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
List of Tables
1 SPI Timing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 config enumerated types . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3 power_mask enumerated types . . . . . . . . . . . . . . . . . . . . . . . . 31
4 Status code enumerated types . . . . . . . . . . . . . . . . . . . . . . . . . 32
5
2
I C Advanced Feature Options . . . . . . . . . . . . . . . . . . . . . . . . 33
6
2
I C Extended Status Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7 pullup_mask enumerated types . . . . . . . . . . . . . . . . . . . . . . . 35
8 AA_GPIO_BITS: enumerated type of line locations in bit mask . . . . . . . . 51
9 Aardvark API Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Contents
1 General Overview 2
1.1
2
I C Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2
I C History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2
I C Theory of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2
I C Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2
I C Bene ts and Drawbacks . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2
I C References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 SPI Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
SPI History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
SPI Theory of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
SPI Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
SPI Bene ts and Drawbacks . . . . . . . . . . . . . . . . . . . . . . . . . 5
SPI References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Hardware Speci cations 6
2.1 Pinouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Connector Speci cation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Order of Leads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Ground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2
I C Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
www.totalphase.com 59
Aardvark I2C/SPI Embedded Systems Interface
SPI Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Powering Downstream Devices . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Signal Levels/Voltage Ratings . . . . . . . . . . . . . . . . . . . . . . . . . 8
Logic High Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
ESD protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Drive Current . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3
2
I C Signaling Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Pullup Resistors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2
I C Clock Stretching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2
Known I C Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 SPI Signaling Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . 10
SPI Waveforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Speeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Pin Driving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Known SPI Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Aardvark Device Power Consumption . . . . . . . . . . . . . . . . . . . . . 12
2.5 USB 1.1 Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.6 Temperature Speci cations . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3 Software 13
3.1 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Linux Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Windows Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2 Linux USB Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
USB Hotplug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Driver Installation/Uninstallation . . . . . . . . . . . . . . . . . . . . . . . 13
3.3 Windows USB Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Driver Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Driver Removal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.4 USB Port Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Detecting Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.5 Aardvark Dynamically Linked Library . . . . . . . . . . . . . . . . . . . . . 16
DLL Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
DLL Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
DLL Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.6 Rosetta Language Bindings: API Integration into Custom Applications . . . 17
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.7 Application Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Asynchronous Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Receive Saturation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
www.totalphase.com 60
Aardvark I2C/SPI Embedded Systems Interface
Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
USB Scheduling Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4 Firmware 20
4.1 Field Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Upgrade Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Upgrade Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5 API Documentation 22
5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2 General Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.3 Notes on Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Find Devices (aa_ nd_devices) . . . . . . . . . . . . . . . . . . . 24
Find Devices (aa_ nd_devices_ext) . . . . . . . . . . . . . . . . . 24
Open an Aardvark device (aa_open) . . . . . . . . . . . . . . . . . 25
Open an Aardvark device (aa_open_ext) . . . . . . . . . . . . . . 25
Close an Aardvark (aa_close) . . . . . . . . . . . . . . . . . . . . . 27
Get Port (aa_port) . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Get Features (aa_features) . . . . . . . . . . . . . . . . . . . . . . 28
Get Unique ID (aa_unique_id) . . . . . . . . . . . . . . . . . . . . 28
Status String (aa_status_string) . . . . . . . . . . . . . . . . . . . 28
Logging (aa_log) . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Version (aa_version) . . . . . . . . . . . . . . . . . . . . . . . . . 29
Con gure (aa_con gure) . . . . . . . . . . . . . . . . . . . . . . . 30
Target Power (aa_target_power) . . . . . . . . . . . . . . . . . . . 31
Asynchronous Polling (aa_async_poll) . . . . . . . . . . . . . . . . 31
5.5
2
I C Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2
I C Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2
General I C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
I2C Pullup (aa_i2c_pullup) . . . . . . . . . . . . . . . . . . . . . . 34
Free bus (aa_i2c_free_bus) . . . . . . . . . . . . . . . . . . . . . 35
2
I C Master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Set Bitrate (aa_i2c_bitrate) . . . . . . . . . . . . . . . . . . . . . 36
Master Read (aa_i2c_read) . . . . . . . . . . . . . . . . . . . . . 36
Master Read Extended (aa_i2c_read_ext) . . . . . . . . . . . . . 37
Master Write (aa_i2c_write) . . . . . . . . . . . . . . . . . . . . . 38
Master Write Extended (aa_i2c_write_ext) . . . . . . . . . . . . . 39
2
I C Slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Slave Enable (aa_i2c_slave_enable) . . . . . . . . . . . . . . . . . 40
Slave Disable (aa_i2c_slave_disable) . . . . . . . . . . . . . . . . 41
Slave Set Response (aa_i2c_slave_set_response) . . . . . . . . . 41
Slave Write Statistics (aa_i2c_slave_write_stats) . . . . . . . . . 42
www.totalphase.com 61
Aardvark I2C/SPI Embedded Systems Interface
Slave Write Statistics Extended (aa_i2c_slave_write_stats_ext) . 42
Slave Read (aa_i2c_slave_read) . . . . . . . . . . . . . . . . . . . 43
Slave Read Extended (aa_i2c_slave_read_ext) . . . . . . . . . . . 44
5.6 SPI Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
SPI Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
General SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Con gure (aa_spi_con gure) . . . . . . . . . . . . . . . . . . . . 45
SPI Master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Set Bitrate (aa_spi_bitrate) . . . . . . . . . . . . . . . . . . . . . 46
Set Slave Select Polarity (aa_spi_master_ss_polarity) . . . . . . . 46
Master Write/Read (aa_spi_write) . . . . . . . . . . . . . . . . . 47
SPI Slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Slave Enable (aa_spi_slave_enable) . . . . . . . . . . . . . . . . . 48
Slave Disable (aa_spi_slave_disable) . . . . . . . . . . . . . . . . 48
Slave Set Response (aa_spi_slave_set_response) . . . . . . . . . . 48
Slave Read (aa_spi_slave_read) . . . . . . . . . . . . . . . . . . . 49
5.7 GPIO Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
GPIO Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
GPIO Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Direction (aa_gpio_direction) . . . . . . . . . . . . . . . . . . . . 51
Pullup (aa_gpio_pullup) . . . . . . . . . . . . . . . . . . . . . . . 52
Get (aa_gpio_get) . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Set (aa_gpio_set) . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Change (aa_gpio_change) . . . . . . . . . . . . . . . . . . . . . . 53
5.8
2
I C Bus Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Monitor Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2
I C Bus Monitor Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Monitor Enable (aa_i2c_monitor_enable) . . . . . . . . . . . . . . 54
Monitor Disable (aa_i2c_monitor_disable) . . . . . . . . . . . . . 55
Monitor Read (aa_i2c_monitor_read) . . . . . . . . . . . . . . . . 55
5.9 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6 Legal / Contact 58
6.1 Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.2 Life Support Equipment Policy . . . . . . . . . . . . . . . . . . . . . . . . 58
6.3 Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
www.totalphase.com 62
You might also like
- Y3 Ug Handbook 2019 2020 Final 8october2019 45543No ratings yetY3 Ug Handbook 2019 2020 Final 8october2019 4554337 pages
- 1-Wire Is A Device Communications Bus System Designed by Dallas Semiconductor Corp. ThatNo ratings yet1-Wire Is A Device Communications Bus System Designed by Dallas Semiconductor Corp. That5 pages
- Implementation of I2C-DMA & SPI-DMA Interface: A Comparative StudyNo ratings yetImplementation of I2C-DMA & SPI-DMA Interface: A Comparative Study6 pages
- SPI Vs I2C Vs UART - What Are The Differences Between These Protocols100% (1)SPI Vs I2C Vs UART - What Are The Differences Between These Protocols10 pages
- What Is I2C?: To Know The I2C in Detail See This Article100% (2)What Is I2C?: To Know The I2C in Detail See This Article6 pages
- I C Slave To SPI Master Bridge: December 2010 Reference Design RD1094No ratings yetI C Slave To SPI Master Bridge: December 2010 Reference Design RD10947 pages
- Serial Interfaces, Part Deux C and SPI: December 4, 2002 Presented by Eugene HoNo ratings yetSerial Interfaces, Part Deux C and SPI: December 4, 2002 Presented by Eugene Ho18 pages
- MES MODULE 4 Embedded System ComponentsNo ratings yetMES MODULE 4 Embedded System Components103 pages
- Islamic University of Technology: EEE 4483 Digital Electronics & Pulse TechniquesNo ratings yetIslamic University of Technology: EEE 4483 Digital Electronics & Pulse Techniques20 pages
- Presentation of I2C Communicatio Protocol and SPI CommunicationNo ratings yetPresentation of I2C Communicatio Protocol and SPI Communication9 pages
- I2c Advanced Concepts Toughest Interview Questions - 1100% (1)I2c Advanced Concepts Toughest Interview Questions - 150 pages
- What Is It? - Basic SPI - Capabilities - Protocol - Pros and Cons - UsesNo ratings yetWhat Is It? - Basic SPI - Capabilities - Protocol - Pros and Cons - Uses29 pages
- FPGA Implementation of I2C & SPI Protocols A Comparative StudyNo ratings yetFPGA Implementation of I2C & SPI Protocols A Comparative Study4 pages
- FPGA Implementation of I C & SPI Protocols: A Comparative StudyNo ratings yetFPGA Implementation of I C & SPI Protocols: A Comparative Study4 pages
- Basics of The Spi Communication ProtocolNo ratings yetBasics of The Spi Communication Protocol5 pages
- Designing SPI To I2C Protocol Converter Base On ASIC Technology and Implementing On The FPGA PlatformNo ratings yetDesigning SPI To I2C Protocol Converter Base On ASIC Technology and Implementing On The FPGA Platform8 pages
- MicroprocessorBasedSystems Term-II Lec3 SPI and I2C InterfaceNo ratings yetMicroprocessorBasedSystems Term-II Lec3 SPI and I2C Interface39 pages
- I2C Info - I2C Bus, Interface and ProtocolNo ratings yetI2C Info - I2C Bus, Interface and Protocol2 pages
- SPI I2C Bus Lines Control Multiple Peripherals100% (3)SPI I2C Bus Lines Control Multiple Peripherals10 pages
- MRSGI - SECForm20IS - Preliminary IS - SEC Received PDFNo ratings yetMRSGI - SECForm20IS - Preliminary IS - SEC Received PDF65 pages
- Post Graduate Diploma in Applied StatisticsNo ratings yetPost Graduate Diploma in Applied Statistics1 page
- Teach Yourself Cobol in 21 Days (2nd Ed)No ratings yetTeach Yourself Cobol in 21 Days (2nd Ed)590 pages
- Matriz de Certificacion Forms y ReportsNo ratings yetMatriz de Certificacion Forms y Reports44 pages
- NairaCompare - Pitch Deck - Rv-Final - v4 1 2b 1No ratings yetNairaCompare - Pitch Deck - Rv-Final - v4 1 2b 116 pages
- Capital Expenditure - Wikipedia, The Free EncyclopediaNo ratings yetCapital Expenditure - Wikipedia, The Free Encyclopedia2 pages
- Saltzman Et Al-2024-Clinical ProteomicsNo ratings yetSaltzman Et Al-2024-Clinical Proteomics17 pages
- Mli102 - Management of Library and Information Centres100% (1)Mli102 - Management of Library and Information Centres49 pages
- Khan v. Ombudsman, GR 125296, 20 July 2006No ratings yetKhan v. Ombudsman, GR 125296, 20 July 20063 pages
