during the procedure.

7. The upgraded Aardvark adapter should now be usable by any Aardvark-enabled

application.

8. In the event that there was a malfunction in the firmware update, the Aardvark
adapter may not be recognizable by an Aardvark-enabled application. Try the update
again, since the Aardvark adapter has most likely become locked due to a corruption in
the upgrade process. If the update still does not take effect, it is best to revert back to
the previous firmware. This can be done by running a previous version of aaflash that
contains an earlier firmware version. Check the Total Phase website or the
distribution CD that was included with your Aardvark adapter for previous versions of
the firmware.

5 API Documentation

Top
5.1 Introduction

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

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

Top
5.2 General Data Types

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

typedef unsigned char aa_u08; typedef unsigned short aa_u16; typedef

unsigned int aa_u32;

Top
5.3 Notes on Status Codes

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

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

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

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

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

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

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

Top
5.4 General

5.4.1 Interface

Find Devices (aa_find_devices) Top

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.

Specific Error Codes

None.

Details
Each element of the array is written with the port number. Devices that are in use are
ORed with AA_PORT_NOT_FREE ( 0x8000 ).

Example:

Devices are attached to port 0, 1, 2

ports 0 and 2 are available, and port 1 is in-use.

array => 0x0000, 0x8001, 0x0002;

If the input array is NULL, it is not filled with any values.

If there are more devices than the array size (as specified by nelem ), only the first
nelem port numbers will be written into the array.

Find Devices (aa_find_devices_ext) Top

int aa_find_devices_ext (int num_devices, aa_u16 * devices, int
num_ids, aa_u32 * unique_ids);
Get a list of ports and unique IDs to which Aardvark devices are attached.

Arguments

num_devices maximum number of device port numbers to return

devices array into which the device port numbers are returned
num_ids maximum number of unique IDs to return
unique_ids array into which the unique IDs are returned

Return Value
This function returns the number of devices found, regardless of the array sizes.

Specific 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 non-zero if valid.

The IDs are the unsigned integer representation of the 10-digit serial numbers.

The number of devices and IDs returned in each of their respective arrays is
determined by the minimum of num_devices and num_ids. However, if either array is
NULL, the length passed in for the other array is used as-is, and the NULL array is not
populated. If both arrays are NULL, neither array is populated, but the number of
devices found is still returned.
 Open an Aardvark device (aa_open) Top
Aardvark aa_open (int port_number);
Open the Aardvark port.

Arguments

port_number The port is the same as the one obtained from function
aa_find_devices. It is a zero-based number.

Return Value

This function returns an Aardvark handle, which is guaranteed to be greater than zero
if valid.

Specific Error Codes

AA_UNABLE_TO_OPEN The specified 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 firmware. The DLL is not of a sufficient version
for interoperability with the firmware 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 configured to send
asynchronous responses to a third-party 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 a known-state. Also the I2C bus is freed, in
the event that it was held indefinitely from a previous AA_I2C_NO_STOP transaction.

Open an Aardvark device (aa_open_ext) Top

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

aa_ext pointer to pre-allocated 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.

Specific Error Codes

AA_UNABLE_TO_OPEN The specified 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 firmware. The DLL is not of a sufficient version
for interoperability with the firmware 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 field 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.

The structure is zeroed before the open is attempted. It is filled with whatever
information is available. For example, if the firmware version is not filled, 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) Top

int aa_close (Aardvark aardvark);
Close the Aardvark port.

Arguments

aardvark handle of an Aardvark adapter to be closed

Return Value
 The number of adapters closed is returned on success. This will usually be 1.

Specific Error Codes

None.

Details
An Aardvark adapter could have potentially been opened, enabled as a slave, and
configured to send and receive asynchronous responses to and from a third-party
master. A call to aa_close() will deactivate all slave functionality. Also the I2C bus is
freed, in the event that it was held indefinitely from a previous AA_I2C_NO_STOP
transaction.

If the handle argument is zero, the function will attempt to close all possible handles,
thereby closing all open Aardvark adapters. The total number of Aardvark adapters
closed is returned by the function.

Get Port (aa_port) Top

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 zero-based

number.

Specific Error Codes

None.

Details
None.

Get Features (aa_features) Top

int aa_features (Aardvark aardvark);
Return the device features as a bit-mask of values, or an error code if the handle is not
valid.

Arguments

aardvark handle of an Aardvark adapter

Return Value
The features of the Aardvark device are returned. These are a bit-mask of the
following values.

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

#define AA_FEATURE_GPIO (1<<3)

Specific Error Codes

None.

Details
 None.

Get Unique ID (aa_unique_id) Top

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 non-zero if valid. The ID is the unsigned integer representation of the 10-digit
serial number.

Specific Error Codes

None.

Details
None.

Status String (aa_status_string) Top

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
This function returns a human readable string that corresponds to status. If the code is
not valid, it returns a NULL string.

Specific Error Codes

None.

Details

None.

Logging (aa_log) Top

int aa_log (Aardvark aardvark, int level, int handle);
Enable logging to a file.

Arguments

aardvark handle of an Aardvark adapter

level the logging detail level as described below
handle a file descriptor
Return Value
An Aardvark status code is returned with AA_OK on success.

Specific Error Codes

 None.

Details

The handle must be standard file descriptor. In C, a file descriptor can be obtained by
using the ANSI C function "open" or by using the function "fileno" 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.

Due to inconsistencies arising from how Microsoft handles linkage to the C runtime
library, logging to a file may not work in Windows. However, logging to stdout and
stderr is still supported. As a convenience, the following two constants are defined
and can be passed as the handle argument.

AA_LOG_STDOUT

AA_LOG_STDERR

Version (aa_version) Top

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 pre-allocated structure

Return Value
An Aardvark status code is returned with AA_OK on success.

Specific 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 definition of AardvarkVersion.

Configure (aa_configure) Top

int aa_configure (Aardvark aardvark, AardvarkConfig config);

Activate/deactivate individual subsystems (I2C, SPI, GPIO).

Arguments
 aardvark handle of an Aardvark adapter
config enumerated type specifying configuration. See Table 2

Table 2 : config enumerated types

AA_CONFIG_GPIO_ONLY Configure all pins as GPIO. Disable both I2C and SPI.
AA_CONFIG_SPI_GPIO Configure I2C pins as GPIO. Enable SPI.
AA_CONFIG_GPIO_I2C Configure SPI pins as GPIO. Enable I2C.
AA_CONFIG_SPI_I2C Disable GPIO. Enable both I2C and SPI.
AA_CONFIG_QUERY Queries existing configuration (does not modify).

Return Value
The current configuration on the Aardvark adapter will be returned. The configuration
will be described by the same values in AardvarkConfig.

Specific Error Codes

AA_CONFIG_ERROR The I2C or SPI subsystem is currently active and the new
configuration requires the subsystem to be deactivated.
Details
If either the I2C or SPI subsystems have been disabled by this API call, all other API
functions that interact with I2C or SPI will return AA_CONFIG_ERROR.

If configurations are switched, the subsystem specific 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 mode, SPI slave response, I2C bitrate, I2C slave response, etc.

However, if a subsystem is shut off, it will be restarted in a quiescent mode. That is to

say, the I2C slave function will not be reactivated after re-enabling the I2C subsystem,
even if the I2C slave function was active before first disabling the I2C subsystem.

Note: Whenever the configure command is executed and GPIO lines are enabled, the
GPIO lines will be momentarily switched to high-Z before their direction and pullup
configurations are executed.

Target Power (aa_target_power) Top

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 configuration will be described by the same values as in the table above.

Specific 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) Top

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.

Table 4 : Status code enumerated types

AA_ASYNC_NO_DATA No asynchronous data is available.

AA_ASYNC_I2C_READ I2C slave read data is available. Use aa_i2c_slave_read
to get data.
AA_ASYNC_I2C_WRITE I2C 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.

These codes can be bitwise ORed together if there are multiple types of data available.

Specific Error Codes

None.

Details
Recall that, like all other Aardvark functions, this function is not thread-safe.

If the timeout value is negative, the function will block indefinitely until data arrives. If
the timeout value is 0, the function will perform a non-blocking check for pending
asynchronous data.

As described before, the Aardvark software contains asynchronous queues that can
be filled 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 systems incoming receive buffer, but the function will not examine that
data. Hence any pending data in the operating systems incoming buffer will not be
reported to the user until the Aardvarks software queues have been fully serviced.

If there is no data already available, this function will check the operating systems
receive buffer for the presence of asynchronous data. The function will block for the
specified timeout. It will then only report the type of the very first data that has been
received. The function will not examine the remainder of the operating systems
receive buffer 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 specified 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.
Sleep (aa_sleep_ms) Top
u32 aa_sleep_ms (u32 milliseconds);
Sleep for given amount of time.

Arguments

milliseconds number of milliseconds to sleep

Return Value
This function returns the number of milliseconds slept.

Specific Error Codes

None.

Details

This function provides a convenient cross-platform function to sleep the current

thread using standard operating system functions.

The accuracy of this function depends on the operating system scheduler. This
function will return the number of milliseconds that were actually slept.

Top
5.5 I2C Interface

5.5.1 I2C Notes

1. It is not necessary to set the bitrate for the Aardvark I2C slave.
2. An I2C master operation read or write operation can be transacted while leaving the
I2C slave functionality enabled. In a multi-master situation it is possible for the
Aardvark adapter to lose the bus during the slave addressing portion of the
transaction. If the other master that wins the bus subsequently addresses this
Aardvark adapters slave address, the Aardvark adapter will respond appropriately to
the request using its slave mode capabilities.

3. It is always advisable to set the slave response before first enabling the slave. This
ensures that valid data is sent to any requesting master.

4. It is not possible to receive messages larger than approximately 4 KiB as a slave due to
operating system limitations on the asynchronous incoming buffer. As such, one
should not queue up more than 4 KiB of total slave data between calls to the Aardvark
API.

5. Since firmware revision 2.00 it is possible for the Aardvark I2C master to employ some
of the advanced features of I2C. This is accomplished by the AardvarkI2cFlags
argument type that is included in the aa_i2c_read and aa_i2c_write argument lists.
The options in Table 5 are available can be logically ORed together to combine them
for one operation.

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

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

Table 6 : 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 adapters
slave address. As a result, this Aardvark adapter
has automatically switched to slave mode and is
responding.
AA_I2C_STATUS_SLA_NACK The Aardvark adapter failed to receive
acknowledgment for the requested slave
address during a master operation.
AA_I2C_STATUS_DATA_NACK The last data byte in the transaction was not
acknowledged by the slave.
AA_I2C_STATUS_ARB_LOST Another master device on the bus was accessing
the bus simultaneously with this Aardvark
adapter. That device won arbitration of the bus
as per the I2Cspecification.
AA_I2C_STATUS_BUS_LOCKED An I2C packet is in progress, and the time since
the last I2C event executed or received on the
bus has exceeded the bus lock timeout. This is
most likely due to the clock line of the bus being
held low by some other device, or due to the
data line held low such that a start condition
cannot be executed by the Aardvark. The bus
lock timeout can be configured using the
aa_i2c_bus_timeout function. The Aardvark
adapter resets its own I2C interface when a
timeout is observed and no further action is
taken on the bus.
AA_I2C_STATUS_LAST_DATA_ACK When the Aardvark slave is configured with a
fixed length transmit buffer, it will detach itself
from the I2C bus after the buffer is fully
transmitted. The Aardvark slave also expects
that the last byte sent from this buffer is
NACKed by the opposing master device. This
status code is returned by the Aardvark slave
(see Slave Write Statistics API) if the master
device instead ACKs the last byte. The
notification can be useful when debugging a
third-party master device.
These codes can provide hints as to why an impartial transaction was
executed by the Aardvark adapter. In the event that a bus error occurs while
the Aardvark adapter is idle and enabled as a slave (but not currently
receiving a message), the adapter will return the bus error through the
aa_i2c_slave_read function. The length of the message will be 0 bytes but
the status code will reflect the bus error.

 
 5.5.2 General I2C

I2C Pullup (aa_i2c_pullup) Top

int aa_i2c_pullup (Aardvark aardvark, aa_u08 pullup_mask);
Activate/deactivate I2C pull-up resistors on SCL and SDA.

Arguments

aardvark handle of an Aardvark adapter

pullup_mask enumerated values specifying pullup state. See Table 7.
Table 7 : pullup_mask enumerated types

AA_I2C_PULLUP_NONE Disable SCL/SDA pull-up resistors

AA_I2C_PULLUP_BOTH Enable SCL/SDA pull-up resistors
AA_I2C_PULLUP_QUERY Queries the pull-up resistor state

Return Value
The current state of the I2C pull-up resistors on the Aardvark adapter will be
returned. The configuration will be described by the same values as in the table above.

Specific Error Codes

AA_INCOMPATIBLE_DEVICE The hardware version is not compatible with this

feature. Only hardware versions 2.00 or greater
support switchable pull-up resistors pins.

Details
Both pull-up resistors are controlled together. Independent control is not supported.
This function may be performed in any operation mode.

Free bus (aa_i2c_free_bus) Top

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.

Specific Error Codes

AA_I2C_ALREADY_FREE_BUS The bus was already free and no action was taken.

Details
If the Aardvark I2C subsystem had executed a master transaction and is holding the
bus due to a previous AA_I2C_NO_STOP flag, 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.

Similarly, if the Aardvark I2C subsystem was placed into slave mode and in the middle
of a slave transaction, this command will disconnect the slave from the bus, flush the
last transfer, and re-enable the slave. Such a feature is useful if the Aardvark adapter
was receiving bytes but then was forced to wait indefinitely 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.

Set Bus Lock Timeout (aa_i2c_bus_timeout) Top

int aa_i2c_bus_timeout (Aardvark aardvark, aa_u16 timeout_ms);
Set the I2C bus lock timeout in milliseconds.

Arguments

aardvark handle of an Aardvark adapter

timeout_ms the requested bus lock timeout in ms.

Return Value
This function returns the actual timeout set.

Specific Error Codes

None.

Details
The power-on default timeout is 200ms. The minimum timeout value is 10ms and the
maximum is 450ms. If a timeout value outside this range is passed to the API function,
the timeout will be restricted. The exact timeout that is set can vary based on the
resolution of the timer within the Aardvark adapter. The nominal timeout that was set
is returned back by the API function.

If timeout_ms is 0, the function will return the bus lock timeout presently set on the
Aardvark adapter and the bus lock timeout will be left unmodified.

If the bus is locked during the middle of any I2C transaction (master transmit, master
receive, slave transmit, slave receive) the appropriate extended API function will
return the status code AA_I2C_STATUS_BUS_LOCKED as described in the preceding
Notes section. The bus lock timeout is measured between events on the I2C bus,
where an event is a start condition, the completion of 9bits of data transfer, a repeated
start condition, or a stop condition. For example, if a full 9 bits are not completed
within the bus lock timeout (due to clock stretching or some other error), the bus lock
error will be triggered.

Please note that once the Aardvark adapter detects a bus lock timeout, it will abort its
I2C interface, even if the timeout condition is seen in the middle of a byte. When the
Aardvark is acting as an I2C mater device, this may result in only a partial byte being
executed on the bus.

5.5.3 I2C Master

Set Bitrate (aa_i2c_bitrate) Top

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.

Specific Error Codes

None.

Details
The power-on default bitrate is 100 kHz.

Only certain discrete bitrates are supported by the Aardvark I2C 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 unmodified.

Master Read (aa_i2c_read) Top

int aa_i2c_read (Aardvark aardvark, aa_u16 slave_addr,
AardvarkI2cFlags flags, aa_u16 num_bytes, aa_u08 * data_in);
Read a stream of bytes from the 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 and below
num_bytes the number of bytes to read (maximum 65535)
data_in pointer to data

Return Value
Number of bytes read.

Specific 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
For ordinary 7-bit addressing, the lower 7 bits of slave_addr should correspond to
the slave address. The topmost bits are ignored. The Aardvark I2C subsystem will
assemble the address along with the R/W bit after grabbing the bus. For 10-bit
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 specification, namely by first issuing an write transaction on the bus to
specify the 10-bit 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 10-bit 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 nature of the I2C 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 I2C 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 returned 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 the data transmission due to the presence of another I2C 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 transmission. This behavior is in accordance with the I2C protocol.

Additionally, the flags argument can be used to specify a sized read operation. If the
flag includes the value AA_I2C_SIZED_READ, the Aardvark adapter will treat the first
byte received from the slave as a packet length field. This length denotes the number
of bytes that the slave has available for reading (not including the length byte itself).
The Aardvark adapter will continue to read the minimum of num_bytes-1 and the
length field. The length value must be greater than 0. If it is equal to 0, it will be treated
as though it is 1. In order to support protocols that include an optional checksum byte
(e.g., SMBus) the flag can alternatively be set to AA_I2C_SIZED_READ_EXTRA1. In this
case the Aardvark will read one more data byte beyond the number specified by the
length field.

Master Read Extended (aa_i2c_read_ext) Top

int aa_i2c_read_ext (Aardvark aardvark, aa_u16 slave_addr,
AardvarkI2cFlags flags, aa_u16 num_bytes, aa_u08 * data_in,
aa_u16 * num_read);
Read a stream of bytes from the 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 previously
num_bytes the number of bytes to read (maximum 65535)
data_in pointer to data
 num_read the actual number of bytes read
Return Value
Status code (see "Notes" section).

Specific Error Codes

None.

Details
This function operates exactly like aa_i2c_read, except that the return value now
specifies a status code. The number of bytes read is returned through an additional
pointer argument at the tail of the parameter list.

The status code allows the user to discover specific events on the I2C 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 flag is not used since
the acknowledgment of data bytes is predetermined by the master and the I2C
specification.

Master Write (aa_i2c_write) Top

int aa_i2c_write (Aardvark aardvark, aa_u16 slave_addr,
AardvarkI2cFlags flags, aa_u16 num_bytes, const aa_u08 *
data_out);
Write a stream of bytes to the 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.

Specific 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 7-bit addressing, the lower 7 bits of slave_addr should correspond to
the slave address. The topmost bits are ignored. The Aardvark I2C subsystem will
assemble the address along with the R/W bit after grabbing the bus. For 10-bit
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 specification. There is a limitation that a maximum of only 65534 bytes
can be written in a single transaction if the 10-bit addressing mode is used.
 The slave_addr 0x00 has been reserved in the I2C protocol specification for general
call addressing. I2C slaves that are enabled to respond to a general call will
acknowledge this address. The general call is not treated specially in the Aardvark I2C
master. The user of this API can manually assemble the first 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 I2C 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 of another I2C master.

The slave refuses the reception of any more bytes.

Master Write Extended (aa_i2c_write_ext) Top

int aa_i2c_write_ext (Aardvark aardvark, aa_u16 slave_addr,
AardvarkI2cFlags flags, aa_u16 num_bytes, const aa_u08 *
data_out, aa_u16 * num_written);
Write a stream of bytes to the 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
Status code (see "Notes" section).

Specific Error Codes

None.
Details
This function operates exactly like aa_i2c_write, except that the return value now
specifies a status code. The number of bytes written is returned through an additional
pointer argument at the tail of the parameter list.

The status code allows the user to discover specific events on the I2C 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 flag can be useful in

the following situation:

Normally the I2C master will write to the slave until the slave issues a NACK or
the requested number of bytes have been written.

If the master has wishes to write 10 bytes, the I2C slave issues either an ACK or
NACK on the tenth byte without affecting 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.

Master Write-Read (aa_i2c_write_read) Top

int aa_i2c_write_read (Aardvark aardvark, aa_u16 slave_addr,
AardvarkI2cFlags flags, aa_u16 out_num_bytes, const aa_u08 *
out_data, aa_u16 * num_written, aa_u16 in_num_bytes, aa_u08 *
in_data, aa_u16 * num_read);
Write a stream of bytes to the I2C slave device followed by a read from the same 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
out_num_bytes the number of bytes to write (maximum 65535)
out_data pointer to data to write
num_written the actual number of bytes written
in_num_bytes the number of bytes to read (maximum 65535)
in_data pointer to data for read
num_read the actual number of bytes read

Return Value
Combined I2C status code from the write and read operations.

Specific Error Codes

None.

Details
 This function performs the functions of aa_i2c_write_ext and aa_i2c_read_ext in
one atomic operation, thereby minimizing the latency between consecutive write and
read operations due to the USB communication layer.

A combined status code from the write and the read operations is provided as the
return value of the function. The return value is constructed as (read_status
<< 8) | (write_status). See the "Notes" section, along with the details of
aa_i2c_write_ext and aa_i2c_read_ext, for more discussion about the specific
status codes. Note that if the write phase of the operation completes with a non-zero
status code, the Aardvark adapter will not physically execute the read phase of the
operation.

If either the write or read fails with an error (as opposed to simply a non-zero status
code), the return value of the function reflects the appropriate error code, with
preference given to write errors.

5.5.4 I2C Slave

Slave Enable (aa_i2c_slave_enable) Top

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.

Specific Error Codes

None.

Details
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 I2C master. After having been addressed by a general call, the
Aardvark I2C slave treats the transaction no differently than a single slave
communication. There is no support for the hardware address programming feature of
the general call that is described in the I2C protocol specification 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 non-zero, then the slave will stop transmitting bytes at the
specified limit and subsequent bytes received by the master will be 0xff due to the
bus pull-up 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 non-zero, the slave will send a not-acknowledge 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) Top

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.

Specific Error Codes

None.

Details
None.

Slave Set Response (aa_i2c_slave_set_response) Top

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.

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.

Specific Error Codes

None.

Details
 The value of num_bytes must be greater than zero. If it is zero, the response string is
undefined until this function is called with the correct parameters.

Due to limited buffer 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 buffer space is 64 bytes.

Slave Write Statistics (aa_i2c_slave_write_stats) Top

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.

Specific Error Codes

AA_I2C_SLAVE_TIMEOUT There was no recent slave transmission.

Details
The transmission of bytes from the Aardvark slave, when it is configured as an I2C
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 Top

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

Arguments

aardvark handle of an Aardvark adapter

num_written : the number of bytes written by the slave

Return Value

Status code (see "Notes" section).

Specific Error Codes

None.
Details
This function operates exactly like aa_i2c_slave_write_stats, except that the
return value now specifies 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 reflect the number of bytes written by the
slave. It can be off by 1.

Slave Read (aa_i2c_slave_read) Top

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 buffer
data_out pointer to data buffer

Return Value
This function returns the number of bytes read asynchronously.

Specific 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 specific slave, *addr will be set to the value of this
slaves 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 specifies the size of the memory pointed to by data. It is
possible, 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.

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 slave, when it is configured as an I2C 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) Top

 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 buffer
data_out pointer to data buffer
num_read the actual number of bytes read by the slave
Return Value

Status code (see "Notes" section).

Specific Error Codes

None.

Details
This function operates exactly like aa_i2c_slave_read, except that the return value
now specifies 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.

Top
5.6 SPI Interface

5.6.1 SPI Notes

1. The SPI master and slave must both be configured to use the same bit protocol (mode).

2. It is not necessary to set the bitrate for the Aardvark SPI slave.

3. An SPI master operation read or write operation can be transacted while leaving the
SPI slave functionality enabled. During the master transaction, the slave will be
temporarily deactivated. Once the master transaction is complete, the slave will be
automatically reactivated.

4. It is always advisable to set the slave response before first enabling the slave. This
ensures that valid data is sent to any requesting master.

5. It is not possible to receive messages larger than approximately 4 KiB as a slave due to
operating system limitations on the asynchronous incoming buffer. As such, one
should not queue up more than 4 KiB of total slave data between calls to the Aardvark
API.

6. It is not possible to send messages larger than approximately 4 KiB as a master due to
operating system limitations on the asynchronous incoming buffer. The SPI is full-
duplex so there must be enough buffer space to accommodate the slave response
when sending as a master.
 7. Sending zero bytes as an SPI master will simply toggle the slave select line for 5-10 µs.

5.6.2 General SPI

Configure (aa_spi_configure) Top

int aa_spi_configure (Aardvark aardvark, AardvarkSpiPolarity
polarity, AardvarkSpiPhase phase, AardvarkSpiBitorder bitorder);
Configure 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.

Specific Error Codes

None.

Details
These configuration parameters specify how to clock the bits that are sent and
received on the Aardvark SPI interface.

The polarity option specifies which transition constitutes the leading edge and which
transition is the falling edge. For example, AA_SPI_POL_RISING_FALLING would
configure the SPI to idle the SCLK clock line low. The clock would then transition low-
to-high on the leading edge and high-to-low 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 configure 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 first.

The pair ( AA_SPI_POL_FALLING_RISING, AA_SPI_PHASE_SETUP_SAMPLE ) would

correspond to mode 3 in the figure found in the "SPI Background" chapter.

5.6.3 SPI Master

Set Bitrate (aa_spi_bitrate) Top

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.
Specific Error Codes

None.

Details

The power-on 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 unmodified.

Set Slave Select Polarity Top

(aa_spi_master_ss_polarity)
int aa_spi_master_ss_polarity (Aardvark aardvark,
AardvarkSpiSSPolarity polarity);
Change the output polarity on the SS line.

Arguments

aardvark handle of an Aardvark adapter

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.

Specific Error Codes

None.

Details
This function only affects the SPI master functions on the Aardvark adapter. When
configured as an SPI slave, the Aardvark adapter will always be setup with SS as active
low.

Master Write/Read (aa_spi_write) Top

int aa_spi_write (Aardvark aardvark, aa_u16 out_num_bytes, const
aa_u08 * data_out, aa_u16 in_num_bytes, aa_u08 * data_in);
Write a stream of bytes to the downstream SPI slave device and read back the full-duplex
response.

Arguments

aardvark handle of an Aardvark adapter

out_num_bytes number of bytes to send
data_out pointer to the bytes to transmit out
in_num_bytes number of bytes to receive
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. See below for how this
value relates to in_num_bytes.

Specific 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 out_num_bytes is less than 4 KiB.

Details
Due to the full-duplex nature of the SPI protocol, for every byte written to the slave,
one byte is also received. The Aardvark will always receive the same number of bytes
that it sends out (barring any error). This is the return value mentioned above. The
user has the option of saving all, some, or none of those received bytes by varying the
size of in_num_bytes.

This function will always write out the number of bytes defined by out_num_bytes
from the memory pointed to by data_out. When out_num_bytes is larger than
in_num_bytes, data_in is completely filled and any extra bytes are dropped. When
out_num_bytes is less than in_num_bytes, all the received bytes are saved and
data_in is only partially filled.

The data_in pointer should reference memory that is at least allocated to the size
specified by in_num_bytes. Otherwise there will be a memory access violation in the
program.

If out_num_bytes is 0, no bytes will be written to the slave. However, the slave select
line will be dropped for 5-10 µ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 firmware for an subsequent
reception of bytes. If out_num_bytes is 0, data_out, data_in, and in_num_bytes
can be set to 0.

If the return value of this function is less than out_num_bytes, there was an error. SPI
is a bit-blasting 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.

An error will likely occur if the number of bytes sent is significantly greater than 4 KiB.
This function cannot reliably execute larger transfers due to the buffering 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 any received data up to in_num_bytes will be in the
memory pointed to by data_in. Note that the last few bytes of the response may be
corrupted as well.

5.6.4 SPI Slave

Slave Enable (aa_spi_slave_enable) Top

 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.

Specific Error Codes

None.

Details
None.

Slave Disable (aa_spi_slave_disable) Top

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.

Specific Error Codes

None.

Details
None.

Slave Set Response (aa_spi_slave_set_response) Top

int aa_spi_slave_set_response (Aardvark aardvark, aa_u08
num_bytes, const aa_u08 * data_out);
Set the slave response in the event the Aardvark adapter is put into slave mode and
contacted by a master.

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.

Specific Error Codes

None.

Details
The value of num_bytes must be greater than zero. If it is zero, the response string is
undefined until this function is called with the correct parameters.
 Due to limited buffer 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 buffer space will nominally be 64 bytes but may change depending on firmware
revision.

Slave Read (aa_spi_slave_read) Top

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 buffer
data_in pointer to data buffer
Return Value
This function returns the number of bytes read asynchronously.

Specific 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 specifies the size of the memory pointed to by data. It is
possible, 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.

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

The SPI API does not include a function that is analogous to the I2C function

aa_i2c_slave_write_stats. Since SPI is a full-duplex 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.

 
 Top
5.7 GPIO Interface

5.7.1 GPIO Notes

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

AA_GPIO_SCL Pin 1 0x01 I2C SCL line

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

2. There is no check in the GPIO API calls to see if a particular GPIO line is enabled in the
current configuration. If a line is not enabled for GPIO, the get function will simply
return 0 for those bits. Another example is if one changes the GPIO directions for I2C
lines while the I2C subsystem is still active. These new direction values will be cached
and will automatically be activate if a later call to aa_configure disables the I2C
subsystem and enables GPIO for the I2C lines. The same type of behavior holds for
aa_gpio_pullup and aa_gpio_set.

3. Additionally, for lines that are not configured as inputs, a change in the pullup
configuration using aa_gpio_pullup will be cached and will take effect the next time
the line is active and configured as an input. The same behavior holds for aa_gpio_set
when a line is configured as an input instead of an output.

4. On Aardvark adapter power-up, directions default to all input, pullups default to

disabled and outputs default to logic low. Also the GPIO subsystem is off by default. It
must be activated by using aa_configure.

5. Note: For hardware version 1.02, it is not possible to have high-Z inputs on the I2C
lines since that hardware has 2.2K pullups on the I2C bus.

5.7.2 GPIO Interface

Direction (aa_gpio_direction) Top

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

direction_mask each bit corresponds to the physical line as given by
AardvarkGpioBits. If a line's bit is 0, the line is configured as
an input. Otherwise it will be an output.
Return Value
An Aardvark status code is returned that is AA_OK on success.

Specific Error Codes

None.

Details
None.

Pullup (aa_gpio_pullup) Top

int aa_gpio_pullup (Aardvark aardvark, aa_u08 pullup_mask);
Change the pullup configuration of the GPIO lines.

Arguments

aardvark handle of an Aardvark adapter

pullup_mask each bit corresponds to the physical line as given by
AardvarkGpioBits. If a line's bit is 1, the line's pullup is active
whenever the line is configured as an input. Otherwise the pullup
will be deactivated.

Return Value
An Aardvark status code is returned that is AA_OK on success.

Specific Error Codes

None.

Details
None.

Get (aa_gpio_get) Top

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

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

Specific Error Codes

None.

Details
A line's bit position in the mask will be 0 if it is configured as an output or if it
corresponds to a subsystem that is still active.

Set (aa_gpio_set) Top

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.

Specific Error Codes

None.

Details
If a line is configured 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 effect.

Change (aa_gpio_change) Top

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.

Specific Error Codes

None.

Details
The function will return either when a change has occurred or the timeout expires.
Pins configured for I2C or SPI will be ignored. Pins configured as outputs will be
ignored. The timeout, specified in milliseconds, has a precision of approximately 2 ms.
The maximum allowable timeout is approximately 60 seconds. If the timeout expires,
this function will return the current state of the GPIO lines. It is the applications
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 first 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.

Top
5.8 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 configuration 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 config
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
 

6 Legal / Contact
Top
6.1 Disclaimer

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