node-red-contrib-mcp23017

Node-RED nodes for controlling the MCP23017 16-bit I/O expander over the I2C bus.

This package provides simple input and output nodes for the MCP23017 module. It allows selected pins to be configured as digital inputs or digital outputs directly from Node-RED. The library is intended for experimental automation, prototyping, education, and embedded control applications.

Features

• communication with MCP23017 over I2C
• support for all 16 GPIO pins
• digital input node with polling
• optional internal pull-up for input pins
• optional sending only when the input value changes
• digital output node
• support for inverted output logic
• shared configuration node for I2C bus and device address
• suitable for simple digital I/O expansion in Node-RED projects

Installation

Install the package directly from the Node-RED Palette Manager:

Menu → Manage palette → Install

Search for:

node-red-contrib-mcp23017

and click Install.

Alternatively, install it from the Node-RED user directory:

cd ~/.node-red
npm install node-red-contrib-mcp23017

After installation, restart Node-RED if required.

Nodes

This package contains three Node-RED nodes:

| Node | Type | Description | |---|---|---| | mcp23017-config | configuration node | Stores I2C bus, MCP23017 address, and debug option | | mcp23017-in | input node | Reads selected MCP23017 pin periodically | | mcp23017-out | output node | Writes a digital value to selected MCP23017 pin |

Example flow

The following example shows a simple flow with one MCP23017 output node and one MCP23017 input node.

Configuration node

The mcp23017-config node defines the shared hardware parameters of the MCP23017 module.

Parameters

| Parameter | Description | Example | |---|---|---| | Name | Optional name of the configured device | MCP23017 | | I2C bus | I2C bus number used by the target system | 1 or 2 | | Address | I2C address of the MCP23017 module | 0x20 | | Debug | Enables debug output | false |

Typical MCP23017 I2C addresses are:

0x20 - 0x27

Example configuration:

I2C bus: 2
Address: 0x20
Debug: false

The I2C bus number corresponds to the Linux device path:

/dev/i2c-X

For example, I2C bus 2 means:

/dev/i2c-2

Input node

The mcp23017-in node reads the selected MCP23017 pin periodically.

Parameters

| Parameter | Description | |---|---| | Name | Optional name displayed on the node | | MCP config | Selected mcp23017-config configuration node | | Pin | MCP23017 pin number from 0 to 15 | | Pull-up | Enables internal pull-up resistor | | Poll (ms) | Polling interval in milliseconds | | Only on change | Sends output only when the value changes | | Topic | Optional custom msg.topic |

Output message

The output msg.payload contains a boolean value.

Example output:

{
  "payload": true,
  "pin": 1,
  "address": 32,
  "bus": 2,
  "topic": "mcp23017/20/pin/1"
}

If the Topic field is empty, the node automatically creates a topic in this format:

mcp23017/<address>/pin/<pin>

Output node

The mcp23017-out node writes a digital value to the selected MCP23017 pin.

Parameters

| Parameter | Description | |---|---| | Name | Optional name displayed on the node | | MCP config | Selected mcp23017-config configuration node | | Pin | MCP23017 pin number from 0 to 15 | | Set OUTPUT on start | Configures the pin as output when Node-RED starts | | Invert | Inverts the output logic |

Input message

The node accepts boolean, numeric, or string values in msg.payload.

Supported values:

true / false
1 / 0
"true" / "false"
"on" / "off"
"high" / "low"

Example input:

{
  "payload": true
}

Output message

After writing to the pin, the node sends the message to its output.

Example output:

{
  "payload": true,
  "pin": 0,
  "address": 32,
  "bus": 2
}

If the Invert option is enabled, the logical value is inverted before being written to the MCP23017 pin.

Pin numbering

The node uses MCP23017 pin numbers from 0 to 15.

0 - 7    GPIOA pins
8 - 15   GPIOB pins

The exact physical pin mapping depends on the MCP23017 module or board that is used.

Hardware requirements

This node requires:

• Node-RED
• MCP23017 I/O expander module
• system with I2C support
• enabled I2C interface
• correct I2C wiring
• Linux-based target device, such as Raspberry Pi, Luckfox, or another embedded board with I2C support

Wiring

Typical MCP23017 module connection:

| MCP23017 pin | Target device | |---|---| | VCC | 3.3 V or 5 V, depending on the module | | GND | GND | | SDA | I2C SDA | | SCL | I2C SCL | | GPIO pins | Digital inputs or outputs |

Make sure that the voltage levels of the MCP23017 module are compatible with the target device.

Platform note

This node uses the node-mcp23017 package and is intended to run on Linux-based devices with I2C support.

On Windows, the package may install successfully, but real I2C communication is not supported unless a compatible I2C interface and driver are available.

Notes

For reliable operation, make sure that:

• the I2C interface is enabled,
• the correct I2C bus number is selected,
• the correct MCP23017 address is configured,
• the MCP23017 module is connected correctly,
• the selected pin number is in range 0 to 15,
• the pin is not used by another part of the flow in a conflicting mode.

License

This project is licensed under the MIT License.