Signal Hound SA44/124B API for 64-bit Linux systems

The API was developed and tested on Ubuntu 14.04 LTS
Installation instructions may reflect this.

Email/Support: roger@signalhound.com

For version specific release notes, see the change log at
www.signalhound.com/Spike

Release Notes: 
6/21/2016 : API Version 3.0.11 compiled for 64-bit Linux.

-- Description --
The SA44/124B API is now available for 64-bit Linux. You can use the API to control both the SA44B and SA124B Signal Hound spectrum analyzers. The API will function identical to the Windows version, and as such, share examples and documentation. 
You can find the latest API manuals at
www.signalhound.com/support/product-downloads/sa44b-sa124b-downloads

-- Compilation Notes -- 
The API is compiled on Ubuntu 14.04 using g++ 4.8.2 as a shared object library.
The API depends on libusb-1.0 and ftdi USB drivers. Installation instructions can be found below for both libraries.

-- Libusb 1.0 requirement -- 
You will need libusb-1.0 installed in the system path. 
Determine if libusb-1.0 is installed on your system with
  'locate libusb-1.0.so'
You can install libusb-1.0 with
  'sudo apt-get install libusb-1.0-0' 
or
  download and install from www.libusb.org

-- FTDI D2XX library requirement --
You will need the FTDI D2XX USB library (libftd2xx.so) in your system path.
You can find the latest library at
www.ftdichip.com/Drivers/D2XX.htm and find the 64-bit Linux driver download on the download table 
or
You can find a copy of the library in the lib folder shipped with this SDK. The version of the distributed library is the latest version at the time of development for 64-bit systems. 

-- Low latency kernel requirement --
To guarantee adequate USB throughput, the lowlatency kernel should be installed. It will then be possible to switch back and forth between the lowlatency and generic kernels (instructions follow).

Determine what kernel you are currently using with
  'uname -r'
If you haven't made any changes then it should say "generic."

You can install the lowlatency kernel with 
  'sudo apt-get install linux-lowlatency'

If you would like to be able to switch between the lowlatency and generic kernels, on Ubuntu you can do the following:
  1) Download ubuntustudio-default-settings package from 
     http://packages.ubuntu.com/trusty/ubuntustudio-default-settings (choose your release through links in top right corner)
  2) Exctract it.
  3) Copy 09_lowlatency file to /etc/grub.d

To switch from generic to lowlatency:
  1) In /etc/grub.d XX_lowlatency should occur before 10_linux, so you can do something like 
       'sudo mv 11_lowlatency 09_lowlatency'
  2) In /etc/grub.d/10_linux comment out 2 lines as shown:

        machine=`uname -m`
	case "x$machine" in
	    xi?86 | xx86_64)
		list=`for i in /boot/vmlinuz-* /vmlinuz-* /boot/kernel-* ; do
	                  # if [ -z "${i##*lowlatency}" ] ; then continue ; fi
	                  if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
	              done` ;;
	    *) 
		list=`for i in /boot/vmlinuz-* /boot/vmlinux-* /vmlinuz-* /vmlinux-* /boot/kernel-* ; do
	                  # if [ -z "${i##*lowlatency}" ] ; then continue ; fi
	                  if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
		     done` ;;
	esac

  3) Run 
       'sudo update-grub2'
  4) Reboot

To switch from lowlatency to generic follow the same steps but in steps 1 and 2 do the opposite.

-- Device Permissions --
To run an application utilizing libusb, you need to be have
root permissions. You can either run your application as root or change permissions for the device.

-- Changing Device Permissions --
If you do not want to run your application with root permissions, you will need to change permissions for the Signal Hound SA44/124 devices. You will need to place the sa.rules file in the /etc/udev/rules.d/ directory. Once you have done this, you will need to unplug and plug in the device for the rules to take effect. You should then be able to interface the device without root permissions.

-- Installation --
The SA44/124 API is a 64 bit shared library. The library can be found in the lib/ folder.
The best way to develop to the sa_api is to place the included libraries in the /usr/local/lib directory. Steps to perform this are below.

To install the shared library on your system from the lib folder type

   ldconfig -v -n .
   ln -sf libsa_api.so.3.0.11 libsa_api.so
   sudo cp libsa_api.* /usr/local/lib
 
This should create the necessary symlinks to the main library and place them in the library directory.

The shared library can now be linked in with g++ by
    g++ sources -o output_exe -Wl,-rpath=/usr/local/lib -lsa_api

This same process can be performed for the ftdi library if you wish to install the one distributed.

To prevent some kernel modules from loading automatically you will want to copy the blacklist file 
  'sudo cp hound-blacklist.conf /etc/modprobe.d/hound-blacklist.conf'

You will need to reboot for all changes to take effect.

-- Calibration Files --
To use an SA44B or SA124B device the API must have access to device-specific calibration files. There are two such files, whose names contain the device's serial number and extensions are .bin and .tep. The first time you load a new device the API will attempt to pull these files from the device's flash storage, and copy them into the executable directory of the project you are running. It always checks this directory first for the cal files. If for some reason the API is unable to retrieve the cal files from your device, as will be indicated by a runtime invalid device error upon attempting to open device, and a lack of cal files in your executable directory, you may copy these files from a Windows computer to this directory. On Windows they are located at 'C:\ProgramData\SignalHound\cal_files'. Otherwise contact support@signalhound.com with the serial number of your device and we can provide its cal files.     

