io.dvlopt.linux.i2c

Class I2CBus

java.lang.Object

io.dvlopt.linux.i2c.I2CBus

All Implemented Interfaces:

AutoCloseable

public class I2CBus
extends Object
implements AutoCloseable

Class representing an I2C bus.

It provides 3 sets of operations for doing IO :

• Directly reading and writing by using read and write.
• Doing transactions (ie. uninterrupted reads and writes)
• Using SMBUS operations as defined in the standard (all the other IO functions).

SMBUS operations are a subset of what I2C can achieve but propose common interactions. However, getFunctionnalities should be used in order to understand what operations the underlying driver support.

I2C is a standard but your master device and the slaves devices it talks do probably do not support everything properly. For instance, as is, the Raspberry Pi only supports a few SMBUS operations and do not support transactions involving more than one message at a time (which defeats the purpose of having them in the first place). Furthermore, talking to an Arduino will result in timing issues if it is too slow to answer. Communication between those two is very much possible but requires more preparation and testing. This is an example of how things are not always that simple.

In this API, `command` is just another word for what is sometimes called `register`. Essentially, it means that before reading or writing bytes, the master writes a byte specifying a command, something to do with the following byte(s). If an SMBUS functionality is not available, this can often be emulated by explicitly sending the command byte and then reading or writing as needed.

See Also:

SMBUS operations

Constructor Summary

Constructors

Constructor and Description
I2CBus(int busNumber) Opens an I2C bus by number, `/dev/i2c-$busNumber`.
I2CBus(String path) Opens an I2C bus on the given path.

Method Summary

Modifier and Type	Method and Description
int	blockProcessCall(int command, I2CBlock block) SMBUS RPC-like operation, writing several bytes after specifying a command and then reading several bytes as an answer.
int	blockProcessCall(int command, I2CBlock blockWrite, I2CBlock blockRead) SMBUS RPC-like operation, writing several bytes after specifying a command and then reading several bytes as an answer.
void	close() Closes this bus.
void	doTransaction(I2CTransaction transaction) Do an uninterrupted transaction of several messages.
I2CFunctionalities	getFunctionalities() Finds out what this I2C bus can do.
int	processCall(int command, int word) SMBUS RPC-like operation, writing a short after specifying a command and then reading the answer.
void	quick(boolean isWrite) SMBUS operation sending only the READ or WRITE bit, no data is carried.
void	read(I2CBuffer buffer) Directly reads bytes from the slave device (length is specified by the buffer).
void	read(I2CBuffer buffer, int length) Directly reads length bytes from the slave device.
int	readBlock(int command, I2CBlock block) SMBUS operation reading several bytes after specifying a command.
int	readByte(int command) SMBUS operation reading a byte after specifying a command.
int	readByteDirectly() SMBUS operation reading a byte without a command.
void	readI2CBlock(int command, I2CBlock block, int length) SMBUS-like operation reading several bytes after specifying a command where the length is part of the message.
int	readWord(int command) SMBUS operation reading a short after specifying a command.
void	selectSlave(int address) Selects an available slave device using a regular 7-bit address.
void	selectSlave(int address, boolean force, boolean isTenBit) Selects an available slave device.
void	setRetries(int nRetries) Sets the number of time a slave should be polled when not acknowledging.
void	setTimeout(int milliseconds) Sets the timeout in milliseconds.
void	usePEC(boolean usePEC) Enables or disables packet error checking for SMBUS commands.
void	write(I2CBuffer buffer) Directly writes bytes to the slave device (length is specified by the buffer).
void	write(I2CBuffer buffer, int length) Directly writes length bytes to the slave device.
void	writeBlock(int command, I2CBlock block) SMBUS operation writing several bytes after specifying a command.
void	writeByte(int command, int b) SMBUS operation writing a byte after specifying a command.
void	writeByteDirectly(int b) SMBUS operation writing a byte without a command.
void	writeI2CBlock(int command, I2CBlock block) SMBUS-like operation writing several bytes after specifying a command where the length is part of the message.
void	writeWord(int command, int word) SMBUS operation writing a short after specifying a command.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

I2CBus

public I2CBus(int busNumber)
       throws LinuxException

Opens an I2C bus by number, `/dev/i2c-$busNumber`.

Parameters:

busNumber - The number of the bus.

Throws:

LinuxException - When something fails on the native side.

I2CBus

public I2CBus(String path)
       throws LinuxException

Opens an I2C bus on the given path.

Parameters:

path - A path to the bus such as `/dev/i2c-1`.

Throws:

LinuxException - When something fails on the native side.

Method Detail

close

public void close()
           throws LinuxException

Closes this bus.

Specified by:

close in interface AutoCloseable

Throws:

LinuxException - When something fails on the native side.

doTransaction

public void doTransaction(I2CTransaction transaction)
                   throws LinuxException

Do an uninterrupted transaction of several messages.

Not all devices support this feature, or support only one message at a time which is not very interesting.

Parameters:

transaction - The transaction that will be carried out.

Throws:

LinuxException - When something fails on the native side.

getFunctionalities

public I2CFunctionalities getFunctionalities()
                                      throws LinuxException

Finds out what this I2C bus can do.

Returns:

Functionalities.

Throws:

LinuxException - When something fails on the native side.

selectSlave

public void selectSlave(int address)
                 throws LinuxException

Selects an available slave device using a regular 7-bit address.

Parameters:

address - The address of the needed slave.

Throws:

LinuxException - When something fails on the native side.

See Also:

selectSlave( int, boolean, boolean )

selectSlave

public void selectSlave(int address,
                        boolean force,
                        boolean isTenBit)
                 throws LinuxException

Selects an available slave device.

This needs to be called only once if several IO operations are performed on the same slave and has no effect on transactions.

Parameters:

address - The address of the needed slave.

force - Should the slave be selected even if it is already used somewhere else ?

isTenBit - Is the given address in 10-bit resolution ?

Throws:

LinuxException - When something fails on the native side.

setRetries

public void setRetries(int nRetries)
                throws LinuxException

Sets the number of time a slave should be polled when not acknowledging.

Does not always have an effect depending on the underlying driver.

Parameters:

nRetries - the number of retries.

Throws:

LinuxException - When something fails on the native side.

setTimeout

public void setTimeout(int milliseconds)
                throws LinuxException

Sets the timeout in milliseconds.

Does not always have an effect depending on the underlying driver.

Parameters:

milliseconds - The timeout in milliseconds.

Throws:

LinuxException - When something fails on the native side.

usePEC

public void usePEC(boolean usePEC)
            throws LinuxException

Enables or disables packet error checking for SMBUS commands.

Is ignored unless the underlying driver provides this functionality.

Slave devices do not necessarely support this feature either.

Parameters:

usePEC - Should PEC be enabled ?

Throws:

LinuxException - When something fails on the native side.

quick

public void quick(boolean isWrite)
           throws LinuxException

SMBUS operation sending only the READ or WRITE bit, no data is carried.

Parameters:

isWrite - True if the WRITE bit must be set.

Throws:

LinuxException - When something fails on the native side.

readByteDirectly

public int readByteDirectly()
                     throws LinuxException

SMBUS operation reading a byte without a command.

Returns:

The unsigned byte received from the slave.

Throws:

LinuxException - When something fails on the native side.

readByte

public int readByte(int command)
             throws LinuxException

SMBUS operation reading a byte after specifying a command.

Parameters:

command - The command.

Returns:

The unsigned byte received from the slave.

Throws:

LinuxException - When something fails on the native side.

readWord

public int readWord(int command)
             throws LinuxException

SMBUS operation reading a short after specifying a command.

Parameters:

command - The command.

Returns:

The unsigned short received from the slave.

Throws:

LinuxException - When something fails on the native side.

readBlock

public int readBlock(int command,
                     I2CBlock block)
              throws LinuxException

SMBUS operation reading several bytes after specifying a command.

Parameters:

command - The command.

block - Block of bytes the answer will be written to.

Returns:

The number of bytes read.

Throws:

LinuxException - When something fails on the native side.

readI2CBlock

public void readI2CBlock(int command,
                         I2CBlock block,
                         int length)
                  throws LinuxException

SMBUS-like operation reading several bytes after specifying a command where the length is part of the message.

This operation is not in the SMBUS standard but is often supported nonetheless.

Parameters:

command - The command.

block - Block of bytes the answer will be written to.

length - How many bytes should be read.

Throws:

LinuxException - When something fails on the native side.

read

public void read(I2CBuffer buffer)
          throws LinuxException

Directly reads bytes from the slave device (length is specified by the buffer).

Parameters:

buffer - Buffer the answer will be written to.

Throws:

LinuxException - When something fails on the native side.

See Also:

read( I2CBuffer, int )

read

public void read(I2CBuffer buffer,
                 int length)
          throws LinuxException

Directly reads length bytes from the slave device.

Parameters:

buffer - Buffer the answer will be written to.

length - The number of bytes requested.

Throws:

LinuxException - When something fails on the native side.

writeByteDirectly

public void writeByteDirectly(int b)
                       throws LinuxException

SMBUS operation writing a byte without a command.

Parameters:

b - The unsigned byte that needs to be sent.

Throws:

LinuxException - When something fails on the native side.

writeByte

public void writeByte(int command,
                      int b)
               throws LinuxException

SMBUS operation writing a byte after specifying a command.

Parameters:

command - The command.

b - The unsigned byte that need to be sent.

Throws:

LinuxException - When something fails on the native side.

writeWord

public void writeWord(int command,
                      int word)
               throws LinuxException

SMBUS operation writing a short after specifying a command.

Parameters:

command - The command.

word - The unsigned short that needs to be sent.

Throws:

LinuxException - When something fails on the native side.

writeBlock

public void writeBlock(int command,
                       I2CBlock block)
                throws LinuxException

SMBUS operation writing several bytes after specifying a command.

After the command byte, the master also sends a byte count, how many bytes will be written.

Parameters:

command - The command.

block - Block of bytes to write.

Throws:

LinuxException - When something fails on the native side.

writeI2CBlock

public void writeI2CBlock(int command,
                          I2CBlock block)
                   throws LinuxException

SMBUS-like operation writing several bytes after specifying a command where the length is part of the message.

This operation is not in the SMBUS standard but is often supported nonetheless.

Unlike writeBlock, this operation does not send a byte count after the command.

Parameters:

command - The command.

block - Block of bytes to write.

Throws:

LinuxException - When something fails on the native side.

write

public void write(I2CBuffer buffer)
           throws LinuxException

Directly writes bytes to the slave device (length is specified by the buffer).

Parameters:

buffer - Buffer to write.

Throws:

LinuxException - When something fails on the native side.

See Also:

write( I2CBuffer, int )

write

public void write(I2CBuffer buffer,
                  int length)
           throws LinuxException

Directly writes length bytes to the slave device.

Parameters:

buffer - Buffer to write.

length - The number of bytes.

Throws:

LinuxException - When something fails on the native side.

processCall

public int processCall(int command,
                       int word)
                throws LinuxException

SMBUS RPC-like operation, writing a short after specifying a command and then reading the answer.

Parameters:

command - The command.

word - The unsigned short to be sent.

Returns:

The unsigned short given back by the slave.

Throws:

LinuxException - When something fails on the native side.

blockProcessCall

public int blockProcessCall(int command,
                            I2CBlock block)
                     throws LinuxException

SMBUS RPC-like operation, writing several bytes after specifying a command and then reading several bytes as an answer.

Parameters:

command - The command.

block - Block of bytes to write, also where the answer will be written to.

Returns:

The number of bytes read.

Throws:

LinuxException - When something fails on the native side.

blockProcessCall

public int blockProcessCall(int command,
                            I2CBlock blockWrite,
                            I2CBlock blockRead)
                     throws LinuxException

SMBUS RPC-like operation, writing several bytes after specifying a command and then reading several bytes as an answer.

Parameters:

command - The command.

blockWrite - Block of bytes to write.

blockRead - Block of bytes the answer will be written to (can be the same as blockWrite is it can be overwritten

Returns:

The number of bytes read.

Throws:

LinuxException - When something fails on the native side.