The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
RPi-GPIOExpander-MCP23017-1.02
River stage one • 1 direct dependent • 2 total dependents
/ RPi::GPIOExpander::MCP23017

NAME

RPi::GPIOExpander::MCP23017 - Interface to the MCP23017 GPIO Expander Integrated Circuit over I2C

DESCRIPTION

This distribution allows you to interface with an MCP23017 (i2c based communication) GPIO expander chip. It provides 16 GPIO digital pins.

There are two "banks" of pins, bank 0 (A) and bank 1 (B). Each bank contains eight pins.

Pins can be accessed/modified individually, by bank, or all at once.

In this initial distribution, not all of the chip's functionality is included, but the core functionality is. In upcoming releases, we'll add the remaining functionality, particularly interrupts.

SYNOPSIS

    use RPi::GPIOExpander::MCP23017;

    my $mcp23017_i2c_addr = 0x20;

    my $exp = RPi::GPIOExpander::MCP23017->new($mcp23017_i2c_addr);

    # pins are INPUT by default. Turn the first pin to OUTPUT

    $exp->mode(0, 0); # or MCP23017_OUTPUT if using RPi::Const

    # turn the pin on (HIGH)

    $exp->write(0, 1); # or HIGH

    # read the pin's status (HIGH or LOW)

    $exp->read(6);

    # turn the first bank (0) of pins (0-7) to OUTPUT, and make them live (HIGH)

    $exp->mode_bank(0, 0);  # bank A, OUTPUT
    $exp->write_bank(0, 1); # bank A, HIGH

    # enable internal pullup resistors on the entire bank A (0)

    $exp->pullup_bank(0, 1); # bank A, pullup enabled

    # put all 16 pins as OUTPUT, and put them on (HIGH)

    $exp->mode_all(0);  # or OUTPUT
    $exp->write_all(1); # or HIGH

    # cleanup all pins and reset them to default before exiting your program

    $exp->cleanup;

OPERATIONAL METHODS

new($addr)

Instantiates and returns a new RPi::GPIOExpander::MCP23017 object.

Parameters:

    $addr

Optional, Integer: The I2C address of the device. Defaults to 0x20.

cleanup

Resets the device registers back to their original startup configuration.

PIN METHODS

The pins on the expander are arranged in two banks. Bank A (ie. 0 in code) are pins 0 through 7. Bank B (ie. 1 in code) contains pins 8 through 15.

The first argument to these individual pin methods is the pin number (0-15), the second is the argument to instruct what you want the pin to do.

read($pin)

Fetches the current state of the pin, on or off (HIGH or LOW).

Parameters:

    $pin

Mandatory, Integer: The pin number, 0-15.

Return: Bool. 1 for on (HIGH), 0 for off (LOW).

mode($pin, [$mode])

Allows toggling of a pin between input and output mode.

Parameters:

    $pin

Mandatory, Integer: The pin number, 0-15.

    $mode

Optional, Bool: 0 for output, 1 for input. If using RPi::Const, these equate to MCP23017_OUTPUT and MCP23017_INPUT. Default startup of the IC is input.

Return: Bool. 1 for input (MCP23017_INPUT), 0 for output (MCP23017_OUTPUT).

write($pin, $state)

Turns an output pin on (HIGH) or off (LOW). Will only have effect if the pin is in output mode.

Parameters:

    $pin

Mandatory, Integer: The pin number, 0-15.

    $state

Mandatory, Bool: 0 for off (LOW), 1 for on (HIGH).

Return: None (void function).

pullup($pin, [$state])

The MCP23017 only has pull-up resistors (ie. there's no pull-downs). This method allows you to toggle the state of the pullup resistor.

Parameters:

    $pin

Mandatory, Integer: The pin number, 0-15.

    $state

Optional, Bool: 0 for off (LOW), 1 for on (HIGH).

Return: Bool. 1 if the pullup is enabled, and 0 if not.

BANK METHODS

The following methods deal with pin "banks". There are two banks of pins on the device, bank A (represented as 0 here), and bank B (represented as 1)

These methods will act on an entire bank of pins. Bank 0 (A) consists of pins 0-7 whereas bank 1 (B) encompasses pins 8-15.

mode_bank($bank, [$mode])

This method will set the mode for the eight pins associated with the specified bank in one fell swoop.

Parameters:

    $bank

Mandatory, Integer: 0 for bank A (pins 0-7) or 1 for bank B (pins 8-15).

    $mode

Optional, Integer: 0 (or MCP23017_OUTPUT) for output mode, or 1 (or MCP23017_INPUT for input mode. The default mode on device startup is input for all pins.

Return: Ingeter. A byte containing the state of the entire bank's mode register.

write_bank($bank, $state)

This method will write the operational state (on/off aka high/low) for an entire bank of pins. Has no effect for pins that are currently in INPUT mode.

Parameters:

    $bank

Mandatory, Integer: 0 for bank A (pins 0-7) or 1 for bank B (pins 8-15).

    $state

Mandatory, Bool: 0 (or LOW) for off, or 1 (or HIGH) for on.

pullup_bank($bank, [$state])

Allows you to enable or disable the built-in pull-up resistors for an entire bank of pins all at the same time.

Parameters:

    $bank

Mandatory, Integer: 0 for bank A (pins 0-7) or 1 for bank B (pins 8-15).

    $state

Mandatory, Bool: 0 (or LOW) to disable the pullups, or 1 (or HIGH) to enable them.

Return: Ingeter. A byte containing the state of the entire bank's pullup register.

ALL PIN METHODS

The following methods allows you to act on all pins across both banks in one fell swoop.

mode_all($mode)

This method allows you to set the mode (input or output) on all 16 pins at the same time.

Parameters:

    $mode

Mandatory, Integer: 0 (or MCP23017_OUTPUT) for output mode, or 1 (or MCP23017_INPUT for input mode. The default mode on device startup is input for all pins.

write_all($state)

This method will write the operational state (on/off aka high/low) for all 16 pins at the same time. Has no effect for pins that are currently in INPUT mode.

Parameters:

    $state

Mandatory, Bool: 0 (or LOW) for off, or 1 (or HIGH) for on.

pullup_all($state)

Allows you to enable or disable the built-in pull-up resistors for all 16 pins at the same time.

Parameters:

    $state

Mandatory, Bool: 0 (or LOW) to disable the pullups, or 1 (or HIGH) to enable them.

REGISTER ACCESS METHODS

These methods provide you direct access to the device registers themselves. They are here for convenience only, and really shouldn't be used unless you are familiar with the registers and how they operate.

register($register, [$data]);

Gets and or sets the specified register.

Parameters:

    $register

Mandatory, Integer: The register to read and or write.

    $data

Optional, Integer: A single byte to enable/disable bits in the specified register.

Return: Integer, the value of the register specified.

register_bit($register, $bit)

Allows you to read a single bit from within the specified register.

Parameters:

    $register

Mandatory, Integer: The register to read the bit from.

    $bit

Mandatory, Integer: The bit to read from the given register. Valid values are 0 through 7.

Return: Bool, 0 if the bit is not set, and 1 if it is.

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2018,2019 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0