HiPi::Device::I2C

The HiPi::Device::I2C module provides access to the kernel driver for the I2C bus. With it you can control and query ics attached to the bus.

Several of the HiPi Interface Modules are wrappers around HiPi::Device::I2C. You can use HiPi::Device::I2C directly to interface with other I2C peripherals.

Methods

• new
• select_address
• bus_write
• bus_read
• delay
• delayMicroseconds
• scan_bus
• check_address
• get_baudrate
• get_driver
• get_device_list
• i2c_write
• i2c_read_register
• i2c_read
• smbus_write
• smbus_read
• smbus_write_quick
• smbus_read_byte
• smbus_write_byte
• smbus_read_byte_data
• smbus_write_byte_data
• smbus_read_word_data
• smbus_write_word_data
• smbus_read_word_swapped
• smbus_process_call
• smbus_read_block_data
• smbus_read_i2c_block_data
• smbus_write_block_data
• smbus_write_i2c_block_data

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

use HiPi qw( :i2c );
use HiPi::Device::I2C;
my $dev = HiPi::Device::I2C->new;

Possible params and their defaults are:

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

address

This is the address of the device you want to control. It isn't mandatory as some of the module methods do not target a specific address. If you do specify an address then there must be a device at that address or the method call will fail. If you do not provide an address in the constructor, you must use the method 'select_address' to set the address before you can access the specific device.

# fails if no device at 0x20
my $dev = HiPi::Device::I2C->new( address => 0x20 );

# check if address is on 'devicename' ( /dev/i2c-1, etc ) first;

my $dev = HiPi::Device::I2C->new();
if( $dev->scan_bus( 0x20 ) ) {
    $dev->check_address( 0x20 );
} else {
    # handle missing device
}

devicename

/dev/i2c-1 is the standard i2c device connected to the I2C_SDA and I2C_SCL pins on the GPIO header for nearly all Raspberry Pi versions. On some very early boards, /dev/i2c-0 was connected and if HiPi detects you are using one of these boards, it will set the default value for devicename accordingly.

If you use the gpio bit banging driver then you can pass /dev/i2c-3 as the devicename.

busmode

The HiPi::Device::I2C wraps both SMBus and I2C protocol functions. The methods 'bus_read' and 'bus_write' will use whichever backend method is indicated by the 'busmode' - either SMBus or I2C. Most devices work well with the 'smbus' busmode but many will work with either.

Set the address of the device you ant to control.

$dev->select_address( 0x41 );

Write data to the address specified in the constructor or by 'select_address'.

# device needs register or command to write to first.
            
$dev->bus_write( $register, @databytes );

# device doesn't want register or command, only data:

$dev->bus_write( @databytes );

Read data from the address specified in the constructor or by 'select_address'. Returns an array of bytes from the device.

# device needs register or command to read first

my @data = $dev->bus_read( $register, $num_bytes_to_read );

# device does not want $register ( some devices just return their whole register )
# you must pass undef for the first param.

@data = $dev->bus_read( undef, $num_bytes_to_read );

Note : For devices that do not want a register specified, the SMBus wrapper can only return a single byte. If your device returns more than a single byte, specify

 busmode => 'i2c' 

in the constructor.

Wait for the specified number of milliseconds.

$dev->delay( 50 );

Wait for the specified number of microseconds.

$dev->delayMicroseconds( 20000 );

Return an array of the addresses of all the devices detected on the i2c bus.

my @attached = $dev->scan_bus;

Check if the provided address is on the bus. Returns 1 ( true ) or 0 ( false )

my $present = $dev->check_address( 0x42 );

Gets the 'baudrate' ( speed ) of the current bus as set in /boot/config.txt ( default 100000 )

my $speed = $dev->get_baudrate();

Gets the name of the i2c driver being used. Returns either 'i2c_bcm2835' or if you have forced the old driver to be loaded, will return 'i2c_bcm2708'.

my $driver = $dev->get_driver;

Returns an array of all the devices available ( e.g. '/dev/i2c-1' ). Can be called as a class method.

my @devs = HiPi::Device::GPIO->get_device_list;

i2c method to write @data bytes. Using $dev->bus_write is the preferred method.

$dev->i2c_write( $register, @bytes );
$dev->i2c_write( @bytes );

Read a register providing the register and number of bytes to retrieve. Returns an array of bytes.

Using 'bus_read' is the preferred method.

my @bytes = $dev->i2c_read_register($register, $numbytes)

Read a number of bytes without sending register first. Returns an array of bytes.

Using 'bus_read' is the preferred method.

my @bytes = $dev->i2c_read($register, $numbytes);

Calls the required SMBus method depending on the number of bytes written.

• If number of bytes is 1, calls smbus_write_byte.
• If number of bytes is 2, calls smbus_write_byte_data.
• If number of bytes is 3 or greater, calls smbus_write_i2c_block_data.

$dev->bus_write is the preferred method of writing to the bus.

Calls the required SMBus method depending on parameters.

• If $register is undefined, calls smbus_read_byte which can only return a single byte.
• If $numbytes is 1, calls smbus_read_byte_data.
• If $numbytes is greater than 1, calls smbus_read_i2c_block_data.

Returns an array of bytes.

$dev->bus_read is the preferred method of reading from the bus.

my @bytes = $dev->smbus_read( $register, $num_bytes_to_read );
@bytes = $dev->smbus_read( undef, $num_bytes_to_read );

A wrapper for the SMBus method i2c_smbus_write_quick.

$dev->smbus_write_quick( $byte );

A wrapper for the SMBus method i2c_smbus_read_byte Returns an array containing a single byte.

my @byte = $dev->smbus_read_byte;

A wrapper for the SMBus method i2c_smbus_write_byte

$dev->smbus_write_byte( $byte );

A wrapper for the SMBus method i2c_smbus_read_byte_data. Returns an array of bytes.

my @bytes = $dev->smbus_read_byte_data( $register );

A wrapper for the SMBus method i2c_smbus_write_byte_data

$dev->smbus_write_byte_data( $register, $byte )

A wrapper for the SMBus method i2c_smbus_read_word_data. Returns an array containing a single 'word' value.

my @data = $dev->smbus_read_word_data( $register );

A wrapper for the SMBus method i2c_smbus_write_word_data.

$dev->smbus_write_word_data( $register, $word );

A wrapper for the SMBus method i2c_smbus_read_word_swapped. Returns an array containing a single 'word' value.

my @data = $dev->smbus_read_word_swapped( $register );

A wrapper for the SMBus method i2c_smbus_write_word_swapped.

$dev->smbus_write_word_swapped( $register, $word )

A wrapper for the SMBus method i2c_smbus_process_call

my $result = $dev->smbus_process_call( $register, $data );

A wrapper for the SMBus method i2c_smbus_read_block_data. Returns an array of up to 32 bytes.

my @data = $dev->smbus_read_block_data( $register );

A wrapper for the SMBus method i2c_smbus_read_i2c_block_data. Returns an array of bytes requested.

my @data = $dev->smbus_read_i2c_block_data( $register, $numbytes );

A wrapper for the SMBus method i2c_smbus_write_block_data wrting up to 32 bytes

$dev->smbus_write_block_data( $register, \@bytes )

A wrapper for the SMBus method i2c_smbus_write_i2c_block_data writing any number of bytes

$dev->smbus_write_i2c_block_data( $register, \@bytes )