## 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.

HiPi Modules Copyright © 2013 - 2016 Mark Dootson