From 01c15a1d1b78773177ef630708f9cd5211f5c6ab Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Fri, 21 Oct 2022 12:50:27 -0400 Subject: [PATCH] catalog implementation limitations in documentation --- shared-bindings/alarm/SleepMemory.c | 2 + shared-bindings/alarm/__init__.c | 2 + shared-bindings/alarm/touch/TouchAlarm.c | 2 + shared-bindings/analogio/AnalogOut.c | 6 ++- shared-bindings/audiobusio/PDMIn.c | 41 +++++++++++---------- shared-bindings/busio/SPI.c | 5 ++- shared-bindings/busio/UART.c | 7 ++-- shared-bindings/countio/Edge.c | 5 ++- shared-bindings/microcontroller/Processor.c | 2 +- shared-bindings/os/__init__.c | 5 ++- shared-bindings/rtc/RTC.c | 3 ++ shared-bindings/watchdog/WatchDogMode.c | 2 + 12 files changed, 54 insertions(+), 28 deletions(-) diff --git a/shared-bindings/alarm/SleepMemory.c b/shared-bindings/alarm/SleepMemory.c index 318f2b772d..0304abfbcc 100644 --- a/shared-bindings/alarm/SleepMemory.c +++ b/shared-bindings/alarm/SleepMemory.c @@ -42,6 +42,8 @@ //| instance of :class:`SleepMemory` is available at //| :attr:`alarm.sleep_memory`. //| +//| **Limitations:** Not supported on RP2040. +//| //| Usage:: //| //| import alarm diff --git a/shared-bindings/alarm/__init__.c b/shared-bindings/alarm/__init__.c index 2682d64e5b..33e2c8b0b0 100644 --- a/shared-bindings/alarm/__init__.c +++ b/shared-bindings/alarm/__init__.c @@ -144,6 +144,8 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(alarm_light_sleep_until_alarms_obj, 1, MP_OB //| //| On some microcontrollers, some pins cannot remain in their original state for hardware reasons. //| +//| **Limitations:** ``preserve_dios`` is currently only available on Espressif. +//| //| .. note:: //| On Espressif chips, preserving pin settings during deep sleep may consume extra current. //| On ESP32, this was measured to be 250 uA or more. diff --git a/shared-bindings/alarm/touch/TouchAlarm.c b/shared-bindings/alarm/touch/TouchAlarm.c index 03f9ea4757..cce31e6ffe 100644 --- a/shared-bindings/alarm/touch/TouchAlarm.c +++ b/shared-bindings/alarm/touch/TouchAlarm.c @@ -39,6 +39,8 @@ //| //| :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, nRF, or RP2040. //| """ //| ... STATIC mp_obj_t alarm_touch_touchalarm_make_new(const mp_obj_type_t *type, diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index fa33944164..c8a109aa23 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -50,7 +50,11 @@ //| def __init__(self, pin: microcontroller.Pin) -> None: //| """Use the AnalogOut on the given pin. //| -//| :param ~microcontroller.Pin pin: the pin to output to""" +//| :param ~microcontroller.Pin pin: the pin to output to +//| +//| **Limitations:** Not available on nRF, RP2040, Spresense: there is no on-chip DAC. +//| Espressif: available only on ESP32 and ESP32-S2; other chips do not have a DAC. +//| """ //| ... STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, size_t n_kw, const mp_obj_t *args) { // check arguments diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index c44a640d6f..db19ab6edd 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -65,31 +65,32 @@ //| :param int oversample: Number of single bit samples to decimate into a final sample. Must be divisible by 8 //| :param float startup_delay: seconds to wait after starting microphone clock //| 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.""" - -//| """Record 8-bit unsigned samples to buffer:: +//| Must be in range 0.0-1.0 seconds. //| -//| import audiobusio -//| import board +//| **Limitations:** On SAMD and RP2040, 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. Not available on Espressif. //| -//| # Prep a buffer to record into -//| b = bytearray(200) -//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic: -//| mic.record(b, len(b)) +//| For example, to record 8-bit unsigned samples to a buffer:: //| -//| Record 16-bit unsigned samples to buffer:: +//| import audiobusio +//| import board //| -//| import audiobusio -//| import board +//| # Prep a buffer to record into +//| b = bytearray(200) +//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic: +//| mic.record(b, len(b)) //| -//| # Prep a buffer to record into. The array interface doesn't allow for -//| # constructing with a set size so we append to it until we have the size -//| # we want. -//| b = array.array("H") -//| for i in range(200): -//| b.append(0) -//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000, bit_depth=16) as mic: -//| mic.record(b, len(b))""" +//| To record 16-bit unsigned samples to a buffer:: +//| +//| import audiobusio +//| import board +//| +//| # Prep a buffer to record into. +//| b = array.array("H", [0] * 200) +//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000, bit_depth=16) as mic: +//| mic.record(b, len(b)) +//| """ //| ... STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) { #if !CIRCUITPY_AUDIOBUSIO_PDMIN diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 4826797ee2..badf80bf93 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -81,7 +81,10 @@ //| :param ~microcontroller.Pin clock: the pin to use for the clock. //| :param ~microcontroller.Pin MOSI: the Main Out Selected In pin. //| :param ~microcontroller.Pin MISO: the Main In Selected Out pin. -//| :param bool half_duplex: True when MOSI is used for bidirectional data. False when SPI is full-duplex or simplex.""" +//| :param bool half_duplex: True when MOSI is used for bidirectional data. False when SPI is full-duplex or simplex. +//| +//| **Limitations:** ``half_duplex`` is available only on STM; other chips do not have the hardware support. +//| """ //| ... diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 5663254897..eb4f15afe5 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -77,9 +77,10 @@ //| *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. //| -//| .. note:: RS485 support on i.MX and Raspberry Pi RP2040 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. +//| **Limitations:** RS485 is not supported on SAMD, nRF, Broadcom, Spresense, or STM. +//| On i.MX and Raspberry Pi RP2040 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. //| """ //| ... typedef struct { diff --git a/shared-bindings/countio/Edge.c b/shared-bindings/countio/Edge.c index 104b75a5be..ec96163b3e 100644 --- a/shared-bindings/countio/Edge.c +++ b/shared-bindings/countio/Edge.c @@ -47,7 +47,10 @@ MAKE_ENUM_VALUE(countio_edge_type, edge, RISE_AND_FALL, EDGE_RISE_AND_FALL); //| """Count the falling edges.""" //| //| RISE_AND_FALL: Edge -//| """Count the rising and falling edges.""" +//| """Count the rising and falling edges. +//| +//| **Limitations:** ``RISE_AND_FALL`` is not available to RP2040 due to hardware limitations. +//| """ //| MAKE_ENUM_MAP(countio_edge) { MAKE_ENUM_MAP_ENTRY(edge, RISE), diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c index 5a4a2556e1..16312c0c94 100644 --- a/shared-bindings/microcontroller/Processor.c +++ b/shared-bindings/microcontroller/Processor.c @@ -106,7 +106,7 @@ MP_PROPERTY_GETTER(mcu_processor_reset_reason_obj, //| //| Is `None` if the temperature is not available. //| -//| .. note :: On small SAMD21 builds without external flash, +//| **Limitations:** Not available on ESP32 or ESP32-S3. 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/os/__init__.c b/shared-bindings/os/__init__.c index 4049c04722..1260903203 100644 --- a/shared-bindings/os/__init__.c +++ b/shared-bindings/os/__init__.c @@ -235,7 +235,10 @@ MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync); //| def urandom(size: int) -> str: //| """Returns a string of *size* random bytes based on a hardware True Random -//| Number Generator. When not available, it will raise a NotImplementedError.""" +//| Number Generator. When not available, it will raise a NotImplementedError. +//| +//| **Limitations:** Not yet available on nRF. Not available on SAMD21 due to lack of hardware. +//| """ //| ... //| STATIC mp_obj_t os_urandom(mp_obj_t size_in) { diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c index 8e2d9e5e09..bf2b0915c4 100644 --- a/shared-bindings/rtc/RTC.c +++ b/shared-bindings/rtc/RTC.c @@ -93,6 +93,9 @@ MP_PROPERTY_GETSET(rtc_rtc_datetime_obj, //| """The RTC calibration value as an `int`. //| //| A positive value speeds up the clock and a negative value slows it down. +//| +//| **Limitations:** Calibration not supported on SAMD, nRF, RP240, Spresense, and STM. +//| //| Range and value is hardware specific, but one step is often approximately 1 ppm:: //| //| import rtc diff --git a/shared-bindings/watchdog/WatchDogMode.c b/shared-bindings/watchdog/WatchDogMode.c index b9ee82e186..c707054d27 100644 --- a/shared-bindings/watchdog/WatchDogMode.c +++ b/shared-bindings/watchdog/WatchDogMode.c @@ -34,6 +34,8 @@ //| RAISE: WatchDogMode //| """Raise an exception when the WatchDogTimer expires. //| +//| **Limitations:** ``RAISE`` mode is not supported on SAMD or RP2040. +//| //| :type WatchDogMode:""" //| //| RESET: WatchDogMode