From bc0b298775b1c17cd92e596816ef3a23f324dcaa Mon Sep 17 00:00:00 2001
From: "Jardi A.M. Jordan" <1088732+jardiamj@users.noreply.github.com>
Date: Mon, 15 Apr 2019 13:53:42 -0700
Subject: [PATCH] Added documentation for MCP23017 component: binary sensor and
 switch platforms.

---
 source/_components/mcp23017.markdown | 128 +++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 source/_components/mcp23017.markdown

diff --git a/source/_components/mcp23017.markdown b/source/_components/mcp23017.markdown
new file mode 100644
index 00000000000..af488631203
--- /dev/null
+++ b/source/_components/mcp23017.markdown
@@ -0,0 +1,128 @@
+---
+layout: page
+title: "MCP23017 I2C GPIO expander"
+description: "Instructions on how to integrate the MCP23017 GPIO pin expander with I2C interface into Home Assistant."
+date: 2019-04-14 07:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: raspberry-pi.png
+ha_category:
+  - DIY
+  - Binary Sensor
+  - Switch
+ha_release: 0.92
+ha_iot_class: Local Polling
+redirect_from:
+  - /components/binary_sensor.mcp23017/
+  - /components/switch.mcp23017/
+---
+
+The `mcp23017` component is the base for all related mcp23017 platforms in Home Assistant. There is no setup needed for the component itself, for the platforms please check their corresponding pages.
+
+## {% linkable_title 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).
+
+## {% linkable_title Configuration %}
+
+To use the I/O pins of an mcp23017 connected to and 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 %}
+
+NOTE: MCP23017 only has internal pull-up resistors, if you want to use pull-down you will have to wire your own pull-down resistors.
+
+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).
+
+## {% linkable_title 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).
+
+## {% linkable_title Configuration %}
+
+To use the I/O pins of an mcp23017 connected to and 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
+    ports:
+      11: Fan Office
+      12: Light Desk
+```
+
+{% configuration %}
+i2c_address:
+  description: i2c address of MCP23017 chip.
+  required: false
+  type: integer
+  default: "`0x20`"
+ports:
+  description: Array of used pins.
+  required: true
+  type: list
+  keys:
+    port:
+      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 %}
+
+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).
+
+<p class='note warning'>
+Note that a pin managed by HASS is expected to be exclusive to HASS.
+</p>