API

Module Interface

pyaardvark.find_devices()

Return a list of dictionaries. Each dictionary represents one device.

The dictionary contains the following keys: port, unique_id and in_use. port can be used with open(). serial_number is the serial number of the device (and can also be used with open()) and in_use indicates whether the device was opened before and can currently not be opened.

Note

There is no guarantee, that the returned information is still valid when you open the device. Esp. if you open a device by the port, the unique_id may change because you’ve just opened another device. Eg. it may be disconnected from the machine after you call find_devices() but before you call open().

To open a device by its serial number, you should use the open() with the serial_number parameter.

pyaardvark.open(port=None, serial_number=None)

Open an aardvark device and return an Aardvark object. If the device cannot be opened an IOError is raised.

The port can be retrieved by find_devices(). Usually, the first device is 0, the second 1, etc.

If you are using only one device, you can therefore omit the parameter in which case 0 is used.

Another method to open a device is to use the serial number. You can either find the number on the device itself or in the in the corresponding USB property. The serial number is a string which looks like NNNN-MMMMMMM.

Raises an IOError if the port (or serial number) does not exist, is already connected or an incompatible device is found.

Note

There is a small chance that this function raises an IOError although the correct device is available and not opened. The open-by-serial-number method works by scanning the devices. But as explained in find_devices(), the returned information may be outdated. Therefore, open() checks the serial number once the device is opened and if it is not the expected one, raises IOError. No retry mechanism is implemented.

As long as nobody comes along with a better idea, this failure case is up to the user.

Aardvark Object

class pyaardvark.Aardvark(port=0)

Represents an Aardvark device.

api_version = None

Version of underlying C module (aardvark.so, aardvark.dll) as a string. See hardware_revision for more information on the format.

close()

Close the device.

disable_i2c_monitor()

Disable the I2C monitor.

Raises an IOError if the hardware adapter does not support monitor mode.

disable_i2c_slave()

Disable I2C slave mode.

enable_i2c

Set this to True to enable the hardware I2C interface. If set to False the hardware interface will be disabled and its pins (SDA and SCL) can be used as GPIOs.

enable_i2c_monitor()

Activate the I2C monitor.

Enabling the monitor will disable all other functions of the adapter.

Raises an IOError if the hardware adapter does not support monitor mode.

enable_i2c_slave(slave_address)

Enable I2C slave mode.

The device will respond to the specified slave_address if it is addressed.

You can wait for the data with poll() and get it with i2c_slave_read.

enable_spi

Set this to True to enable the hardware SPI interface. If set to False the hardware interface will be disabled and its pins (MISO, MOSI, SCK and SS) can be used as GPIOs.

firmware_version = None

Firmware version of the host adapter as a string. See hardware_revision for more information on the format.

handle = None

A handle which is used as the first paramter for all calls to the underlying API.

hardware_revision = None

Hardware revision of the host adapter as a string. The format is M.NN where M is the major number and NN the zero padded minor number.

i2c_bitrate

I2C bitrate in kHz. Not every bitrate is supported by the host adapter. Therefore, the actual bitrate may be less than the value which is set.

The power-on default value is 100 kHz.

i2c_master_read(addr, length, flags=0)

Make an I2C read access.

The given I2C device is addressed and clock cycles for length bytes are generated. A short read will occur if the device generates an early NAK.

The transaction is finished with an I2C stop condition unless the I2C_NO_STOP flag is set.

i2c_master_write(i2c_address, data, flags=0)

Make an I2C write access.

The given I2C device is addressed and data given as a string is written. The transaction is finished with an I2C stop condition unless I2C_NO_STOP is set in the flags.

10 bit addresses are supported if the I2C_10_BIT_ADDR flag is set.

i2c_master_write_read(i2c_address, data, length)

Make an I2C write/read access.

First an I2C write access is issued. No stop condition will be generated. Instead the read access begins with a repeated start.

This method is useful for accessing most addressable I2C devices like EEPROMs, port expander, etc.

Basically, this is just a convinient function which interally uses i2c_master_write and i2c_master_read.

i2c_monitor_read()

Retrieved any data fetched by the monitor.

This function has an integrated timeout mechanism. You should use poll() to determine if there is any data available.

Returns a list of data bytes and special symbols. There are three special symbols: I2C_MONITOR_NACK, I2C_MONITOR_START and I2C_MONITOR_STOP.

i2c_pullups

Setting this to True will enable the I2C pullup resistors. If set to False the pullup resistors will be disabled.

Raises an IOError if the hardware adapter does not support pullup resistors.

i2c_slave_read()

Read the bytes from an I2C slave reception.

The bytes are returns as an string object.

poll(timeout=None)

Wait for an event to occur.

If timeout is given, if specifies the length of time in milliseconds which the function will wait for events before returing. If timeout is omitted, negative or None, the call will block until there is an event.

Returns a list of events. In case no event is pending, an empty list is returned.

spi_bitrate

SPI bitrate in kHz. Not every bitrate is supported by the host adapter. Therefore, the actual bitrate may be less than the value which is set. The slowest bitrate supported is 125kHz. Any smaller value will be rounded up to 125kHz.

The power-on default value is 1000 kHz.

spi_configure(polarity, phase, bitorder)

Configure the SPI interface.

spi_configure_mode(spi_mode)

Configure the SPI interface by the well known SPI modes.

spi_ss_polarity(polarity)

Change the ouput polarity on the SS line.

Please note, that this only affects the master functions.

spi_write(data)

Write a stream of bytes to a SPI device.

target_power

Setting this to True will activate the power pins (4 and 6). If set to False the power will be deactivated.

Raises an IOError if the hardware adapter does not support the switchable power pins.

unique_id()

Return the unique identifier of the device. The identifier is the serial number you can find on the adapter without the dash. Eg. the serial number 0012-345678 would be 12345678.

unique_id_str()

Return the unique identifier. But unlike unique_id(), the ID is returned as a string which has the format NNNN-MMMMMMM.