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
| Key | Type | Default | |
|---|---|---|---|
bus | i2c0 | i2c1 | the bus it sits on, declared under [buses] | |
addr | 0x20..0x27 | 0x20 | I2C address, set by the A2..A0 pins |
int | GPIO, shareable | the GPIO its INT output drives | |
pins | list of tables | what is wired to each pin, see below | |
mhz | 1..1000 | 125 | core 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.
| Key | For | Values | Default | |
|---|---|---|---|---|
as | switch | toggle | led | bare | a momentary switch, a latching one, or an LED (or any load that is on at one level) | |
name | switches, LEDs | one word | the switch's action and event, the LED's event | |
contact | switches | no | nc | no | normally open (closes when pressed) or normally closed (opens when pressed) |
to | switches | gnd | vcc | gnd | what the closed contact connects the pin to |
bounce_us | switches | 0..100000 | 0 | how long the contact chatters after it moves |
initial | toggles | off | on | off | its position at power-on |
lit | LEDs | high | low | high | the level that lights it: low for an LED from VCC, sunk by the pin |
pull | any | up | down | an 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:
| Wiring | Cell |
|---|---|
led | a lamp, lit while the LED is |
switch | pressed while the cell (or its key) is held; lit while pressed |
toggle | flips on each click; lit while on |
| bare | pulls 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"] },
]
| Option | Default | |
|---|---|---|
pins | which pins, in order | all eight |
mode | ignore the wiring and treat every pin as bare. hold: drive the pin while the cell is held; toggle: each click flips it; view: show only | from the wiring |
active | low or high: the level a cell drives a bare pin to | low |
keys | a keyboard key per pin | |
labels | text per cell | names, 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.1drives it high,0low, overriding whatever is wired;-1lets go.sw0..sw7, or a switch'sname:1presses the switch (turns a toggle on),0releases 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.