RobTillaart / MCP23S17

Arduino library for SPI based MCP23S17 16 channel port expander
MIT License
27 stars 11 forks source link
arduino input-output spi

Arduino CI Arduino-lint JSON check GitHub issues

License: MIT GitHub release PlatformIO Registry

MCP23S17

Arduino library for MCP23S17 16 channel SPI port expander.

Description

This library gives easy control over the 16 pins of a (SPI) MCP23S17 chip.

This IC is strongly related to the MCP23017 I2C port expander - https://github.com/RobTillaart/MCP23017_RT Programming Interface is kept the same as much as possible.

The write1(pin, value) is optimized. If a pin is not changed it will not be written again to save time.

0.5.0 Breaking change

Version 0.5.0 introduced a breaking change to improve handling the SPI dependency. The user has to call SPI.begin() or equivalent before calling MCP.begin(). Optionally the user can provide parameters to the SPI.begin(...)

0.4.0 Breaking change

The version 0.4.0 has breaking changes in the interface. The rationale is that the programming environment of the Arduino ESP32 S3 board uses a remapping by means of the include file io_pin_remap.h. This file remaps the pins of several core Arduino functions. The remapping is implemented by #define macros and these implement "hard" text replacements without considering context. The effect is that methods from this class (and several others) which have the same name as those Arduino core functions will be remapped into something not working.

The following library functions have been renamed:

old name new name notes
analogRead() read()
analogWrite() write()
pinMode() pinMode1()
digitalRead() read1()
digitalWrite() write1()

0.3.0 Breaking change

The version 0.3.0 has breaking changes in the interface. The essence is removal of ESP32 specific code from the library. This makes it possible to support the ESP32-S3 and other processors in the future. Also it makes the library a bit simpler to maintain.

Related

16 bit port expanders

8 bit port expanders

Interface

#include "MCP23S17.h"

Constructor

The two hardware constructors allow to call 4 different constructors.

- MCP23S17(10);            // select pin only
- MCP23S17(10, 7);         // select pin + address pins
- MCP23S17(10, 7, &SPI2);  // select pin + address pins + SPI port
- MCP23S17(10, &SPI2);     // select pin + SPI port

Sharing SELECT lines

(verified in #19)
Technically two chips could use the same SELECT pin and a different address. Since 0.2.5 the constructors allow to setup such a configuration. The added value is that one can use up to 8 devices (= 128 IO lines) with only four lines (MISO, MOSI, CLOCK, SELECT).

I assume that this configuration is less used and IMHO not recommended. NB it is more difficult to detect which device is selected when debugging.

To use the hardware addresses the Hardware Address ENable register must be set. See datasheet 3.3.2 ADDRESSING SPI DEVICES, need to set IOCON.HAEN.

The library supports two ways:

MCP.enableControlRegister(MCP23S17_IOCR_HAEN);  //  or 0x08
or
MCP.enableHardwareAddress();  //  0.2.5 version and up

See also IO Control Register section below.

Single pin interface

8 pins interface

16 pins interface

The reading and writing to registers have been performance optimized for the 16 bit interface. If there are problems please open an issue.

Interrupts (experimental 0.5.2)

Read the datasheet for the details, page 24,25.
Note: Error handling is limited.

pin = 0..15
mode = { RISING, FALLING, CHANGE }

16 pin interface, overrides all earlier settings. Sets all pins to the same interrupt mode { RISING, FALLING, CHANGE }.

Determine which pins caused the Interrupt. (datasheet).

Merge INTA and INTB into one signal so only one line handles all interrupts. This reduces the number of interrupt lines to handle, however one has to read more registers to find the changed ones.

SPI

Debugging

IO Control Register

The library supports setting bit fields in the IO control register. Read the datasheet carefully!

constant mask description
MCP23x17_IOCR_BANK 0x80 Controls how the registers are addressed.
MCP23x17_IOCR_MIRROR 0x40 INT Pins Mirror bit.
MCP23x17_IOCR_SEQOP 0x20 Sequential Operation mode bit.
MCP23x17_IOCR_DISSLW 0x10 Slew Rate control bit for SDA output.
MCP23x17_IOCR_HAEN 0x08 Hardware Address Enable bit (MCP23S17 only).
MCP23x17_IOCR_ODR 0x04 Configures the INT pin as an open-drain output.
MCP23x17_IOCR_INTPOL 0x02 This bit sets the polarity of the INT output pin.
MCP23x17_IOCR_NI 0x01 Not implemented.

Two dedicated functions are added: (MCP23S17 only)

Error codes

If one of the above functions return false, there might be an error.

name value description
MCP23S17_OK 0x00 No error
MCP23S17_PIN_ERROR 0x81
MCP23S17_I2C_ERROR 0x82 (compatibility)
MCP23S17_VALUE_ERROR 0x83
MCP23S17_PORT_ERROR 0x84
MCP23S17_REGISTER_ERROR 0xFF low level.
MCP23S17_INVALID_READ 0xFF low level.

Future

Must

Should

Could

Wont

Support

If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.

Thank you,