Main Site 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

An interface is also provided for the MCP23S17 SPI version of this extender

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
 
Note that you can also export tag mcp23S17 with all the above tags renamed
e.g MCP23017_BANK == MCP23S17_BANK

The spi version of this extender provides identical methods.
 
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
    You can usefully read 2 bytes if the controller is in
    default sequential mode.
    
    # 1 byte ( 8 bits )
    bits are populated according to bit numbers as described in
    the MCP23017 / MCP23S17 documentation
    $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[3]  will contain value for pin A3
    # $bits[10] will contain value for pin B2

    # 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('IODIRA', 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
    
    You can usefully write 8 or 16 bits if the controller is in
    default sequential mode.

    @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( 'OLATB', @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( 'IODIRA' );
    $bits[5] = MCP23017_INPUT;
    $ext->write_register_bits( 'IODIRA', @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.

Configuration Methods

$ext->iocon_bank( $bitval );
    A convenience method to set and get the BANK
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.
$ext->iocon_mirror( $bitval );
    A convenience method to set and get the MIRROR
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.
$ext->iocon_seqop( $bitval );
    A convenience method to set and get the SEQOP
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.
$ext->iocon_disslw( $bitval );
    A convenience method to set and get the DISSLW
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.
$ext->iocon_haen( $bitval );
    A convenience method to set and get the HAEN
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.
$ext->iocon_odr( $bitval );
    A convenience method to set and get the ODR
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.
$ext->iocon_intpol( $bitval );
    A convenience method to set and get the INTPOL
    value from the IOCON register.
    If the optional $bitval is provided ( 0 or 1 ) the 
    IOCON register bit is set to that value.
    The method returns the value of the IOCON bit.

Pin Methods

The pin methods provide convenient access to the register values for individual pins. Pins are described by string constants. You can export the string constants and use those, or use the string values directly in your code. To export pin constants:
    use HiPi::Interface::MCP23017 qw( :mcppin );
    
    # exports pin description constants

    MCP_PIN_A0     = 'A0'
    MCP_PIN_A1     = 'A1'
    MCP_PIN_A2     = 'A2'
    MCP_PIN_A3     = 'A3'
    MCP_PIN_A4     = 'A4'
    MCP_PIN_A5     = 'A5'
    MCP_PIN_A6     = 'A6'
    MCP_PIN_A7     = 'A7'
    MCP_PIN_B1     = 'B0'
    MCP_PIN_B2     = 'B1'
    MCP_PIN_B3     = 'B2'
    MCP_PIN_B4     = 'B3'
    MCP_PIN_B5     = 'B4'
    MCP_PIN_B6     = 'B5'
    MCP_PIN_B7     = 'B6'
    MCP_PIN_B8     = 'B7'

    # then
    my $val = $mcp->pin_value( MCP_PIN_A5 );
    # or
    my $val = $mcp->pin_value( 'A5' );
$mcp->pin_value( $pinname, $bitval );
    Read the value of the pin named in $pinname from the GPIO register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the OLAT register.
    The constants MCP23017_HIGH and MCP23017_LOW ( 1 and 0 ) may be used
    for the $bitval if preferred.
$mcp->pin_mode( $pinname, $bitval );
    Read the value of the pin named in $pinname from the IODIR register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the IODIR register.
    The constants MCP23017_INPUT and MCP23017_OUTPUT ( 1 and 0 ) may be used
    for the $bitval if preferred.
$mcp->pin_pull_up( $pinname, $bitval );
    Read the value of the pin named in $pinname from the GPPU register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the GPPU register.
$mcp->pin_polarity( $pinname, $bitval );
    Read the value of the pin named in $pinname from the IPOL register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the IPOL register.
$mcp->pin_interrupt_enable( $pinname, $bitval );
    Read the value of the pin named in $pinname from the GPINTEN register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the GPINTEN register.
$mcp->pin_interrupt_default( $pinname, $bitval );
    Read the value of the pin named in $pinname from the DEFVAL register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the DEFVAL register.
$mcp->pin_interrupt_control( $pinname, $bitval );
    Read the value of the pin named in $pinname from the INTCON register.
    If the optional $bitval is provided the value will be written to the 
    appropriate bit in the INTCON register.




Contents Up Previous Next


HiPi Modules Copyright © 2013 - 2016 Mark Dootson