Contents Up Previous Next

HiPi::Device::I2C

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

See : I2C Device Driver

The settings for the I2C device can be controlled in the HiPi Control GUI. This includes the baudrate or transfer rate used on the I2C bus.

On Model B Revision 2 and Model A boards, you may use a second I2C bus by attaching a connector to the P5 Pad on the Raspberry Pi. See: Second I2C Bus.

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 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 ( as an optional backend )

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

Class Methods

HiPi::Device::I2C->load_modules( $forceunload );
    Loads the kernel device driver modules for i2c
    i2c_bcm2708
    i2c_dev

    When $forceunload is true, unloads the kernel modules
    first if they are loaded (effectively forces a reload)

    i2c_bcm2708 is loaded with the current baudrate

    Of course, the user the script is running as must have
    root permissions to load and unload kernel modules.
HiPi::Device::I2C->unload_modules();
    Unloads the kernel device driver modules for i2c
    i2c_bcm2708
    i2c_dev

    Of course, the user the script is running as must have
    root permissions to load and unload kernel modules.
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.

    Of course, 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.
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.
                   revision 1 = /dev/i2c-0
                   revision 2 = /dev/i2c-1
    
    returns a new instance of the HiPi::Device::I2C class.
    
    You can specify 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( 
        devicename => '/dev/i2c-1',
        address    => 0x28,
        busmode    => 'smbus',
    );
    
    or

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

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.

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




Contents Up Previous Next


HiPi Modules Copyright © 2013 Mark Dootson