TestEngine API Overview

• Building a C/C Application
• Building a C# Application
• Building a Visual Basic Application
• Building a Delphi Application
• Example: Accessing the Persistent Store (BlueCore ICs)
• Example: ACL Data Transmission

The TestEngine API provides an interface for the development of PC based production test systems for testing BlueCore and other supported Qualcomm Bluetooth devices (see the release note for further details of IC support).

The API provides functions to perform a variety of operations including executing radio tests; reading/writing the Persistent Store; and executing a subset of HCI commands for performing operations such as creating a connection.

An application utilising the API can communicate with a device over a host transport (BCSP, H4, H4DS, H5, or USB) or a debug (SPI via USB or LPT, USBTRB or USBDBG) connection, depending on the supported transports for the IC type.

While some example code is included in on this overview page, some functions have example code within their own help page.

BlueCore ICs Function Support

For BlueCore ICs, some functions are not supported over SPI connections. These are summarised in the table below:

* HQ functions, and Radiotest functions that generate HQ traffic are only supported if the device firmware supports HQ over SPI.

NOTES:
Functions in the "Reference Endpoint" group are only supported for the BlueCore based Reference Endpoint product.
Functions in the "Audio" group are not supported for BlueCore ICs (audio tests are supported via BCCMD functions for BlueCore).
Functions in the "Radio Control" group are not supported for BlueCore ICs (use Radiotest functions for BlueCore).
In the "Persistent Store" group, only ps* functions are supported for BlueCore ICs.
For functions in the "Miscellaneous" group, see the help for each function for any restrictions based on IC or transport type.

Combo Digital Architecture ICs Function Support

For CDA ICs, support for some function groups is IC family dependent, as summarised in the table below:

NOTES:
Functions in the "DM" group are not supported for CDA ICs.
Functions in the "Reference Endpoint" group are not supported for CDA ICs.
In the "Persistent Store group", only te* functions are supported for CDA ICs.
For functions in the "Miscellaneous" group, see the help for each function for any restrictions based on IC or transport type.

Using the TestEngine API

The TestEngine API can be used with a variety of programming languages. Your application will have to be executed in a folder containing all of the dynamic link libraries shipped with TrueTest.

Building a C/C Application

To build a C or C application you will need to include the TestEngine.h header file in your source files. Your application will also need to be linked against the TestEngine.lib import library. These files can be found in the following locations:

• Include files TestEngine.h in <BlueSuiteDir>\include
• Import library TestEngine.lib in <BlueSuiteDir>\lib

NOTE: The supplied import library is in COFF format. Borland users should use implib.exe to extract an OMF import library from TestEngine.dll.

Building a C# Application

To build a C# application you will need to add the TestEngineAPI.cs wrapper class file to your project. The unit file can be found in the following location:

• C# wrapper class file TestEngineAPI.cs in <BlueSuiteDir>\include\C#

To use the methods in the wrapper class, add the line "using TestEngineAPI;" to the top of the client code file. This gives access to the namespace containing the TestEngine wrapper class. The methods can then be called using the class name, e.g.: "TestEngine.initTestEngine()".

Building a Visual Basic Application

To build a Visual Basic application you will need to add the TestEngine function declarations module to your project. There are modules for three versions of Visual Basic which can be found in the following locations:

• VB6 function declarations TestEngineAPI.bas in <BlueSuiteDir>\include\VB6
• VB7 (.NET) function declarations TestEngineAPI.vb in <BlueSuiteDir>\include\VB7
• VB2005 (.NET) and later function declarations TestEngineAPI_05.vb in <BlueSuiteDir>\include\VB2005

Unsigned function arguments

Arguments of type uint16 are represented in Visual Basic as the signed 'Short' data type which is 16-bits wide but represents the values -32768 to 32767. This presents a problem when trying to pass values greater than 32767 to functions that take uint16 (Short) arguments as the Visual Basic compiler will not accept these values as being in the valid range for that type.

Unsigned values greater than 32767 must therefore be represented by their equivalent negative value. For example to pass the unsigned value 32768 as a Short, the value -32768 must be passed and to pass the unsigned value 65535, the value -1 must be passed.

The equivalent Short value can be found using a function similar to the one below. This will convert the desired unsigned value represented as a 32-bit Integer to the Short equivalent:

Function AsUShort(ByVal intVal As Integer) As Short
    AsUShort = intVal Mod 32768
    If intVal > 32767 Then
        AsUShort = AsUShort Or &H8000S
    End If
End Function

AsUShort(1) ==> 1
AsUShort(32767) ==> 32767
AsUShort(32768) ==> -32768
AsUShort(65535) ==> -1

A similar function is required to convert signed Short values from functions that return a uint16 as a Short.

An alternative exists for passing constants in to a function, which is to pass them as a hexadecimal literal suffixed with the Short character 'S' as below:

Const FOO As Short = &H8000S ' Represents 32768 as a Short

Building a Delphi Application

To build a Delphi application you will need to add the TestEngineAPI.pas function declarations unit to your project. The unit file can be found in the following location:

• Delphi function declarations TestEngineAPI.pas in <BlueSuiteDir>\include\Delphi

Example: Accessing the Persistent Store (BlueCore ICs)

Below is a sample C program showing how to use the functions in the API to write a value to the BlueCore persistent store.

#include "testengine.h"
#include <iostream>

const uint16 PSKEY_USR0 = 650;

int main(int argc, char** argv)
{
    uint32 devHandle = openTestEngine(BCSP, "COM1", 115200, 5000, 0);

    if(devHandle != 0)
    {
        std::cout << "Device Handle = " << devHandle << std::endl;

        uint16 data[20];
        data[0] = 123;
        data[1] = 456;

        if(psWrite(devHandle, PSKEY_USR0, PS_STORES_I, 2, data) == TE_OK)
        {
            std::cout << "Successfully wrote key" << std::endl;
        }
        else
        {
            std::cout << "Failed to write key" << std::endl;
            closeTestEngine(devHandle);
            return -1;
        }

        uint16 keySize;
        psSize(devHandle, PSKEY_USR0, PS_STORES_IFR, &keySize);

        data[0] = data[1] = 0;

        if(psRead(devHandle, PSKEY_USR0, PS_STORES_IFR, 16, data, &keySize) == TE_OK)
        {
            std::cout << "data[0] = " << data[0] << std::endl
                      << "data[1] = " << data[1] << std::endl;
        }
        else
        {
            std::cout << "Failed to read key" << std::endl;
            closeTestEngine(devHandle);
            return -1;
        }

        closeTestEngine(devHandle);
    }
    else
    {
        std::cout << "Failed to initialise device" << std::endl;
        return -1;
    }

    return 0;
}

Example: ACL Data Transmission

The following example shows how to transmit a data file from one device to another.

#include "testengine.h"
#include <windows.h>
#include <iostream>

extern int DiffFiles(const char* file1, const char* file2);

int main(int argc, char** argv)
{
    uint32 rxHandle = openTestEngine(BCSP, "com1", 115200, 5000, 0);
    uint32 txHandle = openTestEngine(USB, "\\\\.\\csr0", 0, 5000, 1000);

    if((txHandle != 0) && (rxHandle != 0))
    {
        hciSlave(rxHandle);

        uint16 connHandle;
        if(hciCreateConnectionNoInquiry(txHandle, 0x1be8f, 0x5b, 0x2, 0xcc18, 0, 0, 0, 1, &connHandle) != TE_OK)
        {
            std::cout << "Failed to connect to device" << std::endl;
            closeTestEngine(txHandle);
            closeTestEngine(rxHandle);
            return -1;
        }
        std::cout << "Connection Handle = " << connHandle << std::endl;

        hciResetAclState(rxHandle);

        if(hciSendAclFile(txHandle, connHandle, "data.txt") == TE_OK)
        {
            int32 aclState;
            do
            {
                Sleep(500);
                if(hciGetAclState(rxHandle, &aclState) != TE_OK)
                {
                    std::cout << "Error getting ACL state" << std::endl;
                    return -1;
                }
            } while(aclState != 3 && aclState != 4);

            if(aclState == 3)
            {
                uint32 rxFileNameLength;
                if(hciGetAclFileName(rxHandle, 0, &rxFileNameLength) != TE_OK)
                {
                    std::cout << "Error getting ACL file name length" << std::endl;
                    return -1;
                }
                char* rxFileName = (char*)malloc((rxFileNameLength * sizeof(char))   1);

                if(hciGetAclFileName(rxHandle, rxFileName, &rxFileNameLength) != TE_OK)
                {
                    std::cout << "Error getting ACL file name" << std::endl;
                    return -1;
                }
                std::cout << "File name = " << rxFileName << std::endl;

                /*DiffFiles("data.txt", rxFileName);*/

                free(rxFileName);
            }
        }
        else
        {
            std::cout << "Failed to send file" << std::endl;
        }

        hciDisconnect(txHandle, connHandle);

        closeTestEngine(txHandle);
        closeTestEngine(rxHandle);
    }
    else
    {
        std::cout << "Failed to get handles to one or both devices" << std::endl;
        return -1;
    }

    return 0;
}