/ 
Device-FTDI-0.14
River stage zero No dependents
/ Device::FTDI::I2C

NAME

Device::FTDI::I2C - use an FDTI chip to talk the I²C protocol

DESCRIPTION

This subclass of Device::FTDI::MPSSE provides helpers around the basic MPSSE to fully implement the I²C protocol.

CONSTRUCTOR

new

$i2c = Device::FTDI::I2C->new( %args )

In addition to the arguments taken by "new" in Device::FTDI::MPSSE, this constructor also accepts:

clock_rate => INT

Sets the initial value of the bit clock rate; as per "set_clock_rate".

METHODS

Any of the following methods documented with a trailing ->get call return Future instances.

set_clock_rate

$i2c->set_clock_rate( $rate )->get

Sets the clock rate for data transfers, in units of bits per second.

set_check_mode

$i2c->set_check_mode( $mode )

Sets the amount of ACK checking that the module will perform. Must be one of of the following exported constants:

CHECK_NONE, CHECK_AT_END, CHECK_AFTER_ADDR, CHECK_EACH_BYTE

This controls how eagerly the module will check for incoming ACK conditions from the addressed I²C device. The more often the module checks, the better it can detect error conditions from devices, but the more USB transfers it requires and so the entire operation will take longer.

  • In CHECK_EACH_BYTE mode, the module will wait to receive an ACK condition after every single byte of transfer. This mode is the most technically-correct in terms of aborting the transfer as soon as the required ACK is not received, but consumes an entire USB transfer roundtrip for every byte transferred, and is therefore the slowest.

  • In CHECK_AFTER_ADDR mode, just the addressing command is sent and then the first ACK or NACK bit is read in. At this point the module takes the decision to abort (on NACK) or continue (on ACK). If it continues, it will send or receive all the subsequent bytes of data in one go.

  • In CHECK_AT_END mode, the entire I²C transaction is sent to the FDTI device, which will collect all the incoming ACK or NACK bits and any incoming data. Once the entire transaction has taken place, the module will check that all the required ACKs were received. This mode is the fastest and involves the fewest USB operations.

  • In CHECK_NONE mode, the module will not check any of the ACK conditions. The entire write (or write-then-read) transaction will be sent in a single USB transfer, and the bytes received will be returned to the caller.

Because it offers a useful hybrid between speed efficiency and technical correctness, CHECK_AFTER_ADDR is the default mode.

write

$i2c->write( $addr, $data_out )->get

Performs an I²C write operation to the chip at the given (7-bit) address value.

The device sends a start condition, then a command to address the chip for writing, followed by the bytes given in the data, and finally a stop condition.

read

$data_in = $i2c->read( $addr, $len_in )->get

Performs an I²C read operation to the chip at the given (7-bit) address value.

The device sends a start condition, then a command to address the chip for reading. It then attempts to read up to the given number of bytes of input from the chip, sending an ACK condition to all but the final byte, to which it sends NACK, then finally a stop condition.

write_then_read

$data_in = $i2c->write_then_read( $addr, $data_out, $len_in )->get

Performs an I²C write operation followed by a read operation within the same transaction to the chip at the given (7-bit) address value. This is roughly equivalent to performing separate calls to "write" and "read" except that the two will be combined into a single I²C transaction using a repeated start condition.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>