LabJackPython is our cross-platform Python module for communicating with the LabJack U3, U6, UE9, and U12. It works on Windows with the UD Driver and U12 Driver, and on Linux and macOS with the Exodriver. For the LJM library (T7, T4, and Digit), use Python_LJM.
For LabJackPython examples, please see the Examples directory in the LabJackPython download, or see on GitHub: https://github.com/labjack/LabJackPython/tree/master/Examples
The latest release of LabJackPython is 2.0.4 from September 9, 2020: Download the 2.0.4 release of LabJackPython.
For the latest development version, archived versions and code repository, visit LabJackPython on GitHub.
Unzip the LabJackPython.zip file and open a terminal/command prompt. In the terminal, use the command line to go to the unzipped LabJackPython directory (e.g., “cd Desktop/LabJackPython”). Then run one of the following commands to install the LabJackPython modules:
python setup.py install
If running the above command causes a "'python' is not recognized as an internal or external command, operable program or batch file." or similar error, that means either Python is not installed on your computer or the Python executable's path was not added to the Windows user or system path. To help resolve this issue, please run the Python Windows installer and in the "Customize Python" window, click the "Add python.exe to Path" option towards the bottom and select "Will be installed on local hard drive".
Then finish the Python installation. Open a new terminal/console window and then go through our LabJackPython installation instructions again.
Alternatively, after Python is installed you can run the Python executable from its path. For example:
C:\Python27\python.exe setup.py install
Note that the above command uses the Python 2.7 path, and you should use the correct path on your computer which may differ.
Another option is to manually add the Python executable's path to the Windows path as described in the Python documentation.
$ sudo python setup.py install
Note the LabJackPython zip file and unzipped directory name will vary on the download.
macOS: As of macOS 10.15, opening a U6 the first time after plugging it in sometimes fails. Subsequent attempts to open succeed.
For documentation, please refer to the docstrings in the source code or use the help function on the module, class, or method.
For the U3, refer to its u3.py source, or use the “help(u3)” call in Python (“import u3” beforehand).
For the U6, refer to its u6.py source, or use the “help(u6)” call in Python (“import u6” beforehand).
For the UE9, refer to its ue9.py source, or use the “help(ue9)” call in Python (“import ue9” beforehand).
For the U12, refer to its u12.py source, or use the “help(u12)” call in Python (“import u12” beforehand).
LabJackPython provides both a Modbus and low-level command interface for performing operations on a LabJack device. Quickstarts can be found for both in the Modbus Quickstart and Low-level Commands Quickstart sections.
This quickstart uses a U3-HV, but the principles and most of the code apply to all LabJack devices.
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.
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 UD Modbus map. Find the table at the bottom of the UD Modbus page in the "UD Modbus Map" section. 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 UD 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).
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 UD Modbus map is also essential for involved Modbus work.
This quickstart uses a U3-HV, but the principles apply to all LabJack devices.
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.
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()
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.
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 recreated all the Modbus Quickstart (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.
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 0x1F 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,
...
}
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.