Skip to content

ESP32 I2C expanders

For Heltec V4.3 ESP32-S3R2, download 1.18.0.3 Preview 1. The same image supports OLED and TFT. This preview passed software/build checks; physical expander and TFT operation remain unqualified.

ESP32 Full Companion and custom builds with MESH_CUSTOM_PERIPHERALS=1 support one configured expander on the board's existing expansion I2C bus. The board must define PIN_BOARD_SDA and PIN_BOARD_SCL. Native GPIO numbers retain their meanings; expander pins are explicitly named x0–x15. Repeater GPIO/timer commands do not accept expander pins. A passive buzzer still needs a native MCU pin for RTTTL tones.

For an OLED-only Heltec V4.3, an expander is optional: select OLED and reboot to release four native accessory pins.

Chip CLI type Pins Address range
PCF8575 pcf8575 x0–x15 0x20–0x27
PCF8574 / PCF8574T pcf8574 x0–x7 0x20–0x27
PCF8574A / PCF8574AT pcf8574a x0–x7 0x38–0x3f
MCP23017 mcp23017 x0–x15, except x7 and x15 0x20–0x27
MCP23008 mcp23008 x0–x7 0x20–0x27

The MCP23017 exclusions accommodate the manufacturer's input restrictions without leaving reassigned output pins driven. Leave MCP23017 GPA7/GPB7 unconnected. PCF inputs retain their weak pull-ups; rotary.pullup off cannot be used with PCF encoder inputs. Choose a general-purpose breakout with individually exposed GPIO terminals. LCD1602/2004 backpack boards wire their outputs for a display and are not the recommended breakout for this arrangement.

Heltec V4.3: PCF8575, encoder, buzzer and three LEDs

For TFT, keep display.type auto or tft; the encoder and LEDs use the expander, leaving GPIO6 for the buzzer. OLED can use this arrangement too, or the native-pin setup without an expander.

Use the unified native-USB Full Companion preview linked above. Before powering the module, set its address jumpers to 0x27 (A0, A1 and A2 high). Default 0x20 can conflict with a soil-sensor probe. Compiled sensor/display addresses are protected, so another board may require a different unused address.

Connection Destination
Expander VCC / GND Heltec 3.3 V / GND
Expander SDA / SCL GPIO4 / GPIO3
Encoder CLK / DT Expander P00 (x0) / P01 (x1)
Encoder common and switch ground GND
Encoder switch GPIO0
Notification LED negative Expander P02 (x2)
GPS LED negative Expander P03 (x3)
Bluetooth LED negative Expander P04 (x4)
Each LED positive 3.3 V through its current-limiting resistor
Passive buzzer signal GPIO6, through a driver if its load requires one
Passive buzzer ground GND

Power both the expander and its I2C pull-ups from 3.3 V. Suitable prewired LEDs with built-in resistors need no additional resistor; check their current against the chip's per-pin and total ratings. Leave INT unconnected: this implementation polls inputs. GPIO43 is unused here, so its encoder series resistor is no longer needed. Release the GPIO0 switch during reset.

Enter each command separately:

set rotary off
set expander pcf8575,0x27
get expander
set rotary.pullup on
set rotary.pins x0,x1,0
set rotary.steps 4
set rotary on
set peripheral.buzzer 6
set peripheral.led.notify x2,low
set peripheral.led.gps x3,low
set peripheral.led.ble x4,low

The existing sound/mute and notification rules still control the buzzer. The GPS LED indicates active GPS use; the Bluetooth LED indicates that Bluetooth is enabled, including advertising. See notifications for sound and alert rules.

Other expanders and settings

Use the matching type and the module's actual seven-bit address:

get expander
set expander mcp23017,0x27
get rotary.pins.available
get peripheral.pins.available

x0–x7 map to PCF8575 P00–P07 or MCP23017 GPA0–GPA7. x8–x15 map to PCF8575 P10–P17 or MCP23017 GPB0–GPB7. Eight-pin chips use P0–P7/GP0–GP7. LED assignments accept ,low or ,high. PCF pins default to low (current sinking), MCP pins to high. An active-high MCP LED connects through its LED/resistor to ground.

Disable rotary and clear expander LED assignments before changing chip type/address or using set expander off. Configuration and assignments are saved separately. Firmware does not guess the chip type or scan all addresses. These parts lack a universal immutable chip-ID register, so the selected type must match the physical chip.

An absent chip or failed I2C transaction stops further input/output traffic; physical outputs can retain their last state until the device is reset or power-cycled. Correct the fault and explicitly reconfigure/re-enable them. Mechanical encoders can lose fast turns while firmware is busy: these chips do not queue every transition. Test physical turning speed on the completed device. This feature does not turn an expander into a PWM/audio source.

Hardware references: TI PCF8575, NXP PCF8574/8574A, Microchip MCP23017, and MCP23008.