Summary

This adds I2C.scl() and I2C.sda(), which return the machine.Pin objects a bus is using.

The motivating use case is I2C bus recovery. In the Arduino Modulino package, Modulino nodes have their own MCU, so resetting the host board or hot-swapping a node mid-transaction can leave the bus stuck with a peripheral holding SDA low. Recovering from that means driving SCL for up to nine cycles while SDA is held high, then re-initialising the bus object. To do this the code has to know which pins the bus is on, and there is currently no API that answers that question. The library just receives an I2C object. This way we don't have to ask the library users to explicitly provide (and know) the pins used for the I2C bus. (The target audience is beginners).

The workaround in use today is to take repr() of the I2C object and pull the pin names out with a regular expression. That is expensive (it formats and allocates a string on a code path that runs at startup), and it depends on the exact layout of a debug representation that is port-specific and not an API contract.

The methods are backed by two new optional entries in the mp_machine_i2c_p_t
protocol struct:

• machine.SoftI2C implements them on all ports.
• Hardware I2C implements them on esp32, renesas-ra, rp2, samd and stm32.
• Hardware I2C on the remaining ports returns None, which is documented.

To keep the shared code portable this also adds mp_hal_pin_to_obj() to the C-level
pin HAL of every port that builds extmod/machine_i2c.c with SoftI2C enabled. See
Trade-offs and Alternatives for why that is needed.

docs/library/machine.I2C.rst documents both methods, including the None case and
which ports report hardware pins.

Testing

A new hardware test, tests/extmod_hardware/machine_i2c_pins.py, checks that both
SoftI2C and hardware I2C report their pins, that the reported pins follow a subsequent
init(), and that a port which does not report hardware pins returns None
consistently for both. It needs no external wiring, and selects pins per target the
same way extmod_hardware/machine_i2c_target.py does.

Tested on hardware, 3/3 tests passing on each, covering all three ways a port can
represent a pin:

Beyond the test, the returned objects were checked to be the same canonical Pin
objects reachable by name on each board - e.g. on the Nano RP2040 Connect,
I2C(1).scl() is Pin('A1'), and on the Nicla Vision the hardware buses report
Pin(Pin.cpu.B8, mode=ALT_OPEN_DRAIN, pull=PULL_UP, alt=AF4_I2C1) and friends for
I2C1/2/3, matching the board definition.

Build-tested only: samd (ADAFRUIT_ITSYBITSY_M4_EXPRESS) and unix.

Not tested at all, and where I would appreciate CI or another contributor's boards:
esp8266, nrf, mimxrt, alif, zephyr, psoc-edge. These receive only the one-line
mp_hal_pin_to_obj addition. For five of them it is the same pointer cast that stm32
and renesas-ra use, both of which are hardware-tested. esp8266 is the one that
differs materially - it indexes the port's pin table rather than casting a pointer -
and I have no toolchain for it here, so it is unverified. nrf could not be built
locally either (its build needs SoftDevice headers that make submodules does not
fetch).

Trade-offs and Alternatives

Code size. Measured on PYBV11, the whole series costs +104 bytes of text, with
no change to data or bss (376360 -> 376464). Per-symbol on that build: the two shared
dispatchers in extmod are 20 bytes each, the two stm32 accessors are 4 bytes each
(the HAL conversion is a cast, so the compiler emits almost nothing), the two function
objects are 8 bytes each, plus two locals-dict entries and two protocol-struct slots.
Ports with integer pin types pay ~32 bytes more for the mp_hal_pin_to_obj lookup
function. Every port pays for the two dict entries even if its hardware I2C returns
None; that could be avoided with a config option, but a two-entry gate did not seem
worth the mpconfig surface.

Alternative considered and rejected: standardising repr() instead. Since the
existing workaround parses repr(), one option is to make that output complete and
uniform across ports rather than add an API. Rejected for three reasons. First,
repr() is a debug representation, not an API contract - code that parses it relies on
something no port promises to keep stable, and changing the output to standardise it
would itself break anyone already parsing it. Second, it is not merely inconsistent, it
is absent: mimxrt prints I2C(%u, freq=%u, timeout=%u) and zephyr prints
<I2C %s>, neither of which contains the pins - and neither port stores the pins in
its I2C object, so completing their repr() needs exactly the same underlying change
as implementing the accessors. Third, where pins are printed the formats differ
(integers on esp32/rp2, quoted names on stm32/renesas-ra/alif/samd), so a parser still
needs per-port handling, and it pays string formatting, allocation and regex matching
at runtime for information the object already holds.

API shape: two methods, rather than one config()/dict getter or attributes.
Per-parameter accessor methods are what machine peripheral classes already use -
PWM.freq(), PWM.duty_u16(), PWM.duty_ns() - whereas the config('param') form
belongs to the network and Bluetooth classes (WLAN.config(), BLE.config()). Two
methods therefore follow the convention for this class, reuse the existing scl/sda
QSTRs so they add no new strings, and return the pin objects without allocating; a dict
would build and allocate one on every call, on a path that may run precisely when a bus
is already wedged.

The counter-argument is real, though: constructors take more than these two parameters
(id, freq, timeout), and a general getter would scale to all of them where adding
one method per parameter does not. I think that is worth doing as its own discussion
rather than here, because it is a cross-class decision - SPI, UART and PWM would
all want the same shape - and because scl/sda are the parameters with a concrete
use case today. If maintainers would rather have config() on machine classes, I am
happy to rework this on top of that decision. Either way the API shape set here is a
precedent for the other bus classes, so it is worth settling explicitly.

Why not store mp_obj_t in the SoftI2C object and avoid the conversion entirely?
mp_machine_soft_i2c_obj_t stores mp_hal_pin_obj_t because the bit-banging code
calls mp_hal_pin_od_low(), mp_hal_pin_read() and friends on it once per bit.
Storing the Python object would move a conversion into that hot path, change a struct that is public to every
port's soft-I2C code, and add GC-visible references to a struct that has none today.

Why is mp_hal_pin_to_obj a macro on some ports and a function on others? It
follows what mp_hal_pin_obj_t actually is, and matches how each port already defines
mp_hal_get_pin_obj in the same header:

• Where a pin is already a pointer to the pin object (stm32, renesas-ra, nrf, mimxrt,
  alif, zephyr), the conversion is a pure cast - MP_OBJ_FROM_PTR - so a macro emits
  no code at all.
• Where a pin is an integer (esp32, rp2, samd), it needs a bounds-checked table lookup
  that raises on failure. That cannot go in the header: the tables and helpers are
  declared in machine_pin.h / pin_af.h, which mphalport.h does not include, and
  mphalport.h is pulled in extremely early by nearly every file - adding those
  includes invites include cycles. The body also raises, which would drag
  py/runtime.h into every consumer.
• esp8266 is integer-typed but stays a macro: its pin table is already visible in
  esp_mphal.h, the table index equals phys_port for every valid entry, pin ids only
  ever arrive from the validating mp_obj_get_pin(), and that port is the most
  ROM-constrained in the tree.

Each port's helper therefore raises that port's own existing message for a bad pin
("invalid pin" on esp32/rp2, "not a Pin" on samd, via pin_find_by_id()) rather than a
new uniform one. In practice these paths are unreachable through this feature, since
stored pins always came from mp_hal_get_pin_obj() or a board's compile-time defaults;
the checks are for future callers of the HAL helper.

The cost of the mixed macro/function form is that macros get no type checking, and a
new port that omits the definition finds out only when something compiles
machine_i2c.c with SoftI2C enabled - a loud build error rather than silent breakage.
Making all ten real functions would be more uniform, at the price of adding a .c
definition to six ports that currently need no code; happy to change it if preferred.

Hardware I2C returning None on some ports. Filling the gap
is not uniform work: alif already stores its pins and would be the same two-liner, but
mimxrt and zephyr do not keep the pins in their I2C object (so it means adding fields or
recovering them from the peripheral/devicetree config), and nrf and psoc-edge have no
ports/*/machine_i2c.c at all. Since I cannot test any of those boards, I would rather
leave them to people who can than add unverified code. The alternative - raising
NotImplementedError instead of returning None - would make the gap louder but costs
an error message on every affected port; happy to switch if that is preferred.

Generative AI

I used generative AI tools when creating this PR, but a human has checked the
code and is responsible for the code and the description above.