Contents Up Previous Next

HiPi::BCM2835::I2C

The HiPi::BCM2835::I2C module provides direct access to the Broadcom I2C Serial peripheral.

The module uses HiPi::BCM2835 and so requires administrator privileges to start. You can reduce priveleges near the very start of your program after HiPi::BCM2835 has initialised.

The module implements a common set of bus methods also implemented by HiPi::Device::I2C so you may write code that can use any of the three i2c backends available - bcm2835, smbus and i2c.

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

HiPi::Interface::HTADCI2C
HiPi::Interface::MCP23017
HiPi::Interface::MPL3115A2
HiPi::Interface::HTBackpackV2 ( as an optional backend )

You can also access your i2c peripherals through the kernel device driver. See: HiPi::Device::I2C

For Model B Rev 2 and Model A boards you can gain access to a second I2C bus on the P5 header. See: Second I2C Bus.

The main advantage of HiPi::BCM2835::I2C is that it provides support for i2c devices that require a repeated start byte to be sent when reading from the device. For example the MPL3115A2 pressure and temperature sensor. Currently, repeated starts are not supported in the kernel driver.

Class Methods

HiPi::BCM2835::I2C->get_baudrate($channel);
    Returns the current baudrate of the BSC peripheral in $channel.
    $channel can be one of BB_I2C_PERI_0 or BB_I2C_PERI_1.
    On model A and Model B Revision 2 boards BB_I2C_PERI_1 is broken
    out on Raspberry Pins 3 and 5. For Model B Revsion 1 boards, 
    BB_I2C_PERI_0 is broken out on these pins.
    
    Please not that the object method $obj->get_baudrate returns the 
    baudrate that will be used in transfers using that particular
    instance of HiPi::BCM2835::I2C. You may be able to apply different
    bus speeds to different devices using individual instance 
    settings. 
HiPi::BCM2835::I2C->set_baudrate( $channel, $baudrate );
    Sets the baudrate of the BSC peripheral in $channel.
    $channel can be one of BB_I2C_PERI_0 or BB_I2C_PERI_1.
    On model A and Model B Revision 2 boards BB_I2C_PERI_1 is broken
    out on Raspberry Pins 3 and 5. For Model B Revsion 1 boards, 
    BB_I2C_PERI_0 is broken out on these pins.

    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.

    Please not that the object method $obj->set_baudrate($newrate) sets
    the baudrate that will be used in transfers using that particular
    instance of HiPi::BCM2835::I2C. You may be able to apply different
    bus speeds to different devices using individual instance 
    settings.

Exported Constants

    use HiPi::BCM2835 qw( :i2c );

    exports:
        BB_I2C_PERI_0
        BB_I2C_PERI_1
        BB_I2C_RESULT_SUCCESS 
        BB_I2C_RESULT_NACKRCV
        BB_I2C_RESULT_CLOCKTO
        BB_I2C_RESULT_DATAERR

Object Constructor and Methods

my $dev = HiPi::BCM2835::I2C->new( address => $devaddress );
    $devaddress    address of the device ( e.g. 0x20 ) on the
    default perpheral. The default perpheral is determined according 
    to your Pi board revision.
                   revision 1 = BB_I2C_PERI_0
                   revision 2 = BB_I2C_PERI_1
    
    Returns a new instance of the HiPi::BCM2835::I2C class.
    
    You can specify which i2c channel to use in the constructor if
    you wish using the key 'peripheral'.

    my $dev = HiPi::BCM2835::I2C->new( 
        peripheral => BB_I2C_PERI_0,
        address    => 0x28 
    );

    Note that on revision 1 boards only BB_I2C_PERI_0 is available
    while on revision 2 boards only BB_I2C_PERI_1 is available unless
    you solder a connector to PAD 5. See Second I2C Bus

    For interface modules that use I2C, you may specify

        backend => 'bcm2835'

    in the constructor to use this module as a backend.
$dev->get_baudrate();
    Returns the baudrate that will be used in transfers using this 
    particular instance of HiPi::BCM2835::I2C. You may be able to apply 
    different bus speeds to different devices using individual instance 
    settings. 
$dev->set_baudrate( $baudrate );
    Sets the baudrate that will be used in transfers using this 
    particular instance of HiPi::BCM2835::I2C. You may be able to apply 
    different bus speeds to different devices using individual instance 
    settings for baudrate.

    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.

Busmode Methods

HiPi::BCM2835::I2C provides wrappers for its i2c calls. Note that HiPi::Device::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

$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.
$dev->i2c_read_register_rs( $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.
    
    This method is designed for slaves that require sending a 
    repeated start before a read can commence. It is used in place 
    of i2c_read_register for such devices. 

    HiPi::Interface::MPL3115A2 which provides access to a popular
    temperature and pressure sensor requires this method.

Timing Methods

$dev->delay( $millis );
    $millis  Delay in milliseconds

    Delays for the specified number of milliseconds. Uses nanosleep(), 
    and therefore does not use CPU until the time is up. However, you are 
    at the mercy of nanosleep(). From the manual for nanosleep(): If the 
    interval specified in req is not an exact multiple of the granularity 
    underlying clock (see time(7)), then the interval will be rounded up 
    to the next multiple. Furthermore, after the sleep completes, there 
    may still be a delay before the CPU becomes free to once again execute 
    the calling thread.
$dev->delayMicroseconds( $micros );
    $micros  Delay in microseconds

    Delays for the specified number of microseconds. Uses a combination of 
    nanosleep() and a busy wait loop on the BCM2835 system timers, However, 
    you are at the mercy of nanosleep(). From the manual for nanosleep(): 
    If the interval specified in req is not an exact multiple of the
    granularity underlying clock (see time(7)), then the interval will be 
    rounded up to the next multiple. Furthermore, after the sleep completes, 
    there may still be a delay before the CPU becomes free to once again 
    execute the calling thread. For times less than about 450 microseconds, 
    uses a busy wait on the System Timer. It is reported that a delay of 0 
    microseconds on RaspberryPi will in fact result in a delay of about 
    80 microseconds. Your mileage may vary.




Contents Up Previous Next


HiPi Modules Copyright © 2013 Mark Dootson