Contents Up Previous Next

HiPi::Interface::MCP23017

This module provides an interface to the popular MCP23017 GPIO extender with i2c interface.

It uses HiPi::Device::I2C as a backend

Object Constructor and Methods

The module exports the following constants using tag mcp23017

    use HiPi::Interface::MCP23017 qw( :mcp23017 );
    
    # exports constants

    # for bit positions in the IOCON register byte
    MCP23017_BANK
    MCP23017_MIRROR
    MCP23017_SEQOP
    MCP23017_DISSLW
    MCP23017_HAEN
    MCP23017_ODR
    MCP23017_INTPOL
    
    # for defining pin direction in the IODIRA/IODIRB registers
    MCP23017_INPUT
    MCP23017_OUTPUT

    # if you like constants for pin levels
    MCP23017_HIGH
    MCP23017_LOW
 
 
my $ext = HiPi::Interface::MCP23017->new( %params );
    Returns a new instance of the HiPi::Interface::MCP23017 class.

    Optional key => values pairs in %params and their defaults

    devicename  => ( RPi board revision == 1 ) 
                    ? '/dev/i2c-0' : '/dev/i2c-1',
    
    address     => 0x20,

    Example overriding defaults
    
    my $ext = HiPi::Interface::MCP23017->new(
        devicename => '/dev/i2c-0',
        address    => 0x28,
    );
my @bits = $ext->read_register_bits( $register, $numbytes );
    Read an array of bit values ( 0 or 1 ) from the specified register.
    
    $numbytes is the number of bytes to read - defaults to 1
    
    # 1 byte ( 8 bits )
    $bits[0] is populated from register bit 0 from the first byte
    $bits[7] is populated from register bit 7 from the first byte
    # 2 bytes ( 16 bits )
    $bits[8] is populated from register bit 0 from the second byte

    $register is a string containing the register name.
    Valid values are:

    'IODIRA', 'IPOLA', 'GPINTENA', 'DEFVALA', 'INTCONA',
    'IOCON',  'GPPUA', 'INTFA',    'INTCAPA', 'GPIOA',
    'OLATA',  'IODIRB','IPOLB',    'GPINTENB','DEFVALB', 
    'INTCONB','GPPUB', 'INTFB',    'INTCAPB', 'GPIOB',
    'OLATB'
    
    Examples:
    
    # get the value ( 1 or 0 ) for pin A0
    
    my @bits = $ext->read_register_bits('GPIOA');
    my $a0value = $bits[0];

    # get the value ( 1 or 0 ) for pin B6

    my @bits = $ext->read_register_bits('GPIOB');
    my $b6value = $bits[6];

    # get the values for all 16 pins when registers
    # are sequential
    # i.e. ($ext->read_register_bits('IOCON'))[MCP23017_BANK] == 0;

    my @bits = $ext->read_register_bits('GPIOA', 2);
    
    # $bits[1] will contain value for pin A0
    # $bits[9] will contain value for pin B1

    # note that you can return all the values from
    # the entire MCP23017 register assuming
    # default sequential read mode with

    my @bits = $ext->read_register_bits('GPIOA', 22 );

    # which values are in which bits will depend
    # on the current IOCON.BANK value
    # i.e. ($ext->read_register_bits('IOCON'))[MCP23017_BANK]
    # consult the MCP23017 data sheet
$ext->write_register_bits( $register, @bits );
    Write an array of bit values ( 0 or 1 ) to the specified register.
    $bits[0] is written to register bit 0
    $bits[7] is written to register bit 7

    @bits can contain between 1 x 8 and 22 x 8 values
    but writing the correct values for 22 * 8 bits 
    at once seems an unlikely thing to want to do.
    
    $register is a string containing the register name.
    Valid values are:

    'IODIRA', 'IPOLA', 'GPINTENA', 'DEFVALA', 'INTCONA',
    'IOCON',  'GPPUA', 'INTFA',    'INTCAPA', 'GPIOA',
    'OLATA',  'IODIRB','IPOLB',    'GPINTENB','DEFVALB', 
    'INTCONB','GPPUB', 'INTFB',    'INTCAPB', 'GPIOB',
    'OLATB'

    Examples :

    # starting in default power on mode, set pin B3 as an
    # output and set its value high.
    # note that when writing single values, each operation
    # is essentially a read / write
    
    # first set B3 as output
    my @bits = $ext->read_register_bits( 'IODIRB' );
 
    $bits[3] = 0; # the module provides the exported
                  # constants MCP23017_OUTPUT and MCP23017_INPUT
                  # which are very useful if you find using
                  # 0 to define an output pin and 1 to
                  # define an input pin confusing

    $ext->write_register_bits( 'IODIRB', @bits );

    # then set its value high
    @bits = $ext->read_register_bits( 'GPIOB' );
    $bits[3] = MCP23017_HIGH;
    $ext->write_register_bits( 'GPIOB', @bits );

    
    # switch mode to IOCON.BANK=1 - segregated registers
    my @bits = $ext->read_register_bits( 'IOCON' );
    $bits[MCP23017_BANK] = 1;
    $ext->write_register_bits( 'IOCON', @bits );

    # ensure A5 is an input and apply pull up resistor
    my @bits = $ext->read_register_bits( 'GPIOA' );
    $bits[5] = MCP23017_INPUT;
    $ext->write_register_bits( 'GPIOA', @bits );
    @bits = $ext->read_register_bits( 'GPPUA' );
    $bits[5] = 1;
    $ext->write_register_bits( 'GPPUA', @bits );
my @bytes = $ext->read_register_bytes( $register, $numbytes );
    Read an array of bytes starting at the specified register.
    $numbytes is the number of bytes to read - defaults to 1

    $register is a string containing the register name.
    Valid values are:

    'IODIRA', 'IPOLA', 'GPINTENA', 'DEFVALA', 'INTCONA',
    'IOCON',  'GPPUA', 'INTFA',    'INTCAPA', 'GPIOA',
    'OLATA',  'IODIRB','IPOLB',    'GPINTENB','DEFVALB', 
    'INTCONB','GPPUB', 'INTFB',    'INTCAPB', 'GPIOB',
    'OLATB'
    
    It is often more convenient to use read_register_bits
    which calls read_register_bytes internally and separates
    the returned values into ordered bit values.
    Calling read_register_bytes may be quicker if your
    handling of the return values is more efficient than
    read_register_bits.
$ext->write_register_bytes( $register, @bytes );
    Write an array of  1 or more bytes starting at the 
    specified register.
    
    $register is a string containing the register name.
    Valid values are:

    'IODIRA', 'IPOLA', 'GPINTENA', 'DEFVALA', 'INTCONA',
    'IOCON',  'GPPUA', 'INTFA',    'INTCAPA', 'GPIOA',
    'OLATA',  'IODIRB','IPOLB',    'GPINTENB','DEFVALB', 
    'INTCONB','GPPUB', 'INTFB',    'INTCAPB', 'GPIOB',
    'OLATB'

    It is often more convenient to use write_register_bits
    which calls write_register_bytes internally.
    Calling write_register_bytes may be quicker if your
    creating of the byte values is more efficient than
    write_register_bits.




Contents Up Previous Next


HiPi Modules Copyright © 2013 Mark Dootson