circuitpython-stubs 10.0.3__tar.gz → 10.1.0__tar.gz

circuitpython_stubs-10.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: circuitpython-stubs
+Version: 10.1.0
+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.1.0/audiobusio/__init__.pyi

@@ -0,0 +1,205 @@
+"""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`.
+
+        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. Not available on Espressif.
+
+        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."""

circuitpython_stubs-10.1.0/aurora_epaper/__init__.pyi

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import busio
+import microcontroller
+
+class AuroraMemoryFramebuffer:
+    """A framebuffer for Pervasive Displays Aurora E-paper displays.
+
+    These displays are 2 color only.
+
+    This initializes a display and connects it to CircuitPython.
+
+    For Example::
+
+        import busio
+        import framebufferio
+        from aurora_epaper import AuroraMemoryFramebuffer
+        spi = busio.SPI(EINK_CLKS, EINK_MOSI, EINK_MISO)
+        aurora = AuroraMemoryFramebuffer(spi, EINK_CS, EINK_RST, EINK_BUSY, EINK_DISCHARGE, HEIGHT, WIDTH)
+        display = framebufferio.FramebufferDisplay(t, auto_refresh=False)
+        display.refresh()
+
+    For more information on how these displays are driven see:
+    https://www.pervasivedisplays.com/wp-content/uploads/2023/02/4P018-00_04_G2_Aurora-Mb_COG_Driver_Interface_Timing_for_small-size_20231107.pdf
+    """
+
+    def __init__(
+        self,
+        spi_bus: busio.SPI,
+        chip_select: microcontroller.Pin,
+        reset: microcontroller.Pin,
+        busy: microcontroller.Pin,
+        discharge: microcontroller.Pin,
+        width: int,
+        height: int,
+        power: Optional[microcontroller.Pin] = None,
+        free_bus: Optional[bool] = True,
+    ) -> None:
+        """Create a framebuffer for the Aurora CoG display.
+
+        .. note:: Displays of size 1.9" and 2.6" are not tested, and may exhibit unexpected behavior.
+
+        :param busio.SPI spi_bus: The SPI bus that the display is connected to
+        :param microcontroller.Pin chip_select: The pin connected to the displays chip select input
+        :param microcontroller.Pin reset: The pin connected to the displays reset input
+        :param microcontroller.Pin busy: The pin connected to the displays busy output
+        :param microcontroller.Pin discharge: The pin connected to the displays discharge input
+        :param int width: The width of the display in pixels
+        :param int height: The height of the display in pixels
+        :param microcontroller.Pin power: The pin that controls power to the display (optional).
+        :param bool free_bus: Determines whether the SPI bus passed in will be freed when the frame buffer is freed (optional).
+        """
+        ...
+
+    def deinit(self) -> None:
+        """Free the resources (pins, timers, etc.) associated with this
+        AuroraMemoryFramebuffer instance.  After deinitialization, no further operations
+        may be performed."""
+        ...
+
+    def set_temperature(self, celsius: int) -> None:
+        """Set the ambient temperature (in celsius) for the display driver.
+        Higher temperature means faster update speed.
+        """
+        ...
+    free_bus: bool
+    """When True the spi bus passed into the device will be freed on deinit.
+    If you have multiple displays this could be used to keep the other active on soft reset."""
+    ...

circuitpython_stubs-10.1.0/bitbangio/__init__.pyi

@@ -0,0 +1,340 @@
+"""Digital protocols implemented by the CPU
+
+The `bitbangio` module contains classes to provide digital bus protocol
+support regardless of whether the underlying hardware exists to use the
+protocol.
+
+First try to use `busio` module instead which may utilize peripheral
+hardware to implement the protocols. Native implementations will be faster
+than bitbanged versions and have more capabilities.
+
+All classes change hardware state and should be deinitialized when they
+are no longer needed if the program continues after use. To do so, either
+call :py:meth:`!deinit` or use a context manager. See
+:ref:`lifetime-and-contextmanagers` for more info.
+
+For example::
+
+  import bitbangio
+  from board import *
+
+  i2c = bitbangio.I2C(SCL, SDA)
+  print(i2c.scan())
+  i2c.deinit()
+
+This example will initialize the the device, run
+:py:meth:`~bitbangio.I2C.scan` and then :py:meth:`~bitbangio.I2C.deinit` the
+hardware. The last step is optional because CircuitPython automatically
+resets hardware after a program finishes."""
+
+from __future__ import annotations
+
+from typing import List, Optional, Union
+
+import digitalio
+import microcontroller
+from circuitpython_typing import ReadableBuffer, WriteableBuffer
+
+class I2C:
+    """Two wire serial protocol"""
+
+    def __init__(
+        self,
+        scl: Union[microcontroller.Pin, digitalio.DigitalInOutProtocol],
+        sda: Union[microcontroller.Pin, digitalio.DigitalInOutProtocol],
+        *,
+        frequency: int = 400000,
+        timeout: int = 255,
+    ) -> None:
+        """I2C is a two-wire protocol for communicating between devices.  At the
+        physical level it consists of 2 wires: SCL and SDA, the clock and data
+        lines respectively.
+
+        .. seealso:: Using this class directly requires careful lock management.
+            Instead, use :class:`~adafruit_bus_device.i2c_device.I2CDevice` to
+            manage locks.
+
+        .. seealso:: Using this class to directly read registers requires manual
+            bit unpacking. Instead, use an existing driver or make one with
+            :ref:`Register <register-module-reference>` data descriptors.
+
+        :param ~microcontroller.Pin scl: The clock pin or DigitalInOut object
+        :param ~microcontroller.Pin sda: The data pin or DigitalInOut object
+        :param int frequency: The clock frequency of the bus
+        :param int timeout: The maximum clock stretching timeout in microseconds"""
+        ...
+
+    def deinit(self) -> None:
+        """Releases control of the underlying hardware so other classes can use it."""
+        ...
+
+    def __enter__(self) -> I2C:
+        """No-op used in Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes the hardware on context exit. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+
+    def probe(self, address: int) -> List[int]:
+        """Check if a device at the specified address responds.
+
+        :param int address: 7-bit device address
+        :return: ``True`` if a device at ``address`` responds; ``False`` otherwise
+        :rtype: bool"""
+        ...
+
+    def scan(self) -> List[int]:
+        """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of
+        those that respond.  A device responds if it pulls the SDA line low after
+        its address (including a read bit) is sent on the bus."""
+        ...
+
+    def try_lock(self) -> bool:
+        """Attempts to grab the I2C lock. Returns True on success."""
+        ...
+
+    def unlock(self) -> None:
+        """Releases the I2C lock."""
+        ...
+    import sys
+
+    def readfrom_into(
+        self,
+        address: int,
+        buffer: WriteableBuffer,
+        *,
+        start: int = 0,
+        end: int = sys.maxsize,
+    ) -> None:
+        """Read into ``buffer`` from the device selected by ``address``.
+        The number of bytes read will be the length of ``buffer``.
+        At least one byte must be read.
+
+        If ``start`` or ``end`` is provided, then the buffer will be sliced
+        as if ``buffer[start:end]``. This will not cause an allocation like
+        ``buf[start:end]`` will so it saves memory.
+
+        :param int address: 7-bit device address
+        :param WriteableBuffer buffer: buffer to write into
+        :param int start: Index to start writing at
+        :param int end: Index to write up to but not include"""
+        ...
+    import sys
+
+    def writeto(
+        self,
+        address: int,
+        buffer: ReadableBuffer,
+        *,
+        start: int = 0,
+        end: int = sys.maxsize,
+    ) -> None:
+        """Write the bytes from ``buffer`` to the device selected by ``address`` and then transmits a
+        stop bit. Use `writeto_then_readfrom` when needing a write, no stop and repeated start
+        before a read.
+
+        If ``start`` or ``end`` is provided, then the buffer will be sliced
+        as if ``buffer[start:end]`` were passed, but without copying the data.
+        The number of bytes written will be the length of ``buffer[start:end]``.
+
+        Writing a buffer or slice of length zero is permitted, as it can be used
+        to poll for the existence of a device.
+
+        :param int address: 7-bit device address
+        :param ReadableBuffer buffer: buffer containing the bytes to write
+        :param int start: beginning of buffer slice
+        :param int end: end of buffer slice; if not specified, use ``len(buffer)``
+        """
+        ...
+    import sys
+
+    def writeto_then_readfrom(
+        self,
+        address: int,
+        out_buffer: ReadableBuffer,
+        in_buffer: ReadableBuffer,
+        *,
+        out_start: int = 0,
+        out_end: int = sys.maxsize,
+        in_start: int = 0,
+        in_end: int = sys.maxsize,
+    ) -> None:
+        """Write the bytes from ``out_buffer`` to the device selected by ``address``, generate no stop
+        bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and
+        ``in_buffer`` can be the same buffer because they are used sequentially.
+
+        If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced
+        as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data.
+        The number of bytes written will be the length of ``out_buffer[start:end]``.
+
+        If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced
+        as if ``in_buffer[in_start:in_end]`` were passed,
+        The number of bytes read will be the length of ``out_buffer[in_start:in_end]``.
+
+        :param int address: 7-bit device address
+        :param ~circuitpython_typing.ReadableBuffer out_buffer: buffer containing the bytes to write
+        :param ~circuitpython_typing.WriteableBuffer in_buffer: buffer to write into
+        :param int out_start: beginning of ``out_buffer`` slice
+        :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)``
+        :param int in_start: beginning of ``in_buffer`` slice
+        :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)``
+        """
+        ...
+
+class SPI:
+    """A 3-4 wire serial protocol
+
+    SPI is a serial protocol that has exclusive pins for data in and out of the
+    main device.  It is typically faster than :py:class:`~bitbangio.I2C` because a
+    separate pin is used to select a device rather than a transmitted
+    address. This class only manages three of the four SPI lines: `!clock`,
+    `!MOSI`, `!MISO`. Its up to the client to manage the appropriate
+    select line, often abbreviated `!CS` or `!SS`. (This is common because
+    multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines
+    and therefore the hardware.)"""
+
+    def __init__(
+        self,
+        clock: Union[microcontroller.Pin, digitalio.DigitalInOutProtocol],
+        MOSI: Optional[
+            Union[microcontroller.Pin, digitalio.DigitalInOutProtocol]
+        ] = None,
+        MISO: Optional[
+            Union[microcontroller.Pin, digitalio.DigitalInOutProtocol]
+        ] = None,
+    ) -> None:
+        """Construct an SPI object on the given pins.
+
+        .. seealso:: Using this class directly requires careful lock management.
+            Instead, use :class:`~adafruit_bus_device.spi_device.SPIDevice` to
+            manage locks.
+
+        .. seealso:: Using this class to directly read registers requires manual
+            bit unpacking. Instead, use an existing driver or make one with
+            :ref:`Register <register-module-reference>` data descriptors.
+
+
+        :param ~microcontroller.Pin clock: the pin to use for the clock or DigitalInOut object
+        :param ~microcontroller.Pin MOSI: the Main Out Selected In pin or DigitalInOut object
+        :param ~microcontroller.Pin MISO: the Main In Selected Out pin or DigitalInOut object
+        """
+        ...
+
+    def deinit(self) -> None:
+        """Turn off the SPI bus."""
+        ...
+
+    def __enter__(self) -> SPI:
+        """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 configure(
+        self,
+        *,
+        baudrate: int = 100000,
+        polarity: int = 0,
+        phase: int = 0,
+        bits: int = 8,
+    ) -> None:
+        """Configures the SPI bus. Only valid when locked.
+
+        :param int baudrate: the clock rate in Hertz
+        :param int polarity: the base state of the clock line (0 or 1)
+        :param int phase: the edge of the clock that data is captured. First (0)
+          or second (1). Rising or falling depends on clock polarity.
+        :param int bits: the number of bits per word"""
+        ...
+
+    def try_lock(self) -> bool:
+        """Attempts to grab the SPI lock. Returns True on success.
+
+        :return: True when lock has been grabbed
+        :rtype: bool"""
+        ...
+
+    def unlock(self) -> None:
+        """Releases the SPI lock."""
+        ...
+    import sys
+
+    def write(
+        self, buf: ReadableBuffer, *, start: int = 0, end: int = sys.maxsize
+    ) -> None:
+        """Write the data contained in ``buf``. Requires the SPI being locked.
+        If the buffer is empty, nothing happens.
+
+        If ``start`` or ``end`` is provided, then the buffer will be sliced
+        as if ``buffer[start:end]`` were passed, but without copying the data.
+        The number of bytes written will be the length of ``buffer[start:end]``.
+
+        :param ReadableBuffer buffer: buffer containing the bytes to write
+        :param int start: beginning of buffer slice
+        :param int end: end of buffer slice; if not specified, use ``len(buffer)``
+        """
+        ...
+    import sys
+
+    def readinto(
+        self,
+        buffer: WriteableBuffer,
+        *,
+        start: int = 0,
+        end: int = sys.maxsize,
+        write_value: int = 0,
+    ) -> None:
+        """Read into ``buffer`` while writing ``write_value`` for each byte read.
+        The SPI object must be locked.
+        If the number of bytes to read is 0, nothing happens.
+
+        If ``start`` or ``end`` is provided, then the buffer will be sliced
+        as if ``buffer[start:end]`` were passed.
+        The number of bytes read will be the length of ``buffer[start:end]``.
+
+        :param WriteableBuffer buffer: read bytes into this buffer
+        :param int start: beginning of buffer slice
+        :param int end: end of buffer slice; if not specified, use ``len(buffer)``
+        :param int write_value: value to write while reading
+        """
+        ...
+    import sys
+
+    def write_readinto(
+        self,
+        out_buffer: ReadableBuffer,
+        in_buffer: WriteableBuffer,
+        *,
+        out_start: int = 0,
+        out_end: int = sys.maxsize,
+        in_start: int = 0,
+        in_end: int = sys.maxsize,
+    ) -> None:
+        """Write out the data in ``out_buffer`` while simultaneously reading data into ``in_buffer``.
+        The SPI object must be locked.
+
+        If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced
+        as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data.
+        The number of bytes written will be the length of ``out_buffer[out_start:out_end]``.
+
+        If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced
+        as if ``in_buffer[in_start:in_end]`` were passed,
+        The number of bytes read will be the length of ``out_buffer[in_start:in_end]``.
+
+        The lengths of the slices defined by ``out_buffer[out_start:out_end]``
+        and ``in_buffer[in_start:in_end]`` must be equal.
+        If buffer slice lengths are both 0, nothing happens.
+
+        :param ReadableBuffer out_buffer: write out bytes from this buffer
+        :param WriteableBuffer in_buffer: read bytes into this buffer
+        :param int out_start: beginning of ``out_buffer`` slice
+        :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)``
+        :param int in_start: beginning of ``in_buffer`` slice
+        :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)``
+        """
+        ...