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 by using the interface via the smbus field.

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 to 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

Field Summary

Fields

Modifier and Type	Field and Description
SMBus	smbus For executing SMBus operations using this I2C bus.

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
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.
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.
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	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.

Methods inherited from class java.lang.Object

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

Field Detail

smbus

public final SMBus smbus

For executing SMBus operations using this I2C bus.

Constructor Detail

I2CBus

public I2CBus(int busNumber)
       throws IOException

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

Parameters:

busNumber - Number of the bus.

Throws:

IOException - When an unplanned error occured.

I2CBus

public I2CBus(String path)
       throws IOException

Opens an I2C bus on the given path.

Parameters:

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

Throws:

FileNotFoundException - When the bus is not found or the user does not have permissions.

IOException - When an unplanned error occured.

Method Detail

close

public void close()
           throws IOException

Closes this bus.

Specified by:

close in interface AutoCloseable

Throws:

IOException - When an unplanned error occured.

doTransaction

public void doTransaction(I2CTransaction transaction)
                   throws IOException

Do an uninterrupted transaction of several messages.

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

Parameters:

transaction - Transaction that will be carried out.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

getFunctionalities

public I2CFunctionalities getFunctionalities()
                                      throws IOException

Finds out what this I2C bus can do.

Returns:

Functionalities.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

selectSlave

public void selectSlave(int address)
                 throws IOException

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

Parameters:

address - 1ddress of the needed slave.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

See Also:

selectSlave( int, boolean, boolean )

selectSlave

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

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 - 1ddress 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:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

setRetries

public void setRetries(int nRetries)
                throws IOException

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 - Number of retries.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

setTimeout

public void setTimeout(int milliseconds)
                throws IOException

Sets the timeout in milliseconds.

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

Parameters:

milliseconds - Timeout in milliseconds.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

read

public void read(I2CBuffer buffer)
          throws IOException

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

Parameters:

buffer - Buffer the answer will be written to.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

See Also:

read( I2CBuffer, int )

read

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

Directly reads length bytes from the slave device.

Parameters:

buffer - Buffer the answer will be written to.

length - Number of bytes requested.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

write

public void write(I2CBuffer buffer)
           throws IOException

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

Parameters:

buffer - Buffer to write.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.

See Also:

write( I2CBuffer, int )

write

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

Directly writes length bytes to the slave device.

Parameters:

buffer - Buffer to write.

length - Number of bytes.

Throws:

IllegalStateException - When the I2C bus has been closed.

IOException - When the bus is not a proper I2C bus or an unplanned error occured.