Skip to content

Commit 47fc0d5

Browse files
pi-anldpgeorge
authored andcommitted
docs/library: Document Pin.board and Pin.cpu attributes.
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 <andrew.leech@planetinnovation.com.au>
1 parent c16a484 commit 47fc0d5

1 file changed

Lines changed: 40 additions & 0 deletions

File tree

docs/library/machine.Pin.rst

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,46 @@ The following methods are not part of the core Pin API and only implemented on c
244244

245245
Availability: cc3200, esp32, esp8266, mimxrt, rp2, samd ports.
246246

247+
Attributes
248+
----------
249+
250+
.. data:: Pin.board
251+
252+
Contains pins named after the board's silkscreen or schematic labels.
253+
For example ``Pin.board.X1`` or ``Pin.board.LED``.
254+
255+
Availability: alif, esp32, mimxrt, nrf, renesas-ra, rp2, samd, stm32 ports.
256+
257+
.. data:: Pin.cpu
258+
259+
Contains the MCU pin names as given in the datasheet.
260+
For example ``Pin.cpu.A0`` or ``Pin.cpu.GPIO0``.
261+
262+
Availability: alif, mimxrt, nrf, renesas-ra, rp2, samd, stm32 ports.
263+
264+
Multiple board pins can refer to the same CPU pin. Not all ports provide
265+
both attributes, and the available names depend on the board definition. On
266+
the esp32 port only ``Pin.board`` is provided, and only for boards whose
267+
definition includes named pins (e.g. ``UM_TINYS3``, ``M5STACK_NANOC6``).
268+
Generic ESP32 boards do not define any board pin names.
269+
270+
When constructing a ``Pin`` from a string name, the board pins are searched
271+
first, then the cpu pins::
272+
273+
from machine import Pin
274+
275+
# On a Pyboard v1.0, these all refer to the same physical pin:
276+
p = Pin(Pin.board.X1, Pin.OUT)
277+
p = Pin(Pin.cpu.A0, Pin.OUT)
278+
p = Pin("X1", Pin.OUT) # searches Pin.board, then Pin.cpu
279+
280+
# On a Raspberry Pi Pico W:
281+
p = Pin(Pin.board.LED, Pin.OUT)
282+
p = Pin("LED", Pin.OUT)
283+
284+
Use ``help(Pin.board)`` or ``help(Pin.cpu)`` to list the pin names available
285+
on a particular board.
286+
247287
Constants
248288
---------
249289

0 commit comments

Comments
 (0)