Linux and Mac OS X drivers

Introducing the Exodriver

The native USB drivers for Linux and Mac OS X have merged into a single driver: the Exodriver. The Exodriver is a thin interface (think exoskeleton) to LabJack devices. It’s written as a C library that uses libusb-1.0 for USB communication. The library can open, close, read from, and write to a LabJack U3, U6, UE9, and U12. Because it’s a library and doesn’t have any kernel code, it’s easy to build.

U12 users also have the option to use the ljacklm high-level driver, which requires the Exodriver. For more details visit the ljacklm web page .

Mac OS X Quickstart

Mac OS X users can use the pre-built installer rather than building the Exodriver from the source. The installer includes an patched copy of libusb 1.0.8 (source code). We also provide a simple Xcode project if you would like to use Xcode to build LabJack applications with the Exodriver. C language examples are provided with the Exodriver’s source code.

If you would prefer to build the Exodriver from the source, the instructions in the next section work on Mac OS X.

Two notes to U12 Users on Mac OS X: First, there is an issue with interrupt transfers and libusb that can be a huge problem for U12 users. There is an unofficial patch that should be included in the next release (1.0.9) of libusb. For now, we offer the libusb source with the patch applied. We have also updated the pre-built installer to use this version. (You should probably use the installer anyway because of the second note.) Second, use the “Customize install” option of the pre-built installer to add the LabJackHID kernel extension. This is a null kernel extension which prevents the OS’s HID driver from claiming a LabJack HID device. This is only required by U12 and SkyMote Bridge devices, otherwise it does not need to be installed.

Quickstart: Building from the source

If you have all the requirements:

1. A modern Linux or Mac OS X system
2. A C compiler (gcc, e.g., build-essential on Debian/Ubuntu, Xcode on Mac OS X)
3. libusb-1.0 installed (from the source or -dev binary packages)

then building the Exodriver is easy. Download the source (click the “ZIP” button or “Download Source” link on that page), build it, and install it.

On both Linux and Mac OS X, run

  
$ cd liblabjackusb/
$ make
$ sudo make install
  

After installing the Exodriver, build the U3, U6, or UE9 example programs:

  
$ cd ../examples/U6/
$ make
  

Run one of example programs like this:

  
$ ./u6BasicConfigU6
  

For more information, consult INSTALL.Linux or INSTALL.MacOSX. INSTALL.Linux details which kernel versions are required and how to automatically set device permissions properly. INSTALL.MacOSX lists which releases of Mac OS X are supported.

In-depth Linux build instructions

As we detailed in May 2010, Ubuntu 10.04 comes with a binary release of libusb-1.0, so building the Exodriver is easier than ever. Install the dependencies with apt-get, checkout the Exodriver source code, and build it. Here are the complete steps, along with a handful of steps at the end that build LabJackPython, which is our Python module that works well with the Exodriver:

  
$ sudo apt-get install build-essential
$ sudo apt-get install libusb-1.0-0-dev
$ sudo apt-get install git-core
$ git clone git://github.com/labjack/exodriver.git
$ cd exodriver/liblabjackusb/
$ make
$ sudo make install
$ cd ..
$ sudo cp 10-labjack.rules /etc/udev/rules.d/.
$ sudo udevadm control --reload-rules
$ cd
$ git clone git://github.com/labjack/LabJackPython.git
$ cd LabJackPython/
$ sudo python setup.py install
$ python
>>> import u3
>>> d = u3.U3()
>>> d.configU3()
   

If you don’t have Ubuntu 10.04, and your distribution doesn’t have binary libusb-1.0 packages, this step will fail:

  
$ sudo apt-get install libusb-1.0-0-dev
   

Instead build libusb-1.0 from the source. Download the source from SourceForge. Version 1.0.8 is the latest as of July 2010. Build it in the standard way:

  
$ tar xvfj libusb-1.0.8.tar.bz2 
$ cd libusb-1.0.8/
$ ./configure
$ make
$ sudo make install
   

Be sure to consult INSTALL.Linux for instructions on how to set the device permissions correctly using udev.

In-depth Mac OS X build instructions

Download Xcode and install it if you don’t have it already.

Mac OS X requires libusb-1.0 to be built from the source (like many Linux distributions). Download the source from SourceForge. Version 1.0.8 is the latest as of July 2010. Build it in the standard way:

  
$ tar xvfj libusb-1.0.8.tar.bz2 
$ cd libusb-1.0.8/
$ ./configure
$ make
$ sudo make install
   

After installing libusb-1.0, install the Exodriver as described in the Quickstart.

Optional: Build a combined 32-/64-bit Exodriver on Mac OS X

These steps are generally not needed, but there are circumstances that require a combined 32-bit and 64-bit Exodriver. You need both architectures when you get error messages like the one in this LabJack forum topic

  
dlopen(liblabjackusb.dylib, 6): no suitable image found.  Did find:
    /usr/local/lib/liblabjackusb.dylib: mach-o, but wrong architecture
   

In this case, a 32-bit process tried to load a 64-bit Exodriver. Here’s how it happened: When following the instructions in the Quickstart, the compiler built a copy of the Exodriver for its native architecture. On modern Mac OS X systems, that’s x86_64 (64-bit). Verify this by running:

  
$ file /usr/local/lib/liblabjackusb.dylib 
/usr/local/lib/liblabjackusb.dylib: Mach-O 64-bit dynamically linked shared library x86_64
   

Normally, this is what you want. The programs you will use to call the Exodriver will also be 64-bit. The built-in Python on Mac OS X, for example, is compiled for three architectures, including x86_64:

  
$ file /usr/bin/python
/usr/bin/python: Mach-O universal binary with 3 architectures
/usr/bin/python (for architecture x86_64):	Mach-O 64-bit executable x86_64
/usr/bin/python (for architecture i386):	Mach-O executable i386
/usr/bin/python (for architecture ppc7400):	Mach-O executable ppc
   

There are some programs on Mac OS X, though, that are not 64-bit (they’re i386 only), and they can’t load a 64-bit Exodriver. The Python download from python.org, for example, is 32-bit at the time of this writing. We recommend using the built-in Python on Mac OS X.

When you must load the Exodriver from a 32-bit process, you must compile libusb-1.0 and the Exodriver to be combined 32-/64-bit libraries. Start with libusb-1.0

  
$ tar xvfj libusb-1.0.8.tar.bz2 
$ cd libusb-1.0.8/
$ export CFLAGS="-arch i386 -arch x86_64"
$ ./configure --disable-dependency-tracking
$ make
$ sudo make install
   

Confirm it worked by running:

  
$ file /usr/local/lib/libusb-1.0.dylib
/usr/local/lib/libusb-1.0.dylib: Mach-O universal binary with 2 architectures
/usr/local/lib/libusb-1.0.dylib (for architecture i386):	Mach-O dynamically linked shared library i386
/usr/local/lib/libusb-1.0.dylib (for architecture x86_64):	Mach-O 64-bit dynamically linked shared library x86_64
   

After libusb-1.0 is installed correctly, move on to the Exodriver. Download the source link on GitHub. Find the Exodriver download directory

  
$ cd path/to/exodriver
$ cd liblabjackusb/
   

Now edit the Makefile in a text editor to comment out (put a # sign in front of) this ARCHFLAGS line:

  
#ARCHFLAGS =
   

and uncomment (remove the # sign from) this ARCHFLAGS line two lines above it:

  
ARCHFLAGS = -arch i386 -arch x86_64
   

Now build and install the software

  
$ make clean
$ make
$ sudo make install
   

Verify that it worked by running:

  
$ file /usr/local/lib/liblabjackusb.dylib 
/usr/local/lib/liblabjackusb.dylib: Mach-O universal binary with 2 architectures
/usr/local/lib/liblabjackusb.dylib (for architecture i386):	Mach-O dynamically linked shared library i386
/usr/local/lib/liblabjackusb.dylib (for architecture x86_64):	Mach-O 64-bit dynamically linked shared library x86_64
   

Because libusb-1.0 and the Exodriver are built for the i386 architecture, 32-bit applications can load them.