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. .. only:: latex .. rubric:: Document navigation This manual contains intra-document links. You will need a PDF viewer with “Previous View” functionality to navigate through the manual with ease. If you are opening this PDF manual with the built-in Mozilla® Firefox® PDF viewer, you can right-click anywhere in the PDF window to access page navigation: .. image:: res/SDKguide_Firefox-PDF-Navigation.JPG Otherwise, this PDF manual is best viewed using a PDF viewer with “Previous View” functionality. If your preferred PDF viewer does not include this functionality, you may wish to use one of the following [#f1]_ options: - Foxit® Reader: https://www.foxitsoftware.com/pdf-reader/ (available for Linux and Windows) - PDF Studio 2018: https://www.qoppa.com/pdfstudioviewer/download/ (available for Linux and Windows) - Adobe® Acrobat® Reader DC: https://get.adobe.com/reader/ (available for Windows) If you are using Adobe Acrobat Reader, you will need to enable the Previous View and Next View Page Navigation tools: Right-click on the top toolbar and go to Show Page Navigation Tools, then select Previous View. Repeat the process for Next View. .. image:: res/SDKguide_Acrobat_Add-PDF-Navigation.JPG .. [#f1] This manual includes links to information created and maintained by other private and/or public organizations. Alazar Technologies Inc. (AlazarTech) provides these links solely for our users' information and convenience. AlazarTech does not control or guarantee the accuracy, relevance, or completeness of information contained on a linked website. Furthermore, AlazarTech does not endorse these organizations or the views they express or the products/services they offer. AlazarTech is not responsible for transmissions users receive from linked websites, nor is it responsible for or liable in any way for commercial transactions which users transact with linked websites. 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: 1. MATLAB functions do not return error codes, instead, they throw exceptions if the return code of the associated C function is not :c:member:`ApiSuccess`. For example, a C program that wants to call the :c:func:`AlazarStartCapture` function should be written like so: .. code-block:: c 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: .. code-block:: MATLAB 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. 2. Output parameters in C functions are return values in their MATLAB equivalents. Here is how :c:func:`AlazarGetChannelInfo` can be called from a C program: .. code-block:: c 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: .. code-block:: MATLAB [memorySizeInSamples, bitsPerSample] = AlazarGetChannelInfo(boardHandle) 3. 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: .. code-block:: c 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: .. code-block:: 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 ------------- Contact us if you have any questions or comments about this document, or the sample code. +---------+------------------------------------------+ | 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