Board pins vs MCU pins #18186

victorallume · 2025-10-01T23:05:33Z

victorallume
Oct 1, 2025

I'm using an STM32 Nucleo board, and the board has a defined set of pins for analog inputs (A0-A8) and Digital IO (D0-D71). However, the MCU has pins labelled A0-A15, B0-B15, C0-C15, D0-D15, etc. If I want to access the MCU pin C3 I would do so using machine.Pin('C4'). However, there is a naming collision between the board pins and MCU pins on A0-A8 and D0-D15. Micropython appears to preference the board pins, so Pin('A4') is the same as (MCU pin) Pin('F5') and there is no direct way to access the MCU pin A4 (I would need to use the board pin Pin('D24'))

While these pins are defined in the boards pins.csv, and the MCU pins all start with P (e.g. PA4), micropython strips the leading P. The docs say a pin can be creating using a tuple of (port, pin) (e.g. Pin((0,4))), this returns a TypeError on the STM32 port (as of micropython 1.26.0). It is not possible to positively specify an MCU pin (e.g. Pin('PA4'))

So, this post is partly a cautionary tale, partly a question if this behaviour is appropriate (I would prefer some kind of error or warning if there are pin name collisions, or a mechanism to specify a board pin vs MCU pin).

The workarounds I see at the moment are to either use the board pins, or to change pins.csv to remove the board pin definitions

victorallume · 2025-10-01T23:28:29Z

victorallume
Oct 1, 2025
Author

I have now discovered the (undocumented?) Pin.cpu and Pin.board attributes, so I can do

>>> Pin.cpu.A4
Pin(Pin.cpu.A4, mode=Pin.OUT)
>>> Pin.board.A4
Pin(Pin.cpu.F5, mode=Pin.IN, pull=Pin.PULL_DOWN)

1 reply

robert-hh Oct 2, 2025
Collaborator

Pin.cpu.F5 and similar are already Pin objects. You do not have to instantiate them again, although it does not matter. The Pin constructor checks for it and just returns a Pin object if one is supplied as argument.
AT most devices like Pin, SPI, I2C, .. where pins are supplied as arguments one can use either a Pin object, the name from Pin.cpu or Pin.board as a string or a number. Using a number is not supported by all ports, and even if, the number is not obvious. Using a number is common for ESP8266, ESP32 and RP2. The names from Pin.board shall match the pin label printed on the board and/or the board's schematics..

scruss · 2025-10-02T00:39:44Z

scruss
Oct 2, 2025
Sponsor

This is documented for the pyboard (and by extension, other STM32 boards) here: class Pin – control I/O pins. It's present in other ports, too, such as on the rp2:

>>> help(machine.Pin.board)
object <class 'board'> is of type type
  GP0 -- Pin(GPIO0, mode=ALT, pull=PULL_DOWN, alt=31)
  GP1 -- Pin(GPIO1, mode=ALT, pull=PULL_DOWN, alt=31)
  GP2 -- Pin(GPIO2, mode=ALT, pull=PULL_DOWN, alt=31)
  GP3 -- Pin(GPIO3, mode=ALT, pull=PULL_DOWN, alt=31)
  GP4 -- Pin(GPIO4, mode=ALT, pull=PULL_DOWN, alt=31)
  GP5 -- Pin(GPIO5, mode=ALT, pull=PULL_DOWN, alt=31)
  GP6 -- Pin(GPIO6, mo
10000
de=ALT, pull=PULL_DOWN, alt=31)
  GP7 -- Pin(GPIO7, mode=ALT, pull=PULL_DOWN, alt=31)
  GP8 -- Pin(GPIO8, mode=ALT, pull=PULL_DOWN, alt=31)
  GP9 -- Pin(GPIO9, mode=ALT, pull=PULL_DOWN, alt=31)
  GP10 -- Pin(GPIO10, mode=ALT, alt=SPI)
  GP11 -- Pin(GPIO11, mode=ALT, alt=SPI)
  GP12 -- Pin(GPIO12, mode=ALT, alt=SPI)
  GP13 -- Pin(GPIO13, mode=ALT, pull=PULL_DOWN, alt=31)
  GP14 -- Pin(GPIO14, mode=ALT, pull=PULL_DOWN, alt=31)
  GP15 -- Pin(GPIO15, mode=OUT)
  GP16 -- Pin(GPIO16, mode=ALT, pull=PULL_DOWN, alt=31)
  GP17 -- Pin(GPIO17, mode=ALT, pull=PULL_DOWN, alt=31)
  GP18 -- Pin(GPIO18, mode=ALT, pull=PULL_DOWN, alt=31)
  GP19 -- Pin(GPIO19, mode=ALT, pull=PULL_DOWN, alt=31)
  GP20 -- Pin(GPIO20, mode=ALT, pull=PULL_DOWN, alt=31)
  GP21 -- Pin(GPIO21, mode=ALT, pull=PULL_DOWN, alt=31)
  GP22 -- Pin(GPIO22, mode=ALT, pull=PULL_DOWN, alt=31)
  GP26 -- Pin(GPIO26, mode=ALT, pull=PULL_DOWN, alt=31)
  GP27 -- Pin(GPIO27, mode=ALT, pull=PULL_DOWN, alt=31)
  GP28 -- Pin(GPIO28, mode=ALT, pull=PULL_DOWN, alt=31)
  LED -- Pin(EXT_GPIO0, mode=IN)
  WL_GPIO0 -- Pin(EXT_GPIO0, mode=IN)
  WL_GPIO1 -- Pin(EXT_GPIO1, mode=IN)
  WL_GPIO2 -- Pin(EXT_GPIO2, mode=IN)
>>> help(machine.Pin.cpu)
object <class 'cpu'> is of type type
  GPIO0 -- Pin(GPIO0, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO1 -- Pin(GPIO1, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO2 -- Pin(GPIO2, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO3 -- Pin(GPIO3, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO4 -- Pin(GPIO4, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO5 -- Pin(GPIO5, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO6 -- Pin(GPIO6, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO7 -- Pin(GPIO7, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO8 -- Pin(GPIO8, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO9 -- Pin(GPIO9, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO10 -- Pin(GPIO10, mode=ALT, alt=SPI)
  GPIO11 -- Pin(GPIO11, mode=ALT, alt=SPI)
  GPIO12 -- Pin(GPIO12, mode=ALT, alt=SPI)
  GPIO13 -- Pin(GPIO13, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO14 -- Pin(GPIO14, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO15 -- Pin(GPIO15, mode=OUT)
  GPIO16 -- Pin(GPIO16, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO17 -- Pin(GPIO17, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO18 -- Pin(GPIO18, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO19 -- Pin(GPIO19, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO20 -- Pin(GPIO20, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO21 -- Pin(GPIO21, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO22 -- Pin(GPIO22, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO23 -- Pin(GPIO23, mode=OUT, pull=PULL_UP)
  GPIO24 -- Pin(GPIO24, mode=ALT, pull=PULL_DOWN, alt=GPCK)
  GPIO25 -- Pin(GPIO25, mode=OUT, pull=PULL_DOWN)
  GPIO26 -- Pin(GPIO26, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO27 -- Pin(GPIO27, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO28 -- Pin(GPIO28, mode=ALT, pull=PULL_DOWN, alt=31)
  GPIO29 -- Pin(GPIO29, mode=ALT, pull=PULL_DOWN, alt=8)
  EXT_GPIO0 -- Pin(EXT_GPIO0, mode=IN)
  EXT_GPIO1 -- Pin(EXT_GPIO1, mode=IN)
  EXT_GPIO2 -- Pin(EXT_GPIO2, mode=IN)

With RP2, the board and CPU mappings appear to be the same. I'd have expected the board mapping to contain physical pin numbers (1..40), but that doesn't seem to be the case

1 reply

scruss Oct 7, 2025
Sponsor

With RP2, the board and CPU mappings appear to be the same

Famous last words: the SparkFun Pro Micro RP2040 doesn't expose machine.Pin.board names, but machine.Pin.cpu is as above.

victorallume · 2025-10-02T02:11:02Z

victorallume
Oct 2, 2025
Author

Oh, interesting, so it looks like the machine module is using the same Pins as the pyb module, but this isn't documented in machine https://docs.micropython.org/en/v1.26.0/library/machine.Pin.html

1 reply

scruss Oct 2, 2025
Sponsor

I checked on an ESP32: machine.Pin.cpu doesn't exist, and machine.Pin.board has no usable members.

shariltumin · 2025-10-03T22:48:05Z

shariltumin
Oct 3, 2025

I am using an STM32F411CEU6 board. I do not include the help() function in my build. Instead, I use the REPL autocomplete feature (i.e., pressing the TAB key). Here is what I have:

>>> import pyb
>>> pyb.Pin.cpu.
A0              A1              A10             A11
A12             A13             A14             A15
A2              A3              A4              A5
A6              A7              A8              A9
B0              B1              B10             B12
B13             B14             B15             B2
B3              B4              B5              B6
B7              B8              B9              C13
C14             C15             H0              H1

>>> pyb.Pin.board.
A0              A1              A2              A3
A4              A5              F_CS            F_MISO
F_MOSI          F_SCK           LED_BLUE        OSC32_IN
OSC32_OUT       PA0             PA1             PA10
PA11            PA12            PA15            PA2
PA3             PA4             PA5             PA6
PA7             PA8             PA9             PB0
PB1             PB10            PB12            PB13
PB14            PB15            PB2             PB3
PB4             PB5             PB6             PB7
PB8             PB9             PC13    
8000
        PC14
PC15            PH0             PH1             SW
SWCLK           SWDIO           USB_DM          USB_DP

>>> pyb.Pin.board.PA0 == pyb.Pin.cpu.A0
True
>>> pyb.Pin.board.PB9 == pyb.Pin.cpu.B9
True
>>> pyb.Pin.board.A0 == pyb.Pin.cpu.A0
True
>>> pyb.Pin.board.LED_BLUE == pyb.Pin.cpu.C13
True
>>> led_on = pyb.Pin.cpu.C13.low
>>> led_off = pyb.Pin.board.LED_BLUE.high

>>> led_on() # blue LED on
>>> led_off() # blue LED off

>>> import machine
>>> machine.Pin('C13') == pyb.Pin.cpu.C13
True
>>> LED = 'C13'
>>> machine.Pin(LED) == pyb.Pin.cpu.C13 == pyb.Pin.board.LED_BLUE
True

When working on STM32, I prefer to use pyb.Pin.cpu.

0 replies

pyramids · 2025-10-20T22:54:50Z

pyramids
Oct 20, 2025

Maybe this is an appropriate place for a somewhat related question regarding advisable pin definitions.

There can be very standardized boards across different cpu/mcu ports. In particular, the SEED studio XIAO line has 2x7 pin boards with lots of generic interfacing boards (compatible with all of them). The XIAO mcu boards all seem to have D0 to D10 GPIO pins (plus 5V, GND, 3.3V) accessible on the side (top/bottom) plus a seemingly (almost) equally standardized set of pads on the bottom (MTDO, MTDI, MTCK, MTMS plus a few not relevant to programmable GPIO). CPU/MCU-depending, these have aliases; for example, on microcontrollers with an ADC, "D0" is always also labelled "A0", and likewise for consecutive pins (but how many of them depends on the MCU). Also, XIAO boards have 0 to 4 GPIO-controllable LEDs (plus one for an integrated battery charger if there is one, or 5V power indicator if not).

IMHO it would be very helpful to have consistent pin naming, especially since lots of projects will then be trivially portable across all or most XIAO boards, but MicroPython has gone a different way:

ports/nrf/boards/SEEED_XIAO_NRF52/pins.csv defines names like "D4_A4" and "USER_LED" but not "D4" (or "D0").
ports/samd/boards/SEEED_XIAO_SAMD21/pins.csv defines names like "A10_D10" but not "D10" (or "D0").
ports/rp2/boards/SEEED_XIAO_RP2350/pins.csv defines names like "D0" and "LED" (and also "D4") but not "D0_A0".

The situation is bound to get worse with existing (or likely future!) PRs being even less consistent:

PR rp2/boards/SEEED_XIAO_RP2040: New board definition. #14402 (comment) defines "LED_R". "LED_G", and "LED_B" but not "LED" or "USER_LED" for code looking for just any LED.
ports/rp2/boards/SEEED_XIAO_RP2350/pins.csv (for comparison) defines names like "LED", "NEOPIXEL_POWER" and "NEOPIXEL".
several PRs do not define/name any pins other than D0 through D10 (seeed_xiao_esp32c5 support (IDF v5.5) #17912 (comment) , esp32/boards/SEEED_XIAO_ESP32_C6: Add new board definition. #17429 (comment) , esp32/boards/SEEED_XIAO_ESP32_C3: Add new board definition. #17795 (comment)) --- which might be correct for one or two of these, as at least the final one of these boards might not have anything to define.
my own implementation (not submitted as PR) for the board that the PR esp32/boards/SEEED_XIAO_ESP32_C6: Add new board definition. #17429 introduces (XIAO ESP32C6) defines names like "LED", "RF_PWR", "RF_SEL", as well as the common XIAO-bottom pads ("MTDO", "MTCK", "MTMS" and "MTDI" plus "BOOT" for the button).
[Added as EDIT] There seem to be more PRs for XIAO board definitions waiting then I found initially, e.g. Xiao esp32 s3 #17796 and seeed_xiao_esp32c5 support (IDF v5.5) #17912 .

So I wonder:

Can we agree on a more standardized approach on whether an only on-board LED will have the pin name "USER_LED" or "LED"?
Should we alias definitions, such that a board having only "LED_R", "LED_G" and "LED_B" still exposes one of them as "LED"? Or should machine.Pin be altered on those boards to expose a virtual pin "LED" that simultaneously drives all three?
Should pins like "RF_PWR" (necessary to connect an antenna to the WLAN-Interface) or "RF_SEL" (select which antenna port to connect, if any) be exposed as pin names at all? Or should e.g. "RF_PWR" be driven by a suitable modified WLAN module? Perhaps even customized with an optional parameter for an antenna selection defaulting to the internal antenna?
Should the BOOT-Button present on XIAO boards get a pin name on MCUs where that makes sense (e.g. ESP32)? Should it be called "BTN" or "BOOT" or something else?
Can/should any of these ideas be expanded beyond just XIAO boards? Lots of MicroPython boards have a boot button (or at least some non-reset button) and a unified way to read whatever button suitable for UI would be nice---then again, how does one extend that to the rp2 port where its special multiplexed functionality means it can only be polled (implemented as rp2.bootsel_button())? Should/could we have a machine.btn() poll function, or perhaps a module named "board" that provides something like that?
Why isn't machine.Pin.board or machine.Pin.cpu doccumented (in a place where I, conditioned by experience to ignore the pyboard (called that in the documentation but "stm32" in the repo?) port because it always seems to be unique and not applicable to ports I have used so far, would find it resp. consider it potentially relevant to other ports)?

1 reply

dhalbert Oct 21, 2025

Some guidelines we use for CircuitPython: https://learn.adafruit.com/how-to-add-a-new-board-to-circuitpython/pin-and-device-names

aliarifat · 2025-10-23T18:19:39Z

aliarifat
Oct 23, 2025

You’re seeing pin-naming collisions because the board aliases (A0-A8, D0-D71) map to MCU names (e.g., PA4) in the firmware. The string names for MCU pins lose the leading “P”. So Pin('A4') ends up referencing the board alias instead of MCU pin PA4.

The constructor Pin((port, pin)) raises a TypeError on the STM32 port in v1.26.0, so you can’t force access to MCU pins by tuple. That means you either use board names, or rebuild with changed aliases. You can patch pins.csv, remove the board alias, or enable a Pin.cpu namespace to restore direct MCU pin naming.

For future enhancement, it’d be helpful if MicroPython warned on name collisions or provided cpu: vs board: prefix to disambiguate. Also, see this link for context on custom STM32 board design: https://www.pcbway.com/blog/PCB_Design_Tutorial/Tutorial__How_to_Design_Your_Own_Custom_STM32_Microcontroller_Board.html

2 replies

pyramids Oct 23, 2025

Do we not already have the (largely undocumented) machine.Pin.board.csv_defined_pin_name and machine.Pin.cpu.port_defined_pin_name for what you look for as future enhancement?

aliarifat Oct 23, 2025

Yes, you’re right. MicroPython already has Pin.board and Pin.cpu. Pin.board uses names from pins.csv, while Pin.cpu accesses real MCU pins like PA4.

Many STM32 boards don’t enable both by default. Pyboard does, but Nucleo boards often don’t. To enable both, set these in mpconfigboard.h:

#define MICROPY_HW_ENABLE_PIN_DEFS (1)
#define MICROPY_HW_ENABLE_PIN_CPU (1)

Board pins vs MCU pins #18186

Uh oh!

Uh oh!

Replies: 6 comments · 6 replies

Uh oh!

victorallume Oct 1, 2025 Author

Uh oh!

Uh oh!

robert-hh Oct 2, 2025 Collaborator

Uh oh!

scruss Oct 2, 2025 Sponsor

Uh oh!

scruss Oct 7, 2025 Sponsor

Uh oh!

victorallume Oct 2, 2025 Author

Uh oh!

scruss Oct 2, 2025 Sponsor

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Replies: 6 comments 6 replies

victorallume
Oct 1, 2025
Author

robert-hh Oct 2, 2025
Collaborator

scruss
Oct 2, 2025
Sponsor

scruss Oct 7, 2025
Sponsor

victorallume
Oct 2, 2025
Author

scruss Oct 2, 2025
Sponsor