docs/library: Document Pin.board and Pin.cpu attributes.

pi-anl · dpgeorge · commit 47fc0d5b8142 · 2026-04-07T13:58:11.000+10:00
Add an Attributes section to the machine.Pin reference describing the
Pin.board and Pin.cpu class attributes, their purpose, availability
across ports, and their role in string-based pin name resolution.

Signed-off-by: Andrew Leech &lt;andrew.leech@planetinnovation.com.au&gt;
diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst
@@ -244,6 +244,46 @@ The following methods are not part of the core Pin API and only implemented on c
 
    Availability: cc3200, esp32, esp8266, mimxrt, rp2, samd ports.
 
+Attributes
+----------
+
+.. data:: Pin.board
+
+   Contains pins named after the board's silkscreen or schematic labels.
+   For example ``Pin.board.X1`` or ``Pin.board.LED``.
+
+   Availability: alif, esp32, mimxrt, nrf, renesas-ra, rp2, samd, stm32 ports.
+
+.. data:: Pin.cpu
+
+   Contains the MCU pin names as given in the datasheet.
+   For example ``Pin.cpu.A0`` or ``Pin.cpu.GPIO0``.
+
+   Availability: alif, mimxrt, nrf, renesas-ra, rp2, samd, stm32 ports.
+
+Multiple board pins can refer to the same CPU pin. Not all ports provide
+both attributes, and the available names depend on the board definition. On
+the esp32 port only ``Pin.board`` is provided, and only for boards whose
+definition includes named pins (e.g. ``UM_TINYS3``, ``M5STACK_NANOC6``).
+Generic ESP32 boards do not define any board pin names.
+
+When constructing a ``Pin`` from a string name, the board pins are searched
+first, then the cpu pins::
+
+    from machine import Pin
+
+    # On a Pyboard v1.0, these all refer to the same physical pin:
+    p = Pin(Pin.board.X1, Pin.OUT)
+    p = Pin(Pin.cpu.A0, Pin.OUT)
+    p = Pin("X1", Pin.OUT)         # searches Pin.board, then Pin.cpu
+
+    # On a Raspberry Pi Pico W:
+    p = Pin(Pin.board.LED, Pin.OUT)
+    p = Pin("LED", Pin.OUT)
+
+Use ``help(Pin.board)`` or ``help(Pin.cpu)`` to list the pin names available
+on a particular board.
+
 Constants
 ---------
 
