MCP23x17

This is library to control the MCP23x17 (MCP23S17, MCP23017) IO-Expander.

I created this because MCP23S17 library that already exists in NPM is outdated and is not working on newer Node.JS versions.

This library support Node.JS versions 12, 14, 16 and probably newers versions.

I will really appreciate making issues and pull requests on GitHub.

Contents

• Installation
• What's working
• Usage
• API Documentation

Installation

npm i @mrvanosh/mcp23x17

What's working?

• Setting pin mode
• Writing pin state to HIGH or LOW
• Reading pin state
• Pull-up input pins
• Software onChange callbacks

Usage

Toggles LED on input (button) change on an MCP23x17 extender.

const {
  i2c,
  spi,
  MCP23x17,
  A7,
  B5,
  MODE_OUTPUT,
  MODE_INPUT,
  PULL_UP,
  OUTPUT_HIGH,
} = require("@mrvanosh/mcp23s17");

(async () => {
  // MCP23S17 is on BUS 0 and it's device 0
  // this stands for /dev/spidev0.0
  // const bus = new spi(0,0);

  // MCP23017 is on BUS 1 and it's device 1
  // const bus = new i2c(1);
  const bus = new i2c(1);
  const mcp = new MCP23x17(bus, 0x20);

  // Button is connected to pin #7 and ground
  // LED anode connected to pin #13 (B5), LED cathode is connected to ground through resistor 300 ohm

  await mcp.begin();

  // Set pin #7 (A7) as input with pull-up resistor
  const input = await mcp.mode(A7, MODE_INPUT, PULL_UP);
  // Set pin #13 (B5) as output with initial state LOW
  const output = await mcp.mode(B5, MODE_OUTPUT, OUTPUT_HIGH);

  input.onChange((value) => {
    // Revert value because input is pull-up
    output.write(!value);
  });

  while (1) {
    // continuously reading input to detect changes
    await input.read();
    // If you don't need track a immediate change, use small pause
    // await (new Promise((resolve) => setTimeout(resolve, 50)));
  }
})();

See more examples in examples directory

API Documentation

All methods are asynchronous.

• MCP23x17
  • Contents
  • Installation
  • What's working?
  • Usage
  • API Documentation
  • Class MCP23x17
    • MCP23x17(bus, slaveAddress)
    • directions(arrayOfPins)
    • begin()
    • mode(pin, mode, stateOrPullUp)
    • read([pin])
    • write(pin, state) on MCP23x17 object
    • toggle(pin)
    • isPulledUp(pin)
    • onChange(pin, callback)
  • InputPin
    • read()
    • pullUp()
    • pullOff()
    • onChange(callback)
  • OutputPin
    • write(state)
    • high()
    • low()
    • toggle()

Class MCP23x17

MCP23x17(bus, slaveAddress)

• bus - object of interface SPI or I2C (new spi(0,0), new i2c(1))
• slaveAddress - address of MCP23x17 chip e.g. const bus = new i2c(1); const mcp = new MCP23x17(bus, 0x20);

directions(arrayOfPins)

Setting pins directions through 16 length array (see examples), Must be executed before begin function

• arrayOfPins - array of pin directions

begin()

Initializes MCP23x17 e.g. await mcp.begin();

mode(pin, mode, stateOrPullUp)

Setup pin mode

• pin - pin on MCP23X17 imported from library (A1, ..., A7) (B1, ... B7)
• mode - MODE_INPUT or MODE_OUTPUT
• stateOrPullUp - pull-up for inputs and LOW/HIGH state for outputs - OUTPUT_HIGH, OUTPUT_LOW, PULL_UP, PULL_DOWN e.g. const input = await mcp.mode(A1, MODE_INPUT, PULL_UP) - creates InputPin object const output = await mcp.mode(A2, MODE_OUTPUT, OUTPUT_HIGH) - creates OutputPin object

read([pin])

Read certain pin or read all pins to cache. Return true/false for pin reading or 16bit number with pins state

• pin - pin for reading (A1, ..., A7) (B1, ... B7)

write(pin, state) on MCP23x17 object

Write LOW or HIGH value to output pin

• pin - pin number (A1, ..., A7) (B1, ... B7)
• state - true/false

toggle(pin)

Revert state of output pin

• pin - pin number (A1, ..., A7) (B1, ... B7)

isPulledUp(pin)

• pin - pin number (A1, ..., A7) (B1, ... B7)

onChange(pin, callback)

Track changes value at input pin and execute callback with new value

• pin - input pin number
• callback - function to be executed on pin state change

InputPin

read()

Return true/false for pin reading

pullUp()

Pull Up a pin

pullOff()

Disable pull up on a pin

onChange(callback)

Track changes value at input pin and execute callback with new value

• callback - function to be executed on pin state change

OutputPin

write(state)

Set pin state

• true/false -> true - ON, false - OFF

high()

Set pin state to high

low()

Set pin state to low

toggle()

Revert state of output pin