Exodriver (liblabjackusb) Library Installation Instructions ============================================================ Table of Contents ----------------- Linux Requirements About These Instructions liblabjackusb Library Script Installation Install Without Root Compiling and Running the Example Programs Machines Using VirtualBox liblabjackusb Library Manual Installation LabJackPython and the Exodriver on Ubuntu 10.04 Uninstalling the Old U3 and UE9 Driver Linux Requirements ------------------ 1. GNU C compiler (gcc). For example in Ubuntu, run the following shell command to get it if needed: $ sudo apt-get install build-essential 2. The libusb-1.0 library and development files. Download the source here: http://libusb.info 3. Linux kernel 2.6.28 or higher. To use older 2.6.x kernels, you must upgrade your firmware. These are the required firmware versions when using older 2.6 kernels: * U3 with hardware version 1.30 or higher - Firmware 1.18 and higher * U3 with hardware version less than 1.30 - Only kernel 2.6.28 and higher supported. Unsupported on older kernels. * U6 - Firmware 0.81 and greater * UE9 - Comm Firmware 1.49 and greater 4. Uninstall any old U3 and UE9 kernel-module based drivers. The old driver and custom kernel modules conflict with the current liblabjackusb library. See the "Uninstalling the Old U3 and UE9 Driver" section for more information. About These Instructions ------------------------ All lines that start with a dollar sign ($) are commands and need to be run from a terminal. For example, the Terminal application in Ubuntu version 10.04 is usually accessed through Applications -> Accessories -> Terminal. liblabjackusb Library Script Installation ----------------------------------------- In the exodriver/ directory, run the following command: $ sudo ./install.sh This script will attempt to build, install, and make any necessary system configurations so that the user that runs it will be able to use LabJack devices. For information on allowing multiple users to use LabJack devices, see the "Permissions" section under "liblabjackusb Library Manual Installation". For more information, read the section titled liblabjackusb Library Manual Installation later in this file. Install Without Root -------------------- To install without root / sudo access, invoke `make install` with: - PREFIX set to the desired installation directory - LINK_SO set to true - RUN_LDCONFIG set to false For example: $ cd libjabjack/ $ make $ make install PREFIX=myprefix LINK_SO=1 RUN_LDCONFIG=0 Note: when installing without root and setting up LabJackPython, the LabJackPython.py source file will need to be modified to properly load the liblabjackusb library. Change the line in the _loadLinuxSo() function From: l = ctypes.CDLL("liblabjackusb.so", use_errno=True) To: l = ctypes.CDLL("new absolute path for liblabjackusb.so", use_errno=True) Compiling and Running the Example Programs ------------------------------------------ The example code/programs use the liblabjackusb library and the labjackusb.h header files in the liblabjackusb/ directory. The examples are located in the U3, U6, and UE9 subdirectories in the examples/ directory. To compile the programs go to your device's directory and run $ cd examples/U6/ $ make Run one of example programs like this: $ ./u6BasicConfigU6 Machines Using VirtualBox ------------------------- Customers using Oracle's VirtualBox software should add themselves to the vboxusers group, either through their distribution's GUI interface or through the command: sudo usermod -a -G vboxusers USERNAME liblabjackusb Library Manual Installation ----------------------------------------- For Ubuntu 10.04, see the section titled "Up and running with LabJackPython and the Exodriver on Ubuntu 10.04" later in this document. In the liblabjackusb/ directory, run the following commands to compile and install the library. $ cd liblabjackusb/ $ make $ sudo make install Programs that use liblabjackusb will need to access the USB device bus at /dev/bus/usb/, without root permission. On Debian-based distributions, we provide udev rules that allow all users to access LabJack devices. To Install The udev Rules: To install the udev rules, run the following command from the root directory of this package: $ sudo cp 90-labjack.rules /lib/udev/rules.d Next, reload the udev rules. For instructions, see the section "To Reload the udev Rules" below. To Set Restrictive Permissions: The current udev rules in 90-labjack.rules give LabJack device access to all users. If you need to restrict permissions, alter 90-labjack.rules or install custom rules to /etc/udev/rules.d/, which takes priority over /lib/udev/rules.d/. For example, to restrict usage to members of the adm group: $ sudo cat > /etc/udev/rules.d/90-labjack.rules << EOF SUBSYSTEM!="usb_device", ACTION!="add", GOTO="labjack_rules_end" # LabJack Vendor ID ATTRS{idVendor}=="0cd5", MODE="0664", GROUP="adm" LABEL="labjack_rules_end" Next, reload the udev rules. For instructions, see the section "To Reload the udev Rules" below. Also, notice that the MODE is 0664, which is the only difference between what's installed as /lib/udev/rules.d/90-labjack.rules by default. For more information about writing udev rules, see "man udev". To Reload the udev Rules: To reload the udev rules, the following command works on most systems: $ sudo udevadm control --reload-rules Older vesions of udevadm (e.g., the version included in Ubuntu 8.04) use an underscore instead of a dash: "--reload_rules" instead of "--reload-rules": $ sudo udevadm control --reload_rules On Debian-based distributions, the above two commands are sufficient. If your distribution does not have udevadm, restart udev or restart your computer. On a Fedora machine run: $ sudo /etc/init.d/udev-post reload LabJackPython and the Exodriver on Ubuntu 10.04 ----------------------------------------------- As we detailed in May 2010 (updated with the "liblabjackusb Library Manual Installation" section's steps): http://labjack.com/blog/running-labjackpython-and-exodriver-ubuntu-1004 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 (http://labjack.com/support/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/ $ sudo ./install.sh $ cd .. $ git clone git://github.com/labjack/LabJackPython.git $ cd LabJackPython/ $ sudo python setup.py install $ python >>> import u3 >>> d = u3.U3() >>> d.configU3() Uninstalling the Old U3 and UE9 Driver -------------------------------------- The old U3 and UE9 driver used custom kernel modules, and will conflict with with the current liblabjackusb library. To uninstall the old driver please unload and delete the U3 and/or UE9 kernel modules, delete the liblabjackusb.so library and remove any scripts or udev rules you may have been using to load the kernel module's device nodes. The following commands, or similar depending on the directories you copied files to, should help prepare your system for the new liblabjackusb 2.0 library: $ rmmod labjacku3 $ rm labjacku3.ko /lib/modules/`uname -r`/kernel/drivers/usb/misc/labjacku3.ko $ depmod -a $ rm /usr/lib/liblabjackusb.so These commands remove the udev rules we provided on the forums: $ rm /etc/udev/rules.d/10-labjack.rules $ sudo udevadm control --reload-rules