Skip to content

Commit a4238d8

Browse files
kattnikattni
authored
Merge pull request #7097 from dhalbert/document-limitations
catalog implementation limitations in documentation
2 parents 87a0201 + 01c15a1 commit a4238d8

File tree

12 files changed

+54
-28
lines changed

12 files changed

+54
-28
lines changed

‎shared-bindings/alarm/SleepMemory.c

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@
4242
//| instance of :class:`SleepMemory` is available at
4343
//| :attr:`alarm.sleep_memory`.
4444
//|
45+
//| **Limitations:** Not supported on RP2040.
46+
//|
4547
//| Usage::
4648
//|
4749
//| import alarm

‎shared-bindings/alarm/__init__.c

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,8 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(alarm_light_sleep_until_alarms_obj, 1, MP_OB
146146
//|
147147
//| On some microcontrollers, some pins cannot remain in their original state for hardware reasons.
148148
//|
149+
//| **Limitations:** ``preserve_dios`` is currently only available on Espressif.
150+
//|
149151
//| .. note::
150152
//| On Espressif chips, preserving pin settings during deep sleep may consume extra current.
151153
//| On ESP32, this was measured to be 250 uA or more.

‎shared-bindings/alarm/touch/TouchAlarm.c

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@
3939
//|
4040
//| :param microcontroller.Pin pin: The pin to monitor. On some ports, the choice of pin
4141
//| may be limited due to hardware restrictions, particularly for deep-sleep alarms.
42+
//|
43+
//| **Limitations:** Not available on SAMD, nRF, or RP2040.
4244
//| """
4345
//| ...
4446
STATIC mp_obj_t alarm_touch_touchalarm_make_new(const mp_obj_type_t *type,

‎shared-bindings/analogio/AnalogOut.c

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,11 @@
5050
//| def __init__(self, pin: microcontroller.Pin) -> None:
5151
//| """Use the AnalogOut on the given pin.
5252
//|
53-
//| :param ~microcontroller.Pin pin: the pin to output to"""
53+
//| :param ~microcontroller.Pin pin: the pin to output to
54+
//|
55+
//| **Limitations:** Not available on nRF, RP2040, Spresense: there is no on-chip DAC.
56+
//| Espressif: available only on ESP32 and ESP32-S2; other chips do not have a DAC.
57+
//| """
5458
//| ...
5559
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) {
5660
// check arguments

‎shared-bindings/audiobusio/PDMIn.c

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -65,31 +65,32 @@
6565
//| :param int oversample: Number of single bit samples to decimate into a final sample. Must be divisible by 8
6666
//| :param float startup_delay: seconds to wait after starting microphone clock
6767
//| to allow microphone to turn on. Most require only 0.01s; some require 0.1s. Longer is safer.
68-
//| Must be in range 0.0-1.0 seconds."""
69-
70-
//| """Record 8-bit unsigned samples to buffer::
68+
//| Must be in range 0.0-1.0 seconds.
69+
//|
70+
//| **Limitations:** On SAMD and RP2040, supports only 8 or 16 bit mono input, with 64x oversampling.
71+
//| On nRF52840, supports only 16 bit mono input at 16 kHz; oversampling is fixed at 64x. Not provided
72+
//| on nRF52833 for space reasons. Not available on Espressif.
73+
//|
74+
//| For example, to record 8-bit unsigned samples to a buffer::
7175
//|
72-
//| import audiobusio
73-
//| import board
76+
//| import audiobusio
77+
//| import board
7478
//|
75-
//| # Prep a buffer to record into
76-
//| b = bytearray(200)
77-
//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic:
78-
//| mic.record(b, len(b))
79+
//| # Prep a buffer to record into
80+
//| b = bytearray(200)
81+
//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic:
82+
//| mic.record(b, len(b))
7983
//|
80-
//| Record 16-bit unsigned samples to buffer::
84+
//| To record 16-bit unsigned samples to a buffer::
8185
//|
82-
//| import audiobusio
83-
//| import board
86+
//| import audiobusio
87+
//| import board
8488
//|
85-
//| # Prep a buffer to record into. The array interface doesn't allow for
86-
//| # constructing with a set size so we append to it until we have the size
87-
//| # we want.
88-
//| b = array.array("H")
89-
//| for i in range(200):
90-
//| b.append(0)
91-
//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000, bit_depth=16) as mic:
92-
//| mic.record(b, len(b))"""
89+
//| # Prep a buffer to record into.
90+
//| b = array.array("H", [0] * 200)
91+
//| with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000, bit_depth=16) as mic:
92+
//| mic.record(b, len(b))
93+
//| """
9394
//| ...
9495
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) {
9596
#if !CIRCUITPY_AUDIOBUSIO_PDMIN

‎shared-bindings/busio/SPI.c

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,10 @@
8181
//| :param ~microcontroller.Pin clock: the pin to use for the clock.
8282
//| :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
8383
//| :param ~microcontroller.Pin MISO: the Main In Selected Out pin.
84-
//| :param bool half_duplex: True when MOSI is used for bidirectional data. False when SPI is full-duplex or simplex."""
84+
//| :param bool half_duplex: True when MOSI is used for bidirectional data. False when SPI is full-duplex or simplex.
85+
//|
86+
//| **Limitations:** ``half_duplex`` is available only on STM; other chips do not have the hardware support.
87+
//| """
8588
//| ...
8689

8790

‎shared-bindings/busio/UART.c

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,10 @@
7777
//| *New in CircuitPython 4.0:* ``timeout`` has incompatibly changed units from milliseconds to seconds.
7878
//| The new upper limit on ``timeout`` is meant to catch mistaken use of milliseconds.
7979
//|
80-
//| .. note:: RS485 support on i.MX and Raspberry Pi RP2040 is implemented in software.
81-
//| The timing for the ``rs485_dir`` pin signal is done on a best-effort basis, and may not meet
82-
//| RS485 specifications intermittently.
80+
//| **Limitations:** RS485 is not supported on SAMD, nRF, Broadcom, Spresense, or STM.
81+
//| On i.MX and Raspberry Pi RP2040 support is implemented in software:
82+
//| The timing for the ``rs485_dir`` pin signal is done on a best-effort basis, and may not meet
83+
//| RS485 specifications intermittently.
8384
//| """
8485
//| ...
8586
typedef struct {

‎shared-bindings/countio/Edge.c

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,10 @@ MAKE_ENUM_VALUE(countio_edge_type, edge, RISE_AND_FALL, EDGE_RISE_AND_FALL);
4747
//| """Count the falling edges."""
4848
//|
4949
//| RISE_AND_FALL: Edge
50-
//| """Count the rising and falling edges."""
50+
//| """Count the rising and falling edges.
51+
//|
52+
//| **Limitations:** ``RISE_AND_FALL`` is not available to RP2040 due to hardware limitations.
53+
//| """
5154
//|
5255
MAKE_ENUM_MAP(countio_edge) {
5356
MAKE_ENUM_MAP_ENTRY(edge, RISE),

‎shared-bindings/microcontroller/Processor.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ MP_PROPERTY_GETTER(mcu_processor_reset_reason_obj,
106106
//|
107107
//| Is `None` if the temperature is not available.
108108
//|
109-
//| .. note :: On small SAMD21 builds without external flash,
109+
//| **Limitations:** Not available on ESP32 or ESP32-S3. On small SAMD21 builds without external flash,
110110
//| the reported temperature has reduced accuracy and precision, to save code space.
111111
//| """
112112
STATIC mp_obj_t mcu_processor_get_temperature(mp_obj_t self) {

‎shared-bindings/os/__init__.c

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,10 @@ MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync);
235235

236236
//| def urandom(size: int) -> str:
237237
//| """Returns a string of *size* random bytes based on a hardware True Random
238-
//| Number Generator. When not available, it will raise a NotImplementedError."""
238+
//| Number Generator. When not available, it will raise a NotImplementedError.
239+
//|
240+
//| **Limitations:** Not yet available on nRF. Not available on SAMD21 due to lack of hardware.
241+
//| """
239242
//| ...
240243
//|
241244
STATIC mp_obj_t os_urandom(mp_obj_t size_in) {

‎shared-bindings/rtc/RTC.c

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,9 @@ MP_PROPERTY_GETSET(rtc_rtc_datetime_obj,
9393
//| """The RTC calibration value as an `int`.
9494
//|
9595
//| A positive value speeds up the clock and a negative value slows it down.
96+
//|
97+
//| **Limitations:** Calibration not supported on SAMD, nRF, RP240, Spresense, and STM.
98+
//|
9699
//| Range and value is hardware specific, but one step is often approximately 1 ppm::
97100
//|
98101
//| import rtc

‎shared-bindings/watchdog/WatchDogMode.c

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
//| RAISE: WatchDogMode
3535
//| """Raise an exception when the WatchDogTimer expires.
3636
//|
37+
//| **Limitations:** ``RAISE`` mode is not supported on SAMD or RP2040.
38+
//|
3739
//| :type WatchDogMode:"""
3840
//|
3941
//| RESET: WatchDogMode

0 commit comments

Comments
 (0)