Getting Started#

Introduction#

AlazarTech supplies device drivers for Windows and Linux that allow software to configure AlazarTech digitizers, and transfer sample data from the digitizer to application buffers.

The AlazarTech software developer’s kit (ATS-SDK) includes header and library files required to call functions exported by these device drivers in user written applications, as well as documentation and sample code describing how to use these functions.

This document is a part of the ATS-SDK. It describes how to call functions exported by AlazarTech device drivers to control one or more digitizer boards. It is divided into the following sections:

A programming guide that describes how to configure, and acquire data from, digitizer boards.
A reference guide that describes the functions exported by the device drivers.

To get the most from your AlazarTech digitizer:

Read the user manual supplied their digitizer board. It provides an overview of the digitizer hardware, as well as detailed specifications.
Read the “Programmer’s guide” section of this document. It describes how to program the digitizer hardware to make an acquisition, and to transfer sample data into application buffers.
Browse the SDK sample programs. They include sample code that demonstrates how to make many types of acquisitions supported by the digitizer.

Note that this document includes descriptions of board specific features and options that may not be available on your digitizer board. Please refer your board’s user manual for its specifications.

Programming Environments#

C/C++ Linux#

C/C++ developers under Linux should include the following header files in source files that use functions exported by the ATS-SDK library:

#include "AlazarError.h"
#include "AlazarApi.h"
#include "AlazarCmd.h"

These modules should also link against libATSApi.so.

The development package for Linux defaults to installing the header files in /usr/local/AlazarTech/include, and the library files in the standard library directory for the target distribution.

C/C++ Windows#

C/C++ developers should include the following header files in source files that use functions exported by the API library:

#include "AlazarError.h"
#include "AlazarApi.h"
#include "AlazarCmd.h"

These applications should also link against the 32- or 64-bit version of ATSApi.lib, as required.

The SDK setup program installs the header files in “Samples_C\Include”, and the library files in “Samples_C\Library”.

C##

C# developers should either:

Add the file AlazarApi.cs to their project; or
Add a reference to AlazarApiNet.dll to their project.

The ATS-SDK includes a wrapper class that declares many of the constants and unmanaged functions exported by AlazarTech device drivers. This class is provided both as a C# source file (AlazarApi.cs), and as a compiled assembly (AlazarApiNet.dll).

The SDK setup program copies AlazarApi.cs to the “Samples_CSharp\AlazarApiNet\AlazarApiNet” directory and AlazarApiNet.dll to the “Samples_CSharp” directory.

Note that you can use the solution “Samples_CSharp\AlazarApiNet” to build AlazarApiNet.dll from AlazarApi.cs.

LabVIEW#

LabVIEW developers can either:

Use the sub-VIs provided with the ATS-SDK (recommended)
Call functions from ATSApi.dll directly using the LabVIEW interface for shared libraries.

The ATS-SDK sub-VIs consists of a very thin wrapper on top of the functions exported by the ATS-SDK. The VIs are named after the functions that they wrap. They are located in “Samples_LabVIEW\Library”, and are used by all the code samples available in “Samples_LabVIEW”.

The only difference between the connector panes of the VIs and the C function signatures is that an error cluster is propagated through the VIs. If the input error cluster contains an error, the VI simply returns without doing anything.

The error cluster output depends on the function:

If the function does not generate errors, the input error cluster is simply propagated to the output.
If the function returns an error code, it is converted to a cluster and send to the output
If the function can return errors using special return values, then these errors are detected by the VI, an appropriate error code is generated, converted to a cluster and sent to the output

Python#

Python developers can use the atsapi.py module provided in the “Samples_Python\Library” directory. It provides a very thin wrapper around the AlazarTech C/C++ API, with only minor differences:

The ‘Alazar’ prefixes have been removed from the function names, and the first letter is not capitalized. For example, ‘AlazarAbortAsyncRead’ becomes ‘abortAsyncRead’.
Board handles have been removed. Instead, a Board class has been added. All the functions that take a board handle as a parameter are moved to being member functions of the Board class.
A DMABuffer convenience class has been added, that takes care of memory allocation of DMA transfers.
Some functions of the API use return parameters to give back to the caller primitive types. In Python, the signature of these functions is changed so that the return parameters are replaced with return types.

MATLAB#

MATLAB developers should use the functions provided in “Samples_MATLAB/Include” to call functions from the ATSApi DLL. There is a one to one mapping between MATLAB and C ATSApi functions, but the arguments and return values differ in the following ways:

MATLAB functions do not return error codes, instead, they throw exceptions if the return code of the associated C function is not ApiSuccess. For example, a C program that wants to call the AlazarStartCapture() function should be written like so:
```
RETURN_CODE rc = AlazarStartCapture(boardHandle);
if (rc != ApiSuccess) {
    // TODO: handle error (e.g. return a failure code).
}
```
By opposition, a MATLAB program that wishes to call the same function should simply use the following at the call site:
```
AlazarStartCapture(boardHandle);
```
Note that because this function will throw in case of an error, it is necessary for the MATLAB program to include exception handling code higher in the call stack if terminating upon error is not acceptable.

Output parameters in C functions are return values in their MATLAB equivalents. Here is how AlazarGetChannelInfo() can be called from a C program:

U32 memorySize = 0;
U32 bitsPerSample = 0;
RETURN_CODE rc = AlazarGetChannelInfo(boardHandle,
                                      &memorySize,
                                      &bitsPerSample);
if (rc != ApiSuccess) {
    // TODO: handle error (e.g. return a failure code).
}

By contrast, here is the same function call in a MATLAB program:

[memorySizeInSamples, bitsPerSample] = AlazarGetChannelInfo(boardHandle)

In C programs, arrays are always allocated by the user code, and are passed as a pair of arguments (a pointer and a size). In MATLAB, arrays are passed to or returned from functions by value instead.

This change significantly simplifies some function calls. For example, here is how to generate a window function in a C program:

U32 windowType = ...;
U32 windowLength = ...;
U32 paddingLength = ...;
float* window = (float*) malloc(windowLength + paddingLength, sizeof(float));
if (!window) {
    // TODO: handle error
}
RETURN_CODE rc AlazarDSPGenerateWindowFunction(windowType,
                                               window,
                                               windowLength,
                                               paddingLength);
if (rc != ApiSuccess) {
    // TODO: handle error (e.g. return a failure code).
}

Here is how to generate this function from MATLAB:

windowType = ...;
windowLength = ...;
paddingLength = ...;
window = AlazarDSPGenerateWindowFunction(windowType,
                                         windowLength,
                                         paddingLength);

Note

This change does not apply to DMA buffers. For performance reasons (to avoid costly copies), buffers are passed by reference in MATLAB functions.

C++/CLI#

C++/CLI programmers should include a reference to “Samples_CSharp\AlazarApiNet.dll” in their solutions. This assembly provides a .NET interface to the functions and constants defined in the ATS-SDK.

The ATS-SDK does not currently include C++/CLI sample code. See the C# samples for .NET sample code.

Sample code#

ATS-SDK includes sample programs that demonstrate how to configure and acquire data from AlazarTech digitizers.

The SDK setup program installs the sample programs to “C:\AlazarTech\ATS-SDK\%API_VERSION%” under Microsoft Windows, and “/usr/local/AlazarTech” under Linux. See the “ReadMe.htm” file in the ATS-SDK base directory for a description of the samples included.

Sample programs are available for the following programming environments in the following sub-directories:

Language	Sub-directory
C/C++	Samples_C
C#	Samples_CSharp
MATLAB	Samples_MATLAB
LabVIEW	Samples_LabVIEW
Python	Samples_Python

Note

Note that the sample programs contain many parameters that should be modified. These lines of code are preceded by “TODO” comments. Please search for these lines and modify them as required for your application.

Warning

Many sample programs require a trigger input. These sample programs configure a board to trigger when a signal connected to its CH A rises through 0V. Before running these samples, connect a 1 kHz sine waveform of amplitude about 90% of the board’s input range from a function generator to the CH A connector, or modify trigger parameters as required. For example, the ATS9360 has an input range of +/- 400 mV. For this board, a sine wave of 700 mVpp is appropriate. If an appropriate trigger signal is not supplied, these samples will fail with an acquisition timeout error.

Contacting us#

Web	https://www.alazartech.com/
Email	support@alazartech.com
Phone	+1-514-426-4899
Fax	+1-514-426-2723
Mail	Alazar Technologies Inc. 6600 Trans-Canada Highway, Suite 310 Pointe-Claire, QC Canada H9R 4S2

Note that you can download the latest drivers and documentation from our web site.

https://www.alazartech.com/Support/Downloads