SpinCore Logo

Using the spinapi to control SpinCore Technologies, Inc. products


   This document describes how to interface with the spinapi control library, which is used to control all SpinCore products, including PulseBlaster, PulseBlasterDDS, PulseBlasterESR, PulseBlasterESR-PRO, and RadioProcessor..

Windows Compilation


    The spinapi control library is a standard windows .dll which can be accessed from a wide variety of programming environments, such as C/C++ programs, LabView, etc.

Accessing spinapi from a C/C++ program

    This section describes the basic steps needed to get your C/C++ program to work with spinapi.  Virtually any C/C++ compiler/programming environment is compatible, feel free to use your favorite.  If you do not currently have a C/C++ compiler, there are several high quality compilers available for free download on the internet, see below for some recommendations.

 Four files are necessary to be able to control your board using this approach.

.c/.cpp file: This is the program itself. Several example C programs are included for each of our different products.

spinapi.h: The spinapi header file. This contains the function declarations and definitions which are needed to access the spinapi functions. This should be #included in all files which use the spinapi functions. (#include "spinapi.h")

Import library: This library must be linked with your program so it will know to look inside the spinapi.dll file to find the API functions. There are several different file formats for import libraries, so we have provided three different ones so that all compilers can be supported. Choose whichever is appropriate for the compiler you are using.

    spinapi.lib: Microsoft compilers
    libspinapi.a: GCC based compilers (such as MinGW)
    spiabibcc.lib: Borland compilers

spinapi.dll: The control library itself. Windows must be able to find this file when you run your program, so it needs to be placed in the same directory as the executable program, or in one of the Windows directories (such as C:\Windows\System32)

    The most straightforward way to compile a program using spinapi is to create a new, empty directory and copy each of the four required files listed above into it. Look in the dll/ directory to find spinapi.h, spinapi.dll, and the import library. An example C program can be found the the appropriate product subdirectory. Then open the C file, configure your compiler to link with the import library, and start the compile. It is recommended that you compile one of the unchanged example programs first, to ensure your compiler is set up correctly. Once the example is compiled correctly, you can move on to creating custom programs.

    Below are detailed instructions for specific compilers on how to configure them to use spinapi. The procedure for other compilers should be similar. These instructions assume you have copied the four required files into their own directory as described above.

Microsoft Visual Studio 6:

1) Open the C file
2) Select "Build | Compile zzz.c" from the menu. (zzz.c will be the name of the C file you opened)
3) You will be asked if you wish to create a new workspace. Answer yes.
4) You must tell the compiler to use the import library. Choose "Product | Settings..." from the menu. Click on the "Link" tab. In the "Object/Library modules:" box, add spinapi.lib in addition to the libraries already listed, and click "Ok"
5) Everything is now configured correctly. To build the executable, simply choose "Build | Build zzz.exe" from the menu, and the program will be created and placed in the Debug subdirectory.

Dev-C++:

1) Open the C file
2) Choose "Tools | Compiler Options".
3) Under the "Compiler" tab, check the "Add these commands to the linker command line" box, and enter "-lspinapi" (that's a lower-case L) in the text box below.
4) Under the "Directories" tab, choose the "Libraries" tab and add the directory where the libspinapi.a file is located. (Click the icon with a picture of a folder on it, choose the directory in the dialog box that pops up, and click the "Add" button).
5) Everything is now configured. Choose "Execute | Compile" from the menu to compile the program.

Free C/C++ Compilers:

    Dev-C++: This is a free C/C++ programming environment. It is available from http://www.bloodshed.net/dev/devcpp.html, be sure to choose the larger download which includes the GCC MinGW compiler. The graphical interface of this environment is very usable, but not quite up to standard with commercial offerings. However, the underlying compiler is of high quality (it is the Windows version of the gcc compiler used on linux) and is what we use for much of our internal software development.


Accessing spinapi from other programming environments

    Virtually all programming environments provide some mechanism for accessing an API provided by a Windows .dll. Please consult the help files of your environment if you are unsure of how to do this.


General Tips

  • We highly recommend you check the result of the pb_get_version() function at the beginning of each program. This way, if you upgrade to a newer version of spinapi, you can check to make sure your program is not accidentally still using the older version of the library.
  • Checking the return value of all spinapi functions is highly recommended. This way you will be able to detect common errors (such as entering too short a time for an instruction length, etc.)
  • If you encounter difficulties controlling your board with spinapi, you can enable debugging features by calling pb_set_debug(1) on the first line of your program. This will create file called log.txt when you run your program, which can then be emailed to us along with a description of the problem to help us solve your problem as quickly as possible.


Linux Compilation

Spinapi can be used with Linux on x86 processors. To get your programs running on Linux:

1. In the spinapi_source/ directory, type "make linux-direct". This will create a file called libspinapi.a which you can link your programs against to use SpinCore hardware. Note that this is not the same thing as the file in the dll/ directory. The dll/ directory contains files for use only with Windows and is not usable on linux.

2. To compile your program, you must link with both the spinapi and math libraries. For example, when compiling the "pb24_ex1.c" example program, you would use a command like (assuming both libspinapi.a and pb24_ex1.c are in the current directory):

gcc -opb24_ex1 pb24_ex1.c -L. -lspinapi -lm

This will create an executable called "pb24_ex1".

3. When running programs, you MUST have superuser priveledges (ie be running as root). This is because the spinapi library needs to be able to gain access to the low-level hardware resources.



Contact Info

SpinCore Technologies, Inc. 
4623 NW 53rd Avenue, SUITE 5 
Gainesville, FL 32653 
USA 

Phone:    (USA) 352-271-7383 
Fax:      (USA) 352-371-8679 
E-mail:   sales@spincore.com
Internet: http://www.spincore.com