From 81e65055106f3ad232c5d3d6fa5b18464458ff53 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Thu, 19 Nov 2026 16:34:27 -0500 Subject: [PATCH 1/2] Fix port-support lists and other documentation Fix Limitations docstrings that left out ports or chips or named the wrong ones, and list where a feature is available where practical. Change RP2040-only notes that also apply to RP2350 to say RP2xxx. Warn against holding busio I2C and SPI locks for a long time, which can starve WiFi and USB on Espressif. Document which errno codes are available on which builds, with code comments next to the errno lists pointing to errno.rst. Fixes #11877. Fixes #10561. Fixes #9737. Co-Authored-By: Claude Opus 5.5 --- docs/library/errno.rst | 16 +++++++++++++++- ports/atmel-samd/mpconfigport.h | 1 + py/moderrno.c | 1 + shared-bindings/alarm/touch/TouchAlarm.c | 3 +-- shared-bindings/analogio/AnalogOut.c | 5 +++-- shared-bindings/audiobusio/PDMIn.c | 2 +- shared-bindings/busio/I2C.c | 6 ++++++ shared-bindings/busio/SPI.c | 6 ++++++ shared-bindings/busio/UART.c | 4 ++-- shared-bindings/countio/Counter.c | 2 +- shared-bindings/countio/Edge.c | 2 +- shared-bindings/microcontroller/Processor.c | 3 ++- shared-bindings/rtc/RTC.c | 2 +- shared-bindings/wifi/Radio.c | 12 +++++++----- 14 files changed, 48 insertions(+), 17 deletions(-) diff --git a/docs/library/errno.rst b/docs/library/errno.rst index 10ecd4d2c79..89f09741d2e 100644 --- a/docs/library/errno.rst +++ b/docs/library/errno.rst @@ -7,7 +7,21 @@ |see_cpython_module| :mod:`python:errno`. This module provides access to symbolic error codes for `OSError` exception. -Some codes are not available on the smallest CircuitPython builds, such as SAMD21, for space reasons. +Most SAMD21 boards, including all SAMD21 boards without external flash, do not include :mod:`errno`. +A few other small builds also do not include it. +To check a particular board, see the :ref:`module-support-matrix`. + +The available codes depend on the build: + +* Most builds provide ``EACCES``, ``EADDRINUSE``, ``EAGAIN``, ``EALREADY``, ``EBADF``, + ``EBUSY``, ``ECONNABORTED``, ``ECONNREFUSED``, ``ECONNRESET``, ``EEXIST``, + ``EHOSTUNREACH``, ``EINPROGRESS``, ``EINVAL``, ``EIO``, ``EISDIR``, ``ENOBUFS``, + ``ENODEV``, ``ENOENT``, ``ENOMEM``, ``ENOSPC``, ``ENOTCONN``, ``EOPNOTSUPP``, + ``EPERM``, ``EROFS``, and ``ETIMEDOUT``. +* SAMD21 builds that include :mod:`errno` provide only ``EACCES``, ``EAGAIN``, ``EEXIST``, + ``EINVAL``, ``EIO``, ``EISDIR``, ``ENODEV``, ``ENOENT``, ``ENOMEM``, and ``EPERM``. + +``dir(errno)`` lists the codes available on a particular board. Constants --------- diff --git a/ports/atmel-samd/mpconfigport.h b/ports/atmel-samd/mpconfigport.h index d6d21c35817..715b0c4266f 100644 --- a/ports/atmel-samd/mpconfigport.h +++ b/ports/atmel-samd/mpconfigport.h @@ -27,6 +27,7 @@ #define MICROPY_PY_REVERSE_SPECIAL_METHODS (0) #define MICROPY_PY_COLLECTIONS_DEQUE (0) #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (0) +// docs/library/errno.rst lists these names. Update it if this list changes. #define MICROPY_PY_ERRNO_LIST \ X(EPERM) \ X(ENOENT) \ diff --git a/py/moderrno.c b/py/moderrno.c index e70b89bce5a..8ea6cdfd65c 100644 --- a/py/moderrno.c +++ b/py/moderrno.c @@ -36,6 +36,7 @@ // specific port's needs. If it's not defined then we provide a default. #ifndef MICROPY_PY_ERRNO_LIST // CIRCUITPY-CHANGE: add ENOSPC and EROFS, because they are in mp_common_errno_to_str(). +// CIRCUITPY-CHANGE: docs/library/errno.rst lists these names. Update it if this list changes. #define MICROPY_PY_ERRNO_LIST \ X(EPERM) \ X(ENOENT) \ diff --git a/shared-bindings/alarm/touch/TouchAlarm.c b/shared-bindings/alarm/touch/TouchAlarm.c index eac3f37b8f4..09a27bfd29d 100644 --- a/shared-bindings/alarm/touch/TouchAlarm.c +++ b/shared-bindings/alarm/touch/TouchAlarm.c @@ -20,8 +20,7 @@ //| :param microcontroller.Pin pin: The pin to monitor. On some ports, the choice of pin //| may be limited due to hardware restrictions, particularly for deep-sleep alarms. //| -//| **Limitations:** Not available on SAMD, Nordic, or RP2040. -//| On Espressif, only available on ESP32, ESP32-S2, ESP32-S3, and ESP32-P4. +//| **Limitations:** Available only on Espressif ESP32, ESP32-S2, ESP32-S3, and ESP32-P4. //| """ //| ... //| diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 24f6fb87d3a..c6b27c7a560 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -18,8 +18,9 @@ //| class AnalogOut: //| """Output analog values (a specific voltage). //| -//| **Limitations:** Not available on Nordic, RP2040, Spresense, as there is no on-chip DAC. -//| On Espressif, available only on ESP32 and ESP32-S2; other chips do not have a DAC. +//| **Limitations:** Available only on chips with an on-chip DAC: +//| SAMD21, SAMD51, ESP32, ESP32-S2, STM32F405, STM32F407, and EFR32MG24. +//| On Zephyr-based boards, available only if the board defines a DAC. //| On ESP32-S2 boards, GPIO18 (DAC2) is often connected to a pull-up resistor, which causes //| `unexpected output values in the lower part of the output range //| `_. diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 79fb6bff1e4..b4289ed1313 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -47,7 +47,7 @@ //| to allow microphone to turn on. Most require only 0.01s; some require 0.1s. Longer is safer. //| Must be in range 0.0-1.0 seconds. //| -//| **Limitations:** On SAMD and RP2040, supports only 8 or 16 bit mono input, with 64x oversampling. +//| **Limitations:** On SAMD and RP2xxx, supports only 8 or 16 bit mono input, with 64x oversampling. //| On nRF52840, supports only 16 bit mono input at 16 kHz; oversampling is fixed at 64x. Not provided //| on nRF52833 for space reasons. On Espressif, only available on ESP32, ESP32-S3, and ESP32-P4. //| diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index b619dfa1140..de2d44f1b19 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -157,6 +157,12 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); //| def try_lock(self) -> bool: //| """Attempts to grab the I2C lock. Returns True on success. //| +//| .. warning:: Ideally, release the lock with `unlock()` as soon as you are done with the bus. +//| Use :class:`~adafruit_bus_device.I2CDevice`, which holds the lock only +//| during each transaction. +//| On Espressif boards, holding the lock for a long time while using WiFi +//| can starve the WiFi and USB tasks, and the board may hang or restart in safe mode. +//| //| :return: True when lock has been grabbed //| :rtype: bool""" //| ... diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 6411fdaa627..e876e7c2094 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -208,6 +208,12 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); //| def try_lock(self) -> bool: //| """Attempts to grab the SPI lock. Returns True on success. //| +//| .. warning:: Ideally, release the lock with `unlock()` as soon as you are done with the bus. +//| Use :class:`~adafruit_bus_device.SPIDevice`, which holds the lock only +//| during each transaction. +//| On Espressif boards, holding the lock for a long time while using WiFi +//| can starve the WiFi and USB tasks, and the board may hang or restart in safe mode. +//| //| :return: True when lock has been grabbed //| :rtype: bool""" //| ... diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index da05b226fd7..f579d15ae38 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -77,8 +77,8 @@ //| *New in CircuitPython 4.0:* ``timeout`` has incompatibly changed units from milliseconds to seconds. //| The new upper limit on ``timeout`` is meant to catch mistaken use of milliseconds. //| -//| **Limitations:** RS485 is not supported on SAMD, Nordic, Spresense, or STM. -//| On i.MX and Raspberry Pi RP2040, RS485 support is implemented in software: +//| **Limitations:** RS485 is available only on Espressif, i.MX, and Raspberry Pi RP2xxx. +//| On i.MX and RP2xxx, RS485 support is implemented in software: //| The timing for the ``rs485_dir`` pin signal is done on a best-effort basis, and may not meet //| RS485 specifications intermittently. //| """ diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c index 9f8bd00645c..9c03098e72b 100644 --- a/shared-bindings/countio/Counter.c +++ b/shared-bindings/countio/Counter.c @@ -47,7 +47,7 @@ //| pin_counter.reset() //| print(pin_counter.count) //| -//| **Limitations:** On RP2040, `Counter` uses the PWM peripheral, and +//| **Limitations:** On RP2xxx, `Counter` uses the PWM peripheral, and //| is limited to using PWM channel B pins due to hardware restrictions. //| See the pin assignments for your board to see which pins can be used. //| """ diff --git a/shared-bindings/countio/Edge.c b/shared-bindings/countio/Edge.c index 9ace6a923ff..7453720d12a 100644 --- a/shared-bindings/countio/Edge.c +++ b/shared-bindings/countio/Edge.c @@ -30,7 +30,7 @@ MAKE_ENUM_VALUE(countio_edge_type, edge, RISE_AND_FALL, EDGE_RISE_AND_FALL); //| RISE_AND_FALL: Edge //| """Count the rising and falling edges. //| -//| **Limitations:** ``RISE_AND_FALL`` is not available to RP2040 due to hardware limitations. +//| **Limitations:** ``RISE_AND_FALL`` is not available on RP2xxx due to hardware limitations. //| """ //| //| diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c index 9a6e1938e80..e0fd68be2ad 100644 --- a/shared-bindings/microcontroller/Processor.c +++ b/shared-bindings/microcontroller/Processor.c @@ -132,7 +132,8 @@ MP_PROPERTY_GETTER(mcu_processor_reset_reason_obj, //| //| Is `None` if the temperature is not available. //| -//| **Limitations:** Not available on ESP32 or ESP32-S3. On small SAMD21 builds without external flash, +//| **Limitations:** Not available on ESP32, MAX32, Spresense, STM chips other than STM32F4, +//| or Zephyr-based boards. On small SAMD21 builds without external flash, //| the reported temperature has reduced accuracy and precision, to save code space. //| """ static mp_obj_t mcu_processor_get_temperature(mp_obj_t self) { diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c index b0cf3ce3caa..a65db08cbb2 100644 --- a/shared-bindings/rtc/RTC.c +++ b/shared-bindings/rtc/RTC.c @@ -78,7 +78,7 @@ MP_PROPERTY_GETSET(rtc_rtc_datetime_obj, //| //| A positive value speeds up the clock and a negative value slows it down. //| -//| **Limitations:** Calibration not supported on SAMD, Nordic, RP2040, Spresense, and STM. +//| **Limitations:** Calibration is supported only on SAMD. On other ports, setting it raises `NotImplementedError`. //| //| Range and value is hardware specific, but one step is often approximately 1 ppm:: //| diff --git a/shared-bindings/wifi/Radio.c b/shared-bindings/wifi/Radio.c index f94c5f3bbd1..5dc58d0510b 100644 --- a/shared-bindings/wifi/Radio.c +++ b/shared-bindings/wifi/Radio.c @@ -147,7 +147,8 @@ MP_PROPERTY_GETSET(wifi_radio_hostname_obj, //| """MAC address for the station. When the address is altered after interface is connected //| the changes would only be reflected once the interface reconnects. //| -//| **Limitations:** Not settable on RP2040 CYW43 boards, such as Pi Pico W. +//| **Limitations:** Settable on Espressif. +//| Not settable on Raspberry Pi RP2xxx CYW43 boards, such as Pico W and Pico 2 W. //| """ @@ -232,7 +233,8 @@ MP_PROPERTY_GETSET(wifi_radio_power_management_obj, //| """MAC address for the AP. When the address is altered after interface is started //| the changes would only be reflected once the interface restarts. //| -//| **Limitations:** Not settable on RP2040 CYW43 boards, such as Pi Pico W. +//| **Limitations:** Settable on Espressif. +//| Not settable on Raspberry Pi RP2xxx CYW43 boards, such as Pico W and Pico 2 W. //| """ //| static mp_obj_t wifi_radio_get_mac_address_ap(mp_obj_t self_in) { @@ -277,7 +279,7 @@ MP_PROPERTY_GETTER(wifi_radio_mac_address_ap_obj, //| //| .. note:: //| -//| In the raspberrypi port (RP2040 CYW43), ``start_channel`` and ``stop_channel`` are ignored. +//| In the raspberrypi port (RP2xxx CYW43), ``start_channel`` and ``stop_channel`` are ignored. //| """ //| ... //| @@ -378,7 +380,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(wifi_radio_stop_station_obj, wifi_radio_stop_station); //| //| .. note:: //| -//| In the raspberrypi port (RP2040 CYW43), ``max_connections`` is ignored +//| In the raspberrypi port (RP2xxx CYW43), ``max_connections`` is ignored //| and only 2.4 GHz channels (1-13) are accepted. //| """ //| ... @@ -635,7 +637,7 @@ MP_PROPERTY_GETTER(wifi_radio_ipv4_subnet_ap_obj, //| //| .. note:: //| -//| In the raspberrypi port (RP2040 CYW43), the access point needs to be started before the IP v4 address can be set. +//| In the raspberrypi port (RP2xxx CYW43), the access point needs to be started before the IP v4 address can be set. //| """ //| ... //| From d135c7a9600f9719cc6f4783a07dc6b06ea8824f Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Fri, 20 Nov 2026 10:37:03 -0500 Subject: [PATCH 2/2] busio.I2C: note probe() and scan() limits on Zephyr nRF at 400 kHz On Zephyr-based nRF boards, a NACKed zero-length write can end the next transfer early when the bus runs at 400 kHz, so probe() and scan() can give wrong results. The cause is in nrfx; see #11604. Co-Authored-By: Claude Opus 5.5 --- shared-bindings/busio/I2C.c | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index de2d44f1b19..c2288135da2 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -115,6 +115,10 @@ static void check_lock(busio_i2c_obj_t *self) { //| def probe(self, address: int) -> bool: //| """Check if a device at the specified address responds. //| +//| **Limitations:** On Zephyr-based nRF boards, `probe()` does not work reliably +//| at 400 kHz. Use 100 kHz. +//| See `#11604 `_. +//| //| :param int address: 7-bit device address //| :return: ``True`` if a device at ``address`` responds; ``False`` otherwise //| :rtype: bool""" @@ -134,6 +138,10 @@ MP_DEFINE_CONST_FUN_OBJ_2(busio_i2c_probe_obj, busio_i2c_probe); //| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a //| list of those that respond. //| +//| **Limitations:** On Zephyr-based nRF boards, `scan()` does not work reliably +//| at 400 kHz. Use 100 kHz. +//| See `#11604 `_. +//| //| :return: List of device ids on the I2C bus //| :rtype: list""" //| ...