Content
# Domodreams MCP23017 ESPHome Component
This is a custom ESPHome component for handling MCP23017 I/O expanders as
**button/gesture processors** with debouncing, single/double/long click detection,
release detection, optional "off" delays, failure guards, and flexible configuration.
---
## Features
- Supports **multiple MCP23017 chips** on the same I²C bus.
- Each instance exposes 16 pins as **text sensors** (optional, can be autogenerated).
- Per-pin **debouncing** and **gesture recognition** (single, double, long, released, "off").
- Configurable timings:
- `debounce`
- `long_min`
- `double_max_delay`
- `off_delay`
- `release_off_delay`
- Per-pin **overrides** for `long_min`, `double_max_delay`, `off_delay`.
- Configurable per-instance **words** for states (`word_off`, `word_single`, `word_double`, `word_long`, `word_released`).
- Automatic creation of sensors if none are declared, with generated IDs/names.
- Guard logic: after 3 consecutive I²C read failures, all pins publish `"off"` and the component is marked failed (optional reboot).
- FSM gesture trigger: `on_fsm_change` with variables available in lambda:
- `pin` (0–15)
- `name` (sensor name, if defined)
- `prev_state`
- `state`
- `time` (millis since boot)
- `unixtime` (RTC-based, or millis-derived fallback)
---
## FSM (Gesture State Machine)
### States
- **IDLE**
- **PRESSING**
- **WAIT_DOUBLE_WINDOW**
- **LONG_HELD**
- **DOUBLE_WAIT_RELEASE**
- **POST_DELAY_OFF**
### Gestures
- `"off"` → default/rest state
- `"single"` → short press, no second press within `double_max_delay`
- `"double"` → two presses within `double_max_delay`
- `"long"` → press held at least `long_min`
- `"released"` → after a `long`, when button is released
### Diagram (Mermaid)
```mermaid
stateDiagram-v2
[*] --> IDLE
IDLE --> PRESSING: press
PRESSING --> LONG_HELD: held >= long_min
PRESSING --> WAIT_DOUBLE_WINDOW: release before long_min
LONG_HELD --> RELEASED: release
RELEASED --> POST_DELAY_OFF: after release_off_delay
WAIT_DOUBLE_WINDOW --> DOUBLE_WAIT_RELEASE: second press before double_max_delay
WAIT_DOUBLE_WINDOW --> SINGLE: timeout without 2nd press
DOUBLE_WAIT_RELEASE --> POST_DELAY_OFF: release after double
SINGLE --> POST_DELAY_OFF: after off_delay
POST_DELAY_OFF --> IDLE: timeout
```
---
## YAML Configuration
### Minimal Example (auto sensors)
```yaml
i2c:
sda: 13
scl: 16
scan: true
text_sensor:
- platform: domodreams_mcp23017
id: mcp1
address: 0x20
```
This generates 16 sensors named `mcp1 0x20 MCP Pin 0` … `Pin 15`.
---
### Example 1 — Per-instance defaults
```yaml
text_sensor:
- platform: domodreams_mcp23017
id: mcp1
address: 0x20
debounce: 50
long_min: 1000
double_max_delay: 300
off_delay: 100
release_off_delay: 1000
word_off: "off"
word_single: "single"
word_double: "double"
word_long: "long"
word_released: "released"
```
---
### Example 2 — With explicit sensors and overrides
```yaml
text_sensor:
- platform: domodreams_mcp23017
id: mcp2
address: 0x21
debounce: 50
long_min: 1000
double_max_delay: 300
off_delay: 200
sensors:
- name: Pin0 SingleOnly
pin: 0
long_min: 0
double_max_delay: 0
- name: Pin1 LongOnly
pin: 1
long_min: 2000
double_max_delay: 0
off_delay: 500
- name: Pin2 DoubleFast
pin: 2
double_max_delay: 150
```
---
### Example 3 — Using FSM trigger
```yaml
text_sensor:
- platform: domodreams_mcp23017
id: mcp3
address: 0x22
debounce: 30
long_min: 800
double_max_delay: 250
off_delay: 200
on_fsm_change:
then:
- lambda: |-
ESP_LOGI("fsm", "FSM change: pin=%d name=%s prev=%s -> state=%s time=%u unixtime=%llu",
pin,
name.c_str(),
prev_state.c_str(),
state.c_str(),
time,
(unsigned long long) unixtime);
```
---
## TODO
- Add binary_sensor variant (direct HIGH/LOW exposure).
- Evaluate performance at >8 MCP chips (scaling tests).
- Optimize I²C batch reads for multiple instances.
- Consider per-pin `released` delay overrides.
---
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.
git
A Model Context Protocol server for Git automation and interaction.