25.1 I2C Library [T-Series Datasheet]

T7 minimum firmware: 1.0225

The I2C library abstracts most of the Modbus calls needed to run I2C. The abstraction allows users to focus on I2C rather than Modbus, and reduces the memory requirements of scripts. Several I2C examples can be found on the I2C Sensor Examples page.

I2C.config

Error = I2C.config(SDA, SCL, Speed, Options, Address)

Sets parameters that are not normally changed. Values set by this function will remain unchanged until this function is called again or the equivalent Modbus registers are written to.

Parameters:

SDA - DIO pin # that will be used as the I2C data line
SCL - DIO pin # that will be used as the I2C clock line
Speed - See I2C documentation
Options - See I2C documentation
Address - Left Justified

Returns:

Error - standard LabJack T-Series error codes.

I2C.writeRead

RxData, Error = I2C.writeRead(TxData, NumToRead)

This function will first write the data in TxData to the preset address, then will read NumToRead bytes from that same address.

Parameters:

TxData - This is a Lua table containing the values to be transmitted. The size of the table determines the number of bytes that will be transmitted.
NumToRead - The number of data bytes to be read.

Returns:

RxData - A Lua table of the values read
Error - standard LabJack T-Series error codes.

I2C.read

RxData, Error = I2C.read(NumToRead)

This function will read NumToRead bytes from the preset address.

Parameters:

NumToRead - The number of data bytes to be read.

Returns:

RxData - A Lua table of the values read
Error - standard LabJack T-Series error codes.

I2C.write

Error = I2C.write(TxData)

This function will write the data in TxData to the preset address.

Parameters:

TxData - This is a Lua table containing the values to be transmitted. The size of the table determines the number of bytes that will be transmitted.

Returns:

Error - standard LabJack T-Series error codes.

I2C.search

AddressList, Error = I2C.search(FirstAddress, LastAddress)

This function will scan the I2C bus addresses are acknowledged. An acknowledged address means that at least one device is set to that address. Addresses are tested sequentially between the first and last address parameters.

Parameters:

FirstAddress - The first address to be tested.
LastAddress - The last address to be tested.

Returns:

AddressList - A Lua table containing all the addresses that responded.
Error - standard LabJack T-Series error codes.

I2C FAQ/Common Questions

Q: Why are no I2C ACK bits being received?

Double check to make sure pull-up resistors are installed. A general rule for selecting the correct size pull-up resistors is to start with 4.7kΩ and adjust down to 1kΩ as necessary. If necessary, an oscilloscope should be used to ensure proper digital signals are present on the SDA and SCL lines.
Double check to make sure the correct I/O lines are being used. It is preferred to do I2C communication on EIO/CIO/MIO lines instead of the FIO lines due to the larger series resistance (ESD protection) implemented on the FIO lines.
Use an oscilloscope to verify the SDA and SCL lines are square waves and not weird arch signals (see "I2C_SPEED_THROTTLE" or use EIO/CIO/MIO lines).
Use a logic analyzer (some oscilloscopes have this functionality) to verify the correct slave address is being used. See this EEVblog post on budget-friendly options. It is common to not take into account 7-bit vs 8-bit slave addresses or properly understand how LabJack handles the defined slave address and the read/write bits defined by the I2C protocol to perform read and write requests.
Make sure your sensor is being properly powered. The VS lines of LJ devices are ~5V and the I/O lines are 3.3V. Sometimes this is a problem. Consider buying a LJTick-LVDigitalIO or powering the sensor with an I/O line or DAC channel.

Q: I've tried everything, still no I2C Ack Bits...

Try slowing down the I2C bus using the "I2C_SPEED_THROTTLE" register/option. Reasons:
Not all I2C sensors can communicate at the full speed of the LabJack. Check the I2C sensor datasheet.
The digital signals could be getting corrupted due to the series resistors of the I/O lines on the LabJack.
Consider finding a way to verify that your sensor is still functioning correctly using an Arduino and that it isn't broken.
Try to establish communications with an LJTick-DAC to ensure the DIO are operating properly and that you are configuring I2C properly.

Q: Why is my device not being found by the I2C.search function?

See information on I2C ACK bits above.

Q: What are I2C Read and Write functions or procedures?

There are a few really good resources for learning about the general flow of I2C communication.
TI's Understanding the I2C Bus by Jonathan Valdez and Jared Becker is a high quality resource
I2C-bus specification by NXP
Using the I2C Bus by Robot Electronics
I2C Bus Specification by i2c.info

Q: Why am I getting a I2C_BUS_BUSY (LJM Error code 2720) error?

See information on I2C ACK Bits above. Try different pull-up resistor sizes.