circuitpython-stubs 10.3.0a2__tar.gz → 10.3.0a4__tar.gz

circuitpython_stubs-10.3.0a4/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: circuitpython-stubs
+Version: 10.3.0a4
+Summary: PEP 561 type stubs for CircuitPython
+Home-page: https://github.com/adafruit/circuitpython
+Author-email: circuitpython@adafruit.com
+Maintainer: CircuitPythonistas
+Maintainer-email: circuitpython@adafruit.com
+License: MIT
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: license
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: summary

circuitpython_stubs-10.3.0a4/alarm/__init__.pyi

@@ -0,0 +1,177 @@
+"""Alarms and sleep
+
+Provides alarms that trigger based on time intervals or on external events, such as pin
+changes.
+The program can simply wait for these alarms, or go to sleep and be awoken when they trigger.
+
+There are two supported levels of sleep: light sleep and deep sleep.
+
+Light sleep keeps sufficient state so the program can resume after sleeping.
+It does not shut down WiFi, BLE, or other communications, or ongoing activities such
+as audio playback. It reduces power consumption to the extent possible that leaves
+these continuing activities running. In some cases there may be no decrease in power consumption.
+
+Deep sleep shuts down power to nearly all of the microcontroller including the CPU and RAM. This can save
+a more significant amount of power, but CircuitPython must restart ``code.py`` from the beginning when
+awakened.
+
+For both light sleep and deep sleep, if CircuitPython is connected to a host computer,
+maintaining the connection takes priority and power consumption may not be reduced.
+
+For more information about working with alarms and light/deep sleep in CircuitPython,
+see `this Learn guide <https://learn.adafruit.com/deep-sleep-with-circuitpython>`_.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence, overload
+
+import circuitpython_typing
+import digitalio
+from circuitpython_typing import ReadableBuffer
+
+sleep_memory: SleepMemory
+"""Memory that persists during deep sleep.
+This object is the sole instance of `alarm.SleepMemory`."""
+wake_alarm: Optional[circuitpython_typing.Alarm]
+"""The most recently triggered alarm. If CircuitPython was sleeping, the alarm that woke it from sleep.
+If no alarm occurred since the last hard reset or soft restart, value is ``None``.
+"""
+
+def light_sleep_until_alarms(
+    *alarms: circuitpython_typing.Alarm,
+) -> circuitpython_typing.Alarm:
+    """Go into a light sleep until awakened one of the alarms. The alarm causing the wake-up
+    is returned, and is also available as `alarm.wake_alarm`.
+
+    If no alarms are specified, return immediately.
+
+    **If CircuitPython is connected to a host computer, the connection will be maintained,
+    and the microcontroller may not actually go into a light sleep.**
+    This allows the user to interrupt an existing program with ctrl-C,
+    and to edit the files in CIRCUITPY, which would not be possible in true light sleep.
+    Thus, to use light sleep and save significant power,
+    it may be necessary to disconnect from the host.
+    """
+    ...
+
+def exit_and_deep_sleep_until_alarms(
+    *alarms: circuitpython_typing.Alarm,
+    preserve_dios: Sequence[digitalio.DigitalInOut] = (),
+) -> None:
+    """Exit the program and go into a deep sleep, until awakened by one of the alarms.
+    This function does not return.
+
+    When awakened, the microcontroller will restart and will run ``boot.py`` and ``code.py``
+    from the beginning.
+
+    After restart, an alarm *equivalent* to the one that caused the wake-up
+    will be available as `alarm.wake_alarm`.
+    Its type and/or attributes may not correspond exactly to the original alarm.
+    For time-base alarms, currently, an `alarm.time.TimeAlarm()` is created.
+
+    If no alarms are specified, the microcontroller will deep sleep until reset.
+
+    You cannot initiate a deep sleep from the REPL.
+    You must call `exit_and_deep_sleep_until_alarms()` from a program file.
+
+    :param circuitpython_typing.Alarm alarms: the alarms that can wake the microcontroller.
+    :param Sequence[digitalio.DigitalInOut] preserve_dios: A sequence of `DigitalInOut` objects
+      whose state should be preserved during deep sleep.
+      If a `DigitalInOut` in the sequence is set to be an output,
+      its current `DigitalInOut.value` (``True`` or ``False``)
+      will be preserved during the deep sleep.
+      If a `DigitalInOut` in the sequence is set to be an input,
+      its current `DigitalInOut.pull` value (``DOWN``, ``UP``, or ``None``)
+      will be preserved during deep sleep.
+
+    Preserving `DigitalInOut` states during deep sleep can be used to ensure that
+    external or on-board devices are powered or unpowered during sleep, among other purposes.
+    Once the board wakes up from deep sleep, the `DigitalInOut` states are no longer preserved
+    and must be restored by your code.
+
+    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.
+      Consider not preserving pins unless you need to.
+      Measure power consumption carefully both with no pins preserved and with the pins you might want to
+      preserve to achieve the lowest consumption.
+
+    **If CircuitPython is connected to a host computer via USB or BLE
+    the first time a deep sleep is requested,
+    the connection will be maintained and the system will not go into deep sleep.**
+    This allows the user to interrupt an existing program with ctrl-C,
+    and to edit the files in CIRCUITPY, which would not be possible in true deep sleep.
+
+    If CircuitPython goes into a true deep sleep, and USB or BLE is reconnected,
+    the next deep sleep will still be a true deep sleep. You must do a hard reset
+    or power-cycle to exit a true deep sleep loop.
+
+    Here is a skeletal example:
+
+    .. code-block:: python
+
+        import alarm
+        import time
+        import board
+
+        print("Waking up")
+
+        # Create an alarm for 60 seconds from now, and also a pin alarm.
+        time_alarm = alarm.time.TimeAlarm(monotonic_time=time.monotonic() + 60)
+        pin_alarm = alarm.pin.PinAlarm(board.D7, False)
+
+        # Deep sleep until one of the alarm goes off. Then restart the program.
+        alarm.exit_and_deep_sleep_until_alarms(time_alarm, pin_alarm)
+    """
+    ...
+
+class SleepMemory:
+    """Store raw bytes in RAM that persists across deep sleep and software resets.
+    The class acts as a ``bytearray``.
+    Contents are preserved across ``microcontroller.reset()``, watchdog resets,
+    and deep sleep wake. Contents are lost when power is removed and restored,
+    or on brown-out reset.
+
+    Note that this class can't be imported and used directly. The sole
+    instance of :class:`SleepMemory` is available at
+    :attr:`alarm.sleep_memory`.
+
+    Usage::
+
+       import alarm
+       alarm.sleep_memory[0] = True
+       alarm.sleep_memory[1] = 12
+    """
+
+    def __init__(self) -> None:
+        """Not used. Access the sole instance through `alarm.sleep_memory`."""
+        ...
+
+    def __bool__(self) -> bool:
+        """``sleep_memory`` is ``True`` if its length is greater than zero.
+        This is an easy way to check for its existence.
+        """
+        ...
+
+    def __len__(self) -> int:
+        """Return the length. This is used by (`len`)"""
+        ...
+
+    @overload
+    def __getitem__(self, index: slice) -> bytearray: ...
+    @overload
+    def __getitem__(self, index: int) -> int:
+        """Returns the value at the given index."""
+        ...
+
+    @overload
+    def __setitem__(self, index: slice, value: ReadableBuffer) -> None: ...
+    @overload
+    def __setitem__(self, index: int, value: int) -> None:
+        """Set the value at the given index."""
+        ...

circuitpython_stubs-10.3.0a4/alarm/touch/__init__.pyi

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import microcontroller
+
+class TouchAlarm:
+    """Trigger an alarm when touch is detected."""
+
+    def __init__(self, *pin: microcontroller.Pin) -> None:
+        """Create an alarm that will be triggered when the given pin is touched.
+        The alarm is not active until it is passed to an `alarm`-enabling function, such as
+        `alarm.light_sleep_until_alarms()` or `alarm.exit_and_deep_sleep_until_alarms()`.
+
+        :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.
+        """
+        ...
+    pin: microcontroller.Pin
+    """The trigger pin."""

circuitpython_stubs-10.3.0a4/audiobusio/__init__.pyi

@@ -0,0 +1,207 @@
+"""Support for audio input and output over digital buses
+
+The `audiobusio` module contains classes to provide access to audio IO
+over digital buses. These protocols are used to communicate audio to other
+chips in the same circuit. It doesn't include audio interconnect protocols
+such as S/PDIF.
+
+All classes change hardware state and should be deinitialized when they
+are no longer needed. To do so, either call :py:meth:`!deinit` or use a
+context manager."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import circuitpython_typing
+import microcontroller
+from circuitpython_typing import WriteableBuffer
+
+class I2SOut:
+    """Output an I2S audio signal"""
+
+    def __init__(
+        self,
+        bit_clock: microcontroller.Pin,
+        word_select: microcontroller.Pin,
+        data: microcontroller.Pin,
+        *,
+        main_clock: Optional[microcontroller.Pin] = None,
+        left_justified: bool = False,
+    ) -> None:
+        """Create a I2SOut object associated with the given pins.
+
+        :param ~microcontroller.Pin bit_clock: The bit clock (or serial clock) pin
+        :param ~microcontroller.Pin word_select: The word select (or left/right clock) pin
+        :param ~microcontroller.Pin data: The data pin
+        :param ~microcontroller.Pin main_clock: The main clock pin
+        :param bool left_justified: True when data bits are aligned with the word select clock. False
+          when they are shifted by one to match classic I2S protocol.
+
+        Simple 8ksps 440 Hz sine wave on `Metro M0 Express <https://www.adafruit.com/product/3505>`_
+        using `UDA1334 Breakout <https://www.adafruit.com/product/3678>`_::
+
+          import audiobusio
+          import audiocore
+          import board
+          import array
+          import time
+          import math
+
+          # Generate one period of sine wave.
+          length = 8000 // 440
+          sine_wave = array.array("H", [0] * length)
+          for i in range(length):
+              sine_wave[i] = int(math.sin(math.pi * 2 * i / length) * (2 ** 15) + 2 ** 15)
+
+          sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000)
+          i2s = audiobusio.I2SOut(board.D1, board.D0, board.D9)
+          i2s.play(sine_wave, loop=True)
+          time.sleep(1)
+          i2s.stop()
+
+        Playing a wave file from flash::
+
+          import board
+          import audiocore
+          import audiobusio
+          import digitalio
+
+
+          f = open("cplay-5.1-16bit-16khz.wav", "rb")
+          wav = audiocore.WaveFile(f)
+
+          a = audiobusio.I2SOut(board.D1, board.D0, board.D9)
+
+          print("playing")
+          a.play(wav)
+          while a.playing:
+            pass
+          print("stopped")"""
+        ...
+
+    def deinit(self) -> None:
+        """Deinitialises the I2SOut and releases any hardware resources for reuse."""
+        ...
+
+    def __enter__(self) -> I2SOut:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes the hardware when exiting a context. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+
+    def play(
+        self, sample: circuitpython_typing.AudioSample, *, loop: bool = False
+    ) -> None:
+        """Plays the sample once when loop=False and continuously when loop=True.
+        Does not block. Use `playing` to block.
+
+        Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, `audiomixer.Mixer` or `audiomp3.MP3Decoder`.
+
+        Mono samples will be converted to stereo by copying value to both the left channel and the right channel.
+
+        The sample itself should consist of 8 bit or 16 bit samples."""
+        ...
+
+    def stop(self) -> None:
+        """Stops playback."""
+        ...
+    playing: bool
+    """True when the audio sample is being output. (read-only)"""
+
+    def pause(self) -> None:
+        """Stops playback temporarily while remembering the position. Use `resume` to resume playback."""
+        ...
+
+    def resume(self) -> None:
+        """Resumes sample playback after :py:func:`pause`."""
+        ...
+    paused: bool
+    """True when playback is paused. (read-only)"""
+
+class PDMIn:
+    """Record an input PDM audio stream"""
+
+    def __init__(
+        self,
+        clock_pin: microcontroller.Pin,
+        data_pin: microcontroller.Pin,
+        *,
+        sample_rate: int = 16000,
+        bit_depth: int = 8,
+        mono: bool = True,
+        oversample: int = 64,
+        startup_delay: float = 0.11,
+    ) -> None:
+        """Create a PDMIn object associated with the given pins. This allows you to
+        record audio signals from the given pins. Individual ports may put further
+        restrictions on the recording parameters. The overall sample rate is
+        determined by `sample_rate` x ``oversample``, and the total must be 1MHz or
+        higher, so `sample_rate` must be a minimum of 16000.
+
+        :param ~microcontroller.Pin clock_pin: The pin to output the clock to
+        :param ~microcontroller.Pin data_pin: The pin to read the data from
+        :param int sample_rate: Target sample_rate of the resulting samples. Check `sample_rate` for actual value.
+          Minimum sample_rate is about 16000 Hz.
+        :param int bit_depth: Final number of bits per sample. Must be divisible by 8
+        :param bool mono: True when capturing a single channel of audio, captures two channels otherwise
+        :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.
+
+        **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. On Espressif, only available on ESP32, ESP32-S3, and ESP32-P4.
+
+        For example, to record 8-bit unsigned samples to a buffer::
+
+          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))
+
+        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))
+        """
+    ...
+
+    def deinit(self) -> None:
+        """Deinitialises the PDMIn and releases any hardware resources for reuse."""
+        ...
+
+    def __enter__(self) -> PDMIn:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes the hardware when exiting a context."""
+        ...
+
+    def record(self, destination: WriteableBuffer, destination_length: int) -> int:
+        """Records destination_length bytes of samples to destination. This is
+        blocking.
+
+        An OSError may be raised when the destination is too slow to record the
+        audio at the given rate. For internal flash, writing all 1s to the file
+        before recording is recommended to speed up writes.
+
+        :return: The number of samples recorded. If this is less than ``destination_length``,
+          some samples were missed due to processing time."""
+        ...
+    sample_rate: int
+    """The actual sample_rate of the recording. This may not match the constructed
+    sample rate due to internal clock limitations."""