## HiPi::Device::I2C

The HiPi::Device::I2C module provides access to the kernel driver for the I2C bus.

See : I2C Device Driver

Loading and configuring the kernel I2C driver is controlled by configuring the device tree in your /boot/config.txt file.

See: Using the Device Tree

This module implements both I2C and SMBus protocol calls. The SMBus protocol appears to be the most widely supported on the i2c bus. It is likely that your i2c devices support it.

The following interface modules can use HiPi::Device::I2C as a backend and may contain code that helps with your own usage.

HiPi::Interface::HTADCI2C
HiPi::Interface::MCP23017
HiPi::Interface::HTBackpackV2
HiPi::Interface::MPL3115A2

You can also access your i2c peripherals through the BCM SOC directly. See: HiPi::BCM2835::I2C

## Class Methods

##### HiPi::Device::I2C->get_baudrate();

        Returns the current baudrate of a loaded i2c_bcm2708
        module. If the module is not loaded or the process
        does not have root permissions, returns the current
        default module setting for baudrate.

##### HiPi::Device::I2C->set_baudrate( $baudrate );

        Sets the baudrate of the i2c_bcm2708 module. Must
        unload and load the kernel module to do this.

        The user the script is running as must have
        root permissions to load and unload kernel modules.

        Common values for baudrate are:

           3816  - the minimum supported
         100000  - the i2c standard
         400000  - fast i2c standard
        1000000  - seems to be the fastest reliable speed that this
    	       implementation supports. Of course, all the
    	       devices on your bus must support this too.
          32000  - the Broadcom I2C peripherals don't support
    	       clock stretching so if you have a device that
    	       employs this, a baudrate of 32000 ( or perhaps
    	       even lower ) will often allow the device to work.

        This method will fail if the i2c device is in use.

##### HiPi::Device::I2C->get_device_list();

        Returns an array containing the names of available
        devices.
        Will normally return ('/dev/i2c-1', '/dev/i2c-0')

## Object Constructor and Methods

##### my $dev = HiPi::Device::I2C->new( address => $devaddress );

        $devaddress    address of the device ( e.g. 0x20 ) on the
                       default bus. The default bus is determined
                       according to your Pi board revision.
                       Model B revision 1            = /dev/i2c-0
                       all other Raspberry Pi boards = /dev/i2c-1

        returns a new instance of the HiPi::Device::I2C class.

        You can override which i2c device to use in the constructor if
        you wish using the key 'devicename'.

        my $dev = HiPi::Device::I2C->new(
            devicename => '/dev/i2c-1',
            address    => 0x28
        );

        You may also specify which backend calls to use with the generic
        busmode methods.

        my $dev = HiPi::Device::I2C->new(
            address    => 0x28,
            busmode    => 'smbus',
        );

        or

        my $dev = HiPi::Device::I2C->new(
            address    => 0x28,
            busmode    => 'i2c',
        );

        HiPi::Device::I2C supports 3 different read modes:

        use HiPi::Constant qw( :i2c_readmode );

        # default
        my $dev = HiPi::Device::I2C->new(
            address    => 0x28,
            busmode    => 'smbus',
            readmode   => I2C_READMODE_SYSTEM,
        );

        The default and 2 other options:

           I2C_READMODE_START_STOP
           I2C_READMODE_REPEATED_START

        are discussed in I2C Repeated Start and Clock Stretching

### Busmode Methods

HiPi::Device::I2C provides both i2c and SMBus style methods. So that you can write backend independent code, these methods are wrappers for the i2c or smbus calls, depending on your chosen backend. Note that HiPi::BCM2835::I2C also supports these methods so you may write code that works with backends i2c, smbus and bcm2835.

The bus methods implement support for the readmode settings ( I2C_READMODE_SYSTEM, I2C_READMODE_START_STOP, I2C_READMODE_REPEATED_START ). Specifically the method `bus_read` has its behaviour altered by the readmode constants.
See : I2C Repeated Start

##### $dev->bus_write( @params );

        The module provides the method bus_write as
        a generic call to the current backend.

        @params is a list of bytes to write to the currently
        addressed device.

##### $dev->bus_write_error( @params );

        The module provides the method bus_write_error as
        a generic call to the current backend.

        @params is a list of bytes to write to the currently
        addressed device.

        The bus_write_error method is error tolerant and is
        generally used when an external device has a soft reset
        or reboot call that exits the i2c conversation when 'reset'
        is set. The standard i2c_write command will return an
        error in this case as the slave did not acknowledge the
        reset byte.

##### $dev->bus_read( $cmdval, $numbytes );

        The module provides the method bus_read as
        a generic call to the current backend.

        $cmdval is the value ( normally a register address
        on the slave) that you wish to read from.

        $numbytes is the number of bytes you wish to read.

        Returns an array of bytes $numbytes long.

##### $dev->bus_read_bits( $cmdval, $numbytes );

        The module provides the method bus_read_bits as
        a generic call to the current backend.

        Returns an array of bits 8 * $numbytes long from the
        register in $cmdval.

        If a single byte is read that has the value 0b01001100
        then the bits in the array will have the values:

        $return[7] == 0
        $return[6] == 1
        $return[5] == 0
        $return[4] == 0
        $return[3] == 1
        $return[2] == 1
        $return[1] == 0
        $return[0] == 0

        Usage:

        my @bits = $dev->bus_read_bits(0xC1, 1);
        $bits[3] = 1;
        dev->bus_write_bits(0xC1, @bits);

##### $dev->bus_write_bits( $cmdval, @bits );

        The module provides the method bus_write_bits as
        a generic call to the current backend.

        Writes a number of bytes equal to @bits / 8 to the
        register in $cmdval.

        For the array of 8 bits:

        my @bits = ( 1,1,1,0,0,0,0,1 )

        the value 0b10000111 will be written to $cmdval.

        Usage:

        my @bits = $dev->bus_read_bits(0xC1, 1);
        $bits[3] = 1;
        dev->bus_write_bits(0xC1, @bits);

### I2C Methods

These methods wrap ioctl calls that use the i2c_rdwr_ioctl_data and i2c_msg structs. This allows for multiple write and read operations in the same transaction.

##### $dev->i2c_write( @params );

        @params is a list of bytes to write to the slave device.
        Normally, the first (and perhaps only) item in the list will
        be a register address on the slave.

        Use of the busmode wrapper methods is recommended.

##### $dev->i2c_write_error( @params );

        @params is a list of bytes to write to the slave device.
        Normally, the first (and perhaps only) item in the list will
        be a register address on the slave.

        The i2c_write_error method is error tolerant and is generally
        used when an external device has a soft reset or reboot call
        that exits the i2c conversation when 'reset' is set.
        The standard i2c_write command will return an error in this case
        as the slave did not acknowledge the reset byte.

##### $dev->i2c_read( $numbytes );

        Reads a number of bytes $numbytes read from the current
        register address in the slave (normally set using a previous
        write).

        Returns an array of bytes containing $numbytes items.

        Use of the busmode wrapper methods is recommended.

##### $dev->i2c_read_register( $register, $numbytes );

        Reads a number of bytes $numbytes read from the register
        address in $register.

        Combines the write of the register address with the subsequent
        read in a single transaction.

        Returns an array of bytes containing $numbytes items.

        Use of the busmode wrapper methods is recommended.

### SMBus Methods

##### $dev->smbus_write( @params );

        The module provides the method smbus_write as
        a generic call to the main smbus methods. I have
        found it is all I need for all i2c devices
        tested so far.

        If @params is a single value, the method calls

        $dev->smbus_write_byte($params[0]);

        If @params contains two values, the method calls

        $dev->smbus_write_byte_data( @params );

        With three or more values in @params, the method does

        my $command = shift @params;
        $dev->smbus_write_i2c_block_data($command, @bytes );

##### $dev->smbus_write_error( @params );

        The smbus_write_error method is an error tolerant version of
        smbus_write. It can be used when an external device has a soft
        reset or reboot call that exits the i2c conversation when 'reset'
        is set. The standard smbus_write command will return an error in
        this case as the slave did not acknowledge the reset byte.

##### $dev->smbus_read( $cmdval, $numbytes );

        The module provides the method smbus_read as
        a generic call to the main smbus methods. I have
        found it is all I need for all i2c devices
        tested so far.

        If $cmdval is not defined, the method returns a
        scalar value from

        $dev->smbus_read_byte;

        If $cmdval is defined but $numbytes is undefined
        or zero, then the method returns a scalar value
        from

        $dev->smbus_read_byte_data( $cmdval );

        If $cmdval is defined and $numbytes is greater
        than zero then the method returns an array of
        values from

        $dev->smbus_read_i2c_block_data( $cmdval, $numbytes );

##### $dev->smbus_write_quick($value);

        writes $value to the device

##### $dev->smbus_read_byte();

        returns the first byte read from the device

##### $dev->smbus_write_byte($value);

        writes byte $value to the device

##### $dev->smbus_read_byte_data( $command );

        returns byte from the device specifying
        register address in $command;

##### $dev->smbus_write_byte_data( $command, $value );

        writes byte $value to the register address specified
        in $command

##### $dev->smbus_read_word_data($command);

        reads a word beginning at the device register
        specified in $command;

##### $dev->smbus_write_word_data($command, $word);

        writes a word to the device register
        specified in $command;

##### $dev->smbus_read_word_swapped($command);

        reads a word beginning at the device register
        specified in $command and swaps the high /low
        bytes in the return value

##### $dev->smbus_write_word_swapped($command, $word);

        writes a word to the device register
        specified in $command after swapping the
        high / low bytes in $word

##### $dev->smbus_read_block_data( $command );

        Returns an array of values read starting at register
        specified in $command.
        In all devices tested so far I have found it necessary
        to use $dev->smbus_read_i2c_block_data; instead.

##### $dev->smbus_read_i2c_block_data( $command, $numbytes );

        returns an array of bytes $numbytes in size reading from
        register specified in $command;

##### $dev->smbus_write_block_data( $command, $arrayref );

        Writes all the bytes from array reference $arrayref to
        device specifying the register in $command.
        In all devices tested so far I have found it necessary
        to use $dev->smbus_write_i2c_block_data instead.

##### $dev->smbus_write_i2c_block_data( $command, $arrayref );

        Writes all the bytes from array reference $arrayref to
        device specifying the register in $command.

HiPi Modules Copyright © 2013 - 2016 Mark Dootson