LabJackPython (Windows UD, Mac, Linux)

LabJackPython is our cross-platform Python module for communicating with LabJack devices. It works on Windows using the UD Driver and U12 Driver, and on Linux and Mac OS X with the Exodriver.

Download

The latest stable release of LabJackPython is from October 22, 2012: Download 10-22-2012 release of LabJackPython.

Python 2.5, 2.6, or 2.7 is required to use LabJackPython. Python 3 is not currently supported. On Mac OS X, the built-in Python works, and it is 32- and 64-bit compatible. It also comes with Twisted, which you would need to use LJSocket. Use the built-in Python unless you have a good reason not to. Recent Linux distributions also ship with new enough versions of Python built in.

Install

Go to the OS X terminal

$ cd Desktop
$ unzip LabJackPython-8-26-2011.zip
$ cd LabJackPython-8-26-2011/
$ sudo python setup.py install
$ python
>>> import u3
>>> d = u3.U3()
>>> d.configU3()

Development

You can download the latest edge version, or previous tagged versions, of LabJackPython on GitHub.

Driver requirements

The LabJackPython module works with the Windows UD driver and U12 driver (only required if using a U12), and the Exodriver on Mac OS X and Linux. Refer to the README file for more information.

Firmware requirements

To use the UE9 over Ethernet, install comm firmware 1.50 or higher. At the moment it’s on the beta page.

Documentation

For LabJackPython documentation, please refer to the docstrings in the source code or use the help function. For example, documentation on classes and functions in the u3 module can be found in the u3.py source or by using the “help(u3)” call in Python (note to “import u3” first). For specific documentation on only the U3 class use “help(u3.U3)”.

Quickstart

This quickstart uses a U3-HV, but the principles and most of the code apply to all LabJack devices.

Opening the device

Here’s how to open a U3:

>>> import u3
>>> d = u3.U3()

The constructor for the U3 class will try to automatically open the first found U3. This is good if you only have one U3 connected.

Basic I/O: DAC0, AIN0, FIO4, FIO6

Wire a jumper from DAC0 to AIN0, connect an LED from FIO4 to VS and jumper FIO6 to GND. Wire the anode (longer-lead) of the LED to VS and the cathode to FIO4. For more information on controlling LEDs, refer to the LED app note . The LED connection we are using is configuration 2 in the app note.

Set DAC0 to 1.5 V, and read the voltage on AIN0:

>>> DAC0_REGISTER = 5000
>>> d.writeRegister(DAC0_REGISTER, 1.5) # Set DAC0 to 1.5 V
1.5
>>> AIN0_REGISTER = 0
>>> d.readRegister(AIN0_REGISTER)     # Read from AIN0
1.5252180099487305

In this example, we’re using the LabJack’s Modbus interface, which is register-based. The values of DAC0_REGISTER and AIN0_REGISTER are taken from the Modbus map. Find the table at the bottom of the Modbus page titled “LabJack ModBus Map”. What register is DAC1 located at? Check the map, and confirm that it’s at 5002.

Now toggle the LED by setting FIO4 to output low and output high:

>>> FIO4_STATE_REGISTER = 6004
>>> d.writeRegister(FIO4_STATE_REGISTER, 0) # Set FIO4 low, LED on
0
>>> d.writeRegister(FIO4_STATE_REGISTER, 1) # Set FIO4 high, LED off
1

The value of FIO4_STATE_REGISTER is also taken from the Modbus map. Verify that the LED toggles on and off as FIO4’s state changes from low to high.

Now use FIO6 for digital input. First, we configure it for input, then we read its state:

>>> FIO6_DIR_REGISTER = 6106
>>> FIO6_STATE_REGISTER = 6006
>>> d.writeRegister(FIO6_DIR_REGISTER, 0)  # Set FIO4 to digital input
0
>>> d.readRegister(FIO6_STATE_REGISTER)    # Read the state of FIO6
0
>>> # Disconnect GND or connect FIO6 to VS
>>> d.readRegister(FIO6_STATE_REGISTER)
1
>>> # Reconnect GND
>>> d.readRegister(FIO6_STATE_REGISTER)
0

With FIO6 connected to GND, reading digital input on FIO6 reads low (0). When GND is disconnected, the FIO’s internal pull-up resistor causes its state to be high (1). With FIO6 connected to VS, reading the digital input on FIO6 reads high (1).

Going further with Modbus

In this quickstart, we’ve used the LabJack’s Modbus interface to use DAC0, AIN0, FIO4 and FIO6. For more examples of using Modbus, consult the workingWithModbus.py distributed with LabJackPython. The Modbus map is also essential for involved Modbus work.

Beyond Modbus: Low-level commands

The rest of this document will use the LabJack’s low-level command set. Unlike the Modbus interface, the low-level commands were written specifically to communicate with the LabJack.

Low-level Commands

If you skipped the Quickstart above, ensure that your LabJack device is open:

>>> import u3
>>> d = u3.U3()

Basic I/O: DAC0, AIN0, FIO4, FIO6 with low-level commands

Using the same wiring as the quickstart, let’s recreate the basic I/O operations using LabJack-specific low-level commands. First, before we perform any other operation we will get your LabJack device’s calibration data. This only needs to be performed once after opening your device. The calibration data will be used by functions that convert binary data to voltage/temperature and vice versa.

>>> d.getCalibrationData()

Setting the DAC is a U3 Feedback command, so we’ll use the U3 class getFeedback() function. For every Feedback command, there is a corresponding class in u3.py. The 8-bit DAC0 feedback command from Section 5.2.5.13 has a class named DAC0_8. Here’s how to use it:

>>> DAC0_VALUE = d.voltageToDACBits(1.5, dacNumber = 0, is16Bits = False)
>>> d.getFeedback(u3.DAC0_8(DAC0_VALUE))        # Set DAC0 to 1.5 V

As the documentation in Section 5.2.5.13 states, the 8-bit DAC0 feedback command takes a value between 0 and 255 (inclusive) and the output of the DAC is between 0 and 4.95 V. The variable DAC0_VALUE converts between the two. Reading from an analog input is also a feedback command. As Section 5.2.5.1 of the U3 User’s Guide states, the feedback command returns a 16-bit unsigned value that we must convert into a voltage. Here’s how to do that:

>>> ain0bits, = d.getFeedback(u3.AIN(0)) # Read from raw bits from AIN0
>>> print ain0bits
37584
>>> ainValue = d.binaryToCalibratedAnalogVoltage(ain0bits, isLowVoltage = False, channelNumber = 0)
>>> print ainValue
1.501376

Similar to setting DAC0, we use the getFeedback() function and the AIN class from the u3 module (u3.AIN). The getFeedback() function always returns a list (more on that later), and so we use a trailing comma after ain0bits:

>>> ain0bits, = d.getFeedback(u3.AIN(0))

to automatically unpack the first value in the list. The U3 class has a function binaryToCalibratedAnalogVoltage() that knows how to apply the proper calibration constants to convert the reading into a voltage. The function applies different constants based on whether we are using a U3-LV (default) or one of the high-voltage inputs on the U3-HV. When using a high-voltage input, we specify isLowVoltage = False. For the U3-HV, the channel number (channelNumber) also needs to be specified so the correct calibrations constants are applied.

Because reading an analog input is such a common operation, the U3 class provides a getAIN() function that calls getFeedback() and binaryToCalibratedAnalogVoltage() with the correct parameters:

>>> ainValue = d.getAIN(0)  # Read from AIN0 in one function
>>> print ainValue
1.501376

Setting a digital line’s state and direction is also done with feedback commands. The relevant ones are BitStateRead, BitStateWrite, BitDirRead, and BitDirWrite.

# Check which FIOs are analog and which are digital
>>> configDict = d.configIO()
>>> configDict["FIOAnalog"]
63
# Set the first four (0-3) to analog (15 = 1111 binary) and the rest to digital
>>> d.configIO(FIOAnalog = 15)
>>> d.getFeedback(u3.BitDirWrite(4, 1))   # Set FIO4 to digital output
[None]
>>> d.getFeedback(u3.BitStateWrite(4, 0)) # Set FIO4 to output low
[None]
>>> d.getFeedback(u3.BitStateWrite(4, 1)) # Set FIO4 to output high
[None]

Note the call to configIO(), which is not a feedback command, but a low-level command in Section 5.2.3. All the low-level commands in Section 5.2 are implemented as functions of the U3 class.

The getFeedback() function also accepts a list of feedback commands, and it accepts multiple arguments directly. For example, here’s how to set FIO4 for digital output and output high at the same time:

>>> outputDirCmd = u3.BitDirWrite(4, 1)
>>> outputHighCmd = u3.BitStateWrite(4, 1)
>>> cmdList = [outputDirCmd, outputHighCmd]
>>> d.getFeedback(cmdList) # Pass a list of commands
[None, None]
>>> d.getFeedback(outputDirCmd, outputHighCmd) # Or pass the commands as arguments
[None, None]

which is exactly what the setFIOState() convenience function does:

>>> d.setFIOState(4, 1) # Set FIO output high in one function
>>> d.setFIOState(4, 0) # Set FIO output low in one function

When you pass multiple feedback commands to getFeedback(), the function processes them sequentially. Here is an example of checking the direction of FIO4 (it’s set to output from above), set the FIO4 direction to input, and read FIO4 direction:

# Multiple feedback commands
#    Read FIO4's direction
#    Set FIO4's direction to input
#    Read FIO4's direction again
>>> d.getFeedback(u3.BitDirRead(4), u3.BitDirWrite(4, 0), u3.BitDirRead(4))
[1, None, 0]

Now lets set FIO6’s direction to input and read its state:

# Set FIO6's direction to input and read its state
>>> d.getFeedback(u3.BitDirWrite(6, 0), u3.BitStateRead(6))
[None, 0]
# Disconnect from GND
>>> d.getFeedback(u3.BitStateRead(6))
[1]
# Reconnect to GND
>>> d.getFeedback(u3.BitStateRead(6))
[0]

To get the actual state (first value of the list), don’t forget to unpack it:

>>> v, = d.getFeedback(u3.BitStateRead(6))
>>> v
0
>>> v = d.getFeedback(u3.BitStateRead(6))[0]
>>> v
0

which is exactly what the getFIOState() convenience function does:

>>> d.getFIOState(6)
0

We’ve now recreated all the Modbus (readRegister() and writeRegister()) operations on DAC0, AIN0, FIO4 and FIO6 using low-level commands. Many low-level commands are feedback commands, so they are passed into getFeedback(), which is a very flexible function that can perform many operations on your device at once. To go beyond the basic low-level operations (basic analog and digital), explore the other built-in commands and the LabJackPython source as described in the sections below.

Low-level commands as built-in functions

Section 5.2 of the U3 User’s Guide describes the low-level commands. All the low-level commands in the U3 User’s Guide have been defined as functions in the U3 LabJackPython class.

For example, we can get helpful information by calling the configU3() command. Note that in Section 5.2.2 of the U3 User’s Guide is a description of ConfigU3.

Here we are going to call configU3 with no arguments to perform only a read.

>>> print d.configU3()
{
    'LocalID': 5, 
    'SerialNumber': 32003XXXX, 
    'DAC1Enable': 1,
    'EIODirection': 0,
    'DeviceName': 'U3-HV',
    ...
}

The configU3() function sets the power-up defaults of the U3. To change the U3’s behavior for this session only, use configIO(). For example, to set the first five FIO lines to analog for this session, call configIO with the FIOAnalog keyword argument:

>>> d.configIO(FIOAnalog = 0x1F)
{'DAC1Enable': 0, 'FIOAnalog': 31, 'EIOAnalog': 0, 'TimerCounterConfig': 64}

The value 0×1F is a bitmask with the lower 5 bits set to 1, signifying the first five FIOs. To make this setting survive power cycles, call configU3() instead of configIO():

>>> d.configU3(FIOAnalog = 0x1F)
{...
'FIOAnalog': 31,
...
}
>>> d.close()
>>> # Unplug the U3 and plug it back in
>>> d.open()
>>> d.configU3()
{...
'FIOAnalog': 31,
...
}

Examining the source

Some of the best low-level documentation of LabJackPython is in the docstrings of the source code. For example, the u3.py module has many examples for the low-level commands. The feedback commands are implemented as classes at the bottom of the module, and every feedback command has a docstring with an example of how to use it.