aardvark_py.py

Aardvark Example Source Code Version: 4.00 Date: 2007-04-20 Source code which shows how to use the

    aa_ext = AardvarkExt()
    (aa_ext.version.software, aa_ext.version.firmware, aa_ext.version.hardware, aa_ext.version.sw_req_by_fw, aa_ext.version.fw_req_by_sw, aa_ext.version.api_req_by_sw, aa_ext.features) = struct.unpack("HHHHHHi", c_aa_ext)
    return (_ret_, aa_ext)


# Close the Aardvark port.
def aa_close (aardvark):
    "usage: int = aa_close(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_close(aardvark)


# Return the port for this Aardvark handle.
# 
# The port number is a zero-indexed integer.
def aa_port (aardvark):
    "usage: int = aa_port(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_port(aardvark)


# Return the device features as a bit-mask of values, or
# an error code if the handle is not valid.
AA_FEATURE_SPI = 0x00000001
AA_FEATURE_I2C = 0x00000002
AA_FEATURE_GPIO = 0x00000008
AA_FEATURE_I2C_MONITOR = 0x00000010
def aa_features (aardvark):
    "usage: int = aa_features(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_features(aardvark)


# Return the unique ID for this Aardvark adapter.
# IDs are guaranteed to be non-zero if valid.
# The ID is the unsigned integer representation of the
# 10-digit serial number.
def aa_unique_id (aardvark):
    "usage: u32 = aa_unique_id(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_unique_id(aardvark) & 0xffffffffL


# Return the status string for the given status code.
# If the code is not valid or the library function cannot
# be loaded, return a NULL string.
def aa_status_string (status):
    "usage: str = aa_status_string(int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_status_string(status)


# Enable logging to a file.  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 can be obtained using "fopen"
# or can correspond to the common "stdout" or "stderr" --
# available when including stdlib.h
def aa_log (aardvark, level, handle):
    "usage: int = aa_log(Aardvark, int, int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_log(aardvark, level, handle)


# Return the version matrix for the device attached to the
# given handle.  If the handle is 0 or invalid, only the
# software and required api versions are set.
def aa_version (aardvark):
    "usage: (int, AardvarkVersion) = aa_version(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    (_ret_, c_version) = api.py_aa_version(aardvark)
    version = AardvarkVersion()
    (version.software, version.firmware, version.hardware, version.sw_req_by_fw, version.fw_req_by_sw, version.api_req_by_sw) = struct.unpack("HHHHHH", c_version)
    return (_ret_, version)


# Configure the device by enabling/disabling I2C, SPI, and
# GPIO functions.
# enum AardvarkConfig
AA_CONFIG_GPIO_ONLY = 0x00
AA_CONFIG_SPI_GPIO  = 0x01
AA_CONFIG_GPIO_I2C  = 0x02
AA_CONFIG_SPI_I2C   = 0x03
AA_CONFIG_QUERY     = 0x80

AA_CONFIG_SPI_MASK = 0x00000001
AA_CONFIG_I2C_MASK = 0x00000002
def aa_configure (aardvark, config):
    "usage: int = aa_configure(Aardvark, AardvarkConfig)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_configure(aardvark, config)


# Configure the target power pins.
# This is only supported on hardware versions >= 2.00
AA_TARGET_POWER_NONE = 0x00
AA_TARGET_POWER_BOTH = 0x03
AA_TARGET_POWER_QUERY = 0x80
def aa_target_power (aardvark, power_mask):
    "usage: int = aa_target_power(Aardvark, u08)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_target_power(aardvark, power_mask)


# Sleep for the specified number of milliseconds
# Accuracy depends on the operating system scheduler
# Returns the number of milliseconds slept
def aa_sleep_ms (milliseconds):
    "usage: u32 = aa_sleep_ms(u32)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_sleep_ms(milliseconds) & 0xffffffffL



#==========================================================================
# ASYNC MESSAGE POLLING
#==========================================================================
# Polling function to check if there are any asynchronous
# messages pending for processing. The function takes a timeout
# value in units of milliseconds.  If the timeout is < 0, the
# function will block until data is received.  If the timeout is 0,
# the function will perform a non-blocking check.
AA_ASYNC_NO_DATA = 0x00000000
AA_ASYNC_I2C_READ = 0x00000001
AA_ASYNC_I2C_WRITE = 0x00000002
AA_ASYNC_SPI = 0x00000004
AA_ASYNC_I2C_MONITOR = 0x00000008
def aa_async_poll (aardvark, timeout):
    "usage: int = aa_async_poll(Aardvark, int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_async_poll(aardvark, timeout)



#==========================================================================
# I2C API
#==========================================================================
# Free the I2C bus.
def aa_i2c_free_bus (aardvark):
    "usage: int = aa_i2c_free_bus(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_i2c_free_bus(aardvark)


# Set the I2C bit rate in kilohertz.  If a zero is passed as the
# bitrate, the bitrate is unchanged and the current bitrate is
# returned.
def aa_i2c_bitrate (aardvark, bitrate_khz):
    "usage: int = aa_i2c_bitrate(Aardvark, int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_i2c_bitrate(aardvark, bitrate_khz)


# enum AardvarkI2cFlags
AA_I2C_NO_FLAGS     = 0x00
AA_I2C_10_BIT_ADDR  = 0x01
AA_I2C_COMBINED_FMT = 0x02
AA_I2C_NO_STOP      = 0x04

# Read a stream of bytes from the I2C slave device.
def aa_i2c_read (aardvark, slave_addr, flags, num_bytes):
    "usage: (int, u08[]) = aa_i2c_read(Aardvark, u16, AardvarkI2cFlags, u16)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    data_in = array('B', [ 0 for i in range(num_bytes) ])
    (_ret_, data_in) = api.py_aa_i2c_read(aardvark, slave_addr, flags, num_bytes, data_in)
    del data_in[max(0, min(_ret_, len(data_in))):]
    return (_ret_, data_in)


# enum AardvarkI2cStatus
AA_I2C_STATUS_OK            = 0
AA_I2C_STATUS_BUS_ERROR     = 1
AA_I2C_STATUS_SLA_ACK       = 2
AA_I2C_STATUS_SLA_NACK      = 3
AA_I2C_STATUS_DATA_NACK     = 4
AA_I2C_STATUS_ARB_LOST      = 5
AA_I2C_STATUS_BUS_LOCKED    = 6
AA_I2C_STATUS_LAST_DATA_ACK = 7

# Read a stream of bytes from the I2C slave device.
# This API function returns the number of bytes read into
# the num_read variable.  The return value of the function
# is a status code.
def aa_i2c_read_ext (aardvark, slave_addr, flags, num_bytes):
    "usage: (int, u08[], u16) = aa_i2c_read_ext(Aardvark, u16, AardvarkI2cFlags, u16)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    data_in = array('B', [ 0 for i in range(num_bytes) ])
    (_ret_, data_in, num_read) = api.py_aa_i2c_read_ext(aardvark, slave_addr, flags, num_bytes, data_in)
    del data_in[max(0, min(num_read, len(data_in))):]
    return (_ret_, data_in, num_read)


# Write a stream of bytes to the I2C slave device.
def aa_i2c_write (aardvark, slave_addr, flags, data_out):
    "usage: int = aa_i2c_write(Aardvark, u16, AardvarkI2cFlags, u08[])"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    if not isinstance(data_out, ArrayType) or data_out.typecode != 'B': raise TypeError("type for 'data_out' must be array('B')")
    num_bytes = len(data_out)
    return api.py_aa_i2c_write(aardvark, slave_addr, flags, num_bytes, data_out)


# Write a stream of bytes to the I2C slave device.
# This API function returns the number of bytes written into
# the num_written variable.  The return value of the function
# is a status code.
def aa_i2c_write_ext (aardvark, slave_addr, flags, data_out):
    "usage: (int, u16) = aa_i2c_write_ext(Aardvark, u16, AardvarkI2cFlags, u08[])"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    if not isinstance(data_out, ArrayType) or data_out.typecode != 'B': raise TypeError("type for 'data_out' must be array('B')")
    num_bytes = len(data_out)
    return api.py_aa_i2c_write_ext(aardvark, slave_addr, flags, num_bytes, data_out)


# Enable/Disable the Aardvark as an I2C slave device
def aa_i2c_slave_enable (aardvark, addr, maxTxBytes, maxRxBytes):
    "usage: int = aa_i2c_slave_enable(Aardvark, u08, u16, u16)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_i2c_slave_enable(aardvark, addr, maxTxBytes, maxRxBytes)


def aa_i2c_slave_disable (aardvark):
    "usage: int = aa_i2c_slave_disable(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_i2c_slave_disable(aardvark)


# Set the slave response in the event the Aardvark is put
# into slave mode and contacted by a Master.
def aa_i2c_slave_set_response (aardvark, data_out):
    "usage: int = aa_i2c_slave_set_response(Aardvark, u08[])"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    if not isinstance(data_out, ArrayType) or data_out.typecode != 'B': raise TypeError("type for 'data_out' must be array('B')")
    num_bytes = len(data_out)
    return api.py_aa_i2c_slave_set_response(aardvark, num_bytes, data_out)


# Return number of bytes written from a previous
# Aardvark->I2C_master transmission.  Since the transmission is
# happening asynchronously with respect to the PC host
# software, there could be responses queued up from many
# previous write transactions.
def aa_i2c_slave_write_stats (aardvark):
    "usage: int = aa_i2c_slave_write_stats(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_i2c_slave_write_stats(aardvark)


# Read the bytes from an I2C slave reception
def aa_i2c_slave_read (aardvark, num_bytes):
    "usage: (int, u08, u08[]) = aa_i2c_slave_read(Aardvark, u16)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    data_in = array('B', [ 0 for i in range(num_bytes) ])
    (_ret_, addr, data_in) = api.py_aa_i2c_slave_read(aardvark, num_bytes, data_in)
    del data_in[max(0, min(_ret_, len(data_in))):]
    return (_ret_, addr, data_in)


# Extended functions that return status code    
def aa_i2c_slave_write_stats_ext (aardvark):
    "usage: (int, u16) = aa_i2c_slave_write_stats_ext(Aardvark)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_i2c_slave_write_stats_ext(aardvark)


def aa_i2c_slave_read_ext (aardvark, num_bytes):