tartelette / documentation demossource ↗

mcp23008: I2C port expander

The Microchip MCP23008: eight GPIOs behind an I2C interface, with an interrupt output, for example for buttons (inputs with pull-ups) and gate outputs.

Keys

KeyTypeDefault
busi2c0 | i2c1the bus it sits on, declared under [buses]
addr0x20..0x270x20I2C address, set by the A2..A0 pins
intGPIO, shareablethe GPIO its INT output drives
pinslist of tableswhat is wired to each pin, see below
mhz1..1000125core clock, to turn bounce_us into cycles
[buses]
i2c1 = { sda = 2, scl = 3 }

[parts.expander]
kind = "mcp23008"
bus = "i2c1"
addr = 0x20
int = 16
pins = [
  { pin = 0, as = "led", name = "gate_a" },
  { pin = 4, as = "switch", name = "key1" },
]

int can be shared between several expanders when they are configured as open drain, as on a real board.

Pins

Each entry of pins says what one pin (pin = 0..7) is wired to. Pins left out are bare: their level is whatever the firmware and the gpN actions make it.

KeyForValuesDefault
asswitch | toggle | ledbarea momentary switch, a latching one, or an LED (or any load that is on at one level)
nameswitches, LEDsone wordthe switch's action and event, the LED's event
contactswitchesno | ncnonormally open (closes when pressed) or normally closed (opens when pressed)
toswitchesgnd | vccgndwhat the closed contact connects the pin to
bounce_usswitches0..1000000how long the contact chatters after it moves
initialtogglesoff | onoffits position at power-on
litLEDshigh | lowhighthe level that lights it: low for an LED from VCC, sunk by the pin
pullanyup | downan external pull resistor
pins = [
  { pin = 0, as = "led", name = "run" },                       # LED to GND
  { pin = 1, as = "led", lit = "low" },                        # LED from VCC
  { pin = 4, as = "switch", name = "ok", bounce_us = 2000 },   # push button to GND
  { pin = 5, as = "switch", contact = "nc", pull = "up" },     # normally closed, external pull-up
  { pin = 6, as = "switch", to = "vcc", pull = "down" },       # button to VCC
  { pin = 7, as = "toggle", initial = "on", name = "mute" },   # latching switch
]

An input pin's level comes from, in order: a gpN probe, then a closed switch contact, then an external pull resistor, then the internal pull-up (GPPU). With none of those it floats, and reads low. An output pin shows OLAT; a closed switch on an output loses (on a real board it would short it). An LED is lit only while its pin is an output at the LED's level.

A bouncing contact moves at once, then flips back and forth at random intervals until bounce_us after the last movement, when it settles. The chatter is the same on every run. Each flip counts as a pin change, for the interrupt logic too.

Warnings

The first time the firmware reads or writes the pins after setting IODIR, and again after it changes IODIR or GPPU, the model checks the setup against the wiring. It warns once per pin about:

  • an LED on a pin set as an input (it stays dark);
  • a switch on a pin set as an output (closing it would short the output);
  • a switch input that nothing pulls up (or down, for a switch to VCC): it floats while open;
  • a switch input pulled to the level the switch connects it to: it reads the same whether open or closed.

The warnings show in the app's log and on stderr when headless.

What's modelled

All eleven registers, with the address pointer auto-incrementing (and wrapping) unless IOCON.SEQOP turns sequential mode off. Input polarity, the internal pull-ups, interrupt-on-change against the previous value or DEFVAL, INTF and INTCAP capture, and the INT pin's polarity and open- drain setting.

Interrupts are evaluated whenever a pin or a register changes.

Panel

A cell per pin. By default each cell follows the pin's wiring:

WiringCell
leda lamp, lit while the LED is
switchpressed while the cell (or its key) is held; lit while pressed
toggleflips on each click; lit while on
barepulls the pin low while held; lit while the pin is high

Cells are labelled with the pin's name, else its number. One expander can have several panel items, so inputs and outputs can sit apart:

[panel]
expander = [
  { at = [0, 3], span = [2, 1], label = "Soft keys", pins = [4, 5, 6, 7], keys = ["1", "2", "3", "4"] },
  { at = [2, 3], span = [2, 1], label = "Gates", pins = [0, 1, 2, 3], labels = ["A", "B", "C", "D"] },
]
OptionDefault
pinswhich pins, in orderall eight
modeignore the wiring and treat every pin as bare. hold: drive the pin while the cell is held; toggle: each click flips it; view: show onlyfrom the wiring
activelow or high: the level a cell drives a bare pin tolow
keysa keyboard key per pin
labelstext per cellnames, else numbers

Events

  • pins, with the eight pin levels as a byte (bit 0 = GP0), whenever any of them changes.
  • A named pin's name, 1 or 0: its switch was pressed (turned on) or released (turned off), or its LED went on or off. A bouncing contact doesn't repeat it.

Actions

  • gp0 .. gp7: probe the pin. 1 drives it high, 0 low, overriding whatever is wired; -1 lets go.
  • sw0 .. sw7, or a switch's name: 1 presses the switch (turns a toggle on), 0 releases it (turns it off).
--input expander:key1=1@1000000 --input expander:key1=0@1100000   # tap soft key 1
--input expander:gp4=0@1000000 --input expander:gp4=-1@1100000    # the same, probing the pin

Any pin's name also works as a synth gate (--osc saw:dac.A:expander.gate_a).

Not modelled

The I2C timing (transfers are instantaneous, see rp2040.md), IOCON.DISSLW, and the analogue side: a weak pull-up fighting a strong external pull-down, or an LED dimly lit through a pull-up.