NAME

    RPi::I2C - Interface to the I2C bus

SYNOPSIS

        use RPi::I2C;
    
        my $device_addr = 0x04;
    
        my $device = RPi::I2C->new($device_addr);
    
        # read a single byte at the default register address
    
        print $device->read;
    
        # read a single byte at a specified register
    
        print $device->read_byte(0x15);
    
        # read a block of five bytes (register param optional, not shown)
    
        my @bytes = $device->read_block(5);
    
        # write a byte
    
        $device->write(255);
    
        # write a byte to a register location
    
        $device->write_byte(255, 0x0A);
    
        # write a block of bytes (register param left out again)
    
        $device->write_block([1, 2, 3, 4]);

    See the examples direcory for more information on usage with an Arduino
    unit.

DESCRIPTION

    Interface to read and write to I2C bus devices.

YOU SHOULD KNOW

    There are particular things to know depending on connecting to certain
    devices.

 General

    You need to have some core software installed before using the I2C bus.
    The Raspberry Pi 3 already has everything pre-loaded. On a typical Unix
    computer, you'd do something along these lines:

        sudo apt-get install libi2c-dev i2c-tools build-essential

    To test your I2C bus:

        i2cdetect -y 1

    ...or on some machines:

        i2cdetect -y 0

 Raspberry Pi

    First thing you need to do is enable the I2C bus. You can do so in
    raspi-config, or ensure the ram=i2c_arm directive is set to on in the
    /boot/config.txt file:

        ram=i2c_arm=on

 Arduino

    Often, the default speed of the I2C bus master is too fast for an
    Arduino. If you do not get any results, try changing the spped. On a
    Raspberry Pi, you do that by setting the dtparam=i2c_arm_baudrate
    directive in the /boot/config.txt file:

        dtparam=i2c_arm_baudrate=10000

METHODS

 new($addr, [$device])

    Instantiates a new I2C device object ready to be read from and written
    to.

    Parameters:

        $addr

    Mandatory, Integer (in hex): The address of the device on the I2C bus
    (i2cdetect -y 1). eg: 0x78.

        $device

    Optional, String: The name of the I2C device file. Defaults to
    /dev/i2c-1.

 read

    Performs a simple read of a single byte from the device, and returns
    it.

 read_byte([$reg])

    Same as "read", but allows you to optionally specify a specific device
    register to read from.

    Parameters:

        $reg

    Optional, Integer: The device's register to read from. eg: 0x01.
    Defaults to 0x0.

 read_bytes($num_bytes, [$reg])

    Allows you to read a specific number of bytes from a register and get
    the bytes returned as an array.

    Parameters:

        $num_bytes

    Mandatory, Integer: The number of bytes you want to read. These are
    contiguous starting from the $reg (if supplied, otherwise 0x00).

        $reg

    Optional, Integer: The device's register to read from. eg: 0x01.
    Defaults to 0x0.

    Return, Array: An array where each element is a byte of data. The
    length of this array is dictated by the $num_bytes parameter.

 read_word([$reg])

    Same as read_byte(), but reads two bytes (16-bit word) instead.

 read_block($num_bytes, [$reg])

    Reads a block of data and returns it as an array.

    Parameters:

        $num_bytes

    Mandatory, Integer: The number of bytes you want to read.

        $reg

    Optional, Integer: The register to start reading the block of bytes
    from. It defaults to 0x00 if you don't send it in.

    Returns an array containing each byte read per element.

 write($data)

    Performs a simple write of a single byte to the I2C device.

    Parameters:

        $data

    Mandatory, 8-bit unsigned integer: The byte to send to the device.

 write_byte($data, [$reg])

    Same as write(), but allows you to optionally specify a specific device
    register to write to.

    Parameters:

        $data

    Mandatory, 8-bit unsigned integer: The byte to send to the device.

        $reg

    Optional, Integer: The device's register to write to. eg: 0x01.
    Defaults to 0x0.

 write_word($data, [$reg])

    Same as write_byte(), but writes two bytes (16-bit word) instead.

 write_block($values, [$reg])

    Writes a block of up to 32 contiguous bytes to the device. Each byte is
    put into an element of an array, and a reference to that array is sent
    in.

    Parameters:

        $values

    Mandatory, Array Reference: Up to 32 elements, where each element is a
    single byte to be written to the device.

        $reg

    Optional, Integer: The register to start writing the block of bytes to.
    It is prudent to be sure you have enough contiguous byte blocks
    available, or things can be overwritten. Defaults to 0x00 if you don't
    send it in.

 process($value, [$reg])

    This method starts at the register address, writes 16 bits of data to
    it, then reads 16 bits of data and returns it.

    Parameters:

        $value

    Mandatory, 16-bit Word: The value (16 bits) that you want to write to
    the device.

        $reg

    Optional, Integer: The device's register to write to. eg: 0x01.
    Defaults to 0x0.

 file_error

    Returns any stored IO::Handle errors since the last clearerr().

 check_device($addr)

    Check to see if a device is available.

    Parameters:

        $addr

    Mandatory, Integer: The I2C address of a device you suspect is
    connected. eg: 0x7c.

    Return, Bool: True (1) if the device responds, False (0) if not.

UNIT TESTS

    This distribution has a bare minimum of unit tests. This is because the
    larger encompassing distribution, RPi::WiringPi has an automated
    Continuous Integration suite (including a dedicated hardware platform)
    for testing all of the RPi:: distributions automatically.

    The tests specific to this distribution use I2C communication between a
    Pi and an Arduino board. The files in the examples directory are the
    foundation of the tests that are now run, and both the examples and the
    real tests use the arduino.ino sketch in the examples directory as the
    Arduino code.

ACKNOWLEDGEMENTS

    All of the XS code was copied directly from Device::I2C, written by
    Slava Volkov (SVOLKOV). The module itself was brought over as well, but
    changed quite a bit. Thanks Slava for a great piece of work!

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

    Copyright (C) 2017 by Steve Bertrand

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.18.2 or, at
    your option, any later version of Perl 5 you may have available.