aardvark.cs

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
 ========================================================================*/

using System;
using System.Reflection;
using System.Runtime.InteropServices;

[assembly: AssemblyTitleAttribute("Aardvark .NET binding")]
[assembly: AssemblyDescriptionAttribute(".NET binding for Aardvark")]
[assembly: AssemblyCompanyAttribute("Total Phase, Inc.")]
[assembly: AssemblyProductAttribute("Aardvark")]
[assembly: AssemblyCopyrightAttribute("Total Phase, Inc. 2007")]

[assembly: CLSCompliantAttribute(true)]

namespace TotalPhase {

public enum AardvarkStatus : int {
    /* 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
}

public enum AardvarkConfig : int {
    AA_CONFIG_GPIO_ONLY = 0x00,
    AA_CONFIG_SPI_GPIO  = 0x01,
    AA_CONFIG_GPIO_I2C  = 0x02,
    AA_CONFIG_SPI_I2C   = 0x03,
    AA_CONFIG_QUERY     = 0x80
}

public enum AardvarkI2cFlags : int {
    AA_I2C_NO_FLAGS     = 0x00,
    AA_I2C_10_BIT_ADDR  = 0x01,
    AA_I2C_COMBINED_FMT = 0x02,
    AA_I2C_NO_STOP      = 0x04
}

public enum AardvarkI2cStatus : int {
    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
}

public enum AardvarkSpiPolarity : int {
    AA_SPI_POL_RISING_FALLING = 0,
    AA_SPI_POL_FALLING_RISING = 1
}

public enum AardvarkSpiPhase : int {
    AA_SPI_PHASE_SAMPLE_SETUP = 0,
    AA_SPI_PHASE_SETUP_SAMPLE = 1
}

public enum AardvarkSpiBitorder : int {
    AA_SPI_BITORDER_MSB = 0,
    AA_SPI_BITORDER_LSB = 1
}

public enum AardvarkSpiSSPolarity : int {
    AA_SPI_SS_ACTIVE_LOW  = 0,
    AA_SPI_SS_ACTIVE_HIGH = 1
}

public enum AardvarkGpioBits : int {
    AA_GPIO_SCL  = 0x01,
    AA_GPIO_SDA  = 0x02,
    AA_GPIO_MISO = 0x04,
    AA_GPIO_SCK  = 0x08,
    AA_GPIO_MOSI = 0x10,
    AA_GPIO_SS   = 0x20
}


[CLSCompliantAttribute(true)]
public class AardvarkApi {

/*=========================================================================
| VERSION
 ========================================================================*/
[DllImport ("aardvark")]
private static extern int c_version ();

public const int AA_API_VERSION    = 0x0400;   // v4.00
public const int AA_REQ_SW_VERSION = 0x0400;   // v4.00

private static short AA_SW_VERSION;
private static short AA_REQ_API_VERSION;
private static bool  AA_LIBRARY_LOADED;

static AardvarkApi () {
    AA_SW_VERSION      = (short)(c_version() & 0xffff);
    AA_REQ_API_VERSION = (short)((c_version() >> 16) & 0xffff);
    AA_LIBRARY_LOADED  = 
        ((AA_SW_VERSION >= AA_REQ_SW_VERSION) &&
         (AA_API_VERSION >= AA_REQ_API_VERSION));
}

/*=========================================================================
| 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  (from declaration above)
//     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
//     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
//     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
//     AA_GPIO_NOT_AVAILABLE        = -400
//     AA_I2C_MONITOR_NOT_AVAILABLE = -500
//     AA_I2C_MONITOR_NOT_ENABLED   = -501


/*=========================================================================
| GENERAL TYPE DEFINITIONS
 ========================================================================*/
/* Aardvark handle type definition */
/* typedef Aardvark => int */

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

/* typedef aa_u16 => short */

/* typedef aa_u32 => int */

/* typedef aa_s08 => byte */

/* typedef aa_s16 => short */

/* typedef aa_s32 => int */

/*
 * 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
 */
[StructLayout(LayoutKind.Sequential)]
public struct AardvarkVersion {
    /* Software, firmware, and hardware versions. */
    public short software;
    public short firmware;
    public short hardware;

    /* Firmware requires that software must be >= this version. */
    public short sw_req_by_fw;

    /* Software requires that firmware must be >= this version. */
    public short fw_req_by_sw;

    /* Software requires that the API interface must be >= this version. */
    public short api_req_by_sw;
}


/*=========================================================================
| 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.
 */
public const short AA_PORT_NOT_FREE = unchecked((short)0x8000);
public static int aa_find_devices (
    int          nelem,
    ref short[]  devices
)
{
    if (!AA_LIBRARY_LOADED) return (int)AardvarkStatus.AA_INCOMPATIBLE_LIBRARY;
    return c_aa_find_devices(nelem, ref devices[0]);
}

/*
 * 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.
 */
public static int aa_find_devices_ext (
    int          nelem,
    ref short[]  devices,
    ref int[]    unique_ids
)
{
    if (!AA_LIBRARY_LOADED) return (int)AardvarkStatus.AA_INCOMPATIBLE_LIBRARY;
    return c_aa_find_devices_ext(nelem, ref devices[0], ref unique_ids[0]);
}

/*
 * 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.
 */
public static int aa_open (
    int  port_number
)
{
    if (!AA_LIBRARY_LOADED) return (int)AardvarkStatus.AA_INCOMPATIBLE_LIBRARY;
    return c_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.
 */
[StructLayout(LayoutKind.Sequential)]
public struct AardvarkExt {
    /* Version matrix */
    public AardvarkVersion version;

    /* Features of this device. */
    public int             features;
}

public static int aa_open_ext (
    int              port_number,
    ref AardvarkExt  aa_ext
)
{
    if (!AA_LIBRARY_LOADED) return (int)AardvarkStatus.AA_INCOMPATIBLE_LIBRARY;
    return c_aa_open_ext(port_number, ref aa_ext);
}

/* Close the Aardvark port. */
public static int aa_close (
    int  aardvark
)
{
    if (!AA_LIBRARY_LOADED) return (int)AardvarkStatus.AA_INCOMPATIBLE_LIBRARY;
    return c_aa_close(aardvark);
}

/*
 * Return the port for this Aardvark handle.
 * 
 * The port number is a zero-indexed integer.
 */
public static int aa_port (
    int  aardvark
)