aardvark_py.py

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

#==========================================================================
# Aardvark Interface Library
#--------------------------------------------------------------------------
# Copyright (c) 2002-2007 Total Phase, Inc.
# All rights reserved.
# www.totalphase.com
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
# - Redistributions of source code must retain the above copyright
#   notice, this list of conditions and the following disclaimer.
#
# - Redistributions in binary form must reproduce the above copyright
#   notice, this list of conditions and the following disclaimer in the
#   documentation and/or other materials provided with the distribution.
#
# - Neither the name of Total Phase, Inc. nor the names of its
#   contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#--------------------------------------------------------------------------
# To access Aardvark devices through the API:
#
# 1) Use one of the following shared objects:
#      aardvark.so      --  Linux shared object
#      aardvark.dll     --  Windows dynamic link library
#
# 2) Along with one of the following language modules:
#      aardvark.c/h     --  C/C++ API header file and interface module
#      aardvark_py.py   --  Python API
#      aardvark.bas     --  Visual Basic 6 API
#      aardvark.cs      --  C# .NET source
#      aardvark_net.dll --  Compiled .NET binding
#==========================================================================


#==========================================================================
# VERSION
#==========================================================================
AA_API_VERSION    = 0x0400   # v4.00
AA_REQ_SW_VERSION = 0x0400   # v4.00

import os
import sys
import imp
if os.name != 'nt' or (sys.version_info[0] == 2 and sys.version_info[1] < 5):
    import aardvark as api
else:
    api = imp.load_dynamic('aardvark', 'aardvark.dll')

AA_SW_VERSION      = api.py_version() & 0xffff
AA_REQ_API_VERSION = (api.py_version() >> 16) & 0xffff
AA_LIBRARY_LOADED  = \
    ((AA_SW_VERSION >= AA_REQ_SW_VERSION) and \
     (AA_API_VERSION >= AA_REQ_API_VERSION))

from array import array, ArrayType
import struct


#==========================================================================
# STATUS CODES
#==========================================================================
# All API functions return an integer which is the result of the
# transaction, or a status code if negative.  The status codes are
# defined as follows:
# enum AardvarkStatus
# General codes (0 to -99)
AA_OK                        =    0
AA_UNABLE_TO_LOAD_LIBRARY    =   -1
AA_UNABLE_TO_LOAD_DRIVER     =   -2
AA_UNABLE_TO_LOAD_FUNCTION   =   -3
AA_INCOMPATIBLE_LIBRARY      =   -4
AA_INCOMPATIBLE_DEVICE       =   -5
AA_COMMUNICATION_ERROR       =   -6
AA_UNABLE_TO_OPEN            =   -7
AA_UNABLE_TO_CLOSE           =   -8
AA_INVALID_HANDLE            =   -9
AA_CONFIG_ERROR              =  -10

# I2C codes (-100 to -199)
AA_I2C_NOT_AVAILABLE         = -100
AA_I2C_NOT_ENABLED           = -101
AA_I2C_READ_ERROR            = -102
AA_I2C_WRITE_ERROR           = -103
AA_I2C_SLAVE_BAD_CONFIG      = -104
AA_I2C_SLAVE_READ_ERROR      = -105
AA_I2C_SLAVE_TIMEOUT         = -106
AA_I2C_DROPPED_EXCESS_BYTES  = -107
AA_I2C_BUS_ALREADY_FREE      = -108

# SPI codes (-200 to -299)
AA_SPI_NOT_AVAILABLE         = -200
AA_SPI_NOT_ENABLED           = -201
AA_SPI_WRITE_ERROR           = -202
AA_SPI_SLAVE_READ_ERROR      = -203
AA_SPI_SLAVE_TIMEOUT         = -204
AA_SPI_DROPPED_EXCESS_BYTES  = -205

# GPIO codes (-400 to -499)
AA_GPIO_NOT_AVAILABLE        = -400

# I2C bus monitor codes (-500 to -599)
AA_I2C_MONITOR_NOT_AVAILABLE = -500
AA_I2C_MONITOR_NOT_ENABLED   = -501


#==========================================================================
# GENERAL TYPE DEFINITIONS
#==========================================================================
# Aardvark handle type definition
# typedef Aardvark => integer

# Deprecated type definitions.
#
# These are only for use with legacy code and
# should not be used for new development.
# typedef aa_u08 => integer

# typedef aa_u16 => integer

# typedef aa_u32 => integer

# typedef aa_s08 => integer

# typedef aa_s16 => integer

# typedef aa_s32 => integer

# Aardvark version matrix.
# 
# This matrix describes the various version dependencies
# of Aardvark components.  It can be used to determine
# which component caused an incompatibility error.
# 
# All version numbers are of the format:
#   (major << 8) | minor
# 
# ex. v1.20 would be encoded as:  0x0114
class AardvarkVersion:
    def __init__ (self):
        # Software, firmware, and hardware versions.
        self.software      = 0
        self.firmware      = 0
        self.hardware      = 0

        # Firmware requires that software must be >= this version.
        self.sw_req_by_fw  = 0

        # Software requires that firmware must be >= this version.
        self.fw_req_by_sw  = 0

        # Software requires that the API interface must be >= this version.
        self.api_req_by_sw = 0


#==========================================================================
# GENERAL API
#==========================================================================
# Get a list of ports to which Aardvark devices are attached.
# 
# nelem   = maximum number of elements to return
# devices = array into which the port numbers are returned
# 
# Each element of the array is written with the port number.
# Devices that are in-use are ORed with AA_PORT_NOT_FREE (0x8000).
#
# ex.  devices are attached to ports 0, 1, 2
#      ports 0 and 2 are available, and port 1 is in-use.
#      array => 0x0000, 0x8001, 0x0002
# 
# If the array is NULL, it is not filled with any values.
# If there are more devices than the array size, only the
# first nmemb port numbers will be written into the array.
# 
# Returns the number of devices found, regardless of the
# array size.
AA_PORT_NOT_FREE = 0x8000
def aa_find_devices (nelem):
    "usage: (int, u16[]) = aa_find_devices(int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    devices = array('H', [ 0 for i in range(nelem) ])
    (_ret_, devices) = api.py_aa_find_devices(nelem, devices)
    del devices[max(0, min(_ret_, len(devices))):]
    return (_ret_, devices)


# Get a list of ports to which Aardvark devices are attached.
#
# This function is the same as aa_find_devices() except that
# it 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.
def aa_find_devices_ext (nelem):
    "usage: (int, u16[], u32[]) = aa_find_devices_ext(int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    devices = array('H', [ 0 for i in range(nelem) ])
    unique_ids = array('I', [ 0 for i in range(nelem) ])
    (_ret_, devices, unique_ids) = api.py_aa_find_devices_ext(nelem, devices, unique_ids)
    del devices[max(0, min(_ret_, len(devices))):]
    del unique_ids[max(0, min(_ret_, len(unique_ids))):]
    return (_ret_, devices, unique_ids)


# Open the Aardvark port.
# 
# The port number is a zero-indexed integer.
#
# The port number is the same as that obtained from the
# aa_find_devices() function above.
# 
# Returns an Aardvark handle, which is guaranteed to be
# greater than zero if it is valid.
# 
# 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.
def aa_open (port_number):
    "usage: Aardvark = aa_open(int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    return api.py_aa_open(port_number)


# Open the Aardvark port, returning extended information
# in the supplied structure.  Behavior is otherwise identical
# to aa_open() above.  If 0 is passed as the pointer to the
# structure, this function is exactly equivalent to aa_open().
# 
# 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 more simple
# applications, the use of aa_open() is recommended.
class AardvarkExt:
    def __init__ (self):
        # Version matrix
        self.version  = AardvarkVersion()

        # Features of this device.
        self.features = 0

def aa_open_ext (port_number):
    "usage: (Aardvark, AardvarkExt) = aa_open_ext(int)"
    if not AA_LIBRARY_LOADED: return AA_INCOMPATIBLE_LIBRARY
    (_ret_, c_aa_ext) = api.py_aa_open_ext(port_number)