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

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.

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.

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.

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.

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.

None.

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)
#define AA_FEATURE_I2C_MONITOR  (1<<4)

None.

None.

None.

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.

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.

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.

Both target power pins are controlled together. Independent control is not supported. This function may be executed in any operation mode.

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.

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 system’s incoming receive buffer, but the function will not examine that data. Hence any pending data in the operating system’s incoming buffer 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 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 system’s 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.

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.

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.

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

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

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.

This function returns the actual timeout set.

The power-on default timeout is 200 ms. The minimum timeout value is 10 ms and the maximum is 450 ms. 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 9 bits 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.

This function returns the actual bitrate set.

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.

Number of bytes read.

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.

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.

Number of bytes written.

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.

Status code (see "Notes" section).

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.

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

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.

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

None.

The number of bytes accepted by the Aardvark slave for the response.

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 can change depending on firmware revision.

The number of bytes written asynchronously.

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.

Status code (see "Notes" section).

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.

This function returns the number of bytes read asynchronously.

If the message was directed to this specific 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 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.

Status code (see "Notes" section).

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.

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

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.

This function returns the actual bitrate set.

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.

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

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.

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.

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.

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

None.

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

None.

The number of bytes accepted by the Aardvark for the response.

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.

This function returns the number of bytes read asynchronously.

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.