---
title: MCP23017 I/O Expander
description: Instructions on how to integrate the MCP23017 GPIO pin expander with I2C interface into Home Assistant.
ha_category:
  - DIY
  - Binary Sensor
  - Switch
ha_release: 0.94
ha_iot_class: Local Polling
ha_codeowners:
  - '@jardiamj'
ha_domain: mcp23017
---

The `mcp23017` integration is the base for all related mcp23017 platforms in Home Assistant. There is no setup needed for the integration itself, for the platforms please check their corresponding sections.

For more details about the MCP23017 I2C I/O port expander you can find its datasheet here: [MCP23017](https://www.microchip.com/wwwproducts/en/MCP23017).

If you are using the Home Assistant Operating System you can’t use existing methods to enable the I2C bus on a Raspberry Pi, you will have to [enable the I2C interface manually](https://github.com/home-assistant/hassos/blob/dev/Documentation/boards/raspberrypi.md#i2c) using a USB stick. To accomplish that, follow this step by step instructions: [Enable Home Assistant Operating System i2c](https://www.home-assistant.io/hassio/enable_i2c).

## Binary Sensor

The `mcp23017` binary sensor platform allows you to read sensor values from the I/O pins of your [MCP23017 I2C I/O expander](https://www.adafruit.com/product/732).

The pin numbers are from 0 to 15 where: 0-7 correspond to port A (A1-A8) and 8-15 to port B (B1-B8).

### Configuration

To use the I/O pins of an mcp23017 connected to an I2C bus of your Raspberry Pi as binary sensors, add the following to your `configuration.yaml` file:

```yaml
# Example configuration.yaml entry
binary_sensor:
  - platform: mcp23017
    i2c_address: 0x20
    pins:
      0: PIR Office
      1: PIR Bedroom
```

{% configuration %}
i2c_address:
  description: i2c address of MCP23017 chip.
  required: false
  type: integer
  default: "`0x20`"
pins:
  description: List of used pins.
  required: true
  type: map
  keys:
    "pin: name":
      description: The pin numbers (from 0 to 15) and corresponding names.
      required: true
      type: [integer, string]
scan_interval:
  description: Interval to scan for sensor state changes in seconds.
  required: false
  type: integer
  default: 15
invert_logic:
  description: If `true`, inverts the output logic to ACTIVE LOW.
  required: false
  type: boolean
  default: "`false` (ACTIVE HIGH)"
pull_mode:
  description: >
    Type of internal pull resistor to use.
    Options are `UP` - pull-up resistor and `DOWN` - pull-down resistor.
  required: false
  type: string
  default: "`UP`"
{% endconfiguration %}

<div class='note warning'>
  MCP23017 only has internal pull-up resistors, if you want to use pull-down you will have to wire your own pull-down resistors.
</div>

## Switch

The `mcp23017` switch platform allows you to write to the I/O pins of your [MCP23017 I2C I/O expander](https://www.adafruit.com/product/732).

The pin numbers are from 0 to 15 where: 0-7 correspond to port A (A1-A8) and 8-15 to port B (B1-B8).

### Configuration

To use the I/O pins of an mcp23017 connected to an I2C bus of your Raspberry Pi as switches, add the following to your `configuration.yaml` file:

```yaml
# Example configuration.yaml entry
switch:
  - platform: mcp23017
    i2c_address: 0x20
    pins:
      11: Fan Office
      12: Light Desk
```

{% configuration %}
i2c_address:
  description: i2c address of MCP23017 chip.
  required: false
  type: integer
  default: "`0x20`"
pins:
  description: Array of used pins.
  required: true
  type: list
  keys:
    pin:
      description: The pin numbers (from 0 to 15) and corresponding names.
      required: true
      type: [integer, string]
invert_logic:
  description: If true, inverts the output logic to ACTIVE LOW.
  required: false
  default: false
  type: boolean
{% endconfiguration %}
