From a18b991ca90670758afadfe0e78ec97cf56bf5e3 Mon Sep 17 00:00:00 2001 From: dherrada Date: Wed, 22 Apr 2020 15:22:34 -0400 Subject: Added pyi to SPI.c --- shared-bindings/busio/SPI.c | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 043c1089d..e01e9e35e 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -40,6 +40,19 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" +class SPI: + def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): ... + def deinit(self, ) -> Any: ... + def __enter__(self, ) -> Any: ... + def __exit__(self, ) -> Any: ... + def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: ... + def try_lock(self, ) -> Any: ... + def unlock(self, ) -> Any: ... + def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... + def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: ... + def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: ... + frequency: Any = ... + //| .. currentmodule:: busio //| //| :class:`SPI` -- a 3-4 wire serial protocol -- cgit v1.2.3 From 855c2033b59c8451bde30387e668ecfb206888b6 Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 23 Apr 2020 15:35:20 -0400 Subject: Reogranized pyi in spi.c --- shared-bindings/busio/SPI.c | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index e01e9e35e..db84ac97b 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -40,18 +40,6 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -class SPI: - def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): ... - def deinit(self, ) -> Any: ... - def __enter__(self, ) -> Any: ... - def __exit__(self, ) -> Any: ... - def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: ... - def try_lock(self, ) -> Any: ... - def unlock(self, ) -> Any: ... - def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... - def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: ... - def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: ... - frequency: Any = ... //| .. currentmodule:: busio //| @@ -89,6 +77,8 @@ class SPI: //| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. //| :param ~microcontroller.Pin MISO: the Master In Slave Out pin. //| +// class SPI: +// def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): ... // TODO(tannewt): Support LSB SPI. STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -115,6 +105,7 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con //| //| Turn off the SPI bus. //| +// def deinit(self, ) -> Any: ... STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_spi_deinit(self); @@ -127,12 +118,14 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); //| No-op used by Context Managers. //| // Provided by context manager helper. +// def __enter__(self, ) -> Any: ... //| .. method:: __exit__() //| //| Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info. //| +// def __exit__(self, ) -> Any: ... STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_spi_deinit(args[0]); @@ -176,6 +169,7 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { //| Two SPI objects may be created, except on the Circuit Playground Bluefruit, //| which allows only one (to allow for an additional I2C object). //| +// def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: ... STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; static const mp_arg_t allowed_args[] = { @@ -218,6 +212,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); //| :return: True when lock has been grabbed //| :rtype: bool //| +// def try_lock(self, ) -> Any: ... STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); return mp_obj_new_bool(common_hal_busio_spi_try_lock(self)); @@ -228,6 +223,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); //| //| Releases the SPI lock. //| +// def unlock(self, ) -> Any: ... STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -245,6 +241,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); //| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` //| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| +// def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; static const mp_arg_t allowed_args[] = { @@ -288,6 +285,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); //| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| :param int write_value: Value to write while reading. (Usually ignored.) //| +// def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: ... STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; static const mp_arg_t allowed_args[] = { @@ -335,6 +333,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); //| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` //| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` //| +// def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: ... STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { @@ -387,6 +386,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_readinto_obj, 2, busio_spi_write_read //| The actual SPI bus frequency. This may not match the frequency requested //| due to internal limitations. //| +// frequency: Any = ... STATIC mp_obj_t busio_spi_obj_get_frequency(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 55bdee688fc021d8afb70b0868b20699c5f0519b Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 23 Apr 2020 16:14:17 -0400 Subject: Reorganized pyi again --- shared-bindings/busio/SPI.c | 237 +++++++++++++++++++++----------------------- 1 file changed, 112 insertions(+), 125 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index db84ac97b..1ac9629f8 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -41,44 +41,44 @@ #include "supervisor/shared/translate.h" -//| .. currentmodule:: busio +//|class SPI: +//| """.. currentmodule:: busio //| -//| :class:`SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//| `SPI` -- a 3-4 wire serial protocol +//| ----------------------------------------------- //| -//| SPI is a serial protocol that has exclusive pins for data in and out of the -//| master. It is typically faster than :py:class:`~busio.I2C` because a -//| separate pin is used to control the active slave rather than a transitted -//| address. This class only manages three of the four SPI lines: `!clock`, -//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave -//| select line. (This is common because multiple slaves can share the `!clock`, -//| `!MOSI` and `!MISO` lines and therefore the hardware.) +//| SPI is a serial protocol that has exclusive pins for data in and out of the +//| master. It is typically faster than :py:class:`~busio.I2C` because a +//| separate pin is used to control the active slave rather than a transitted +//| address. This class only manages three of the four SPI lines: `!clock`, +//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave +//| select line. (This is common because multiple slaves can share the `!clock`, +//| `!MOSI` and `!MISO` lines and therefore the hardware.)""" //| -//| .. class:: SPI(clock, MOSI=None, MISO=None) +//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): //| -//| Construct an SPI object on the given pins. +//| """Construct an SPI object on the given pins. //| -//| ..note:: The SPI peripherals allocated in order of desirability, if possible, -//| such as highest speed and not shared use first. For instance, on the nRF52840, -//| there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, -//| some of which may also be used for I2C. The 32MHz SPI peripheral is returned -//| first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz -//| peripherals. +//| ..note:: The SPI peripherals allocated in order of desirability, if possible, +//| such as highest speed and not shared use first. For instance, on the nRF52840, +//| there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, +//| some of which may also be used for I2C. The 32MHz SPI peripheral is returned +//| first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz +//| peripherals. //| -//| .. 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 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 ` data descriptors. +//| .. seealso:: Using this class to directly read registers requires manual +//| bit unpacking. Instead, use an existing driver or make one with +//| :ref:`Register ` data descriptors. //| -//| :param ~microcontroller.Pin clock: the pin to use for the clock. -//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. -//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin. -//| -// class SPI: -// def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): ... +//| :param ~microcontroller.Pin clock: the pin to use for the clock. +//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. +//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" +//| ... + // TODO(tannewt): Support LSB SPI. STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -101,11 +101,9 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Turn off the SPI bus. -//| -// def deinit(self, ) -> Any: ... +//| def deinit(self, ) -> Any: +//| """Turn off the SPI bus.""" +//| ... STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_spi_deinit(self); @@ -113,19 +111,15 @@ STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| -// Provided by context manager helper. -// def __enter__(self, ) -> Any: ... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers. +//| Provided by context manager helper.""" +//| ... -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| -// def __exit__(self, ) -> Any: ... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_spi_deinit(args[0]); @@ -146,30 +140,29 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { } } -//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8) -//| -//| Configures the SPI bus. The SPI object must be locked. -//| -//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower -//| due to the granularity of available clock settings. -//| Check the `frequency` attribute for the actual clock rate. -//| :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 -//| -//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that -//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is -//| within spec for the SAMD21. -//| -//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, -//| and 8MHz. -//| If you pick a a baudrate other than one of these, the nearest lower -//| baudrate will be chosen, with a minimum of 125kHz. -//| Two SPI objects may be created, except on the Circuit Playground Bluefruit, -//| which allows only one (to allow for an additional I2C object). -//| -// def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: ... +//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: +//| """Configures the SPI bus. The SPI object must be locked. +//| +//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower +//| due to the granularity of available clock settings. +//| Check the `frequency` attribute for the actual clock rate. +//| :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 +//| +//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that +//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is +//| within spec for the SAMD21. +//| +//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, +//| and 8MHz. +//| If you pick a a baudrate other than one of these, the nearest lower +//| baudrate will be chosen, with a minimum of 125kHz. +//| Two SPI objects may be created, except on the Circuit Playground Bluefruit, +//| which allows only one (to allow for an additional I2C object).""" +//| ... + STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; static const mp_arg_t allowed_args[] = { @@ -205,25 +198,23 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); -//| .. method:: try_lock() -//| -//| Attempts to grab the SPI lock. Returns True on success. +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the SPI lock. Returns True on success. //| -//| :return: True when lock has been grabbed -//| :rtype: bool -//| -// def try_lock(self, ) -> Any: ... +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... + STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); return mp_obj_new_bool(common_hal_busio_spi_try_lock(self)); } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); -//| .. method:: unlock() -//| -//| Releases the SPI lock. -//| -// def unlock(self, ) -> Any: ... +//| def unlock(self, ) -> Any: +//| """Releases the SPI lock.""" +//| ... + STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -232,16 +223,15 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); -//| .. method:: write(buffer, *, start=0, end=None) -//| -//| Write the data contained in ``buffer``. The SPI object must be locked. -//| If the buffer is empty, nothing happens. +//| def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... +//| """Write the data contained in ``buffer``. The SPI object must be locked. +//| If the buffer is empty, nothing happens. //| -//| :param bytearray buffer: Write out the data in this buffer -//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` -//| -// def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... +//| :param bytearray buffer: Write out the data in this buffer +//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" +//| ... + STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; static const mp_arg_t allowed_args[] = { @@ -274,18 +264,17 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); -//| .. method:: readinto(buffer, *, start=0, end=None, write_value=0) -//| -//| 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. -//| -//| :param bytearray buffer: Read data into this buffer -//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` -//| :param int write_value: Value to write while reading. (Usually ignored.) +//| def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: +//| """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. //| -// def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: ... +//| :param bytearray buffer: Read data into this buffer +//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` +//| :param int write_value: Value to write while reading. (Usually ignored.)""" +//| ... + STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; static const mp_arg_t allowed_args[] = { @@ -318,22 +307,21 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); -//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None) -//| -//| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. -//| The SPI object must be locked. -//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//| must be equal. -//| If buffer slice lengths are both 0, nothing happens. -//| -//| :param bytearray buffer_out: Write out the data in this buffer -//| :param bytearray buffer_in: Read data into this buffer -//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` -//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` -//| -// def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: ... +//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: +//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//| The SPI object must be locked. +//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` +//| must be equal. +//| If buffer slice lengths are both 0, nothing happens. +//| +//| :param bytearray buffer_out: Write out the data in this buffer +//| :param bytearray buffer_in: Read data into this buffer +//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` +//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" +//| ... + STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { @@ -381,12 +369,11 @@ STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_readinto_obj, 2, busio_spi_write_readinto); -//| .. attribute:: frequency -//| -//| The actual SPI bus frequency. This may not match the frequency requested -//| due to internal limitations. -//| -// frequency: Any = ... +//| frequency: Any = +//| """The actual SPI bus frequency. This may not match the frequency requested +//| due to internal limitations.""" +//| ... + STATIC mp_obj_t busio_spi_obj_get_frequency(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 28430a9919c511330c4fb833469497a346ad2288 Mon Sep 17 00:00:00 2001 From: dherrada Date: Sat, 25 Apr 2020 15:07:58 -0400 Subject: Added inline pyi to I2C.c --- shared-bindings/busio/I2C.c | 211 +++++++++++++++++++++----------------------- 1 file changed, 100 insertions(+), 111 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index c89215acd..0cd392f9a 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -36,34 +36,33 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: busio -//| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------ -//| -//| .. class:: I2C(scl, sda, *, frequency=400000, timeout=255) -//| -//| 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 ` data descriptors. -//| -//| :param ~microcontroller.Pin scl: The clock pin -//| :param ~microcontroller.Pin sda: The data pin -//| :param int frequency: The clock frequency in Hertz -//| :param int timeout: The maximum clock stretching timeut - (used only for bitbangio.I2C; ignored for busio.I2C) -//| -//| .. note:: On the nRF52840, only one I2C object may be created, -//| except on the Circuit Playground Bluefruit, which allows two, -//| one for the onboard accelerometer, and one for offboard use. -//| +//|class I2C: +//| """.. currentmodule:: busio +//| +//| :class:`I2C` --- Two wire serial protocol +//| ------------------------------------------""" +//| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): +//| """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 ` data descriptors. +//| +//| :param ~microcontroller.Pin scl: The clock pin +//| :param ~microcontroller.Pin sda: The data pin +//| :param int frequency: The clock frequency in Hertz +//| :param int timeout: The maximum clock stretching timeut - (used only for bitbangio.I2C; ignored for busio.I2C) +//| +//| .. note:: On the nRF52840, only one I2C object may be created, +//| except on the Circuit Playground Bluefruit, which allows two, +//| one for the onboard accelerometer, and one for offboard use.""" +//| ... STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { busio_i2c_obj_t *self = m_new_obj(busio_i2c_obj_t); self->base.type = &busio_i2c_type; @@ -84,10 +83,9 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| .. method:: deinit() -//| -//| Releases control of the underlying hardware so other classes can use it. -//| +//| def deinit(self, ) -> Any: +//| """Releases control of the underlying hardware so other classes can use it.""" +//| ... STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_i2c_deinit(self); @@ -101,17 +99,15 @@ STATIC void check_for_deinit(busio_i2c_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used in Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used in Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware on context exit. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_i2c_deinit(args[0]); @@ -126,14 +122,13 @@ static void check_lock(busio_i2c_obj_t *self) { } } -//| .. method:: scan() -//| -//| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a -//| list of those that respond. -//| -//| :return: List of device ids on the I2C bus -//| :rtype: list +//| def scan(self, ) -> Any: +//| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a +//| list of those that respond. //| +//| :return: List of device ids on the I2C bus +//| :rtype: list""" +//| ... STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -150,13 +145,11 @@ STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); -//| .. method:: try_lock() -//| -//| Attempts to grab the I2C lock. Returns True on success. -//| -//| :return: True when lock has been grabbed -//| :rtype: bool -//| +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the I2C lock. Returns True on success. +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -164,10 +157,9 @@ STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); -//| .. method:: unlock() -//| -//| Releases the I2C lock. -//| +//| def unlock(self, ) -> Any: +//| """Releases the I2C lock.""" +//| ... STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -176,21 +168,20 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); -//| .. method:: readfrom_into(address, buffer, *, start=0, end=None) -//| -//| Read into ``buffer`` from the slave specified by ``address``. -//| The number of bytes read will be the length of ``buffer``. -//| At least one byte must be read. +//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: +//| """Read into ``buffer`` from the slave specified 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 bytearray buffer: buffer to write into -//| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)`` +//| 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 bytearray buffer: buffer to write into +//| :param int start: Index to start writing at +//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//| ... // Shared arg parsing for readfrom_into and writeto_then_readfrom. STATIC void readfrom(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end) { mp_buffer_info_t bufinfo; @@ -228,27 +219,26 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into); -//| .. method:: writeto(address, buffer, *, start=0, end=None, stop=True) -//| -//| Write the bytes from ``buffer`` to the slave specified by ``address``. -//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be -//| removed in CircuitPython 6.x. 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]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. -//| -//| 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 bytearray buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param bool stop: If true, output an I2C stop condition after the buffer is written. -//| Deprecated. Will be removed in 6.x and act as stop=True. -//| +//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: +//| """Write the bytes from ``buffer`` to the slave specified by ``address``. +//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be +//| removed in CircuitPython 6.x. 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]``. This will not cause an allocation like +//| ``buffer[start:end]`` will so it saves memory. +//| +//| 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 bytearray buffer: buffer containing the bytes to write +//| :param int start: Index to start writing from +//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param bool stop: If true, output an I2C stop condition after the buffer is written. +//| Deprecated. Will be removed in 6.x and act as stop=True.""" +//| ... // Shared arg parsing for writeto and writeto_then_readfrom. STATIC void writeto(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end, bool stop) { // get the buffer to write the data from @@ -287,24 +277,23 @@ STATIC mp_obj_t busio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, mp_ma } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto); -//| .. method:: writeto_then_readfrom(address, out_buffer, in_buffer, *, out_start=0, out_end=None, in_start=0, in_end=None) -//| -//| Write the bytes from ``out_buffer`` to the slave specified 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 ``start`` or ``end`` is provided, then the corresponding 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 bytearray out_buffer: buffer containing the bytes to write -//| :param bytearray in_buffer: buffer to write into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)`` -//| +//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: +//| """Write the bytes from ``out_buffer`` to the slave specified 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 ``start`` or ``end`` is provided, then the corresponding 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 bytearray out_buffer: buffer containing the bytes to write +//| :param bytearray in_buffer: buffer to write into +//| :param int out_start: Index to start writing from +//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param int in_start: Index to start writing at +//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//| ... STATIC mp_obj_t busio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { -- cgit v1.2.3 From 7070fe1995f70e745699682bbc9776bb54a069a6 Mon Sep 17 00:00:00 2001 From: dherrada Date: Sat, 25 Apr 2020 15:25:31 -0400 Subject: Added inline pyi to UART.c --- shared-bindings/busio/UART.c | 181 +++++++++++++++++++++---------------------- 1 file changed, 88 insertions(+), 93 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index f231924d5..59c95528d 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -40,33 +40,32 @@ #include "supervisor/shared/translate.h" -//| .. currentmodule:: busio -//| -//| :class:`UART` -- a bidirectional serial protocol -//| ================================================= -//| -//| -//| .. class:: UART(tx, rx, *, baudrate=9600, bits=8, parity=None, stop=1, timeout=1, receiver_buffer_size=64) -//| -//| A common bidirectional serial protocol that uses an an agreed upon speed -//| rather than a shared clock line. -//| -//| :param ~microcontroller.Pin tx: the pin to transmit with, or ``None`` if this ``UART`` is receive-only. -//| :param ~microcontroller.Pin rx: the pin to receive on, or ``None`` if this ``UART`` is transmit-only. -//| :param ~microcontroller.Pin rts: the pin for rts, or ``None`` if rts not in use. -//| :param ~microcontroller.Pin cts: the pin for cts, or ``None`` if cts not in use. -//| :param ~microcontroller.Pin rs485_dir: the pin for rs485 direction setting, or ``None`` if rs485 not in use. -//| :param bool rs485_invert: set to invert the sense of the rs485_dir pin. -//| :param int baudrate: the transmit and receive speed. -//| :param int bits: the number of bits per byte, 7, 8 or 9. -//| :param Parity parity: the parity used for error checking. -//| :param int stop: the number of stop bits, 1 or 2. -//| :param float timeout: the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises ``ValueError`` if timeout >100 seconds. -//| :param int receiver_buffer_size: the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.) -//| -//| *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. -//| + +//|class UART: +//| """.. currentmodule:: busio +//| +//| :class:`UART` -- a bidirectional serial protocol +//| =================================================""" +//| def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): +//| """A common bidirectional serial protocol that uses an an agreed upon speed +//| rather than a shared clock line. +//| +//| :param ~microcontroller.Pin tx: the pin to transmit with, or ``None`` if this ``UART`` is receive-only. +//| :param ~microcontroller.Pin rx: the pin to receive on, or ``None`` if this ``UART`` is transmit-only. +//| :param ~microcontroller.Pin rts: the pin for rts, or ``None`` if rts not in use. +//| :param ~microcontroller.Pin cts: the pin for cts, or ``None`` if cts not in use. +//| :param ~microcontroller.Pin rs485_dir: the pin for rs485 direction setting, or ``None`` if rs485 not in use. +//| :param bool rs485_invert: set to invert the sense of the rs485_dir pin. +//| :param int baudrate: the transmit and receive speed. +//| :param int bits: the number of bits per byte, 7, 8 or 9. +//| :param Parity parity: the parity used for error checking. +//| :param int stop: the number of stop bits, 1 or 2. +//| :param float timeout: the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises ``ValueError`` if timeout >100 seconds. +//| :param int receiver_buffer_size: the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.) +//| +//| *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.""" +//| ... typedef struct { mp_obj_base_t base; } busio_uart_parity_obj_t; @@ -144,10 +143,9 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, co return (mp_obj_t)self; } -//| .. method:: deinit() -//| -//| Deinitialises the UART and releases any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the UART and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_uart_deinit(self); @@ -161,17 +159,15 @@ STATIC void check_for_deinit(busio_uart_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_uart_deinit(args[0]); @@ -181,41 +177,46 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ // These are standard stream methods. Code is in py/stream.c. // -//| .. method:: read(nbytes=None) -//| -//| Read characters. If ``nbytes`` is specified then read at most that many -//| bytes. Otherwise, read everything that arrives until the connection -//| times out. Providing the number of bytes expected is highly recommended -//| because it will be faster. +//| def read(self, nbytes: Any = None) -> Any: +//| """Read characters. If ``nbytes`` is specified then read at most that many +//| bytes. Otherwise, read everything that arrives until the connection +//| times out. Providing the number of bytes expected is highly recommended +//| because it will be faster. //| -//| :return: Data read -//| :rtype: bytes or None -//| -//| .. method:: readinto(buf) +//| :return: Data read +//| :rtype: bytes or None""" +//| ... + +//| def readinto(self, buf: Any) -> Any: +//| """.. method:: readinto(buf) //| -//| Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. +//| Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. //| -//| :return: number of bytes read and stored into ``buf`` -//| :rtype: int or None (on a non-blocking error) +//| :return: number of bytes read and stored into ``buf`` +//| :rtype: int or None (on a non-blocking error) //| -//| *New in CircuitPython 4.0:* No length parameter is permitted. +//| *New in CircuitPython 4.0:* No length parameter is permitted.""" +//| ... -//| .. method:: readline() +//| def readline(self, ) -> Any: +//| """.. method:: readline() //| -//| Read a line, ending in a newline character. +//| Read a line, ending in a newline character. //| -//| :return: the line read -//| :rtype: int or None -//| -//| .. method:: write(buf) -//| -//| Write the buffer of bytes to the bus. +//| :return: the line read +//| :rtype: int or None""" +//| ... + +//| def write(self, buf: Any) -> Any: +//| """.. method:: write(buf) //| -//| *New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. +//| Write the buffer of bytes to the bus. //| -//| :return: the number of bytes written -//| :rtype: int or None +//| *New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. //| +//| :return: the number of bytes written +//| :rtype: int or None""" +//| ... // These three methods are used by the shared stream methods. STATIC mp_uint_t busio_uart_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) { @@ -259,10 +260,9 @@ STATIC mp_uint_t busio_uart_ioctl(mp_obj_t self_in, mp_uint_t request, mp_uint_t return ret; } -//| .. attribute:: baudrate -//| -//| The current baudrate. -//| +//| baudrate: Any = +//| """The current baudrate.""" +//| ... STATIC mp_obj_t busio_uart_obj_get_baudrate(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -286,10 +286,9 @@ const mp_obj_property_t busio_uart_baudrate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: in_waiting -//| -//| The number of bytes in the input buffer, available to be read -//| +//| in_waiting: Any = +//| """The number of bytes in the input buffer, available to be read""" +//| ... STATIC mp_obj_t busio_uart_obj_get_in_waiting(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -304,10 +303,9 @@ const mp_obj_property_t busio_uart_in_waiting_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: timeout -//| -//| The current timeout, in seconds (float). -//| +//| timeout: Any = +//| """The current timeout, in seconds (float).""" +//| ... STATIC mp_obj_t busio_uart_obj_get_timeout(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -333,10 +331,9 @@ const mp_obj_property_t busio_uart_timeout_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: reset_input_buffer() -//| -//| Discard any unread characters in the input buffer. -//| +//| def reset_input_buffer(self, ) -> Any: +//| """Discard any unread characters in the input buffer.""" +//| ... STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -345,18 +342,16 @@ STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_obj_reset_input_buffer); -//| .. class:: busio.UART.Parity() -//| -//| Enum-like class to define the parity used to verify correct data transfer. -//| -//| .. data:: ODD -//| -//| Total number of ones should be odd. -//| -//| .. data:: EVEN -//| -//| Total number of ones should be even. -//| +//|class busio: +//| def __init__(self, ): +//| """Enum-like class to define the parity used to verify correct data transfer.""" +//| ODD: Any = +//| """Total number of ones should be odd.""" +//| ... +//| EVEN: Any = +//| """Total number of ones should be even.""" +//| ... +//| ... const mp_obj_type_t busio_uart_parity_type; const busio_uart_parity_obj_t busio_uart_parity_odd_obj = { -- cgit v1.2.3 From e7874277abc43d794f521d519f522cb068ab95ef Mon Sep 17 00:00:00 2001 From: dherrada Date: Sat, 25 Apr 2020 15:35:24 -0400 Subject: Fixed empty lines --- shared-bindings/busio/UART.c | 2 -- 1 file changed, 2 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 59c95528d..954cbdd20 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -39,8 +39,6 @@ #include "py/stream.h" #include "supervisor/shared/translate.h" - - //|class UART: //| """.. currentmodule:: busio //| -- cgit v1.2.3 From 27e085ec360fd625210fe70bf71019b8019363b3 Mon Sep 17 00:00:00 2001 From: dherrada Date: Sat, 25 Apr 2020 15:36:16 -0400 Subject: Added pyi to OneWire.c --- shared-bindings/busio/OneWire.c | 92 ++++++++++++++++++++--------------------- 1 file changed, 44 insertions(+), 48 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index 022d6afcf..dd4410d46 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -34,34 +34,36 @@ #include "shared-bindings/busio/OneWire.h" #include "shared-bindings/util.h" -//| .. currentmodule:: busio +//|class OneWire: +//| """.. currentmodule:: busio //| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| ================================================================= +//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol +//| =================================================================""" //| -//| :class:`~busio.OneWire` implements the timing-sensitive foundation of the Maxim -//| (formerly Dallas Semi) OneWire protocol. +//| def __init__(self, pin: microcontroller.Pin): +//| """:class:`~busio.OneWire` implements the timing-sensitive foundation of the Maxim +//| (formerly Dallas Semi) OneWire protocol. //| -//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 +//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 //| -//| .. class:: OneWire(pin) +//| .. class:: OneWire(pin) //| -//| Create a OneWire object associated with the given pin. The object -//| implements the lowest level timing-sensitive bits of the protocol. +//| Create a OneWire object associated with the given pin. The object +//| implements the lowest level timing-sensitive bits of the protocol. //| -//| :param ~microcontroller.Pin pin: Pin connected to the OneWire bus +//| :param ~microcontroller.Pin pin: Pin connected to the OneWire bus //| -//| Read a short series of pulses:: +//| Read a short series of pulses:: //| -//| import busio -//| import board -//| -//| onewire = busio.OneWire(board.D7) -//| onewire.reset() -//| onewire.write_bit(True) -//| onewire.write_bit(False) -//| print(onewire.read_bit()) +//| import busio +//| import board //| +//| onewire = busio.OneWire(board.D7) +//| onewire.reset() +//| onewire.write_bit(True) +//| onewire.write_bit(False) +//| print(onewire.read_bit())""" +//| ... STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin }; static const mp_arg_t allowed_args[] = { @@ -78,10 +80,9 @@ STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialize the OneWire bus and release any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" +//| ... STATIC mp_obj_t busio_onewire_deinit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_onewire_deinit(self); @@ -95,17 +96,15 @@ STATIC void check_for_deinit(busio_onewire_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_onewire_deinit(args[0]); @@ -113,13 +112,12 @@ STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_onewire___exit___obj, 4, 4, busio_onewire_obj___exit__); -//| .. method:: reset() -//| -//| Reset the OneWire bus and read presence -//| -//| :returns: False when at least one device is present -//| :rtype: bool +//| def reset(self, ) -> Any: +//| """Reset the OneWire bus and read presence //| +//| :returns: False when at least one device is present +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -128,13 +126,12 @@ STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_reset_obj, busio_onewire_obj_reset); -//| .. method:: read_bit() -//| -//| Read in a bit -//| -//| :returns: bit state read -//| :rtype: bool +//| def read_bit(self, ) -> Any: +//| """Read in a bit //| +//| :returns: bit state read +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -143,10 +140,9 @@ STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_read_bit_obj, busio_onewire_obj_read_bit); -//| .. method:: write_bit(value) -//| -//| Write out a bit based on value. -//| +//| def write_bit(self, value: Any) -> Any: +//| """Write out a bit based on value.""" +//| ... STATIC mp_obj_t busio_onewire_obj_write_bit(mp_obj_t self_in, mp_obj_t bool_obj) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 8344fce9940c2c964663e541908069b03cbe14e5 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 27 Apr 2020 13:06:47 -0400 Subject: Added inline pyi to analogio --- shared-bindings/analogio/AnalogIn.c | 71 ++++++++++++++++-------------------- shared-bindings/analogio/AnalogOut.c | 62 +++++++++++++++---------------- 2 files changed, 61 insertions(+), 72 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index b4eeb2af1..a8afe75bd 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -36,27 +36,25 @@ #include "shared-bindings/analogio/AnalogIn.h" #include "shared-bindings/util.h" -//| .. currentmodule:: analogio +//|class AnalogIn: +//| """:class:`AnalogIn` -- read analog voltage +//| ============================================ //| -//| :class:`AnalogIn` -- read analog voltage -//| ============================================ +//| Usage:: //| -//| Usage:: +//| import analogio +//| from board import * //| -//| import analogio -//| from board import * +//| adc = analogio.AnalogIn(A1) +//| val = adc.value""" //| -//| adc = analogio.AnalogIn(A1) -//| val = adc.value +//| def __init__(self, pin: microcontroller.Pin): //| - -//| .. class:: AnalogIn(pin) -//| -//| Use the AnalogIn on the given pin. The reference voltage varies by -//| platform so use ``reference_voltage`` to read the configured setting. -//| -//| :param ~microcontroller.Pin pin: the pin to read from +//| """Use the AnalogIn on the given pin. The reference voltage varies by +//| platform so use ``reference_voltage`` to read the configured setting. //| +//| :param ~microcontroller.Pin pin: the pin to read from""" +//| ... STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // check number of arguments @@ -72,10 +70,9 @@ STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Turn off the AnalogIn and release the pin for other use. -//| +//| def deinit(self, ) -> Any: +//| """Turn off the AnalogIn and release the pin for other use.""" +//| ... STATIC mp_obj_t analogio_analogin_deinit(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_analogio_analogin_deinit(self); @@ -88,17 +85,15 @@ STATIC void check_for_deinit(analogio_analogin_obj_t *self) { raise_deinited_error(); } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_analogio_analogin_deinit(args[0]); @@ -106,13 +101,12 @@ STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogin___exit___obj, 4, 4, analogio_analogin___exit__); -//| .. attribute:: value -//| -//| The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only) -//| -//| Even if the underlying analog to digital converter (ADC) is lower -//| resolution, the value is 16-bit. +//| value: Any = +//| """The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only) //| +//| Even if the underlying analog to digital converter (ADC) is lower +//| resolution, the value is 16-bit.""" +//| ... STATIC mp_obj_t analogio_analogin_obj_get_value(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -127,11 +121,10 @@ const mp_obj_property_t analogio_analogin_value_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: reference_voltage -//| -//| The maximum voltage measurable (also known as the reference voltage) as a -//| `float` in Volts. -//| +//| reference_voltage: Any = +//| """The maximum voltage measurable (also known as the reference voltage) as a +//| `float` in Volts.""" +//| ... STATIC mp_obj_t analogio_analogin_obj_get_reference_voltage(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 89cf147b2..1b5808e6c 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -36,28 +36,27 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: analogio +//|class AnalogOut: +//| """.. currentmodule:: analogio //| -//| :class:`AnalogOut` -- output analog voltage -//| ============================================ +//| :class:`AnalogOut` -- output analog voltage +//| ============================================ //| -//| The AnalogOut is used to output analog values (a specific voltage). +//| The AnalogOut is used to output analog values (a specific voltage). //| -//| Example usage:: +//| Example usage:: //| -//| import analogio -//| from microcontroller import pin +//| import analogio +//| from microcontroller import pin //| -//| dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 -//| dac.value = 32768 # makes PA02 1.65V +//| dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 +//| dac.value = 32768 # makes PA02 1.65V""" +//| def __init__(self, pin: microcontroller.Pin): //| - -//| .. class:: AnalogOut(pin) -//| -//| Use the AnalogOut on the given pin. -//| -//| :param ~microcontroller.Pin pin: the pin to output to +//| """Use the AnalogOut on the given pin. //| +//| :param ~microcontroller.Pin pin: the pin to output to""" +//| ... STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // check arguments mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -71,10 +70,9 @@ STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Turn off the AnalogOut and release the pin for other use. -//| +//| def deinit(self, ) -> Any: +//| """Turn off the AnalogOut and release the pin for other use.""" +//| ... STATIC mp_obj_t analogio_analogout_deinit(mp_obj_t self_in) { analogio_analogout_obj_t *self = self_in; @@ -84,17 +82,15 @@ STATIC mp_obj_t analogio_analogout_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogout_deinit_obj, analogio_analogout_deinit); -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_analogio_analogout_deinit(args[0]); @@ -102,12 +98,12 @@ STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogout___exit___obj, 4, 4, analogio_analogout___exit__); -//| .. attribute:: value -//| -//| The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only) +//| value: Any = +//| """The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only) //| -//| Even if the underlying digital to analog converter (DAC) is lower -//| resolution, the value is 16-bit. +//| Even if the underlying digital to analog converter (DAC) is lower +//| resolution, the value is 16-bit.""" +//| ... STATIC mp_obj_t analogio_analogout_obj_set_value(mp_obj_t self_in, mp_obj_t value) { analogio_analogout_obj_t *self = MP_OBJ_TO_PTR(self_in); if (common_hal_analogio_analogout_deinited(self)) { -- cgit v1.2.3 From e96235d0cf7e6548982d1dde4ef69492dfc19cd2 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 27 Apr 2020 16:35:03 -0400 Subject: Added inline pyi to audiobusio --- shared-bindings/audiobusio/I2SOut.c | 188 +++++++++++++++++------------------- shared-bindings/audiobusio/PDMIn.c | 100 +++++++++---------- 2 files changed, 140 insertions(+), 148 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audiobusio/I2SOut.c b/shared-bindings/audiobusio/I2SOut.c index cd662acb5..cad17ad18 100644 --- a/shared-bindings/audiobusio/I2SOut.c +++ b/shared-bindings/audiobusio/I2SOut.c @@ -35,65 +35,64 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiobusio -//| -//| :class:`I2SOut` -- Output an I2S audio signal -//| ======================================================== -//| -//| I2S is used to output an audio signal on an I2S bus. -//| -//| .. class:: I2SOut(bit_clock, word_select, data, *, left_justified) -//| -//| 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 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 `_ -//| using `UDA1334 Breakout `_:: -//| -//| 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 / 18) * (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 audioio -//| 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") -//| +//|class I2SOut: +//| """.. currentmodule:: audiobusio +//| +//| :class:`I2SOut` -- Output an I2S audio signal +//| ======================================================== +//| +//| I2S is used to output an audio signal on an I2S bus.""" +//| def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): +//| """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 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 `_ +//| using `UDA1334 Breakout `_:: +//| +//| 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 / 18) * (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 audioio +//| 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")""" +//| ... STATIC mp_obj_t audiobusio_i2sout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_bit_clock, ARG_word_select, ARG_data, ARG_left_justified }; static const mp_arg_t allowed_args[] = { @@ -116,10 +115,9 @@ STATIC mp_obj_t audiobusio_i2sout_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the I2SOut and releases any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the I2SOut and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t audiobusio_i2sout_deinit(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiobusio_i2sout_deinit(self); @@ -132,17 +130,15 @@ STATIC void check_for_deinit(audiobusio_i2sout_obj_t *self) { raise_deinited_error(); } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiobusio_i2sout_deinit(args[0]); @@ -151,15 +147,14 @@ STATIC mp_obj_t audiobusio_i2sout_obj___exit__(size_t n_args, const mp_obj_t *ar STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_i2sout___exit___obj, 4, 4, audiobusio_i2sout_obj___exit__); -//| .. method:: play(sample, *, loop=False) +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """Plays the sample once when loop=False and continuously when loop=True. +//| Does not block. Use `playing` to block. //| -//| 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`, or `audiomixer.Mixer`. -//| -//| The sample itself should consist of 8 bit or 16 bit samples. +//| Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. //| +//| The sample itself should consist of 8 bit or 16 bit samples.""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -178,10 +173,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_play(size_t n_args, const mp_obj_t *pos_ar } MP_DEFINE_CONST_FUN_OBJ_KW(audiobusio_i2sout_play_obj, 1, audiobusio_i2sout_obj_play); -//| .. method:: stop() -//| -//| Stops playback. -//| +//| def stop(self, ) -> Any: +//| """Stops playback.""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj_stop(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -190,10 +184,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_stop_obj, audiobusio_i2sout_obj_stop); -//| .. attribute:: playing -//| -//| True when the audio sample is being output. (read-only) -//| +//| playing: Any = +//| """True when the audio sample is being output. (read-only)""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj_get_playing(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -208,10 +201,9 @@ const mp_obj_property_t audiobusio_i2sout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: pause() -//| -//| Stops playback temporarily while remembering the position. Use `resume` to resume playback. -//| +//| def pause(self, ) -> Any: +//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj_pause(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -224,10 +216,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_pause_obj, audiobusio_i2sout_obj_pause); -//| .. method:: resume() -//| -//| Resumes sample playback after :py:func:`pause`. -//| +//| def resume(self, ) -> Any: +//| """Resumes sample playback after :py:func:`pause`.""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj_resume(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -240,10 +231,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_resume_obj, audiobusio_i2sout_obj_resume); -//| .. attribute:: paused -//| -//| True when playback is paused. (read-only) -//| +//| paused: Any = +//| """True when playback is paused. (read-only)""" +//| ... STATIC mp_obj_t audiobusio_i2sout_obj_get_paused(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index fce6cf7a2..b75545ba7 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -36,32 +36,39 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiobusio -//| -//| :class:`PDMIn` -- Record an input PDM audio stream -//| ======================================================== -//| -//| PDMIn can be used to record an input audio signal on a given set of pins. + + + + + + + +//|class PDMIn: +//| """.. currentmodule:: audiobusio //| -//| .. class:: PDMIn(clock_pin, data_pin, *, sample_rate=16000, bit_depth=8, mono=True, oversample=64, startup_delay=0.11) +//| :class:`PDMIn` -- Record an input PDM audio stream +//| ======================================================== //| -//| 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. +//| PDMIn can be used to record an input audio signal on a given set of pins.""" //| -//| :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. +//| 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): +//| """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.""" +//| ... //| Record 8-bit unsigned samples to buffer:: //| @@ -86,7 +93,7 @@ //| 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)) -//| +//| STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_clock_pin, ARG_data_pin, ARG_sample_rate, ARG_bit_depth, ARG_mono, ARG_oversample, ARG_startup_delay }; static const mp_arg_t allowed_args[] = { @@ -138,10 +145,9 @@ STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the PDMIn and releases any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the PDMIn and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t audiobusio_pdmin_deinit(mp_obj_t self_in) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiobusio_pdmin_deinit(self); @@ -154,16 +160,14 @@ STATIC void check_for_deinit(audiobusio_pdmin_obj_t *self) { raise_deinited_error(); } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context.""" +//| ... STATIC mp_obj_t audiobusio_pdmin_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiobusio_pdmin_deinit(args[0]); @@ -172,18 +176,17 @@ STATIC mp_obj_t audiobusio_pdmin_obj___exit__(size_t n_args, const mp_obj_t *arg STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_pdmin___exit___obj, 4, 4, audiobusio_pdmin_obj___exit__); -//| .. method:: record(destination, destination_length) -//| -//| Records destination_length bytes of samples to destination. This is +//| def record(self, destination: Any, destination_length: Any) -> Any: +//| """Records destination_length bytes of samples to destination. This is //| blocking. //| -//| An IOError 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. +//| An IOError 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.""" +//| ... STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destination, mp_obj_t destination_length) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_obj); check_for_deinit(self); @@ -214,11 +217,10 @@ STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destinat } MP_DEFINE_CONST_FUN_OBJ_3(audiobusio_pdmin_record_obj, audiobusio_pdmin_obj_record); -//| .. attribute:: sample_rate -//| -//| The actual sample_rate of the recording. This may not match the constructed -//| sample rate due to internal clock limitations. -//| +//| sample_rate: Any = +//| """The actual sample_rate of the recording. This may not match the constructed +//| sample rate due to internal clock limitations.""" +//| ... STATIC mp_obj_t audiobusio_pdmin_obj_get_sample_rate(mp_obj_t self_in) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 088b5b1785c2acd772dfaf97ce09a3098fdca978 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 27 Apr 2020 16:49:12 -0400 Subject: Added inline pyi to audiocore --- shared-bindings/audiocore/RawSample.c | 114 ++++++++++++++++------------------ shared-bindings/audiocore/WaveFile.c | 105 +++++++++++++++---------------- 2 files changed, 104 insertions(+), 115 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audiocore/RawSample.c b/shared-bindings/audiocore/RawSample.c index 96af58a4f..b879b1b97 100644 --- a/shared-bindings/audiocore/RawSample.c +++ b/shared-bindings/audiocore/RawSample.c @@ -35,45 +35,45 @@ #include "shared-bindings/audiocore/RawSample.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiocore -//| -//| :class:`RawSample` -- A raw audio sample buffer -//| ======================================================== -//| -//| An in-memory sound sample -//| -//| .. class:: RawSample(buffer, *, channel_count=1, sample_rate=8000) -//| -//| Create a RawSample based on the given buffer of signed values. If channel_count is more than -//| 1 then each channel's samples should alternate. In other words, for a two channel buffer, the -//| first sample will be for channel 1, the second sample will be for channel two, the third for -//| channel 1 and so on. -//| -//| :param array.array buffer: An `array.array` with samples -//| :param int channel_count: The number of channels in the buffer -//| :param int sample_rate: The desired playback sample rate -//| -//| Simple 8ksps 440 Hz sin wave:: -//| -//| import audiocore -//| import audioio -//| import board -//| import array -//| import time -//| import math -//| -//| # Generate one period of sine wav. -//| 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 / 18) * (2 ** 15)) -//| -//| dac = audioio.AudioOut(board.SPEAKER) -//| sine_wave = audiocore.RawSample(sine_wave) -//| dac.play(sine_wave, loop=True) -//| time.sleep(1) -//| dac.stop() -//| +//|class RawSample: +//| """.. currentmodule:: audiocore +//| +//| :class:`RawSample` -- A raw audio sample buffer +//| ======================================================== +//| +//| An in-memory sound sample""" +//| +//| def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): +//| """Create a RawSample based on the given buffer of signed values. If channel_count is more than +//| 1 then each channel's samples should alternate. In other words, for a two channel buffer, the +//| first sample will be for channel 1, the second sample will be for channel two, the third for +//| channel 1 and so on. +//| +//| :param array.array buffer: An `array.array` with samples +//| :param int channel_count: The number of channels in the buffer +//| :param int sample_rate: The desired playback sample rate +//| +//| Simple 8ksps 440 Hz sin wave:: +//| +//| import audiocore +//| import audioio +//| import board +//| import array +//| import time +//| import math +//| +//| # Generate one period of sine wav. +//| 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 / 18) * (2 ** 15)) +//| +//| dac = audioio.AudioOut(board.SPEAKER) +//| sine_wave = audiocore.RawSample(sine_wave) +//| dac.play(sine_wave, loop=True) +//| time.sleep(1) +//| dac.stop()""" +//| ... STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_channel_count, ARG_sample_rate }; static const mp_arg_t allowed_args[] = { @@ -105,10 +105,9 @@ STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the AudioOut and releases any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the AudioOut and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t audioio_rawsample_deinit(mp_obj_t self_in) { audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_rawsample_deinit(self); @@ -122,17 +121,15 @@ STATIC void check_for_deinit(audioio_rawsample_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_rawsample_deinit(args[0]); @@ -140,13 +137,12 @@ STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *ar } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_rawsample___exit___obj, 4, 4, audioio_rawsample_obj___exit__); -//| .. attribute:: sample_rate -//| -//| 32 bit value that dictates how quickly samples are played in Hertz (cycles per second). -//| When the sample is looped, this can change the pitch output without changing the underlying -//| sample. This will not change the sample rate of any active playback. Call ``play`` again to -//| change it. -//| +//| sample_rate: Any = +//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second). +//| When the sample is looped, this can change the pitch output without changing the underlying +//| sample. This will not change the sample rate of any active playback. Call ``play`` again to +//| change it.""" +//| ... STATIC mp_obj_t audioio_rawsample_obj_get_sample_rate(mp_obj_t self_in) { audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiocore/WaveFile.c b/shared-bindings/audiocore/WaveFile.c index 178d2a139..f57e1f877 100644 --- a/shared-bindings/audiocore/WaveFile.c +++ b/shared-bindings/audiocore/WaveFile.c @@ -33,44 +33,43 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiocore +//|class WaveFile: +//| """.. currentmodule:: audiocore //| -//| :class:`WaveFile` -- Load a wave file for audio playback -//| ======================================================== +//| :class:`WaveFile` -- Load a wave file for audio playback +//| ======================================================== //| -//| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must -//| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating -//| an internal buffer. +//| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must +//| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating +//| an internal buffer.""" +//| def __init__(self, file: typing.BinaryIO, buffer: bytearray): +//| """Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| .. class:: WaveFile(file[, buffer]) +//| :param typing.BinaryIO file: Already opened wave file +//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally. //| -//| Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| :param typing.BinaryIO file: Already opened wave file -//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally. +//| Playing a wave file from flash:: //| +//| import board +//| import audiocore +//| import audioio +//| import digitalio //| -//| Playing a wave file from flash:: +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) //| -//| import board -//| import audiocore -//| import audioio -//| import digitalio -//| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) -//| -//| data = open("cplay-5.1-16bit-16khz.wav", "rb") -//| wav = audiocore.WaveFile(data) -//| a = audioio.AudioOut(board.A0) -//| -//| print("playing") -//| a.play(wav) -//| while a.playing: -//| pass -//| print("stopped") +//| data = open("cplay-5.1-16bit-16khz.wav", "rb") +//| wav = audiocore.WaveFile(data) +//| a = audioio.AudioOut(board.A0) //| +//| print("playing") +//| a.play(wav) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 2, false); @@ -93,10 +92,9 @@ STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the WaveFile and releases all memory resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the WaveFile and releases all memory resources for reuse.""" +//| ... STATIC mp_obj_t audioio_wavefile_deinit(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_wavefile_deinit(self); @@ -110,17 +108,15 @@ STATIC void check_for_deinit(audioio_wavefile_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_wavefile_deinit(args[0]); @@ -128,12 +124,11 @@ STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_wavefile___exit___obj, 4, 4, audioio_wavefile_obj___exit__); -//| .. attribute:: sample_rate -//| -//| 32 bit value that dictates how quickly samples are loaded into the DAC -//| in Hertz (cycles per second). When the sample is looped, this can change -//| the pitch output without changing the underlying sample. -//| +//| sample_rate: Any = +//| """32 bit value that dictates how quickly samples are loaded into the DAC +//| in Hertz (cycles per second). When the sample is looped, this can change +//| the pitch output without changing the underlying sample.""" +//| ... STATIC mp_obj_t audioio_wavefile_obj_get_sample_rate(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -156,10 +151,9 @@ const mp_obj_property_t audioio_wavefile_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: bits_per_sample -//| -//| Bits per sample. (read only) -//| +//| bits_per_sample: Any = +//| """Bits per sample. (read only)""" +//| ... STATIC mp_obj_t audioio_wavefile_obj_get_bits_per_sample(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -174,10 +168,9 @@ const mp_obj_property_t audioio_wavefile_bits_per_sample_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: channel_count -//| -//| Number of audio channels. (read only) -//| +//| channel_count: Any = +//| """Number of audio channels. (read only)""" +//| ... STATIC mp_obj_t audioio_wavefile_obj_get_channel_count(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 1363e6e724124b6f51619113b2877da53195dd1e Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 27 Apr 2020 17:02:48 -0400 Subject: Added inline pyi to audiocore --- shared-bindings/audioio/AudioOut.c | 191 ++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 100 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c index ea1efcdff..8df923e6f 100644 --- a/shared-bindings/audioio/AudioOut.c +++ b/shared-bindings/audioio/AudioOut.c @@ -36,64 +36,64 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audioio -//| -//| :class:`AudioOut` -- Output an analog audio signal -//| ======================================================== -//| -//| AudioOut can be used to output an analog audio signal on a given pin. -//| -//| .. class:: AudioOut(left_channel, *, right_channel=None, quiescent_value=0x8000) -//| -//| Create a AudioOut object associated with the given pin(s). This allows you to -//| play audio signals out on the given pin(s). -//| -//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to -//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to -//| :param int quiescent_value: The output value when no signal is present. Samples should start -//| and end with this value to prevent audible popping. -//| -//| Simple 8ksps 440 Hz sin wave:: -//| -//| import audiocore -//| import audioio -//| import board -//| import array -//| import time -//| import math -//| -//| # Generate one period of sine wav. -//| 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 / 18) * (2 ** 15) + 2 ** 15) -//| -//| dac = audioio.AudioOut(board.SPEAKER) -//| sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) -//| dac.play(sine_wave, loop=True) -//| time.sleep(1) -//| dac.stop() -//| -//| Playing a wave file from flash:: -//| -//| import board -//| import audioio -//| import digitalio -//| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) -//| -//| data = open("cplay-5.1-16bit-16khz.wav", "rb") -//| wav = audiocore.WaveFile(data) -//| a = audioio.AudioOut(board.A0) -//| -//| print("playing") -//| a.play(wav) -//| while a.playing: -//| pass -//| print("stopped") -//| +//|class AudioOut: +//| """.. currentmodule:: audioio +//| +//| :class:`AudioOut` -- Output an analog audio signal +//| ======================================================== +//| +//| AudioOut can be used to output an analog audio signal on a given pin.""" +//| +//| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): +//| """Create a AudioOut object associated with the given pin(s). This allows you to +//| play audio signals out on the given pin(s). +//| +//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to +//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to +//| :param int quiescent_value: The output value when no signal is present. Samples should start +//| and end with this value to prevent audible popping. +//| +//| Simple 8ksps 440 Hz sin wave:: +//| +//| import audiocore +//| import audioio +//| import board +//| import array +//| import time +//| import math +//| +//| # Generate one period of sine wav. +//| 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 / 18) * (2 ** 15) + 2 ** 15) +//| +//| dac = audioio.AudioOut(board.SPEAKER) +//| sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) +//| dac.play(sine_wave, loop=True) +//| time.sleep(1) +//| dac.stop() +//| +//| Playing a wave file from flash:: +//| +//| import board +//| import audioio +//| import digitalio +//| +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) +//| +//| data = open("cplay-5.1-16bit-16khz.wav", "rb") +//| wav = audiocore.WaveFile(data) +//| a = audioio.AudioOut(board.A0) +//| +//| print("playing") +//| a.play(wav) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... STATIC mp_obj_t audioio_audioout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_left_channel, ARG_right_channel, ARG_quiescent_value }; static const mp_arg_t allowed_args[] = { @@ -115,10 +115,9 @@ STATIC mp_obj_t audioio_audioout_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the AudioOut and releases any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the AudioOut and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t audioio_audioout_deinit(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_audioout_deinit(self); @@ -131,17 +130,15 @@ STATIC void check_for_deinit(audioio_audioout_obj_t *self) { raise_deinited_error(); } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_audioout_deinit(args[0]); @@ -150,17 +147,16 @@ STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *arg STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_audioout___exit___obj, 4, 4, audioio_audioout_obj___exit__); -//| .. method:: play(sample, *, loop=False) +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """Plays the sample once when loop=False and continuously when loop=True. +//| Does not block. Use `playing` to block. //| -//| 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`, or `audiomixer.Mixer`. -//| -//| The sample itself should consist of 16 bit samples. Microcontrollers with a lower output -//| resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit -//| DAC that ignores the lowest 6 bits when playing 16 bit samples. +//| Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. //| +//| The sample itself should consist of 16 bit samples. Microcontrollers with a lower output +//| resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit +//| DAC that ignores the lowest 6 bits when playing 16 bit samples.""" +//| ... STATIC mp_obj_t audioio_audioout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -179,10 +175,9 @@ STATIC mp_obj_t audioio_audioout_obj_play(size_t n_args, const mp_obj_t *pos_arg } MP_DEFINE_CONST_FUN_OBJ_KW(audioio_audioout_play_obj, 1, audioio_audioout_obj_play); -//| .. method:: stop() -//| -//| Stops playback and resets to the start of the sample. -//| +//| def stop(self, ) -> Any: +//| """Stops playback and resets to the start of the sample.""" +//| ... STATIC mp_obj_t audioio_audioout_obj_stop(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -191,10 +186,9 @@ STATIC mp_obj_t audioio_audioout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_stop_obj, audioio_audioout_obj_stop); -//| .. attribute:: playing -//| -//| True when an audio sample is being output even if `paused`. (read-only) -//| +//| playing: Any = +//| """True when an audio sample is being output even if `paused`. (read-only)""" +//| ... STATIC mp_obj_t audioio_audioout_obj_get_playing(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -209,10 +203,9 @@ const mp_obj_property_t audioio_audioout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: pause() -//| -//| Stops playback temporarily while remembering the position. Use `resume` to resume playback. -//| +//| def pause(self, ) -> Any: +//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//| ... STATIC mp_obj_t audioio_audioout_obj_pause(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -225,10 +218,9 @@ STATIC mp_obj_t audioio_audioout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_pause_obj, audioio_audioout_obj_pause); -//| .. method:: resume() -//| -//| Resumes sample playback after :py:func:`pause`. -//| +//| def resume(self, ) -> Any: +//| """Resumes sample playback after :py:func:`pause`.""" +//| ... STATIC mp_obj_t audioio_audioout_obj_resume(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -241,10 +233,9 @@ STATIC mp_obj_t audioio_audioout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_resume_obj, audioio_audioout_obj_resume); -//| .. attribute:: paused -//| -//| True when playback is paused. (read-only) -//| +//| paused: Any = +//| """True when playback is paused. (read-only)""" +//| ... STATIC mp_obj_t audioio_audioout_obj_get_paused(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 8330471068c4cba89802c2b0b9a91a60e656c12e Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 27 Apr 2020 17:20:40 -0400 Subject: Added inline pyi to audiomixer --- shared-bindings/audiomixer/Mixer.c | 141 +++++++++++++++----------------- shared-bindings/audiomixer/MixerVoice.c | 49 ++++++----- 2 files changed, 90 insertions(+), 100 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c index 03ffb9373..1949f2add 100644 --- a/shared-bindings/audiomixer/Mixer.c +++ b/shared-bindings/audiomixer/Mixer.c @@ -38,50 +38,50 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiomixer +//|class Mixer: +//| """.. currentmodule:: audiomixer //| -//| :class:`Mixer` -- Mixes one or more audio samples together -//| =========================================================== +//| :class:`Mixer` -- Mixes one or more audio samples together +//| =========================================================== //| -//| Mixer mixes multiple samples into one sample. +//| Mixer mixes multiple samples into one sample.""" //| -//| .. class:: Mixer(voice_count=2, buffer_size=1024, channel_count=2, bits_per_sample=16, samples_signed=True, sample_rate=8000) +//| def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): +//| """Create a Mixer object that can mix multiple channels with the same sample rate. +//| Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects. //| -//| Create a Mixer object that can mix multiple channels with the same sample rate. -//| Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects. +//| :param int voice_count: The maximum number of voices to mix +//| :param int buffer_size: The total size in bytes of the buffers to mix into +//| :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo. +//| :param int bits_per_sample: The bits per sample of the samples being played +//| :param bool samples_signed: Samples are signed (True) or unsigned (False) +//| :param int sample_rate: The sample rate to be used for all samples //| -//| :param int voice_count: The maximum number of voices to mix -//| :param int buffer_size: The total size in bytes of the buffers to mix into -//| :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo. -//| :param int bits_per_sample: The bits per sample of the samples being played -//| :param bool samples_signed: Samples are signed (True) or unsigned (False) -//| :param int sample_rate: The sample rate to be used for all samples +//| Playing a wave file from flash:: //| -//| Playing a wave file from flash:: +//| import board +//| import audioio +//| import audiocore +//| import audiomixer +//| import digitalio //| -//| import board -//| import audioio -//| import audiocore -//| import audiomixer -//| import digitalio -//| -//| a = audioio.AudioOut(board.A0) -//| music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb")) -//| drum = audiocore.WaveFile(open("drum.wav", "rb")) -//| mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1, -//| bits_per_sample=16, samples_signed=True) -//| -//| print("playing") -//| # Have AudioOut play our Mixer source -//| a.play(mixer) -//| # Play the first sample voice -//| mixer.voice[0].play(music) -//| while mixer.playing: -//| # Play the second sample voice -//| mixer.voice[1].play(drum) -//| time.sleep(1) -//| print("stopped") +//| a = audioio.AudioOut(board.A0) +//| music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb")) +//| drum = audiocore.WaveFile(open("drum.wav", "rb")) +//| mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1, +//| bits_per_sample=16, samples_signed=True) //| +//| print("playing") +//| # Have AudioOut play our Mixer source +//| a.play(mixer) +//| # Play the first sample voice +//| mixer.voice[0].play(music) +//| while mixer.playing: +//| # Play the second sample voice +//| mixer.voice[1].play(drum) +//| time.sleep(1) +//| print("stopped")""" +//| ... STATIC mp_obj_t audiomixer_mixer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice_count, ARG_buffer_size, ARG_channel_count, ARG_bits_per_sample, ARG_samples_signed, ARG_sample_rate }; static const mp_arg_t allowed_args[] = { @@ -125,10 +125,9 @@ STATIC mp_obj_t audiomixer_mixer_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the Mixer and releases any hardware resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the Mixer and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t audiomixer_mixer_deinit(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiomixer_mixer_deinit(self); @@ -142,17 +141,15 @@ STATIC void check_for_deinit(audiomixer_mixer_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audiomixer_mixer_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiomixer_mixer_deinit(args[0]); @@ -160,10 +157,9 @@ STATIC mp_obj_t audiomixer_mixer_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiomixer_mixer___exit___obj, 4, 4, audiomixer_mixer_obj___exit__); -//| .. attribute:: playing -//| -//| True when any voice is being output. (read-only) -//| +//| playing: Any = +//| """True when any voice is being output. (read-only)""" +//| ... STATIC mp_obj_t audiomixer_mixer_obj_get_playing(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -178,10 +174,9 @@ const mp_obj_property_t audiomixer_mixer_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: sample_rate -//| -//| 32 bit value that dictates how quickly samples are played in Hertz (cycles per second). -//| +//| sample_rate: Any = +//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second).""" +//| ... STATIC mp_obj_t audiomixer_mixer_obj_get_sample_rate(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -196,14 +191,14 @@ const mp_obj_property_t audiomixer_mixer_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: voice -//| -//| A tuple of the mixer's `audiomixer.MixerVoice` object(s). +//| voice: Any = +//| """A tuple of the mixer's `audiomixer.MixerVoice` object(s). //| -//| .. code-block:: python +//| .. code-block:: python //| -//| >>> mixer.voice -//| (,) +//| >>> mixer.voice +//| (,)""" +//| ... STATIC mp_obj_t audiomixer_mixer_obj_get_voice(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -218,15 +213,14 @@ const mp_obj_property_t audiomixer_mixer_voice_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: play(sample, *, voice=0, loop=False) +//| def play(self, sample: Any, *, voice: Any = 0, loop: Any = False) -> Any: +//| """Plays the sample once when loop=False and continuously when loop=True. +//| Does not block. Use `playing` to block. //| -//| 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`, or `audiomixer.Mixer`. -//| -//| The sample must match the Mixer's encoding settings given in the constructor. +//| Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. //| +//| The sample must match the Mixer's encoding settings given in the constructor.""" +//| ... STATIC mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_voice, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -251,10 +245,9 @@ STATIC mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_arg } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixer_play_obj, 1, audiomixer_mixer_obj_play); -//| .. method:: stop_voice(voice=0) -//| -//| Stops playback of the sample on the given voice. -//| +//| def stop_voice(self, voice: Any = 0) -> Any: +//| """Stops playback of the sample on the given voice.""" +//| ... STATIC mp_obj_t audiomixer_mixer_obj_stop_voice(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/audiomixer/MixerVoice.c b/shared-bindings/audiomixer/MixerVoice.c index 188f76f57..e6c750baf 100644 --- a/shared-bindings/audiomixer/MixerVoice.c +++ b/shared-bindings/audiomixer/MixerVoice.c @@ -37,17 +37,18 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiomixer +//|class MixerVoice: +//| """.. currentmodule:: audiomixer //| -//| :class:`MixerVoice` -- Voice objects used with Mixer -//| ===================================================== +//| :class:`MixerVoice` -- Voice objects used with Mixer +//| ===================================================== //| -//| Used to access and control samples with `audiomixer.Mixer`. +//| Used to access and control samples with `audiomixer.Mixer`.""" //| -//| .. class:: MixerVoice() -//| -//| MixerVoice instance object(s) created by `audiomixer.Mixer`. +//| def __init__(self, ): //| +//| """MixerVoice instance object(s) created by `audiomixer.Mixer`.""" +//| ... // TODO: support mono or stereo voices STATIC mp_obj_t audiomixer_mixervoice_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { audiomixer_mixervoice_obj_t *self = m_new_obj(audiomixer_mixervoice_obj_t); @@ -58,15 +59,14 @@ STATIC mp_obj_t audiomixer_mixervoice_make_new(const mp_obj_type_t *type, size_t return MP_OBJ_FROM_PTR(self); } -//| .. method:: play(sample, *, loop=False) -//| -//| 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`, `audiomixer.Mixer` or `audiocore.RawSample`. +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """Plays the sample once when ``loop=False``, and continuously when ``loop=True``. +//| Does not block. Use `playing` to block. //| -//| The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor. +//| Sample must be an `audiocore.WaveFile`, `audiomixer.Mixer` or `audiocore.RawSample`. //| +//| The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor.""" +//| ... STATIC mp_obj_t audiomixer_mixervoice_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -83,10 +83,9 @@ STATIC mp_obj_t audiomixer_mixervoice_obj_play(size_t n_args, const mp_obj_t *po } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixervoice_play_obj, 1, audiomixer_mixervoice_obj_play); -//| .. method:: stop() -//| -//| Stops playback of the sample on this voice. -//| +//| def stop(self, ) -> Any: +//| """Stops playback of the sample on this voice.""" +//| ... STATIC mp_obj_t audiomixer_mixervoice_obj_stop(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice }; static const mp_arg_t allowed_args[] = { @@ -102,10 +101,9 @@ STATIC mp_obj_t audiomixer_mixervoice_obj_stop(size_t n_args, const mp_obj_t *po } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixervoice_stop_obj, 1, audiomixer_mixervoice_obj_stop); -//| .. attribute:: level() -//| -//| The volume level of a voice, as a floating point number between 0 and 1. -//| +//| level(): Any = +//| """The volume level of a voice, as a floating point number between 0 and 1.""" +//| ... STATIC mp_obj_t audiomixer_mixervoice_obj_get_level(mp_obj_t self_in) { return mp_obj_new_float(common_hal_audiomixer_mixervoice_get_level(self_in)); } @@ -139,10 +137,9 @@ const mp_obj_property_t audiomixer_mixervoice_level_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: playing -//| -//| True when this voice is being output. (read-only) -//| +//| playing: Any = +//| """True when this voice is being output. (read-only)""" +//| ... STATIC mp_obj_t audiomixer_mixervoice_obj_get_playing(mp_obj_t self_in) { audiomixer_mixervoice_obj_t *self = MP_OBJ_TO_PTR(self_in); -- cgit v1.2.3 From 829da5c12732337cc72f2c089bc72cb437a02e0c Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 27 Apr 2020 17:29:50 -0400 Subject: Added inline pyi to audiomp3 --- shared-bindings/audiomp3/MP3Decoder.c | 113 ++++++++++++++++------------------ 1 file changed, 53 insertions(+), 60 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audiomp3/MP3Decoder.c b/shared-bindings/audiomp3/MP3Decoder.c index 224042212..0bb2c8829 100644 --- a/shared-bindings/audiomp3/MP3Decoder.c +++ b/shared-bindings/audiomp3/MP3Decoder.c @@ -34,42 +34,42 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiomp3 +//|class MP3: +//| """.. currentmodule:: audiomp3 //| -//| :class:`MP3Decoder` -- Load a mp3 file for audio playback -//| ========================================================= +//| :class:`MP3Decoder` -- Load a mp3 file for audio playback +//| ========================================================= //| -//| An object that decodes MP3 files for playback on an audio device. +//| An object that decodes MP3 files for playback on an audio device.""" //| -//| .. class:: MP3(file[, buffer]) +//| def __init__(self, file: typing.BinaryIO, buffer: bytearray): +//| """Load a .mp3 file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| Load a .mp3 file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. +//| :param typing.BinaryIO file: Already opened mp3 file +//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file. //| -//| :param typing.BinaryIO file: Already opened mp3 file -//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file. //| +//| Playing a mp3 file from flash:: //| -//| Playing a mp3 file from flash:: +//| import board +//| import audiomp3 +//| import audioio +//| import digitalio //| -//| import board -//| import audiomp3 -//| import audioio -//| import digitalio +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) //| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) -//| -//| data = open("cplay-16bit-16khz-64kbps.mp3", "rb") -//| mp3 = audiomp3.MP3Decoder(data) -//| a = audioio.AudioOut(board.A0) -//| -//| print("playing") -//| a.play(mp3) -//| while a.playing: -//| pass -//| print("stopped") +//| data = open("cplay-16bit-16khz-64kbps.mp3", "rb") +//| mp3 = audiomp3.MP3Decoder(data) +//| a = audioio.AudioOut(board.A0) //| +//| print("playing") +//| a.play(mp3) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... STATIC mp_obj_t audiomp3_mp3file_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 2, false); @@ -92,10 +92,9 @@ STATIC mp_obj_t audiomp3_mp3file_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the MP3 and releases all memory resources for reuse. -//| +//| def deinit(self, ) -> Any: +//| """Deinitialises the MP3 and releases all memory resources for reuse.""" +//| ... STATIC mp_obj_t audiomp3_mp3file_deinit(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiomp3_mp3file_deinit(self); @@ -109,17 +108,16 @@ STATIC void check_for_deinit(audiomp3_mp3file_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. -//| +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: //| +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audiomp3_mp3file_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiomp3_mp3file_deinit(args[0]); @@ -127,10 +125,9 @@ STATIC mp_obj_t audiomp3_mp3file_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiomp3_mp3file___exit___obj, 4, 4, audiomp3_mp3file_obj___exit__); -//| .. attribute:: file -//| -//| File to play back. -//| +//| file: Any = +//| """File to play back.""" +//| ... STATIC mp_obj_t audiomp3_mp3file_obj_get_file(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -158,12 +155,11 @@ const mp_obj_property_t audiomp3_mp3file_file_obj = { -//| .. attribute:: sample_rate -//| -//| 32 bit value that dictates how quickly samples are loaded into the DAC -//| in Hertz (cycles per second). When the sample is looped, this can change -//| the pitch output without changing the underlying sample. -//| +//| sample_rate: Any = +//| """32 bit value that dictates how quickly samples are loaded into the DAC +//| in Hertz (cycles per second). When the sample is looped, this can change +//| the pitch output without changing the underlying sample.""" +//| ... STATIC mp_obj_t audiomp3_mp3file_obj_get_sample_rate(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -186,10 +182,9 @@ const mp_obj_property_t audiomp3_mp3file_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: bits_per_sample -//| -//| Bits per sample. (read only) -//| +//| bits_per_sample: Any = +//| """Bits per sample. (read only)""" +//| ... STATIC mp_obj_t audiomp3_mp3file_obj_get_bits_per_sample(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -204,10 +199,9 @@ const mp_obj_property_t audiomp3_mp3file_bits_per_sample_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: channel_count -//| -//| Number of audio channels. (read only) -//| +//| channel_count: Any = +//| """Number of audio channels. (read only)""" +//| ... STATIC mp_obj_t audiomp3_mp3file_obj_get_channel_count(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -222,10 +216,9 @@ const mp_obj_property_t audiomp3_mp3file_channel_count_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: rms_level -//| -//| The RMS audio level of a recently played moment of audio. (read only) -//| +//| rms_level: Any = +//| """The RMS audio level of a recently played moment of audio. (read only)""" +//| ... STATIC mp_obj_t audiomp3_mp3file_obj_get_rms_level(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 724dcda3ec8319e961fb032e4bef2524c9bf6948 Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 28 Apr 2020 18:39:58 -0400 Subject: Fixed whitespace in busio --- shared-bindings/busio/I2C.c | 178 ++++++++++++++++++------------------ shared-bindings/busio/OneWire.c | 86 ++++++++--------- shared-bindings/busio/SPI.c | 198 ++++++++++++++++++++-------------------- shared-bindings/busio/UART.c | 160 ++++++++++++++++---------------- 4 files changed, 311 insertions(+), 311 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 0cd392f9a..8b71be085 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -37,32 +37,32 @@ #include "supervisor/shared/translate.h" //|class I2C: -//| """.. currentmodule:: busio +//|""".. currentmodule:: busio //| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------""" -//| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): -//| """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. +//|:class:`I2C` --- Two wire serial protocol +//|------------------------------------------""" +//|def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): +//|"""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 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 ` data descriptors. +//|.. seealso:: Using this class to directly read registers requires manual +//|bit unpacking. Instead, use an existing driver or make one with +//|:ref:`Register ` data descriptors. //| -//| :param ~microcontroller.Pin scl: The clock pin -//| :param ~microcontroller.Pin sda: The data pin -//| :param int frequency: The clock frequency in Hertz -//| :param int timeout: The maximum clock stretching timeut - (used only for bitbangio.I2C; ignored for busio.I2C) +//|:param ~microcontroller.Pin scl: The clock pin +//|:param ~microcontroller.Pin sda: The data pin +//|:param int frequency: The clock frequency in Hertz +//|:param int timeout: The maximum clock stretching timeut - (used only for bitbangio.I2C; ignored for busio.I2C) //| -//| .. note:: On the nRF52840, only one I2C object may be created, -//| except on the Circuit Playground Bluefruit, which allows two, -//| one for the onboard accelerometer, and one for offboard use.""" -//| ... +//|.. note:: On the nRF52840, only one I2C object may be created, +//|except on the Circuit Playground Bluefruit, which allows two, +//|one for the onboard accelerometer, and one for offboard use.""" +//|... STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { busio_i2c_obj_t *self = m_new_obj(busio_i2c_obj_t); self->base.type = &busio_i2c_type; @@ -83,9 +83,9 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| def deinit(self, ) -> Any: -//| """Releases control of the underlying hardware so other classes can use it.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Releases control of the underlying hardware so other classes can use it.""" +//|... STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_i2c_deinit(self); @@ -99,15 +99,15 @@ STATIC void check_for_deinit(busio_i2c_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used in Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used in Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware on context exit. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware on context exit. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_i2c_deinit(args[0]); @@ -122,13 +122,13 @@ static void check_lock(busio_i2c_obj_t *self) { } } -//| def scan(self, ) -> Any: -//| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a -//| list of those that respond. +//|def scan(self, ) -> Any: +//|"""Scan all I2C addresses between 0x08 and 0x77 inclusive and return a +//|list of those that respond. //| -//| :return: List of device ids on the I2C bus -//| :rtype: list""" -//| ... +//|:return: List of device ids on the I2C bus +//|:rtype: list""" +//|... STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -145,11 +145,11 @@ STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); -//| def try_lock(self, ) -> Any: -//| """Attempts to grab the I2C lock. Returns True on success. -//| :return: True when lock has been grabbed -//| :rtype: bool""" -//| ... +//|def try_lock(self, ) -> Any: +//|"""Attempts to grab the I2C lock. Returns True on success. +//|:return: True when lock has been grabbed +//|:rtype: bool""" +//|... STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -157,9 +157,9 @@ STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); -//| def unlock(self, ) -> Any: -//| """Releases the I2C lock.""" -//| ... +//|def unlock(self, ) -> Any: +//|"""Releases the I2C lock.""" +//|... STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -168,20 +168,20 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); -//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: -//| """Read into ``buffer`` from the slave specified by ``address``. -//| The number of bytes read will be the length of ``buffer``. -//| At least one byte must be read. +//|def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: +//|"""Read into ``buffer`` from the slave specified 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. +//|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 bytearray buffer: buffer to write into -//| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" -//| ... +//|:param int address: 7-bit device address +//|:param bytearray buffer: buffer to write into +//|:param int start: Index to start writing at +//|:param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//|... // Shared arg parsing for readfrom_into and writeto_then_readfrom. STATIC void readfrom(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end) { mp_buffer_info_t bufinfo; @@ -219,26 +219,26 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into); -//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: -//| """Write the bytes from ``buffer`` to the slave specified by ``address``. -//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be -//| removed in CircuitPython 6.x. Use `writeto_then_readfrom` when needing a write, no stop and -//| repeated start before a read. +//|def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: +//|"""Write the bytes from ``buffer`` to the slave specified by ``address``. +//|Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be +//|removed in CircuitPython 6.x. 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]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. +//|If ``start`` or ``end`` is provided, then the buffer will be sliced +//|as if ``buffer[start:end]``. This will not cause an allocation like +//|``buffer[start:end]`` will so it saves memory. //| -//| Writing a buffer or slice of length zero is permitted, as it can be used -//| to poll for the existence of a device. +//|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 bytearray buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param bool stop: If true, output an I2C stop condition after the buffer is written. -//| Deprecated. Will be removed in 6.x and act as stop=True.""" -//| ... +//|:param int address: 7-bit device address +//|:param bytearray buffer: buffer containing the bytes to write +//|:param int start: Index to start writing from +//|:param int end: Index to read up to but not include. Defaults to ``len(buffer)`` +//|:param bool stop: If true, output an I2C stop condition after the buffer is written. +//|Deprecated. Will be removed in 6.x and act as stop=True.""" +//|... // Shared arg parsing for writeto and writeto_then_readfrom. STATIC void writeto(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end, bool stop) { // get the buffer to write the data from @@ -277,23 +277,23 @@ STATIC mp_obj_t busio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, mp_ma } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto); -//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: -//| """Write the bytes from ``out_buffer`` to the slave specified 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. +//|def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: +//|"""Write the bytes from ``out_buffer`` to the slave specified 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 ``start`` or ``end`` is provided, then the corresponding buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]`` -//| will so it saves memory. +//|If ``start`` or ``end`` is provided, then the corresponding 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 bytearray out_buffer: buffer containing the bytes to write -//| :param bytearray in_buffer: buffer to write into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" -//| ... +//|:param int address: 7-bit device address +//|:param bytearray out_buffer: buffer containing the bytes to write +//|:param bytearray in_buffer: buffer to write into +//|:param int out_start: Index to start writing from +//|:param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` +//|:param int in_start: Index to start writing at +//|:param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//|... STATIC mp_obj_t busio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index dd4410d46..d6af32bd9 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -35,35 +35,35 @@ #include "shared-bindings/util.h" //|class OneWire: -//| """.. currentmodule:: busio +//|""".. currentmodule:: busio //| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| =================================================================""" +//|:class:`OneWire` -- Lowest-level of the Maxim OneWire protocol +//|=================================================================""" //| -//| def __init__(self, pin: microcontroller.Pin): -//| """:class:`~busio.OneWire` implements the timing-sensitive foundation of the Maxim -//| (formerly Dallas Semi) OneWire protocol. +//|__init__(self, pin: microcontroller.Pin): +//|""":class:`~busio.OneWire` implements the timing-sensitive foundation of the Maxim +//|(formerly Dallas Semi) OneWire protocol. //| -//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 +//|Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 //| -//| .. class:: OneWire(pin) +//|.. class:: OneWire(pin) //| -//| Create a OneWire object associated with the given pin. The object -//| implements the lowest level timing-sensitive bits of the protocol. +//|Create a OneWire object associated with the given pin. The object +//|implements the lowest level timing-sensitive bits of the protocol. //| -//| :param ~microcontroller.Pin pin: Pin connected to the OneWire bus +//|:param ~microcontroller.Pin pin: Pin connected to the OneWire bus //| -//| Read a short series of pulses:: +//|Read a short series of pulses:: //| -//| import busio -//| import board +//|import busio +//|import board //| -//| onewire = busio.OneWire(board.D7) -//| onewire.reset() -//| onewire.write_bit(True) -//| onewire.write_bit(False) -//| print(onewire.read_bit())""" -//| ... +//|onewire = busio.OneWire(board.D7) +//|onewire.reset() +//|onewire.write_bit(True) +//|onewire.write_bit(False) +//|print(onewire.read_bit())""" +//|... STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin }; static const mp_arg_t allowed_args[] = { @@ -80,9 +80,9 @@ STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialize the OneWire bus and release any hardware resources for reuse.""" +//|... STATIC mp_obj_t busio_onewire_deinit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_onewire_deinit(self); @@ -96,15 +96,15 @@ STATIC void check_for_deinit(busio_onewire_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_onewire_deinit(args[0]); @@ -112,12 +112,12 @@ STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_onewire___exit___obj, 4, 4, busio_onewire_obj___exit__); -//| def reset(self, ) -> Any: -//| """Reset the OneWire bus and read presence +//|def reset(self, ) -> Any: +//|"""Reset the OneWire bus and read presence //| -//| :returns: False when at least one device is present -//| :rtype: bool""" -//| ... +//|:returns: False when at least one device is present +//|:rtype: bool""" +//|... STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -126,12 +126,12 @@ STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_reset_obj, busio_onewire_obj_reset); -//| def read_bit(self, ) -> Any: -//| """Read in a bit +//|def read_bit(self, ) -> Any: +//|"""Read in a bit //| -//| :returns: bit state read -//| :rtype: bool""" -//| ... +//|:returns: bit state read +//|:rtype: bool""" +//|... STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -140,9 +140,9 @@ STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_read_bit_obj, busio_onewire_obj_read_bit); -//| def write_bit(self, value: Any) -> Any: -//| """Write out a bit based on value.""" -//| ... +//|def write_bit(self, value: Any) -> Any: +//|"""Write out a bit based on value.""" +//|... STATIC mp_obj_t busio_onewire_obj_write_bit(mp_obj_t self_in, mp_obj_t bool_obj) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 1ac9629f8..5643b0d04 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -42,42 +42,42 @@ //|class SPI: -//| """.. currentmodule:: busio +//|""".. currentmodule:: busio //| -//| `SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//|`SPI` -- a 3-4 wire serial protocol +//|----------------------------------------------- //| -//| SPI is a serial protocol that has exclusive pins for data in and out of the -//| master. It is typically faster than :py:class:`~busio.I2C` because a -//| separate pin is used to control the active slave rather than a transitted -//| address. This class only manages three of the four SPI lines: `!clock`, -//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave -//| select line. (This is common because multiple slaves can share the `!clock`, -//| `!MOSI` and `!MISO` lines and therefore the hardware.)""" +//|SPI is a serial protocol that has exclusive pins for data in and out of the +//|master. It is typically faster than :py:class:`~busio.I2C` because a +//|separate pin is used to control the active slave rather than a transitted +//|address. This class only manages three of the four SPI lines: `!clock`, +//|`!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave +//|select line. (This is common because multiple slaves can share the `!clock`, +//|`!MOSI` and `!MISO` lines and therefore the hardware.)""" //| -//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): +//|def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): //| -//| """Construct an SPI object on the given pins. +//|"""Construct an SPI object on the given pins. //| -//| ..note:: The SPI peripherals allocated in order of desirability, if possible, -//| such as highest speed and not shared use first. For instance, on the nRF52840, -//| there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, -//| some of which may also be used for I2C. The 32MHz SPI peripheral is returned -//| first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz -//| peripherals. +//|..note:: The SPI peripherals allocated in order of desirability, if possible, +//|such as highest speed and not shared use first. For instance, on the nRF52840, +//|there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, +//|some of which may also be used for I2C. The 32MHz SPI peripheral is returned +//|first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz +//|peripherals. //| -//| .. 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 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 ` data descriptors. +//|.. seealso:: Using this class to directly read registers requires manual +//|bit unpacking. Instead, use an existing driver or make one with +//|:ref:`Register ` data descriptors. //| -//| :param ~microcontroller.Pin clock: the pin to use for the clock. -//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. -//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" -//| ... +//|:param ~microcontroller.Pin clock: the pin to use for the clock. +//|:param ~microcontroller.Pin MOSI: the Master Out Slave In pin. +//|:param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" +//|... // TODO(tannewt): Support LSB SPI. @@ -101,9 +101,9 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Turn off the SPI bus.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Turn off the SPI bus.""" +//|... STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_spi_deinit(self); @@ -111,15 +111,15 @@ STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers. -//| Provided by context manager helper.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers. +//|Provided by context manager helper.""" +//|... -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_spi_deinit(args[0]); @@ -140,28 +140,28 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { } } -//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: -//| """Configures the SPI bus. The SPI object must be locked. +//|def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: +//|"""Configures the SPI bus. The SPI object must be locked. //| -//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower -//| due to the granularity of available clock settings. -//| Check the `frequency` attribute for the actual clock rate. -//| :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 +//|:param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower +//|due to the granularity of available clock settings. +//|Check the `frequency` attribute for the actual clock rate. +//|: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 //| -//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that -//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is -//| within spec for the SAMD21. +//|.. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that +//|speed is not guaranteed to work. 12 MHz is the next available lower speed, and is +//|within spec for the SAMD21. //| -//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, -//| and 8MHz. -//| If you pick a a baudrate other than one of these, the nearest lower -//| baudrate will be chosen, with a minimum of 125kHz. -//| Two SPI objects may be created, except on the Circuit Playground Bluefruit, -//| which allows only one (to allow for an additional I2C object).""" -//| ... +//|.. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, +//|and 8MHz. +//|If you pick a a baudrate other than one of these, the nearest lower +//|baudrate will be chosen, with a minimum of 125kHz. +//|Two SPI objects may be created, except on the Circuit Playground Bluefruit, +//|which allows only one (to allow for an additional I2C object).""" +//|... STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; @@ -198,12 +198,12 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); -//| def try_lock(self, ) -> Any: -//| """Attempts to grab the SPI lock. Returns True on success. +//|def try_lock(self, ) -> Any: +//|"""Attempts to grab the SPI lock. Returns True on success. //| -//| :return: True when lock has been grabbed -//| :rtype: bool""" -//| ... +//|:return: True when lock has been grabbed +//|:rtype: bool""" +//|... STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -211,9 +211,9 @@ STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); -//| def unlock(self, ) -> Any: -//| """Releases the SPI lock.""" -//| ... +//|unlock(self, ) -> Any: +//|"""Releases the SPI lock.""" +//|... STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -223,14 +223,14 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); -//| def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... -//| """Write the data contained in ``buffer``. The SPI object must be locked. -//| If the buffer is empty, nothing happens. +//|def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... +//|"""Write the data contained in ``buffer``. The SPI object must be locked. +//|If the buffer is empty, nothing happens. //| -//| :param bytearray buffer: Write out the data in this buffer -//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" -//| ... +//|:param bytearray buffer: Write out the data in this buffer +//|:param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` +//|:param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" +//|... STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; @@ -264,16 +264,16 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); -//| def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: -//| """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. +//|def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: +//|"""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. //| -//| :param bytearray buffer: Read data into this buffer -//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` -//| :param int write_value: Value to write while reading. (Usually ignored.)""" -//| ... +//|:param bytearray buffer: Read data into this buffer +//|:param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` +//|:param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` +//|:param int write_value: Value to write while reading. (Usually ignored.)""" +//|... STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; @@ -307,20 +307,20 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); -//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: -//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. -//| The SPI object must be locked. -//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//| must be equal. -//| If buffer slice lengths are both 0, nothing happens. +//|def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: +//|"""Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//|The SPI object must be locked. +//|The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` +//|must be equal. +//|If buffer slice lengths are both 0, nothing happens. //| -//| :param bytearray buffer_out: Write out the data in this buffer -//| :param bytearray buffer_in: Read data into this buffer -//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` -//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" -//| ... +//|:param bytearray buffer_out: Write out the data in this buffer +//|:param bytearray buffer_in: Read data into this buffer +//|:param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` +//|:param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` +//|:param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` +//|:param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" +//|... STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; @@ -369,10 +369,10 @@ STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_readinto_obj, 2, busio_spi_write_readinto); -//| frequency: Any = -//| """The actual SPI bus frequency. This may not match the frequency requested -//| due to internal limitations.""" -//| ... +//|frequency: Any = +//|"""The actual SPI bus frequency. This may not match the frequency requested +//|due to internal limitations.""" +//|... STATIC mp_obj_t busio_spi_obj_get_frequency(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 954cbdd20..b89b331af 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -40,30 +40,30 @@ #include "supervisor/shared/translate.h" //|class UART: -//| """.. currentmodule:: busio +//|""".. currentmodule:: busio //| -//| :class:`UART` -- a bidirectional serial protocol -//| =================================================""" -//| def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): -//| """A common bidirectional serial protocol that uses an an agreed upon speed -//| rather than a shared clock line. +//|:class:`UART` -- a bidirectional serial protocol +//|=================================================""" +//|def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): +//|"""A common bidirectional serial protocol that uses an an agreed upon speed +//|rather than a shared clock line. //| -//| :param ~microcontroller.Pin tx: the pin to transmit with, or ``None`` if this ``UART`` is receive-only. -//| :param ~microcontroller.Pin rx: the pin to receive on, or ``None`` if this ``UART`` is transmit-only. -//| :param ~microcontroller.Pin rts: the pin for rts, or ``None`` if rts not in use. -//| :param ~microcontroller.Pin cts: the pin for cts, or ``None`` if cts not in use. -//| :param ~microcontroller.Pin rs485_dir: the pin for rs485 direction setting, or ``None`` if rs485 not in use. -//| :param bool rs485_invert: set to invert the sense of the rs485_dir pin. -//| :param int baudrate: the transmit and receive speed. -//| :param int bits: the number of bits per byte, 7, 8 or 9. -//| :param Parity parity: the parity used for error checking. -//| :param int stop: the number of stop bits, 1 or 2. -//| :param float timeout: the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises ``ValueError`` if timeout >100 seconds. -//| :param int receiver_buffer_size: the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.) +//|:param ~microcontroller.Pin tx: the pin to transmit with, or ``None`` if this ``UART`` is receive-only. +//|:param ~microcontroller.Pin rx: the pin to receive on, or ``None`` if this ``UART`` is transmit-only. +//|:param ~microcontroller.Pin rts: the pin for rts, or ``None`` if rts not in use. +//|:param ~microcontroller.Pin cts: the pin for cts, or ``None`` if cts not in use. +//|:param ~microcontroller.Pin rs485_dir: the pin for rs485 direction setting, or ``None`` if rs485 not in use. +//|:param bool rs485_invert: set to invert the sense of the rs485_dir pin. +//|:param int baudrate: the transmit and receive speed. +//|:param int bits: the number of bits per byte, 7, 8 or 9. +//|:param Parity parity: the parity used for error checking. +//|:param int stop: the number of stop bits, 1 or 2. +//|:param float timeout: the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises ``ValueError`` if timeout >100 seconds. +//|:param int receiver_buffer_size: the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.) //| -//| *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.""" -//| ... +//|*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.""" +//|... typedef struct { mp_obj_base_t base; } busio_uart_parity_obj_t; @@ -141,9 +141,9 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, co return (mp_obj_t)self; } -//| def deinit(self, ) -> Any: -//| """Deinitialises the UART and releases any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the UART and releases any hardware resources for reuse.""" +//|... STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_uart_deinit(self); @@ -157,15 +157,15 @@ STATIC void check_for_deinit(busio_uart_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_uart_deinit(args[0]); @@ -175,46 +175,46 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ // These are standard stream methods. Code is in py/stream.c. // -//| def read(self, nbytes: Any = None) -> Any: -//| """Read characters. If ``nbytes`` is specified then read at most that many -//| bytes. Otherwise, read everything that arrives until the connection -//| times out. Providing the number of bytes expected is highly recommended -//| because it will be faster. +//|def read(self, nbytes: Any = None) -> Any: +//|"""Read characters. If ``nbytes`` is specified then read at most that many +//|bytes. Otherwise, read everything that arrives until the connection +//|times out. Providing the number of bytes expected is highly recommended +//|because it will be faster. //| -//| :return: Data read -//| :rtype: bytes or None""" -//| ... +//|:return: Data read +//|:rtype: bytes or None""" +//|... -//| def readinto(self, buf: Any) -> Any: -//| """.. method:: readinto(buf) +//|def readinto(self, buf: Any) -> Any: +//|""".. method:: readinto(buf) //| -//| Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. +//|Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. //| -//| :return: number of bytes read and stored into ``buf`` -//| :rtype: int or None (on a non-blocking error) +//|:return: number of bytes read and stored into ``buf`` +//|:rtype: int or None (on a non-blocking error) //| -//| *New in CircuitPython 4.0:* No length parameter is permitted.""" -//| ... +//|*New in CircuitPython 4.0:* No length parameter is permitted.""" +//|... -//| def readline(self, ) -> Any: -//| """.. method:: readline() +//|def readline(self, ) -> Any: +//|""".. method:: readline() //| -//| Read a line, ending in a newline character. +//|Read a line, ending in a newline character. //| -//| :return: the line read -//| :rtype: int or None""" -//| ... +//|:return: the line read +//|:rtype: int or None""" +//|... -//| def write(self, buf: Any) -> Any: -//| """.. method:: write(buf) +//|def write(self, buf: Any) -> Any: +//|""".. method:: write(buf) //| -//| Write the buffer of bytes to the bus. +//|Write the buffer of bytes to the bus. //| -//| *New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. +//|*New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. //| -//| :return: the number of bytes written -//| :rtype: int or None""" -//| ... +//|:return: the number of bytes written +//|:rtype: int or None""" +//|... // These three methods are used by the shared stream methods. STATIC mp_uint_t busio_uart_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) { @@ -258,9 +258,9 @@ STATIC mp_uint_t busio_uart_ioctl(mp_obj_t self_in, mp_uint_t request, mp_uint_t return ret; } -//| baudrate: Any = -//| """The current baudrate.""" -//| ... +//|baudrate: Any = +//|"""The current baudrate.""" +//|... STATIC mp_obj_t busio_uart_obj_get_baudrate(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -284,9 +284,9 @@ const mp_obj_property_t busio_uart_baudrate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| in_waiting: Any = -//| """The number of bytes in the input buffer, available to be read""" -//| ... +//|in_waiting: Any = +//|"""The number of bytes in the input buffer, available to be read""" +//|... STATIC mp_obj_t busio_uart_obj_get_in_waiting(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -301,9 +301,9 @@ const mp_obj_property_t busio_uart_in_waiting_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| timeout: Any = -//| """The current timeout, in seconds (float).""" -//| ... +//|timeout: Any = +//|"""The current timeout, in seconds (float).""" +//|... STATIC mp_obj_t busio_uart_obj_get_timeout(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -329,9 +329,9 @@ const mp_obj_property_t busio_uart_timeout_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def reset_input_buffer(self, ) -> Any: -//| """Discard any unread characters in the input buffer.""" -//| ... +//|def reset_input_buffer(self, ) -> Any: +//|"""Discard any unread characters in the input buffer.""" +//|... STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -341,15 +341,15 @@ STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_obj_reset_input_buffer); //|class busio: -//| def __init__(self, ): -//| """Enum-like class to define the parity used to verify correct data transfer.""" -//| ODD: Any = -//| """Total number of ones should be odd.""" -//| ... -//| EVEN: Any = -//| """Total number of ones should be even.""" -//| ... -//| ... +//|def __init__(self, ): +//|"""Enum-like class to define the parity used to verify correct data transfer.""" +//|ODD: Any = +//|"""Total number of ones should be odd.""" +//|... +//|EVEN: Any = +//|"""Total number of ones should be even.""" +//|... +//|... const mp_obj_type_t busio_uart_parity_type; const busio_uart_parity_obj_t busio_uart_parity_odd_obj = { -- cgit v1.2.3 From c3897d0add969e0280e445a80eff34c6a2681592 Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 28 Apr 2020 18:43:40 -0400 Subject: Fixed whitespace in analogio --- shared-bindings/analogio/AnalogIn.c | 62 ++++++++++++++++++------------------ shared-bindings/analogio/AnalogOut.c | 57 ++++++++++++++++----------------- 2 files changed, 59 insertions(+), 60 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index a8afe75bd..9b6ac086b 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -37,24 +37,24 @@ #include "shared-bindings/util.h" //|class AnalogIn: -//| """:class:`AnalogIn` -- read analog voltage -//| ============================================ +//|""":class:`AnalogIn` -- read analog voltage +//|============================================ //| -//| Usage:: +//|Usage:: //| -//| import analogio -//| from board import * +//|import analogio +//|from board import * //| -//| adc = analogio.AnalogIn(A1) -//| val = adc.value""" +//|adc = analogio.AnalogIn(A1) +//|val = adc.value""" //| -//| def __init__(self, pin: microcontroller.Pin): +//|def __init__(self, pin: microcontroller.Pin): //| -//| """Use the AnalogIn on the given pin. The reference voltage varies by -//| platform so use ``reference_voltage`` to read the configured setting. +//|"""Use the AnalogIn on the given pin. The reference voltage varies by +//|platform so use ``reference_voltage`` to read the configured setting. //| -//| :param ~microcontroller.Pin pin: the pin to read from""" -//| ... +//|:param ~microcontroller.Pin pin: the pin to read from""" +//|... STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // check number of arguments @@ -70,9 +70,9 @@ STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Turn off the AnalogIn and release the pin for other use.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Turn off the AnalogIn and release the pin for other use.""" +//|... STATIC mp_obj_t analogio_analogin_deinit(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_analogio_analogin_deinit(self); @@ -85,15 +85,15 @@ STATIC void check_for_deinit(analogio_analogin_obj_t *self) { raise_deinited_error(); } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_analogio_analogin_deinit(args[0]); @@ -101,12 +101,12 @@ STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogin___exit___obj, 4, 4, analogio_analogin___exit__); -//| value: Any = -//| """The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only) +//|value: Any = +//|"""The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only) //| -//| Even if the underlying analog to digital converter (ADC) is lower -//| resolution, the value is 16-bit.""" -//| ... +//|Even if the underlying analog to digital converter (ADC) is lower +//|resolution, the value is 16-bit.""" +//|... STATIC mp_obj_t analogio_analogin_obj_get_value(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -121,10 +121,10 @@ const mp_obj_property_t analogio_analogin_value_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| reference_voltage: Any = -//| """The maximum voltage measurable (also known as the reference voltage) as a -//| `float` in Volts.""" -//| ... +//|reference_voltage: Any = +//|"""The maximum voltage measurable (also known as the reference voltage) as a +//|`float` in Volts.""" +//|... STATIC mp_obj_t analogio_analogin_obj_get_reference_voltage(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 1b5808e6c..231668290 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -37,26 +37,25 @@ #include "supervisor/shared/translate.h" //|class AnalogOut: -//| """.. currentmodule:: analogio +//|""".. currentmodule:: analogio //| -//| :class:`AnalogOut` -- output analog voltage -//| ============================================ +//|:class:`AnalogOut` -- output analog voltage +//|============================================ //| -//| The AnalogOut is used to output analog values (a specific voltage). +//|The AnalogOut is used to output analog values (a specific voltage). //| -//| Example usage:: +//|Example usage:: //| -//| import analogio -//| from microcontroller import pin +//|import analogio +//|from microcontroller import pin //| -//| dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 -//| dac.value = 32768 # makes PA02 1.65V""" -//| def __init__(self, pin: microcontroller.Pin): +//|dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 +//|dac.value = 32768 # makes PA02 1.65V""" +//|def __init__(self, pin: microcontroller.Pin): +//|"""Use the AnalogOut on the given pin. //| -//| """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""" +//|... STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // check arguments mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -70,9 +69,9 @@ STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Turn off the AnalogOut and release the pin for other use.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Turn off the AnalogOut and release the pin for other use.""" +//|... STATIC mp_obj_t analogio_analogout_deinit(mp_obj_t self_in) { analogio_analogout_obj_t *self = self_in; @@ -82,15 +81,15 @@ STATIC mp_obj_t analogio_analogout_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogout_deinit_obj, analogio_analogout_deinit); -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_analogio_analogout_deinit(args[0]); @@ -98,12 +97,12 @@ STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogout___exit___obj, 4, 4, analogio_analogout___exit__); -//| value: Any = -//| """The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only) +//|value: Any = +//|"""The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only) //| -//| Even if the underlying digital to analog converter (DAC) is lower -//| resolution, the value is 16-bit.""" -//| ... +//|Even if the underlying digital to analog converter (DAC) is lower +//|resolution, the value is 16-bit.""" +//|... STATIC mp_obj_t analogio_analogout_obj_set_value(mp_obj_t self_in, mp_obj_t value) { analogio_analogout_obj_t *self = MP_OBJ_TO_PTR(self_in); if (common_hal_analogio_analogout_deinited(self)) { -- cgit v1.2.3 From aacca615988e29dd58b5083a0199f60f2f40a263 Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 28 Apr 2020 18:56:19 -0400 Subject: Fixed whitespace on audiocore --- shared-bindings/audiocore/RawSample.c | 92 ++++++++++++++++----------------- shared-bindings/audiocore/WaveFile.c | 96 +++++++++++++++++------------------ 2 files changed, 94 insertions(+), 94 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audiocore/RawSample.c b/shared-bindings/audiocore/RawSample.c index b879b1b97..fdedfe959 100644 --- a/shared-bindings/audiocore/RawSample.c +++ b/shared-bindings/audiocore/RawSample.c @@ -36,44 +36,44 @@ #include "supervisor/shared/translate.h" //|class RawSample: -//| """.. currentmodule:: audiocore +//|""".. currentmodule:: audiocore //| -//| :class:`RawSample` -- A raw audio sample buffer -//| ======================================================== +//|:class:`RawSample` -- A raw audio sample buffer +//|======================================================== //| -//| An in-memory sound sample""" +//|An in-memory sound sample""" //| -//| def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): -//| """Create a RawSample based on the given buffer of signed values. If channel_count is more than -//| 1 then each channel's samples should alternate. In other words, for a two channel buffer, the -//| first sample will be for channel 1, the second sample will be for channel two, the third for -//| channel 1 and so on. +//|def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): +//|"""Create a RawSample based on the given buffer of signed values. If channel_count is more than +//|1 then each channel's samples should alternate. In other words, for a two channel buffer, the +//|first sample will be for channel 1, the second sample will be for channel two, the third for +//|channel 1 and so on. //| -//| :param array.array buffer: An `array.array` with samples -//| :param int channel_count: The number of channels in the buffer -//| :param int sample_rate: The desired playback sample rate +//|:param array.array buffer: An `array.array` with samples +//|:param int channel_count: The number of channels in the buffer +//|:param int sample_rate: The desired playback sample rate //| -//| Simple 8ksps 440 Hz sin wave:: +//|Simple 8ksps 440 Hz sin wave:: //| -//| import audiocore -//| import audioio -//| import board -//| import array -//| import time -//| import math +//|import audiocore +//|import audioio +//|import board +//|import array +//|import time +//|import math //| -//| # Generate one period of sine wav. -//| 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 / 18) * (2 ** 15)) +//|# Generate one period of sine wav. +//|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 / 18) * (2 ** 15)) //| -//| dac = audioio.AudioOut(board.SPEAKER) -//| sine_wave = audiocore.RawSample(sine_wave) -//| dac.play(sine_wave, loop=True) -//| time.sleep(1) -//| dac.stop()""" -//| ... +//|dac = audioio.AudioOut(board.SPEAKER) +//|sine_wave = audiocore.RawSample(sine_wave) +//|dac.play(sine_wave, loop=True) +//|time.sleep(1) +//|dac.stop()""" +//|... STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_channel_count, ARG_sample_rate }; static const mp_arg_t allowed_args[] = { @@ -105,9 +105,9 @@ STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the AudioOut and releases any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the AudioOut and releases any hardware resources for reuse.""" +//|... STATIC mp_obj_t audioio_rawsample_deinit(mp_obj_t self_in) { audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_rawsample_deinit(self); @@ -121,15 +121,15 @@ STATIC void check_for_deinit(audioio_rawsample_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_rawsample_deinit(args[0]); @@ -137,12 +137,12 @@ STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *ar } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_rawsample___exit___obj, 4, 4, audioio_rawsample_obj___exit__); -//| sample_rate: Any = -//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second). -//| When the sample is looped, this can change the pitch output without changing the underlying -//| sample. This will not change the sample rate of any active playback. Call ``play`` again to -//| change it.""" -//| ... +//|sample_rate: Any = +//|"""32 bit value that dictates how quickly samples are played in Hertz (cycles per second). +//|When the sample is looped, this can change the pitch output without changing the underlying +//|sample. This will not change the sample rate of any active playback. Call ``play`` again to +//|change it.""" +//|... STATIC mp_obj_t audioio_rawsample_obj_get_sample_rate(mp_obj_t self_in) { audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiocore/WaveFile.c b/shared-bindings/audiocore/WaveFile.c index f57e1f877..9116e71f0 100644 --- a/shared-bindings/audiocore/WaveFile.c +++ b/shared-bindings/audiocore/WaveFile.c @@ -34,42 +34,42 @@ #include "supervisor/shared/translate.h" //|class WaveFile: -//| """.. currentmodule:: audiocore +//|""".. currentmodule:: audiocore //| -//| :class:`WaveFile` -- Load a wave file for audio playback -//| ======================================================== +//|:class:`WaveFile` -- Load a wave file for audio playback +//|======================================================== //| -//| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must -//| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating -//| an internal buffer.""" -//| def __init__(self, file: typing.BinaryIO, buffer: bytearray): -//| """Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. +//|A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must +//|be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating +//|an internal buffer.""" +//|def __init__(self, file: typing.BinaryIO, buffer: bytearray): +//|"""Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| :param typing.BinaryIO file: Already opened wave file -//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally. +//|:param typing.BinaryIO file: Already opened wave file +//|:param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally. //| //| -//| Playing a wave file from flash:: +//|Playing a wave file from flash:: //| -//| import board -//| import audiocore -//| import audioio -//| import digitalio +//|import board +//|import audiocore +//|import audioio +//|import digitalio //| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) +//|# Required for CircuitPlayground Express +//|speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//|speaker_enable.switch_to_output(value=True) //| -//| data = open("cplay-5.1-16bit-16khz.wav", "rb") -//| wav = audiocore.WaveFile(data) -//| a = audioio.AudioOut(board.A0) +//|data = open("cplay-5.1-16bit-16khz.wav", "rb") +//|wav = audiocore.WaveFile(data) +//|a = audioio.AudioOut(board.A0) //| -//| print("playing") -//| a.play(wav) -//| while a.playing: -//| pass -//| print("stopped")""" -//| ... +//|print("playing") +//|a.play(wav) +//|while a.playing: +//|pass +//|print("stopped")""" +//|... STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 2, false); @@ -92,9 +92,9 @@ STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the WaveFile and releases all memory resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the WaveFile and releases all memory resources for reuse.""" +//|... STATIC mp_obj_t audioio_wavefile_deinit(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_wavefile_deinit(self); @@ -108,15 +108,15 @@ STATIC void check_for_deinit(audioio_wavefile_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_wavefile_deinit(args[0]); @@ -124,11 +124,11 @@ STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_wavefile___exit___obj, 4, 4, audioio_wavefile_obj___exit__); -//| sample_rate: Any = -//| """32 bit value that dictates how quickly samples are loaded into the DAC -//| in Hertz (cycles per second). When the sample is looped, this can change -//| the pitch output without changing the underlying sample.""" -//| ... +//|sample_rate: Any = +//|"""32 bit value that dictates how quickly samples are loaded into the DAC +//|in Hertz (cycles per second). When the sample is looped, this can change +//|the pitch output without changing the underlying sample.""" +//|... STATIC mp_obj_t audioio_wavefile_obj_get_sample_rate(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -151,9 +151,9 @@ const mp_obj_property_t audioio_wavefile_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| bits_per_sample: Any = -//| """Bits per sample. (read only)""" -//| ... +//|bits_per_sample: Any = +//|"""Bits per sample. (read only)""" +//|... STATIC mp_obj_t audioio_wavefile_obj_get_bits_per_sample(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -168,9 +168,9 @@ const mp_obj_property_t audioio_wavefile_bits_per_sample_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| channel_count: Any = -//| """Number of audio channels. (read only)""" -//| ... +//|channel_count: Any = +//|"""Number of audio channels. (read only)""" +//|... STATIC mp_obj_t audioio_wavefile_obj_get_channel_count(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From c7b721f4f19b561006d9d2e1c46d79d9f22bf4b0 Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 28 Apr 2020 19:22:03 -0400 Subject: Fixed some more whitespace --- shared-bindings/audiobusio/I2SOut.c | 150 +++++++++++++++---------------- shared-bindings/audiobusio/PDMIn.c | 131 +++++++++++++-------------- shared-bindings/audioio/AudioOut.c | 154 ++++++++++++++++---------------- shared-bindings/audiomixer/Mixer.c | 132 +++++++++++++-------------- shared-bindings/audiomixer/MixerVoice.c | 44 ++++----- shared-bindings/audiomp3/MP3Decoder.c | 105 +++++++++++----------- 6 files changed, 354 insertions(+), 362 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audiobusio/I2SOut.c b/shared-bindings/audiobusio/I2SOut.c index cad17ad18..765e0a12d 100644 --- a/shared-bindings/audiobusio/I2SOut.c +++ b/shared-bindings/audiobusio/I2SOut.c @@ -36,63 +36,63 @@ #include "supervisor/shared/translate.h" //|class I2SOut: -//| """.. currentmodule:: audiobusio +//|""".. currentmodule:: audiobusio //| -//| :class:`I2SOut` -- Output an I2S audio signal -//| ======================================================== +//|:class:`I2SOut` -- Output an I2S audio signal +//|======================================================== //| -//| I2S is used to output an audio signal on an I2S bus.""" -//| def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): -//| """Create a I2SOut object associated with the given pins. +//|I2S is used to output an audio signal on an I2S bus.""" +//|def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): +//|"""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 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. +//|: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 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 `_ -//| using `UDA1334 Breakout `_:: +//|Simple 8ksps 440 Hz sine wave on `Metro M0 Express `_ +//|using `UDA1334 Breakout `_:: //| -//| import audiobusio -//| import audiocore -//| import board -//| import array -//| import time -//| import math +//|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 / 18) * (2 ** 15) + 2 ** 15) +//|# 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 / 18) * (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() +//|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:: +//|Playing a wave file from flash:: //| -//| import board -//| import audioio -//| import audiocore -//| import audiobusio -//| import digitalio +//|import board +//|import audioio +//|import audiocore +//|import audiobusio +//|import digitalio //| //| -//| f = open("cplay-5.1-16bit-16khz.wav", "rb") -//| wav = audiocore.WaveFile(f) +//|f = open("cplay-5.1-16bit-16khz.wav", "rb") +//|wav = audiocore.WaveFile(f) //| -//| a = audiobusio.I2SOut(board.D1, board.D0, board.D9) +//|a = audiobusio.I2SOut(board.D1, board.D0, board.D9) //| -//| print("playing") -//| a.play(wav) -//| while a.playing: -//| pass -//| print("stopped")""" -//| ... +//|print("playing") +//|a.play(wav) +//|while a.playing: +//|pass +//|print("stopped")""" +//|... STATIC mp_obj_t audiobusio_i2sout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_bit_clock, ARG_word_select, ARG_data, ARG_left_justified }; static const mp_arg_t allowed_args[] = { @@ -115,9 +115,9 @@ STATIC mp_obj_t audiobusio_i2sout_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the I2SOut and releases any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the I2SOut and releases any hardware resources for reuse.""" +//|... STATIC mp_obj_t audiobusio_i2sout_deinit(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiobusio_i2sout_deinit(self); @@ -130,15 +130,15 @@ STATIC void check_for_deinit(audiobusio_i2sout_obj_t *self) { raise_deinited_error(); } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiobusio_i2sout_deinit(args[0]); @@ -147,14 +147,14 @@ STATIC mp_obj_t audiobusio_i2sout_obj___exit__(size_t n_args, const mp_obj_t *ar STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_i2sout___exit___obj, 4, 4, audiobusio_i2sout_obj___exit__); -//| def play(self, sample: Any, *, loop: Any = False) -> Any: -//| """Plays the sample once when loop=False and continuously when loop=True. -//| Does not block. Use `playing` to block. +//|def play(self, sample: Any, *, loop: Any = False) -> Any: +//|"""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`, or `audiomixer.Mixer`. +//|Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. //| -//| The sample itself should consist of 8 bit or 16 bit samples.""" -//| ... +//|The sample itself should consist of 8 bit or 16 bit samples.""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -173,9 +173,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_play(size_t n_args, const mp_obj_t *pos_ar } MP_DEFINE_CONST_FUN_OBJ_KW(audiobusio_i2sout_play_obj, 1, audiobusio_i2sout_obj_play); -//| def stop(self, ) -> Any: -//| """Stops playback.""" -//| ... +//|def stop(self, ) -> Any: +//|"""Stops playback.""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj_stop(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -184,9 +184,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_stop_obj, audiobusio_i2sout_obj_stop); -//| playing: Any = -//| """True when the audio sample is being output. (read-only)""" -//| ... +//|playing: Any = +//|"""True when the audio sample is being output. (read-only)""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj_get_playing(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -201,9 +201,9 @@ const mp_obj_property_t audiobusio_i2sout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def pause(self, ) -> Any: -//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" -//| ... +//|def pause(self, ) -> Any: +//|"""Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj_pause(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -216,9 +216,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_pause_obj, audiobusio_i2sout_obj_pause); -//| def resume(self, ) -> Any: -//| """Resumes sample playback after :py:func:`pause`.""" -//| ... +//|def resume(self, ) -> Any: +//|"""Resumes sample playback after :py:func:`pause`.""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj_resume(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -231,9 +231,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_resume_obj, audiobusio_i2sout_obj_resume); -//| paused: Any = -//| """True when playback is paused. (read-only)""" -//| ... +//|paused: Any = +//|"""True when playback is paused. (read-only)""" +//|... STATIC mp_obj_t audiobusio_i2sout_obj_get_paused(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index b75545ba7..28ff9a481 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -36,63 +36,56 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" - - - - - - - //|class PDMIn: -//| """.. currentmodule:: audiobusio +//|""".. currentmodule:: audiobusio //| -//| :class:`PDMIn` -- Record an input PDM audio stream -//| ======================================================== +//|:class:`PDMIn` -- Record an input PDM audio stream +//|======================================================== //| -//| PDMIn can be used to record an input audio signal on a given set of pins.""" +//|PDMIn can be used to record an input audio signal on a given set of pins.""" //| -//| 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): -//| """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. +//|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): +//|"""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.""" -//| ... - -//| Record 8-bit unsigned samples to buffer:: +//|: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.""" +//|... + +//|Record 8-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 +//|b = bytearray(200) +//|with audiobusio.PDMIn(board.MICROPHONE_CLOCK, board.MICROPHONE_DATA, sample_rate=16000) as mic: +//|mic.record(b, len(b)) //| -//| Record 16-bit unsigned samples to buffer:: +//|Record 16-bit unsigned samples to buffer:: //| -//| import audiobusio -//| import board +//|import audiobusio +//|import board //| -//| # 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)) +//|# 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)) //| STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_clock_pin, ARG_data_pin, ARG_sample_rate, ARG_bit_depth, ARG_mono, ARG_oversample, ARG_startup_delay }; @@ -145,9 +138,9 @@ STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the PDMIn and releases any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the PDMIn and releases any hardware resources for reuse.""" +//|... STATIC mp_obj_t audiobusio_pdmin_deinit(mp_obj_t self_in) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiobusio_pdmin_deinit(self); @@ -160,14 +153,14 @@ STATIC void check_for_deinit(audiobusio_pdmin_obj_t *self) { raise_deinited_error(); } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context.""" +//|... STATIC mp_obj_t audiobusio_pdmin_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiobusio_pdmin_deinit(args[0]); @@ -176,17 +169,17 @@ STATIC mp_obj_t audiobusio_pdmin_obj___exit__(size_t n_args, const mp_obj_t *arg STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_pdmin___exit___obj, 4, 4, audiobusio_pdmin_obj___exit__); -//| def record(self, destination: Any, destination_length: Any) -> Any: -//| """Records destination_length bytes of samples to destination. This is -//| blocking. +//|def record(self, destination: Any, destination_length: Any) -> Any: +//|"""Records destination_length bytes of samples to destination. This is +//|blocking. //| -//| An IOError 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. +//|An IOError 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.""" -//| ... +//|:return: The number of samples recorded. If this is less than ``destination_length``, +//|some samples were missed due to processing time.""" +//|... STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destination, mp_obj_t destination_length) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_obj); check_for_deinit(self); @@ -217,10 +210,10 @@ STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destinat } MP_DEFINE_CONST_FUN_OBJ_3(audiobusio_pdmin_record_obj, audiobusio_pdmin_obj_record); -//| sample_rate: Any = -//| """The actual sample_rate of the recording. This may not match the constructed -//| sample rate due to internal clock limitations.""" -//| ... +//|sample_rate: Any = +//|"""The actual sample_rate of the recording. This may not match the constructed +//|sample rate due to internal clock limitations.""" +//|... STATIC mp_obj_t audiobusio_pdmin_obj_get_sample_rate(mp_obj_t self_in) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c index 8df923e6f..28c345d16 100644 --- a/shared-bindings/audioio/AudioOut.c +++ b/shared-bindings/audioio/AudioOut.c @@ -37,63 +37,63 @@ #include "supervisor/shared/translate.h" //|class AudioOut: -//| """.. currentmodule:: audioio +//|""".. currentmodule:: audioio //| -//| :class:`AudioOut` -- Output an analog audio signal -//| ======================================================== +//|:class:`AudioOut` -- Output an analog audio signal +//|======================================================== //| -//| AudioOut can be used to output an analog audio signal on a given pin.""" +//|AudioOut can be used to output an analog audio signal on a given pin.""" //| -//| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): -//| """Create a AudioOut object associated with the given pin(s). This allows you to -//| play audio signals out on the given pin(s). +//|def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): +//|"""Create a AudioOut object associated with the given pin(s). This allows you to +//|play audio signals out on the given pin(s). //| -//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to -//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to -//| :param int quiescent_value: The output value when no signal is present. Samples should start -//| and end with this value to prevent audible popping. +//|:param ~microcontroller.Pin left_channel: The pin to output the left channel to +//|:param ~microcontroller.Pin right_channel: The pin to output the right channel to +//|:param int quiescent_value: The output value when no signal is present. Samples should start +//|and end with this value to prevent audible popping. //| -//| Simple 8ksps 440 Hz sin wave:: +//|Simple 8ksps 440 Hz sin wave:: //| -//| import audiocore -//| import audioio -//| import board -//| import array -//| import time -//| import math +//|import audiocore +//|import audioio +//|import board +//|import array +//|import time +//|import math //| -//| # Generate one period of sine wav. -//| 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 / 18) * (2 ** 15) + 2 ** 15) +//|# Generate one period of sine wav. +//|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 / 18) * (2 ** 15) + 2 ** 15) //| -//| dac = audioio.AudioOut(board.SPEAKER) -//| sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) -//| dac.play(sine_wave, loop=True) -//| time.sleep(1) -//| dac.stop() +//|dac = audioio.AudioOut(board.SPEAKER) +//|sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) +//|dac.play(sine_wave, loop=True) +//|time.sleep(1) +//|dac.stop() //| -//| Playing a wave file from flash:: +//|Playing a wave file from flash:: //| -//| import board -//| import audioio -//| import digitalio +//|import board +//|import audioio +//|import digitalio //| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) +//|# Required for CircuitPlayground Express +//|speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//|speaker_enable.switch_to_output(value=True) //| -//| data = open("cplay-5.1-16bit-16khz.wav", "rb") -//| wav = audiocore.WaveFile(data) -//| a = audioio.AudioOut(board.A0) +//|data = open("cplay-5.1-16bit-16khz.wav", "rb") +//|wav = audiocore.WaveFile(data) +//|a = audioio.AudioOut(board.A0) //| -//| print("playing") -//| a.play(wav) -//| while a.playing: -//| pass -//| print("stopped")""" -//| ... +//|print("playing") +//|a.play(wav) +//|while a.playing: +//|pass +//|print("stopped")""" +//|... STATIC mp_obj_t audioio_audioout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_left_channel, ARG_right_channel, ARG_quiescent_value }; static const mp_arg_t allowed_args[] = { @@ -115,9 +115,9 @@ STATIC mp_obj_t audioio_audioout_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the AudioOut and releases any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the AudioOut and releases any hardware resources for reuse.""" +//|... STATIC mp_obj_t audioio_audioout_deinit(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_audioout_deinit(self); @@ -130,15 +130,15 @@ STATIC void check_for_deinit(audioio_audioout_obj_t *self) { raise_deinited_error(); } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_audioout_deinit(args[0]); @@ -147,16 +147,16 @@ STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *arg STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_audioout___exit___obj, 4, 4, audioio_audioout_obj___exit__); -//| def play(self, sample: Any, *, loop: Any = False) -> Any: -//| """Plays the sample once when loop=False and continuously when loop=True. -//| Does not block. Use `playing` to block. +//|def play(self, sample: Any, *, loop: Any = False) -> Any: +//|"""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`, or `audiomixer.Mixer`. +//|Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. //| -//| The sample itself should consist of 16 bit samples. Microcontrollers with a lower output -//| resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit -//| DAC that ignores the lowest 6 bits when playing 16 bit samples.""" -//| ... +//|The sample itself should consist of 16 bit samples. Microcontrollers with a lower output +//|resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit +//|DAC that ignores the lowest 6 bits when playing 16 bit samples.""" +//|... STATIC mp_obj_t audioio_audioout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -175,9 +175,9 @@ STATIC mp_obj_t audioio_audioout_obj_play(size_t n_args, const mp_obj_t *pos_arg } MP_DEFINE_CONST_FUN_OBJ_KW(audioio_audioout_play_obj, 1, audioio_audioout_obj_play); -//| def stop(self, ) -> Any: -//| """Stops playback and resets to the start of the sample.""" -//| ... +//|def stop(self, ) -> Any: +//|"""Stops playback and resets to the start of the sample.""" +//|... STATIC mp_obj_t audioio_audioout_obj_stop(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -186,9 +186,9 @@ STATIC mp_obj_t audioio_audioout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_stop_obj, audioio_audioout_obj_stop); -//| playing: Any = -//| """True when an audio sample is being output even if `paused`. (read-only)""" -//| ... +//|playing: Any = +//|"""True when an audio sample is being output even if `paused`. (read-only)""" +//|... STATIC mp_obj_t audioio_audioout_obj_get_playing(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -203,9 +203,9 @@ const mp_obj_property_t audioio_audioout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def pause(self, ) -> Any: -//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" -//| ... +//|def pause(self, ) -> Any: +//|"""Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//|... STATIC mp_obj_t audioio_audioout_obj_pause(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -218,9 +218,9 @@ STATIC mp_obj_t audioio_audioout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_pause_obj, audioio_audioout_obj_pause); -//| def resume(self, ) -> Any: -//| """Resumes sample playback after :py:func:`pause`.""" -//| ... +//|def resume(self, ) -> Any: +//|"""Resumes sample playback after :py:func:`pause`.""" +//|... STATIC mp_obj_t audioio_audioout_obj_resume(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -233,9 +233,9 @@ STATIC mp_obj_t audioio_audioout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_resume_obj, audioio_audioout_obj_resume); -//| paused: Any = -//| """True when playback is paused. (read-only)""" -//| ... +//|paused: Any = +//|"""True when playback is paused. (read-only)""" +//|... STATIC mp_obj_t audioio_audioout_obj_get_paused(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c index 1949f2add..93b1d3635 100644 --- a/shared-bindings/audiomixer/Mixer.c +++ b/shared-bindings/audiomixer/Mixer.c @@ -39,49 +39,49 @@ #include "supervisor/shared/translate.h" //|class Mixer: -//| """.. currentmodule:: audiomixer +//|""".. currentmodule:: audiomixer //| -//| :class:`Mixer` -- Mixes one or more audio samples together -//| =========================================================== +//|:class:`Mixer` -- Mixes one or more audio samples together +//|=========================================================== //| -//| Mixer mixes multiple samples into one sample.""" +//|Mixer mixes multiple samples into one sample.""" //| -//| def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): -//| """Create a Mixer object that can mix multiple channels with the same sample rate. -//| Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects. +//|def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): +//|"""Create a Mixer object that can mix multiple channels with the same sample rate. +//|Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects. //| -//| :param int voice_count: The maximum number of voices to mix -//| :param int buffer_size: The total size in bytes of the buffers to mix into -//| :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo. -//| :param int bits_per_sample: The bits per sample of the samples being played -//| :param bool samples_signed: Samples are signed (True) or unsigned (False) -//| :param int sample_rate: The sample rate to be used for all samples +//|:param int voice_count: The maximum number of voices to mix +//|:param int buffer_size: The total size in bytes of the buffers to mix into +//|:param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo. +//|:param int bits_per_sample: The bits per sample of the samples being played +//|:param bool samples_signed: Samples are signed (True) or unsigned (False) +//|:param int sample_rate: The sample rate to be used for all samples //| -//| Playing a wave file from flash:: +//|Playing a wave file from flash:: //| -//| import board -//| import audioio -//| import audiocore -//| import audiomixer -//| import digitalio +//|import board +//|import audioio +//|import audiocore +//|import audiomixer +//|import digitalio //| -//| a = audioio.AudioOut(board.A0) -//| music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb")) -//| drum = audiocore.WaveFile(open("drum.wav", "rb")) -//| mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1, -//| bits_per_sample=16, samples_signed=True) +//|a = audioio.AudioOut(board.A0) +//|music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb")) +//|drum = audiocore.WaveFile(open("drum.wav", "rb")) +//|mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1, +//|bits_per_sample=16, samples_signed=True) //| -//| print("playing") -//| # Have AudioOut play our Mixer source -//| a.play(mixer) -//| # Play the first sample voice -//| mixer.voice[0].play(music) -//| while mixer.playing: -//| # Play the second sample voice -//| mixer.voice[1].play(drum) -//| time.sleep(1) -//| print("stopped")""" -//| ... +//|print("playing") +//|# Have AudioOut play our Mixer source +//|a.play(mixer) +//|# Play the first sample voice +//|mixer.voice[0].play(music) +//|while mixer.playing: +//|# Play the second sample voice +//|mixer.voice[1].play(drum) +//|time.sleep(1) +//|print("stopped")""" +//|... STATIC mp_obj_t audiomixer_mixer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice_count, ARG_buffer_size, ARG_channel_count, ARG_bits_per_sample, ARG_samples_signed, ARG_sample_rate }; static const mp_arg_t allowed_args[] = { @@ -125,9 +125,9 @@ STATIC mp_obj_t audiomixer_mixer_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the Mixer and releases any hardware resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the Mixer and releases any hardware resources for reuse.""" +//|... STATIC mp_obj_t audiomixer_mixer_deinit(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiomixer_mixer_deinit(self); @@ -141,15 +141,15 @@ STATIC void check_for_deinit(audiomixer_mixer_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t audiomixer_mixer_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiomixer_mixer_deinit(args[0]); @@ -157,9 +157,9 @@ STATIC mp_obj_t audiomixer_mixer_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiomixer_mixer___exit___obj, 4, 4, audiomixer_mixer_obj___exit__); -//| playing: Any = -//| """True when any voice is being output. (read-only)""" -//| ... +//|playing: Any = +//|"""True when any voice is being output. (read-only)""" +//|... STATIC mp_obj_t audiomixer_mixer_obj_get_playing(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -174,9 +174,9 @@ const mp_obj_property_t audiomixer_mixer_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| sample_rate: Any = -//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second).""" -//| ... +//|sample_rate: Any = +//|"""32 bit value that dictates how quickly samples are played in Hertz (cycles per second).""" +//|... STATIC mp_obj_t audiomixer_mixer_obj_get_sample_rate(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -191,14 +191,14 @@ const mp_obj_property_t audiomixer_mixer_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| voice: Any = -//| """A tuple of the mixer's `audiomixer.MixerVoice` object(s). +//|voice: Any = +//|"""A tuple of the mixer's `audiomixer.MixerVoice` object(s). //| -//| .. code-block:: python +//|.. code-block:: python //| -//| >>> mixer.voice -//| (,)""" -//| ... +//|>>> mixer.voice +//|(,)""" +//|... STATIC mp_obj_t audiomixer_mixer_obj_get_voice(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -213,14 +213,14 @@ const mp_obj_property_t audiomixer_mixer_voice_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def play(self, sample: Any, *, voice: Any = 0, loop: Any = False) -> Any: -//| """Plays the sample once when loop=False and continuously when loop=True. -//| Does not block. Use `playing` to block. +//|def play(self, sample: Any, *, voice: Any = 0, loop: Any = False) -> Any: +//|"""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`, or `audiomixer.Mixer`. +//|Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. //| -//| The sample must match the Mixer's encoding settings given in the constructor.""" -//| ... +//|The sample must match the Mixer's encoding settings given in the constructor.""" +//|... STATIC mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_voice, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -245,9 +245,9 @@ STATIC mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_arg } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixer_play_obj, 1, audiomixer_mixer_obj_play); -//| def stop_voice(self, voice: Any = 0) -> Any: -//| """Stops playback of the sample on the given voice.""" -//| ... +//|def stop_voice(self, voice: Any = 0) -> Any: +//|"""Stops playback of the sample on the given voice.""" +//|... STATIC mp_obj_t audiomixer_mixer_obj_stop_voice(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/audiomixer/MixerVoice.c b/shared-bindings/audiomixer/MixerVoice.c index e6c750baf..299600dd1 100644 --- a/shared-bindings/audiomixer/MixerVoice.c +++ b/shared-bindings/audiomixer/MixerVoice.c @@ -38,17 +38,17 @@ #include "supervisor/shared/translate.h" //|class MixerVoice: -//| """.. currentmodule:: audiomixer +//|""".. currentmodule:: audiomixer //| -//| :class:`MixerVoice` -- Voice objects used with Mixer -//| ===================================================== +//|:class:`MixerVoice` -- Voice objects used with Mixer +//|===================================================== //| -//| Used to access and control samples with `audiomixer.Mixer`.""" +//|Used to access and control samples with `audiomixer.Mixer`.""" //| -//| def __init__(self, ): +//|def __init__(self, ): //| -//| """MixerVoice instance object(s) created by `audiomixer.Mixer`.""" -//| ... +//|"""MixerVoice instance object(s) created by `audiomixer.Mixer`.""" +//|... // TODO: support mono or stereo voices STATIC mp_obj_t audiomixer_mixervoice_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { audiomixer_mixervoice_obj_t *self = m_new_obj(audiomixer_mixervoice_obj_t); @@ -59,14 +59,14 @@ STATIC mp_obj_t audiomixer_mixervoice_make_new(const mp_obj_type_t *type, size_t return MP_OBJ_FROM_PTR(self); } -//| def play(self, sample: Any, *, loop: Any = False) -> Any: -//| """Plays the sample once when ``loop=False``, and continuously when ``loop=True``. -//| Does not block. Use `playing` to block. +//|def play(self, sample: Any, *, loop: Any = False) -> Any: +//|"""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`, `audiomixer.Mixer` or `audiocore.RawSample`. +//|Sample must be an `audiocore.WaveFile`, `audiomixer.Mixer` or `audiocore.RawSample`. //| -//| The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor.""" -//| ... +//|The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor.""" +//|... STATIC mp_obj_t audiomixer_mixervoice_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -83,9 +83,9 @@ STATIC mp_obj_t audiomixer_mixervoice_obj_play(size_t n_args, const mp_obj_t *po } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixervoice_play_obj, 1, audiomixer_mixervoice_obj_play); -//| def stop(self, ) -> Any: -//| """Stops playback of the sample on this voice.""" -//| ... +//|def stop(self, ) -> Any: +//|"""Stops playback of the sample on this voice.""" +//|... STATIC mp_obj_t audiomixer_mixervoice_obj_stop(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice }; static const mp_arg_t allowed_args[] = { @@ -101,9 +101,9 @@ STATIC mp_obj_t audiomixer_mixervoice_obj_stop(size_t n_args, const mp_obj_t *po } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixervoice_stop_obj, 1, audiomixer_mixervoice_obj_stop); -//| level(): Any = -//| """The volume level of a voice, as a floating point number between 0 and 1.""" -//| ... +//|level(): Any = +//|"""The volume level of a voice, as a floating point number between 0 and 1.""" +//|... STATIC mp_obj_t audiomixer_mixervoice_obj_get_level(mp_obj_t self_in) { return mp_obj_new_float(common_hal_audiomixer_mixervoice_get_level(self_in)); } @@ -137,9 +137,9 @@ const mp_obj_property_t audiomixer_mixervoice_level_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| playing: Any = -//| """True when this voice is being output. (read-only)""" -//| ... +//|playing: Any = +//|"""True when this voice is being output. (read-only)""" +//|... STATIC mp_obj_t audiomixer_mixervoice_obj_get_playing(mp_obj_t self_in) { audiomixer_mixervoice_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/audiomp3/MP3Decoder.c b/shared-bindings/audiomp3/MP3Decoder.c index 0bb2c8829..7c011b65f 100644 --- a/shared-bindings/audiomp3/MP3Decoder.c +++ b/shared-bindings/audiomp3/MP3Decoder.c @@ -35,41 +35,41 @@ #include "supervisor/shared/translate.h" //|class MP3: -//| """.. currentmodule:: audiomp3 +//|""".. currentmodule:: audiomp3 //| -//| :class:`MP3Decoder` -- Load a mp3 file for audio playback -//| ========================================================= +//|:class:`MP3Decoder` -- Load a mp3 file for audio playback +//|========================================================= //| -//| An object that decodes MP3 files for playback on an audio device.""" +//|An object that decodes MP3 files for playback on an audio device.""" //| -//| def __init__(self, file: typing.BinaryIO, buffer: bytearray): -//| """Load a .mp3 file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. +//|def __init__(self, file: typing.BinaryIO, buffer: bytearray): +//|"""Load a .mp3 file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| :param typing.BinaryIO file: Already opened mp3 file -//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file. +//|:param typing.BinaryIO file: Already opened mp3 file +//|:param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file. //| //| -//| Playing a mp3 file from flash:: +//|Playing a mp3 file from flash:: //| -//| import board -//| import audiomp3 -//| import audioio -//| import digitalio +//|import board +//|import audiomp3 +//|import audioio +//|import digitalio //| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) +//|# Required for CircuitPlayground Express +//|speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//|speaker_enable.switch_to_output(value=True) //| -//| data = open("cplay-16bit-16khz-64kbps.mp3", "rb") -//| mp3 = audiomp3.MP3Decoder(data) -//| a = audioio.AudioOut(board.A0) +//|data = open("cplay-16bit-16khz-64kbps.mp3", "rb") +//|mp3 = audiomp3.MP3Decoder(data) +//|a = audioio.AudioOut(board.A0) //| -//| print("playing") -//| a.play(mp3) -//| while a.playing: -//| pass -//| print("stopped")""" -//| ... +//|print("playing") +//|a.play(mp3) +//|while a.playing: +//|pass +//|print("stopped")""" +//|... STATIC mp_obj_t audiomp3_mp3file_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 2, false); @@ -92,9 +92,9 @@ STATIC mp_obj_t audiomp3_mp3file_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialises the MP3 and releases all memory resources for reuse.""" -//| ... +//|def deinit(self, ) -> Any: +//|"""Deinitialises the MP3 and releases all memory resources for reuse.""" +//|... STATIC mp_obj_t audiomp3_mp3file_deinit(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiomp3_mp3file_deinit(self); @@ -108,16 +108,15 @@ STATIC void check_for_deinit(audiomp3_mp3file_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//|def __enter__(self, ) -> Any: +//|"""No-op used by Context Managers.""" +//|... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//|def __exit__(self, ) -> Any: +//|"""Automatically deinitializes the hardware when exiting a context. See +//|:ref:`lifetime-and-contextmanagers` for more info.""" +//|... STATIC mp_obj_t audiomp3_mp3file_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiomp3_mp3file_deinit(args[0]); @@ -125,9 +124,9 @@ STATIC mp_obj_t audiomp3_mp3file_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiomp3_mp3file___exit___obj, 4, 4, audiomp3_mp3file_obj___exit__); -//| file: Any = -//| """File to play back.""" -//| ... +//|file: Any = +//|"""File to play back.""" +//|... STATIC mp_obj_t audiomp3_mp3file_obj_get_file(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -155,11 +154,11 @@ const mp_obj_property_t audiomp3_mp3file_file_obj = { -//| sample_rate: Any = -//| """32 bit value that dictates how quickly samples are loaded into the DAC -//| in Hertz (cycles per second). When the sample is looped, this can change -//| the pitch output without changing the underlying sample.""" -//| ... +//|sample_rate: Any = +//|"""32 bit value that dictates how quickly samples are loaded into the DAC +//|in Hertz (cycles per second). When the sample is looped, this can change +//|the pitch output without changing the underlying sample.""" +//|... STATIC mp_obj_t audiomp3_mp3file_obj_get_sample_rate(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -182,9 +181,9 @@ const mp_obj_property_t audiomp3_mp3file_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| bits_per_sample: Any = -//| """Bits per sample. (read only)""" -//| ... +//|bits_per_sample: Any = +//|"""Bits per sample. (read only)""" +//|... STATIC mp_obj_t audiomp3_mp3file_obj_get_bits_per_sample(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -199,9 +198,9 @@ const mp_obj_property_t audiomp3_mp3file_bits_per_sample_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| channel_count: Any = -//| """Number of audio channels. (read only)""" -//| ... +//|channel_count: Any = +//|"""Number of audio channels. (read only)""" +//|... STATIC mp_obj_t audiomp3_mp3file_obj_get_channel_count(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -216,9 +215,9 @@ const mp_obj_property_t audiomp3_mp3file_channel_count_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| rms_level: Any = -//| """The RMS audio level of a recently played moment of audio. (read only)""" -//| ... +//|rms_level: Any = +//|"""The RMS audio level of a recently played moment of audio. (read only)""" +//|... STATIC mp_obj_t audiomp3_mp3file_obj_get_rms_level(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); -- cgit v1.2.3 From 93d1e53c66f73b6a2d85398dba7924472f1f053d Mon Sep 17 00:00:00 2001 From: dherrada Date: Wed, 29 Apr 2020 14:19:04 -0400 Subject: Hopefully fixed whitespace issues --- shared-bindings/busio/SPI.c | 200 +++++++++++++++++++-------------------- shared-bindings/busio/__init__.c | 4 +- 2 files changed, 102 insertions(+), 102 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 5643b0d04..9644f4eb5 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -41,43 +41,43 @@ #include "supervisor/shared/translate.h" -//|class SPI: -//|""".. currentmodule:: busio +//| class SPI: +//| """.. currentmodule:: busio //| -//|`SPI` -- a 3-4 wire serial protocol -//|----------------------------------------------- +//| `SPI` -- a 3-4 wire serial protocol +//| ----------------------------------------------- //| -//|SPI is a serial protocol that has exclusive pins for data in and out of the -//|master. It is typically faster than :py:class:`~busio.I2C` because a -//|separate pin is used to control the active slave rather than a transitted -//|address. This class only manages three of the four SPI lines: `!clock`, -//|`!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave -//|select line. (This is common because multiple slaves can share the `!clock`, -//|`!MOSI` and `!MISO` lines and therefore the hardware.)""" +//| SPI is a serial protocol that has exclusive pins for data in and out of the +//| master. It is typically faster than :py:class:`~busio.I2C` because a +//| separate pin is used to control the active slave rather than a transitted +//| address. This class only manages three of the four SPI lines: `!clock`, +//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave +//| select line. (This is common because multiple slaves can share the `!clock`, +//| `!MOSI` and `!MISO` lines and therefore the hardware.)""" //| -//|def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): +//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): //| -//|"""Construct an SPI object on the given pins. +//| """Construct an SPI object on the given pins. //| -//|..note:: The SPI peripherals allocated in order of desirability, if possible, -//|such as highest speed and not shared use first. For instance, on the nRF52840, -//|there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, -//|some of which may also be used for I2C. The 32MHz SPI peripheral is returned -//|first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz -//|peripherals. +//| ..note:: The SPI peripherals allocated in order of desirability, if possible, +//| such as highest speed and not shared use first. For instance, on the nRF52840, +//| there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, +//| some of which may also be used for I2C. The 32MHz SPI peripheral is returned +//| first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz +//| peripherals. //| -//|.. 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 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 ` data descriptors. +//| .. seealso:: Using this class to directly read registers requires manual +//| bit unpacking. Instead, use an existing driver or make one with +//| :ref:`Register ` data descriptors. //| -//|:param ~microcontroller.Pin clock: the pin to use for the clock. -//|:param ~microcontroller.Pin MOSI: the Master Out Slave In pin. -//|:param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" -//|... +//| :param ~microcontroller.Pin clock: the pin to use for the clock. +//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. +//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" +//| ... // TODO(tannewt): Support LSB SPI. @@ -101,9 +101,9 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Turn off the SPI bus.""" -//|... +//| def deinit(self, ) -> Any: +//| """Turn off the SPI bus.""" +//| ... STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_spi_deinit(self); @@ -111,15 +111,15 @@ STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers. -//|Provided by context manager helper.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers. +//| Provided by context manager helper.""" +//| ... -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_spi_deinit(args[0]); @@ -140,28 +140,28 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { } } -//|def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: -//|"""Configures the SPI bus. The SPI object must be locked. +//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: +//| """Configures the SPI bus. The SPI object must be locked. //| -//|:param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower -//|due to the granularity of available clock settings. -//|Check the `frequency` attribute for the actual clock rate. -//|: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 +//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower +//| due to the granularity of available clock settings. +//| Check the `frequency` attribute for the actual clock rate. +//| :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 //| -//|.. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that -//|speed is not guaranteed to work. 12 MHz is the next available lower speed, and is -//|within spec for the SAMD21. +//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that +//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is +//| within spec for the SAMD21. //| -//|.. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, -//|and 8MHz. -//|If you pick a a baudrate other than one of these, the nearest lower -//|baudrate will be chosen, with a minimum of 125kHz. -//|Two SPI objects may be created, except on the Circuit Playground Bluefruit, -//|which allows only one (to allow for an additional I2C object).""" -//|... +//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, +//| and 8MHz. +//| If you pick a a baudrate other than one of these, the nearest lower +//| baudrate will be chosen, with a minimum of 125kHz. +//| Two SPI objects may be created, except on the Circuit Playground Bluefruit, +//| which allows only one (to allow for an additional I2C object).""" +//| ... STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; @@ -198,12 +198,12 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); -//|def try_lock(self, ) -> Any: -//|"""Attempts to grab the SPI lock. Returns True on success. +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the SPI lock. Returns True on success. //| -//|:return: True when lock has been grabbed -//|:rtype: bool""" -//|... +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -211,9 +211,9 @@ STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); -//|unlock(self, ) -> Any: -//|"""Releases the SPI lock.""" -//|... +//| def unlock(self, ) -> Any: +//| """Releases the SPI lock.""" +//| ... STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -223,14 +223,14 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); -//|def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ... -//|"""Write the data contained in ``buffer``. The SPI object must be locked. -//|If the buffer is empty, nothing happens. +//| def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: +//| """Write the data contained in ``buffer``. The SPI object must be locked. +//| If the buffer is empty, nothing happens. //| -//|:param bytearray buffer: Write out the data in this buffer -//|:param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//|:param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" -//|... +//| :param bytearray buffer: Write out the data in this buffer +//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" +//| ... STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; @@ -264,16 +264,16 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); -//|def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: -//|"""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. +//| def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: +//| """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. //| -//|:param bytearray buffer: Read data into this buffer -//|:param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//|:param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` -//|:param int write_value: Value to write while reading. (Usually ignored.)""" -//|... +//| :param bytearray buffer: Read data into this buffer +//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` +//| :param int write_value: Value to write while reading. (Usually ignored.)""" +//| ... STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; @@ -307,20 +307,20 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); -//|def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: -//|"""Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. -//|The SPI object must be locked. -//|The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//|must be equal. -//|If buffer slice lengths are both 0, nothing happens. +//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: +//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//| The SPI object must be locked. +//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` +//| must be equal. +//| If buffer slice lengths are both 0, nothing happens. //| -//|:param bytearray buffer_out: Write out the data in this buffer -//|:param bytearray buffer_in: Read data into this buffer -//|:param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//|:param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` -//|:param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//|:param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" -//|... +//| :param bytearray buffer_out: Write out the data in this buffer +//| :param bytearray buffer_in: Read data into this buffer +//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` +//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" +//| ... STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; @@ -369,10 +369,10 @@ STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_readinto_obj, 2, busio_spi_write_readinto); -//|frequency: Any = -//|"""The actual SPI bus frequency. This may not match the frequency requested -//|due to internal limitations.""" -//|... +//| frequency: Any = ... +//| """The actual SPI bus frequency. This may not match the frequency requested +//| due to internal limitations.""" +//| STATIC mp_obj_t busio_spi_obj_get_frequency(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/busio/__init__.c b/shared-bindings/busio/__init__.c index ff2933dc6..212b3218c 100644 --- a/shared-bindings/busio/__init__.c +++ b/shared-bindings/busio/__init__.c @@ -38,7 +38,7 @@ #include "py/runtime.h" -//| :mod:`busio` --- Hardware accelerated behavior +//| """:mod:`busio` --- Hardware accelerated behavior //| ================================================= //| //| .. module:: busio @@ -81,7 +81,7 @@ //| This example will initialize the the device, run //| :py:meth:`~busio.I2C.scan` and then :py:meth:`~busio.I2C.deinit` the //| hardware. The last step is optional because CircuitPython automatically -//| resets hardware after a program finishes. +//| resets hardware after a program finishes.""" //| STATIC const mp_rom_map_elem_t busio_module_globals_table[] = { -- cgit v1.2.3 From deccdcc1d668a9e65036872aa0a3064ae9ec959c Mon Sep 17 00:00:00 2001 From: dherrada Date: Wed, 29 Apr 2020 15:20:05 -0400 Subject: Did the same for the rest of busio --- shared-bindings/busio/I2C.c | 184 ++++++++++++++++++++-------------------- shared-bindings/busio/OneWire.c | 87 ++++++++++--------- shared-bindings/busio/UART.c | 164 +++++++++++++++++------------------ 3 files changed, 216 insertions(+), 219 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 8b71be085..31dd9a7bf 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -36,33 +36,35 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//|class I2C: -//|""".. currentmodule:: busio +//| class I2C: +//| """.. currentmodule:: busio //| -//|:class:`I2C` --- Two wire serial protocol -//|------------------------------------------""" -//|def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): -//|"""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. +//| :class:`I2C` --- Two wire serial protocol +//| ------------------------------------------""" //| -//|.. seealso:: Using this class directly requires careful lock management. -//|Instead, use :class:`~adafruit_bus_device.i2c_device.I2CDevice` to -//|manage locks. +//| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): //| -//|.. seealso:: Using this class to directly read registers requires manual -//|bit unpacking. Instead, use an existing driver or make one with -//|:ref:`Register ` data descriptors. +//| """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. //| -//|:param ~microcontroller.Pin scl: The clock pin -//|:param ~microcontroller.Pin sda: The data pin -//|:param int frequency: The clock frequency in Hertz -//|:param int timeout: The maximum clock stretching timeut - (used only for bitbangio.I2C; ignored for busio.I2C) +//| .. seealso:: Using this class directly requires careful lock management. +//| Instead, use :class:`~adafruit_bus_device.i2c_device.I2CDevice` to +//| manage locks. //| -//|.. note:: On the nRF52840, only one I2C object may be created, -//|except on the Circuit Playground Bluefruit, which allows two, -//|one for the onboard accelerometer, and one for offboard use.""" -//|... +//| .. seealso:: Using this class to directly read registers requires manual +//| bit unpacking. Instead, use an existing driver or make one with +//| :ref:`Register ` data descriptors. +//| +//| :param ~microcontroller.Pin scl: The clock pin +//| :param ~microcontroller.Pin sda: The data pin +//| :param int frequency: The clock frequency in Hertz +//| :param int timeout: The maximum clock stretching timeut - (used only for bitbangio.I2C; ignored for busio.I2C) +//| +//| .. note:: On the nRF52840, only one I2C object may be created, +//| except on the Circuit Playground Bluefruit, which allows two, +//| one for the onboard accelerometer, and one for offboard use.""" +//| ... STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { busio_i2c_obj_t *self = m_new_obj(busio_i2c_obj_t); self->base.type = &busio_i2c_type; @@ -83,9 +85,9 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//|def deinit(self, ) -> Any: -//|"""Releases control of the underlying hardware so other classes can use it.""" -//|... +//| def deinit(self, ) -> Any: +//| """Releases control of the underlying hardware so other classes can use it.""" +//| ... STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_i2c_deinit(self); @@ -99,15 +101,15 @@ STATIC void check_for_deinit(busio_i2c_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used in Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used in Context Managers.""" +//| ... // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware on context exit. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_i2c_deinit(args[0]); @@ -122,13 +124,14 @@ static void check_lock(busio_i2c_obj_t *self) { } } -//|def scan(self, ) -> Any: -//|"""Scan all I2C addresses between 0x08 and 0x77 inclusive and return a -//|list of those that respond. +//| def scan(self, ) -> Any: //| -//|:return: List of device ids on the I2C bus -//|:rtype: list""" -//|... +//| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a +//| list of those that respond. +//| +//| :return: List of device ids on the I2C bus +//| :rtype: list""" +//| ... STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -145,11 +148,12 @@ STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); -//|def try_lock(self, ) -> Any: -//|"""Attempts to grab the I2C lock. Returns True on success. -//|:return: True when lock has been grabbed -//|:rtype: bool""" -//|... +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the I2C lock. Returns True on success. +//| +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -157,9 +161,9 @@ STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); -//|def unlock(self, ) -> Any: -//|"""Releases the I2C lock.""" -//|... +//| def unlock(self, ) -> Any: +//| """Releases the I2C lock.""" +//| ... STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -168,20 +172,20 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); -//|def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: -//|"""Read into ``buffer`` from the slave specified by ``address``. -//|The number of bytes read will be the length of ``buffer``. -//|At least one byte must be read. +//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: +//| """Read into ``buffer`` from the slave specified 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. +//| 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 bytearray buffer: buffer to write into -//|:param int start: Index to start writing at -//|:param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" -//|... +//| :param int address: 7-bit device address +//| :param bytearray buffer: buffer to write into +//| :param int start: Index to start writing at +//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//| ... // Shared arg parsing for readfrom_into and writeto_then_readfrom. STATIC void readfrom(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end) { mp_buffer_info_t bufinfo; @@ -219,26 +223,26 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into); -//|def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: -//|"""Write the bytes from ``buffer`` to the slave specified by ``address``. -//|Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be -//|removed in CircuitPython 6.x. Use `writeto_then_readfrom` when needing a write, no stop and -//|repeated start before a read. +//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: +//| """Write the bytes from ``buffer`` to the slave specified by ``address``. +//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be +//| removed in CircuitPython 6.x. 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]``. This will not cause an allocation like -//|``buffer[start:end]`` will so it saves memory. +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]``. This will not cause an allocation like +//| ``buffer[start:end]`` will so it saves memory. //| -//|Writing a buffer or slice of length zero is permitted, as it can be used -//|to poll for the existence of a device. +//| 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 bytearray buffer: buffer containing the bytes to write -//|:param int start: Index to start writing from -//|:param int end: Index to read up to but not include. Defaults to ``len(buffer)`` -//|:param bool stop: If true, output an I2C stop condition after the buffer is written. -//|Deprecated. Will be removed in 6.x and act as stop=True.""" -//|... +//| :param int address: 7-bit device address +//| :param bytearray buffer: buffer containing the bytes to write +//| :param int start: Index to start writing from +//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param bool stop: If true, output an I2C stop condition after the buffer is written. +//| Deprecated. Will be removed in 6.x and act as stop=True.""" +//| ... // Shared arg parsing for writeto and writeto_then_readfrom. STATIC void writeto(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end, bool stop) { // get the buffer to write the data from @@ -277,23 +281,23 @@ STATIC mp_obj_t busio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, mp_ma } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto); -//|def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: -//|"""Write the bytes from ``out_buffer`` to the slave specified 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. +//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: +//| """Write the bytes from ``out_buffer`` to the slave specified 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 ``start`` or ``end`` is provided, then the corresponding buffer will be sliced -//|as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]`` -//|will so it saves memory. +//| If ``start`` or ``end`` is provided, then the corresponding 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 bytearray out_buffer: buffer containing the bytes to write -//|:param bytearray in_buffer: buffer to write into -//|:param int out_start: Index to start writing from -//|:param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` -//|:param int in_start: Index to start writing at -//|:param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" -//|... +//| :param int address: 7-bit device address +//| :param bytearray out_buffer: buffer containing the bytes to write +//| :param bytearray in_buffer: buffer to write into +//| :param int out_start: Index to start writing from +//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param int in_start: Index to start writing at +//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//| ... STATIC mp_obj_t busio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index d6af32bd9..09a76decc 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -34,36 +34,35 @@ #include "shared-bindings/busio/OneWire.h" #include "shared-bindings/util.h" -//|class OneWire: -//|""".. currentmodule:: busio +//| class OneWire: +//| """.. currentmodule:: busio //| -//|:class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//|=================================================================""" +//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol +//| =================================================================""" //| -//|__init__(self, pin: microcontroller.Pin): -//|""":class:`~busio.OneWire` implements the timing-sensitive foundation of the Maxim -//|(formerly Dallas Semi) OneWire protocol. +//| def __init__(self, pin: microcontroller.Pin): +//| """(formerly Dallas Semi) OneWire protocol. //| -//|Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 +//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 //| -//|.. class:: OneWire(pin) +//| .. class:: OneWire(pin) //| -//|Create a OneWire object associated with the given pin. The object -//|implements the lowest level timing-sensitive bits of the protocol. +//| Create a OneWire object associated with the given pin. The object +//| implements the lowest level timing-sensitive bits of the protocol. //| -//|:param ~microcontroller.Pin pin: Pin connected to the OneWire bus +//| :param ~microcontroller.Pin pin: Pin connected to the OneWire bus //| -//|Read a short series of pulses:: +//| Read a short series of pulses:: //| -//|import busio -//|import board +//| import busio +//| import board //| -//|onewire = busio.OneWire(board.D7) -//|onewire.reset() -//|onewire.write_bit(True) -//|onewire.write_bit(False) -//|print(onewire.read_bit())""" -//|... +//| onewire = busio.OneWire(board.D7) +//| onewire.reset() +//| onewire.write_bit(True) +//| onewire.write_bit(False) +//| print(onewire.read_bit())""" +//| ... STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin }; static const mp_arg_t allowed_args[] = { @@ -80,9 +79,9 @@ STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialize the OneWire bus and release any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" +//| ... STATIC mp_obj_t busio_onewire_deinit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_onewire_deinit(self); @@ -96,15 +95,15 @@ STATIC void check_for_deinit(busio_onewire_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_onewire_deinit(args[0]); @@ -112,12 +111,12 @@ STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_onewire___exit___obj, 4, 4, busio_onewire_obj___exit__); -//|def reset(self, ) -> Any: -//|"""Reset the OneWire bus and read presence +//| def reset(self, ) -> Any: +//| """Reset the OneWire bus and read presence //| -//|:returns: False when at least one device is present -//|:rtype: bool""" -//|... +//| :returns: False when at least one device is present +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -126,12 +125,12 @@ STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_reset_obj, busio_onewire_obj_reset); -//|def read_bit(self, ) -> Any: -//|"""Read in a bit +//| def read_bit(self, ) -> Any: +//| """Read in a bit //| -//|:returns: bit state read -//|:rtype: bool""" -//|... +//| :returns: bit state read +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -140,9 +139,9 @@ STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_read_bit_obj, busio_onewire_obj_read_bit); -//|def write_bit(self, value: Any) -> Any: -//|"""Write out a bit based on value.""" -//|... +//| def write_bit(self, value: Any) -> Any: +//| """Write out a bit based on value.""" +//| ... STATIC mp_obj_t busio_onewire_obj_write_bit(mp_obj_t self_in, mp_obj_t bool_obj) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index b89b331af..e5d123ce7 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -39,31 +39,31 @@ #include "py/stream.h" #include "supervisor/shared/translate.h" -//|class UART: -//|""".. currentmodule:: busio +//| class UART: +//| """.. currentmodule:: busio //| -//|:class:`UART` -- a bidirectional serial protocol -//|=================================================""" -//|def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): -//|"""A common bidirectional serial protocol that uses an an agreed upon speed -//|rather than a shared clock line. +//| :class:`UART` -- a bidirectional serial protocol +//| =================================================""" +//| def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): +//| """A common bidirectional serial protocol that uses an an agreed upon speed +//| rather than a shared clock line. //| -//|:param ~microcontroller.Pin tx: the pin to transmit with, or ``None`` if this ``UART`` is receive-only. -//|:param ~microcontroller.Pin rx: the pin to receive on, or ``None`` if this ``UART`` is transmit-only. -//|:param ~microcontroller.Pin rts: the pin for rts, or ``None`` if rts not in use. -//|:param ~microcontroller.Pin cts: the pin for cts, or ``None`` if cts not in use. -//|:param ~microcontroller.Pin rs485_dir: the pin for rs485 direction setting, or ``None`` if rs485 not in use. -//|:param bool rs485_invert: set to invert the sense of the rs485_dir pin. -//|:param int baudrate: the transmit and receive speed. -//|:param int bits: the number of bits per byte, 7, 8 or 9. -//|:param Parity parity: the parity used for error checking. -//|:param int stop: the number of stop bits, 1 or 2. -//|:param float timeout: the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises ``ValueError`` if timeout >100 seconds. -//|:param int receiver_buffer_size: the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.) +//| :param ~microcontroller.Pin tx: the pin to transmit with, or ``None`` if this ``UART`` is receive-only. +//| :param ~microcontroller.Pin rx: the pin to receive on, or ``None`` if this ``UART`` is transmit-only. +//| :param ~microcontroller.Pin rts: the pin for rts, or ``None`` if rts not in use. +//| :param ~microcontroller.Pin cts: the pin for cts, or ``None`` if cts not in use. +//| :param ~microcontroller.Pin rs485_dir: the pin for rs485 direction setting, or ``None`` if rs485 not in use. +//| :param bool rs485_invert: set to invert the sense of the rs485_dir pin. +//| :param int baudrate: the transmit and receive speed. +//| :param int bits: the number of bits per byte, 7, 8 or 9. +//| :param Parity parity: the parity used for error checking. +//| :param int stop: the number of stop bits, 1 or 2. +//| :param float timeout: the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises ``ValueError`` if timeout >100 seconds. +//| :param int receiver_buffer_size: the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.) //| -//|*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.""" -//|... +//| *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.""" +//| ... typedef struct { mp_obj_base_t base; } busio_uart_parity_obj_t; @@ -141,9 +141,9 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, co return (mp_obj_t)self; } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the UART and releases any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the UART and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_uart_deinit(self); @@ -157,15 +157,15 @@ STATIC void check_for_deinit(busio_uart_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_uart_deinit(args[0]); @@ -175,46 +175,40 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ // These are standard stream methods. Code is in py/stream.c. // -//|def read(self, nbytes: Any = None) -> Any: -//|"""Read characters. If ``nbytes`` is specified then read at most that many -//|bytes. Otherwise, read everything that arrives until the connection -//|times out. Providing the number of bytes expected is highly recommended -//|because it will be faster. +//| def read(self, nbytes: Any = None) -> Any: +//| """Read characters. If ``nbytes`` is specified then read at most that many +//| bytes. Otherwise, read everything that arrives until the connection +//| times out. Providing the number of bytes expected is highly recommended +//| because it will be faster. //| -//|:return: Data read -//|:rtype: bytes or None""" -//|... +//| :return: Data read +//| :rtype: bytes or None""" +//| ... -//|def readinto(self, buf: Any) -> Any: -//|""".. method:: readinto(buf) +//| def readinto(self, buf: Any) -> Any: +//| """Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. //| -//|Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. +//| :return: number of bytes read and stored into ``buf`` +//| :rtype: int or None (on a non-blocking error) //| -//|:return: number of bytes read and stored into ``buf`` -//|:rtype: int or None (on a non-blocking error) -//| -//|*New in CircuitPython 4.0:* No length parameter is permitted.""" -//|... +//| *New in CircuitPython 4.0:* No length parameter is permitted.""" +//| ... -//|def readline(self, ) -> Any: -//|""".. method:: readline() -//| -//|Read a line, ending in a newline character. +//| def readline(self, ) -> Any: +//| """Read a line, ending in a newline character. //| -//|:return: the line read -//|:rtype: int or None""" -//|... +//| :return: the line read +//| :rtype: int or None""" +//| ... -//|def write(self, buf: Any) -> Any: -//|""".. method:: write(buf) -//| -//|Write the buffer of bytes to the bus. +//| def write(self, buf: Any) -> Any: +//| """Write the buffer of bytes to the bus. //| -//|*New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. +//| *New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. //| -//|:return: the number of bytes written -//|:rtype: int or None""" -//|... +//| :return: the number of bytes written +//| :rtype: int or None""" +//| ... // These three methods are used by the shared stream methods. STATIC mp_uint_t busio_uart_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) { @@ -258,9 +252,9 @@ STATIC mp_uint_t busio_uart_ioctl(mp_obj_t self_in, mp_uint_t request, mp_uint_t return ret; } -//|baudrate: Any = -//|"""The current baudrate.""" -//|... +//| baudrate: Any = ... +//| """The current baudrate.""" +//| STATIC mp_obj_t busio_uart_obj_get_baudrate(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -284,9 +278,9 @@ const mp_obj_property_t busio_uart_baudrate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|in_waiting: Any = -//|"""The number of bytes in the input buffer, available to be read""" -//|... +//| in_waiting: Any = ... +//| """The number of bytes in the input buffer, available to be read""" +//| STATIC mp_obj_t busio_uart_obj_get_in_waiting(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -301,9 +295,9 @@ const mp_obj_property_t busio_uart_in_waiting_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|timeout: Any = -//|"""The current timeout, in seconds (float).""" -//|... +//| timeout: Any = ... +//| """The current timeout, in seconds (float).""" +//| STATIC mp_obj_t busio_uart_obj_get_timeout(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -329,9 +323,9 @@ const mp_obj_property_t busio_uart_timeout_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|def reset_input_buffer(self, ) -> Any: -//|"""Discard any unread characters in the input buffer.""" -//|... +//| def reset_input_buffer(self, ) -> Any: ... +//| """Discard any unread characters in the input buffer.""" +//| STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -340,16 +334,16 @@ STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_obj_reset_input_buffer); -//|class busio: -//|def __init__(self, ): -//|"""Enum-like class to define the parity used to verify correct data transfer.""" -//|ODD: Any = -//|"""Total number of ones should be odd.""" -//|... -//|EVEN: Any = -//|"""Total number of ones should be even.""" -//|... -//|... +//| class busio: +//| """Enum-like class to define the parity used to verify correct data transfer.""" +//| +//| def __init__(self, ): +//| ODD: Any = ... +//| """Total number of ones should be odd.""" +//| +//| EVEN: Any = ... +//| """Total number of ones should be even.""" +//| ... const mp_obj_type_t busio_uart_parity_type; const busio_uart_parity_obj_t busio_uart_parity_odd_obj = { -- cgit v1.2.3 From 093461e81670d8ad635d8f893a44426a46b9779c Mon Sep 17 00:00:00 2001 From: dherrada Date: Wed, 29 Apr 2020 15:45:19 -0400 Subject: Fixed indentation --- shared-bindings/busio/I2C.c | 136 +++++++++++++++++++------------------- shared-bindings/busio/OneWire.c | 46 ++++++------- shared-bindings/busio/SPI.c | 140 ++++++++++++++++++++-------------------- shared-bindings/busio/UART.c | 88 ++++++++++++------------- 4 files changed, 205 insertions(+), 205 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 31dd9a7bf..98ccbb512 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -85,9 +85,9 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| def deinit(self, ) -> Any: -//| """Releases control of the underlying hardware so other classes can use it.""" -//| ... +//| def deinit(self, ) -> Any: +//| """Releases control of the underlying hardware so other classes can use it.""" +//| ... STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_i2c_deinit(self); @@ -101,15 +101,15 @@ STATIC void check_for_deinit(busio_i2c_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used in Context Managers.""" -//| ... +//| def __enter__(self, ) -> Any: +//| """No-op used in Context Managers.""" +//| ... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware on context exit. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_i2c_deinit(args[0]); @@ -124,14 +124,14 @@ static void check_lock(busio_i2c_obj_t *self) { } } -//| def scan(self, ) -> Any: +//| def scan(self, ) -> Any: //| -//| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a -//| list of those that respond. +//| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a +//| list of those that respond. //| -//| :return: List of device ids on the I2C bus -//| :rtype: list""" -//| ... +//| :return: List of device ids on the I2C bus +//| :rtype: list""" +//| ... STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -148,12 +148,12 @@ STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); -//| def try_lock(self, ) -> Any: -//| """Attempts to grab the I2C lock. Returns True on success. +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the I2C lock. Returns True on success. //| -//| :return: True when lock has been grabbed -//| :rtype: bool""" -//| ... +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -161,9 +161,9 @@ STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); -//| def unlock(self, ) -> Any: -//| """Releases the I2C lock.""" -//| ... +//| def unlock(self, ) -> Any: +//| """Releases the I2C lock.""" +//| ... STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -172,20 +172,20 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); -//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: -//| """Read into ``buffer`` from the slave specified by ``address``. -//| The number of bytes read will be the length of ``buffer``. -//| At least one byte must be read. +//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: +//| """Read into ``buffer`` from the slave specified 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. +//| 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 bytearray buffer: buffer to write into -//| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" -//| ... +//| :param int address: 7-bit device address +//| :param bytearray buffer: buffer to write into +//| :param int start: Index to start writing at +//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//| ... // Shared arg parsing for readfrom_into and writeto_then_readfrom. STATIC void readfrom(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end) { mp_buffer_info_t bufinfo; @@ -223,26 +223,26 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into); -//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: -//| """Write the bytes from ``buffer`` to the slave specified by ``address``. -//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be -//| removed in CircuitPython 6.x. Use `writeto_then_readfrom` when needing a write, no stop and -//| repeated start before a read. +//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: +//| """Write the bytes from ``buffer`` to the slave specified by ``address``. +//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be +//| removed in CircuitPython 6.x. 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]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]``. This will not cause an allocation like +//| ``buffer[start:end]`` will so it saves memory. //| -//| Writing a buffer or slice of length zero is permitted, as it can be used -//| to poll for the existence of a device. +//| 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 bytearray buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param bool stop: If true, output an I2C stop condition after the buffer is written. -//| Deprecated. Will be removed in 6.x and act as stop=True.""" -//| ... +//| :param int address: 7-bit device address +//| :param bytearray buffer: buffer containing the bytes to write +//| :param int start: Index to start writing from +//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param bool stop: If true, output an I2C stop condition after the buffer is written. +//| Deprecated. Will be removed in 6.x and act as stop=True.""" +//| ... // Shared arg parsing for writeto and writeto_then_readfrom. STATIC void writeto(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end, bool stop) { // get the buffer to write the data from @@ -281,23 +281,23 @@ STATIC mp_obj_t busio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, mp_ma } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto); -//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: -//| """Write the bytes from ``out_buffer`` to the slave specified 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. +//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: +//| """Write the bytes from ``out_buffer`` to the slave specified 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 ``start`` or ``end`` is provided, then the corresponding buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]`` -//| will so it saves memory. +//| If ``start`` or ``end`` is provided, then the corresponding 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 bytearray out_buffer: buffer containing the bytes to write -//| :param bytearray in_buffer: buffer to write into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" -//| ... +//| :param int address: 7-bit device address +//| :param bytearray out_buffer: buffer containing the bytes to write +//| :param bytearray in_buffer: buffer to write into +//| :param int out_start: Index to start writing from +//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param int in_start: Index to start writing at +//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" +//| ... STATIC mp_obj_t busio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index 09a76decc..e44c876c5 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -79,9 +79,9 @@ STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" -//| ... +//| def deinit(self, ) -> Any: +//| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" +//| ... STATIC mp_obj_t busio_onewire_deinit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_onewire_deinit(self); @@ -95,15 +95,15 @@ STATIC void check_for_deinit(busio_onewire_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_onewire_deinit(args[0]); @@ -111,12 +111,12 @@ STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_onewire___exit___obj, 4, 4, busio_onewire_obj___exit__); -//| def reset(self, ) -> Any: -//| """Reset the OneWire bus and read presence +//| def reset(self, ) -> Any: +//| """Reset the OneWire bus and read presence //| -//| :returns: False when at least one device is present -//| :rtype: bool""" -//| ... +//| :returns: False when at least one device is present +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -125,12 +125,12 @@ STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_reset_obj, busio_onewire_obj_reset); -//| def read_bit(self, ) -> Any: -//| """Read in a bit +//| def read_bit(self, ) -> Any: +//| """Read in a bit //| -//| :returns: bit state read -//| :rtype: bool""" -//| ... +//| :returns: bit state read +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -139,9 +139,9 @@ STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_read_bit_obj, busio_onewire_obj_read_bit); -//| def write_bit(self, value: Any) -> Any: -//| """Write out a bit based on value.""" -//| ... +//| def write_bit(self, value: Any) -> Any: +//| """Write out a bit based on value.""" +//| ... STATIC mp_obj_t busio_onewire_obj_write_bit(mp_obj_t self_in, mp_obj_t bool_obj) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 9644f4eb5..93588d087 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -101,9 +101,9 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Turn off the SPI bus.""" -//| ... +//| def deinit(self, ) -> Any: +//| """Turn off the SPI bus.""" +//| ... STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_spi_deinit(self); @@ -111,15 +111,15 @@ STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers. -//| Provided by context manager helper.""" -//| ... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers. +//| Provided by context manager helper.""" +//| ... -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_spi_deinit(args[0]); @@ -140,28 +140,28 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { } } -//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: -//| """Configures the SPI bus. The SPI object must be locked. +//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: +//| """Configures the SPI bus. The SPI object must be locked. //| -//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower -//| due to the granularity of available clock settings. -//| Check the `frequency` attribute for the actual clock rate. -//| :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 +//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower +//| due to the granularity of available clock settings. +//| Check the `frequency` attribute for the actual clock rate. +//| :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 //| -//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that -//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is -//| within spec for the SAMD21. +//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that +//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is +//| within spec for the SAMD21. //| -//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, -//| and 8MHz. -//| If you pick a a baudrate other than one of these, the nearest lower -//| baudrate will be chosen, with a minimum of 125kHz. -//| Two SPI objects may be created, except on the Circuit Playground Bluefruit, -//| which allows only one (to allow for an additional I2C object).""" -//| ... +//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, +//| and 8MHz. +//| If you pick a a baudrate other than one of these, the nearest lower +//| baudrate will be chosen, with a minimum of 125kHz. +//| Two SPI objects may be created, except on the Circuit Playground Bluefruit, +//| which allows only one (to allow for an additional I2C object).""" +//| ... STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; @@ -198,12 +198,12 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); -//| def try_lock(self, ) -> Any: -//| """Attempts to grab the SPI lock. Returns True on success. +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the SPI lock. Returns True on success. //| -//| :return: True when lock has been grabbed -//| :rtype: bool""" -//| ... +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -211,9 +211,9 @@ STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); -//| def unlock(self, ) -> Any: -//| """Releases the SPI lock.""" -//| ... +//| def unlock(self, ) -> Any: +//| """Releases the SPI lock.""" +//| ... STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -223,14 +223,14 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); -//| def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: -//| """Write the data contained in ``buffer``. The SPI object must be locked. -//| If the buffer is empty, nothing happens. +//| def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: +//| """Write the data contained in ``buffer``. The SPI object must be locked. +//| If the buffer is empty, nothing happens. //| -//| :param bytearray buffer: Write out the data in this buffer -//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" -//| ... +//| :param bytearray buffer: Write out the data in this buffer +//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" +//| ... STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; @@ -264,16 +264,16 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); -//| def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: -//| """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. +//| def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: +//| """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. //| -//| :param bytearray buffer: Read data into this buffer -//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` -//| :param int write_value: Value to write while reading. (Usually ignored.)""" -//| ... +//| :param bytearray buffer: Read data into this buffer +//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` +//| :param int write_value: Value to write while reading. (Usually ignored.)""" +//| ... STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; @@ -307,20 +307,20 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); -//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: -//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. -//| The SPI object must be locked. -//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//| must be equal. -//| If buffer slice lengths are both 0, nothing happens. +//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: +//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//| The SPI object must be locked. +//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` +//| must be equal. +//| If buffer slice lengths are both 0, nothing happens. //| -//| :param bytearray buffer_out: Write out the data in this buffer -//| :param bytearray buffer_in: Read data into this buffer -//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` -//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" -//| ... +//| :param bytearray buffer_out: Write out the data in this buffer +//| :param bytearray buffer_in: Read data into this buffer +//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` +//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" +//| ... STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; @@ -369,9 +369,9 @@ STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_readinto_obj, 2, busio_spi_write_readinto); -//| frequency: Any = ... -//| """The actual SPI bus frequency. This may not match the frequency requested -//| due to internal limitations.""" +//| frequency: Any = ... +//| """The actual SPI bus frequency. This may not match the frequency requested +//| due to internal limitations.""" //| STATIC mp_obj_t busio_spi_obj_get_frequency(mp_obj_t self_in) { diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index e5d123ce7..7c5c6ec2b 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -141,9 +141,9 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, co return (mp_obj_t)self; } -//| def deinit(self, ) -> Any: -//| """Deinitialises the UART and releases any hardware resources for reuse.""" -//| ... +//| def deinit(self, ) -> Any: +//| """Deinitialises the UART and releases any hardware resources for reuse.""" +//| ... STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_uart_deinit(self); @@ -157,15 +157,15 @@ STATIC void check_for_deinit(busio_uart_obj_t *self) { } } -//| def __enter__(self, ) -> Any: -//| """No-op used by Context Managers.""" -//| ... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... // Provided by context manager helper. -//| def __exit__(self, ) -> Any: -//| """Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info.""" -//| ... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_uart_deinit(args[0]); @@ -175,40 +175,40 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ // These are standard stream methods. Code is in py/stream.c. // -//| def read(self, nbytes: Any = None) -> Any: -//| """Read characters. If ``nbytes`` is specified then read at most that many -//| bytes. Otherwise, read everything that arrives until the connection -//| times out. Providing the number of bytes expected is highly recommended -//| because it will be faster. +//| def read(self, nbytes: Any = None) -> Any: +//| """Read characters. If ``nbytes`` is specified then read at most that many +//| bytes. Otherwise, read everything that arrives until the connection +//| times out. Providing the number of bytes expected is highly recommended +//| because it will be faster. //| -//| :return: Data read -//| :rtype: bytes or None""" -//| ... +//| :return: Data read +//| :rtype: bytes or None""" +//| ... -//| def readinto(self, buf: Any) -> Any: -//| """Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. +//| def readinto(self, buf: Any) -> Any: +//| """Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. //| -//| :return: number of bytes read and stored into ``buf`` -//| :rtype: int or None (on a non-blocking error) +//| :return: number of bytes read and stored into ``buf`` +//| :rtype: int or None (on a non-blocking error) //| -//| *New in CircuitPython 4.0:* No length parameter is permitted.""" -//| ... +//| *New in CircuitPython 4.0:* No length parameter is permitted.""" +//| ... -//| def readline(self, ) -> Any: -//| """Read a line, ending in a newline character. +//| def readline(self, ) -> Any: +//| """Read a line, ending in a newline character. //| -//| :return: the line read -//| :rtype: int or None""" -//| ... +//| :return: the line read +//| :rtype: int or None""" +//| ... -//| def write(self, buf: Any) -> Any: -//| """Write the buffer of bytes to the bus. +//| def write(self, buf: Any) -> Any: +//| """Write the buffer of bytes to the bus. //| -//| *New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. +//| *New in CircuitPython 4.0:* ``buf`` must be bytes, not a string. //| -//| :return: the number of bytes written -//| :rtype: int or None""" -//| ... +//| :return: the number of bytes written +//| :rtype: int or None""" +//| ... // These three methods are used by the shared stream methods. STATIC mp_uint_t busio_uart_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) { @@ -252,8 +252,8 @@ STATIC mp_uint_t busio_uart_ioctl(mp_obj_t self_in, mp_uint_t request, mp_uint_t return ret; } -//| baudrate: Any = ... -//| """The current baudrate.""" +//| baudrate: Any = ... +//| """The current baudrate.""" //| STATIC mp_obj_t busio_uart_obj_get_baudrate(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -278,8 +278,8 @@ const mp_obj_property_t busio_uart_baudrate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| in_waiting: Any = ... -//| """The number of bytes in the input buffer, available to be read""" +//| in_waiting: Any = ... +//| """The number of bytes in the input buffer, available to be read""" //| STATIC mp_obj_t busio_uart_obj_get_in_waiting(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -295,8 +295,8 @@ const mp_obj_property_t busio_uart_in_waiting_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| timeout: Any = ... -//| """The current timeout, in seconds (float).""" +//| timeout: Any = ... +//| """The current timeout, in seconds (float).""" //| STATIC mp_obj_t busio_uart_obj_get_timeout(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -323,8 +323,8 @@ const mp_obj_property_t busio_uart_timeout_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def reset_input_buffer(self, ) -> Any: ... -//| """Discard any unread characters in the input buffer.""" +//| def reset_input_buffer(self, ) -> Any: ... +//| """Discard any unread characters in the input buffer.""" //| STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -334,7 +334,7 @@ STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_obj_reset_input_buffer); -//| class busio: +//| class Parity: //| """Enum-like class to define the parity used to verify correct data transfer.""" //| //| def __init__(self, ): -- cgit v1.2.3 From a2a32fea1acc4caefb6c4142b547d8a09b2ba761 Mon Sep 17 00:00:00 2001 From: dherrada Date: Wed, 29 Apr 2020 15:55:06 -0400 Subject: Added newlines after every ellipsis --- shared-bindings/busio/I2C.c | 10 ++++++++++ shared-bindings/busio/OneWire.c | 7 +++++++ shared-bindings/busio/SPI.c | 10 ++++++++++ shared-bindings/busio/UART.c | 9 +++++++++ 4 files changed, 36 insertions(+) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 98ccbb512..8ae3658ee 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -65,6 +65,7 @@ //| except on the Circuit Playground Bluefruit, which allows two, //| one for the onboard accelerometer, and one for offboard use.""" //| ... +//| STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { busio_i2c_obj_t *self = m_new_obj(busio_i2c_obj_t); self->base.type = &busio_i2c_type; @@ -88,6 +89,7 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con //| def deinit(self, ) -> Any: //| """Releases control of the underlying hardware so other classes can use it.""" //| ... +//| STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_i2c_deinit(self); @@ -104,12 +106,14 @@ STATIC void check_for_deinit(busio_i2c_obj_t *self) { //| def __enter__(self, ) -> Any: //| """No-op used in Context Managers.""" //| ... +//| // Provided by context manager helper. //| def __exit__(self, ) -> Any: //| """Automatically deinitializes the hardware on context exit. See //| :ref:`lifetime-and-contextmanagers` for more info.""" //| ... +//| STATIC mp_obj_t busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_i2c_deinit(args[0]); @@ -132,6 +136,7 @@ static void check_lock(busio_i2c_obj_t *self) { //| :return: List of device ids on the I2C bus //| :rtype: list""" //| ... +//| STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -154,6 +159,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); //| :return: True when lock has been grabbed //| :rtype: bool""" //| ... +//| STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -164,6 +170,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); //| def unlock(self, ) -> Any: //| """Releases the I2C lock.""" //| ... +//| STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -186,6 +193,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); //| :param int start: Index to start writing at //| :param int end: Index to write up to but not include. Defaults to ``len(buffer)``""" //| ... +//| // Shared arg parsing for readfrom_into and writeto_then_readfrom. STATIC void readfrom(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end) { mp_buffer_info_t bufinfo; @@ -243,6 +251,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_in //| :param bool stop: If true, output an I2C stop condition after the buffer is written. //| Deprecated. Will be removed in 6.x and act as stop=True.""" //| ... +//| // Shared arg parsing for writeto and writeto_then_readfrom. STATIC void writeto(busio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end, bool stop) { // get the buffer to write the data from @@ -298,6 +307,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto); //| :param int in_start: Index to start writing at //| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" //| ... +//| STATIC mp_obj_t busio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index e44c876c5..556e567ef 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -63,6 +63,7 @@ //| onewire.write_bit(False) //| print(onewire.read_bit())""" //| ... +//| STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin }; static const mp_arg_t allowed_args[] = { @@ -82,6 +83,7 @@ STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, //| def deinit(self, ) -> Any: //| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" //| ... +//| STATIC mp_obj_t busio_onewire_deinit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_onewire_deinit(self); @@ -98,12 +100,14 @@ STATIC void check_for_deinit(busio_onewire_obj_t *self) { //| def __enter__(self, ) -> Any: //| """No-op used by Context Managers.""" //| ... +//| // Provided by context manager helper. //| def __exit__(self, ) -> Any: //| """Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info.""" //| ... +//| STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_onewire_deinit(args[0]); @@ -117,6 +121,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_onewire___exit___obj, 4, 4, bus //| :returns: False when at least one device is present //| :rtype: bool""" //| ... +//| STATIC mp_obj_t busio_onewire_obj_reset(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -131,6 +136,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_reset_obj, busio_onewire_obj_reset); //| :returns: bit state read //| :rtype: bool""" //| ... +//| STATIC mp_obj_t busio_onewire_obj_read_bit(mp_obj_t self_in) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -142,6 +148,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_read_bit_obj, busio_onewire_obj_read_bit //| def write_bit(self, value: Any) -> Any: //| """Write out a bit based on value.""" //| ... +//| STATIC mp_obj_t busio_onewire_obj_write_bit(mp_obj_t self_in, mp_obj_t bool_obj) { busio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 93588d087..5b1881702 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -78,6 +78,7 @@ //| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. //| :param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" //| ... +//| // TODO(tannewt): Support LSB SPI. @@ -104,6 +105,7 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con //| def deinit(self, ) -> Any: //| """Turn off the SPI bus.""" //| ... +//| STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_spi_deinit(self); @@ -115,11 +117,13 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); //| """No-op used by Context Managers. //| Provided by context manager helper.""" //| ... +//| //| def __exit__(self, ) -> Any: //| """Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info.""" //| ... +//| STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_spi_deinit(args[0]); @@ -162,6 +166,7 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { //| Two SPI objects may be created, except on the Circuit Playground Bluefruit, //| which allows only one (to allow for an additional I2C object).""" //| ... +//| STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; @@ -204,6 +209,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); //| :return: True when lock has been grabbed //| :rtype: bool""" //| ... +//| STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -214,6 +220,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); //| def unlock(self, ) -> Any: //| """Releases the SPI lock.""" //| ... +//| STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -231,6 +238,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); //| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` //| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" //| ... +//| STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; @@ -274,6 +282,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); //| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| :param int write_value: Value to write while reading. (Usually ignored.)""" //| ... +//| STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; @@ -321,6 +330,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); //| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` //| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" //| ... +//| STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 7c5c6ec2b..6a3d542e1 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -64,6 +64,7 @@ //| *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.""" //| ... +//| typedef struct { mp_obj_base_t base; } busio_uart_parity_obj_t; @@ -144,6 +145,7 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, co //| def deinit(self, ) -> Any: //| """Deinitialises the UART and releases any hardware resources for reuse.""" //| ... +//| STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) { busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_busio_uart_deinit(self); @@ -160,12 +162,14 @@ STATIC void check_for_deinit(busio_uart_obj_t *self) { //| def __enter__(self, ) -> Any: //| """No-op used by Context Managers.""" //| ... +//| // Provided by context manager helper. //| def __exit__(self, ) -> Any: //| """Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info.""" //| ... +//| STATIC mp_obj_t busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_busio_uart_deinit(args[0]); @@ -184,6 +188,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ //| :return: Data read //| :rtype: bytes or None""" //| ... +//| //| def readinto(self, buf: Any) -> Any: //| """Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. @@ -193,6 +198,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ //| //| *New in CircuitPython 4.0:* No length parameter is permitted.""" //| ... +//| //| def readline(self, ) -> Any: //| """Read a line, ending in a newline character. @@ -200,6 +206,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ //| :return: the line read //| :rtype: int or None""" //| ... +//| //| def write(self, buf: Any) -> Any: //| """Write the buffer of bytes to the bus. @@ -209,6 +216,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ //| :return: the number of bytes written //| :rtype: int or None""" //| ... +//| // These three methods are used by the shared stream methods. STATIC mp_uint_t busio_uart_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) { @@ -344,6 +352,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_o //| EVEN: Any = ... //| """Total number of ones should be even.""" //| ... +//| const mp_obj_type_t busio_uart_parity_type; const busio_uart_parity_obj_t busio_uart_parity_odd_obj = { -- cgit v1.2.3 From 7ff9b9bc80b3dafd4b263bc8854e4582a21664c2 Mon Sep 17 00:00:00 2001 From: dherrada Date: Wed, 29 Apr 2020 17:36:28 -0400 Subject: Did first 3 --- shared-bindings/analogio/AnalogIn.c | 70 ++++++++------- shared-bindings/analogio/AnalogOut.c | 63 +++++++------ shared-bindings/analogio/__init__.c | 4 +- shared-bindings/audiobusio/I2SOut.c | 161 ++++++++++++++++++---------------- shared-bindings/audiobusio/PDMIn.c | 151 ++++++++++++++++--------------- shared-bindings/audiobusio/__init__.c | 4 +- shared-bindings/audiocore/RawSample.c | 104 ++++++++++++---------- shared-bindings/audiocore/WaveFile.c | 103 +++++++++++----------- shared-bindings/audiocore/__init__.c | 4 +- 9 files changed, 351 insertions(+), 313 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index 9b6ac086b..2fb5051eb 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -36,25 +36,28 @@ #include "shared-bindings/analogio/AnalogIn.h" #include "shared-bindings/util.h" -//|class AnalogIn: -//|""":class:`AnalogIn` -- read analog voltage -//|============================================ +//| class AnalogIn: +//| """.. currentmodule:: analogio //| -//|Usage:: +//| :class:`AnalogIn` -- read analog voltage +//| ============================================ //| -//|import analogio -//|from board import * +//| Usage:: //| -//|adc = analogio.AnalogIn(A1) -//|val = adc.value""" +//| import analogio +//| from board import * //| -//|def __init__(self, pin: microcontroller.Pin): +//| adc = analogio.AnalogIn(A1) +//| val = adc.value""" //| -//|"""Use the AnalogIn on the given pin. The reference voltage varies by -//|platform so use ``reference_voltage`` to read the configured setting. + +//| def __init__(self, pin: microcontroller.Pin): +//| """Use the AnalogIn on the given pin. The reference voltage varies by +//| platform so use ``reference_voltage`` to read the configured setting. +//| +//| :param ~microcontroller.Pin pin: the pin to read from""" +//| ... //| -//|:param ~microcontroller.Pin pin: the pin to read from""" -//|... STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // check number of arguments @@ -70,9 +73,10 @@ STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Turn off the AnalogIn and release the pin for other use.""" -//|... +//| def deinit(self, ) -> Any: +//| """Turn off the AnalogIn and release the pin for other use.""" +//| ... +//| STATIC mp_obj_t analogio_analogin_deinit(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_analogio_analogin_deinit(self); @@ -85,15 +89,17 @@ STATIC void check_for_deinit(analogio_analogin_obj_t *self) { raise_deinited_error(); } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_analogio_analogin_deinit(args[0]); @@ -101,12 +107,12 @@ STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogin___exit___obj, 4, 4, analogio_analogin___exit__); -//|value: Any = -//|"""The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only) +//| value: Any = ... +//| """The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only) +//| +//| Even if the underlying analog to digital converter (ADC) is lower +//| resolution, the value is 16-bit.""" //| -//|Even if the underlying analog to digital converter (ADC) is lower -//|resolution, the value is 16-bit.""" -//|... STATIC mp_obj_t analogio_analogin_obj_get_value(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -121,10 +127,10 @@ const mp_obj_property_t analogio_analogin_value_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|reference_voltage: Any = -//|"""The maximum voltage measurable (also known as the reference voltage) as a -//|`float` in Volts.""" -//|... +//| reference_voltage: Any = ... +//| """The maximum voltage measurable (also known as the reference voltage) as a +//| `float` in Volts.""" +//| STATIC mp_obj_t analogio_analogin_obj_get_reference_voltage(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 231668290..9064bb5dc 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -36,26 +36,28 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class AnalogOut: -//|""".. currentmodule:: analogio +//| class AnalogOut: +//| """.. currentmodule:: analogio //| -//|:class:`AnalogOut` -- output analog voltage -//|============================================ +//| :class:`AnalogOut` -- output analog voltage +//| ============================================ //| -//|The AnalogOut is used to output analog values (a specific voltage). +//| The AnalogOut is used to output analog values (a specific voltage). //| -//|Example usage:: +//| Example usage:: //| -//|import analogio -//|from microcontroller import pin +//| import analogio +//| from microcontroller import pin //| -//|dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 -//|dac.value = 32768 # makes PA02 1.65V""" -//|def __init__(self, pin: microcontroller.Pin): -//|"""Use the AnalogOut on the given pin. +//| dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 +//| dac.value = 32768 # makes PA02 1.65V""" +//| +//| def __init__(self, pin: microcontroller.Pin): +//| """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""" -//|... STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // check arguments mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -69,9 +71,10 @@ STATIC mp_obj_t analogio_analogout_make_new(const mp_obj_type_t *type, mp_uint_t return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Turn off the AnalogOut and release the pin for other use.""" -//|... +//| def deinit(self, ) -> Any: +//| """Turn off the AnalogOut and release the pin for other use.""" +//| ... +//| STATIC mp_obj_t analogio_analogout_deinit(mp_obj_t self_in) { analogio_analogout_obj_t *self = self_in; @@ -81,15 +84,17 @@ STATIC mp_obj_t analogio_analogout_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogout_deinit_obj, analogio_analogout_deinit); -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_analogio_analogout_deinit(args[0]); @@ -97,12 +102,12 @@ STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogout___exit___obj, 4, 4, analogio_analogout___exit__); -//|value: Any = -//|"""The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only) +//| value: Any = ... +//| """The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only) +//| +//| Even if the underlying digital to analog converter (DAC) is lower +//| resolution, the value is 16-bit.""" //| -//|Even if the underlying digital to analog converter (DAC) is lower -//|resolution, the value is 16-bit.""" -//|... STATIC mp_obj_t analogio_analogout_obj_set_value(mp_obj_t self_in, mp_obj_t value) { analogio_analogout_obj_t *self = MP_OBJ_TO_PTR(self_in); if (common_hal_analogio_analogout_deinited(self)) { diff --git a/shared-bindings/analogio/__init__.c b/shared-bindings/analogio/__init__.c index b468bcde0..79627f16a 100644 --- a/shared-bindings/analogio/__init__.c +++ b/shared-bindings/analogio/__init__.c @@ -34,7 +34,7 @@ #include "shared-bindings/analogio/AnalogIn.h" #include "shared-bindings/analogio/AnalogOut.h" -//| :mod:`analogio` --- Analog hardware support +//| """:mod:`analogio` --- Analog hardware support //| ================================================= //| //| .. module:: analogio @@ -70,7 +70,7 @@ //| This example will initialize the the device, read //| :py:data:`~analogio.AnalogIn.value` and then //| :py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional -//| because CircuitPython will do it automatically after the program finishes. +//| because CircuitPython will do it automatically after the program finishes.""" //| STATIC const mp_rom_map_elem_t analogio_module_globals_table[] = { diff --git a/shared-bindings/audiobusio/I2SOut.c b/shared-bindings/audiobusio/I2SOut.c index 765e0a12d..724a65a34 100644 --- a/shared-bindings/audiobusio/I2SOut.c +++ b/shared-bindings/audiobusio/I2SOut.c @@ -35,64 +35,66 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class I2SOut: -//|""".. currentmodule:: audiobusio +//| class I2SOut: +//| """.. currentmodule:: audiobusio //| -//|:class:`I2SOut` -- Output an I2S audio signal -//|======================================================== +//| :class:`I2SOut` -- Output an I2S audio signal +//| ======================================================== //| -//|I2S is used to output an audio signal on an I2S bus.""" -//|def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): -//|"""Create a I2SOut object associated with the given pins. +//| I2S is used to output an audio signal on an I2S bus.""" //| -//|: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 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. +//| def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): +//| """Create a I2SOut object associated with the given pins. //| -//|Simple 8ksps 440 Hz sine wave on `Metro M0 Express `_ -//|using `UDA1334 Breakout `_:: +//| :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 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. //| -//|import audiobusio -//|import audiocore -//|import board -//|import array -//|import time -//|import math +//| Simple 8ksps 440 Hz sine wave on `Metro M0 Express `_ +//| using `UDA1334 Breakout `_:: //| -//|# 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 / 18) * (2 ** 15) + 2 ** 15) +//| import audiobusio +//| import audiocore +//| import board +//| import array +//| import time +//| import math //| -//|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() +//| # 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 / 18) * (2 ** 15) + 2 ** 15) //| -//|Playing a wave file from flash:: +//| 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() //| -//|import board -//|import audioio -//|import audiocore -//|import audiobusio -//|import digitalio +//| Playing a wave file from flash:: //| +//| import board +//| import audioio +//| 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) +//| 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")""" +//| ... //| -//|print("playing") -//|a.play(wav) -//|while a.playing: -//|pass -//|print("stopped")""" -//|... STATIC mp_obj_t audiobusio_i2sout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_bit_clock, ARG_word_select, ARG_data, ARG_left_justified }; static const mp_arg_t allowed_args[] = { @@ -115,9 +117,10 @@ STATIC mp_obj_t audiobusio_i2sout_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the I2SOut and releases any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the I2SOut and releases any hardware resources for reuse.""" +//| ... +//| STATIC mp_obj_t audiobusio_i2sout_deinit(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiobusio_i2sout_deinit(self); @@ -130,15 +133,17 @@ STATIC void check_for_deinit(audiobusio_i2sout_obj_t *self) { raise_deinited_error(); } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t audiobusio_i2sout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiobusio_i2sout_deinit(args[0]); @@ -147,14 +152,15 @@ STATIC mp_obj_t audiobusio_i2sout_obj___exit__(size_t n_args, const mp_obj_t *ar STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_i2sout___exit___obj, 4, 4, audiobusio_i2sout_obj___exit__); -//|def play(self, sample: Any, *, loop: Any = False) -> Any: -//|"""Plays the sample once when loop=False and continuously when loop=True. -//|Does not block. Use `playing` to block. +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """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`, or `audiomixer.Mixer`. //| -//|Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. +//| The sample itself should consist of 8 bit or 16 bit samples.""" +//| ... //| -//|The sample itself should consist of 8 bit or 16 bit samples.""" -//|... STATIC mp_obj_t audiobusio_i2sout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -173,9 +179,10 @@ STATIC mp_obj_t audiobusio_i2sout_obj_play(size_t n_args, const mp_obj_t *pos_ar } MP_DEFINE_CONST_FUN_OBJ_KW(audiobusio_i2sout_play_obj, 1, audiobusio_i2sout_obj_play); -//|def stop(self, ) -> Any: -//|"""Stops playback.""" -//|... +//| def stop(self, ) -> Any: +//| """Stops playback.""" +//| ... +//| STATIC mp_obj_t audiobusio_i2sout_obj_stop(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -184,9 +191,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_stop_obj, audiobusio_i2sout_obj_stop); -//|playing: Any = -//|"""True when the audio sample is being output. (read-only)""" -//|... +//| playing: Any = ... +//| """True when the audio sample is being output. (read-only)""" +//| STATIC mp_obj_t audiobusio_i2sout_obj_get_playing(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -201,9 +208,10 @@ const mp_obj_property_t audiobusio_i2sout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|def pause(self, ) -> Any: -//|"""Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" -//|... +//| def pause(self, ) -> Any: +//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//| ... +//| STATIC mp_obj_t audiobusio_i2sout_obj_pause(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -216,9 +224,10 @@ STATIC mp_obj_t audiobusio_i2sout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_pause_obj, audiobusio_i2sout_obj_pause); -//|def resume(self, ) -> Any: -//|"""Resumes sample playback after :py:func:`pause`.""" -//|... +//| def resume(self, ) -> Any: +//| """Resumes sample playback after :py:func:`pause`.""" +//| ... +//| STATIC mp_obj_t audiobusio_i2sout_obj_resume(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -231,9 +240,9 @@ STATIC mp_obj_t audiobusio_i2sout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiobusio_i2sout_resume_obj, audiobusio_i2sout_obj_resume); -//|paused: Any = -//|"""True when playback is paused. (read-only)""" -//|... +//| paused: Any = ... +//| """True when playback is paused. (read-only)""" +//| STATIC mp_obj_t audiobusio_i2sout_obj_get_paused(mp_obj_t self_in) { audiobusio_i2sout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 28ff9a481..6cc834724 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -36,57 +36,58 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class PDMIn: -//|""".. currentmodule:: audiobusio -//| -//|:class:`PDMIn` -- Record an input PDM audio stream -//|======================================================== -//| -//|PDMIn can be used to record an input audio signal on a given set of pins.""" -//| -//|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): -//|"""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.""" -//|... - -//|Record 8-bit unsigned samples to 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)) -//| -//|Record 16-bit unsigned samples to buffer:: -//| -//|import audiobusio -//|import board -//| -//|# 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)) -//| +//| class PDMIn: +//| """.. currentmodule:: audiobusio +//| +//| :class:`PDMIn` -- Record an input PDM audio stream +//| ======================================================== +//| +//| PDMIn can be used to record an input audio signal on a given set of pins.""" +//| +//| 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): +//| """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.""" +//| + +//| """Record 8-bit unsigned samples to 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)) +//| +//| Record 16-bit unsigned samples to buffer:: +//| +//| import audiobusio +//| import board +//| +//| # 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))""" +//| ... +//| STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_clock_pin, ARG_data_pin, ARG_sample_rate, ARG_bit_depth, ARG_mono, ARG_oversample, ARG_startup_delay }; static const mp_arg_t allowed_args[] = { @@ -138,9 +139,10 @@ STATIC mp_obj_t audiobusio_pdmin_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the PDMIn and releases any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the PDMIn and releases any hardware resources for reuse.""" +//| ... +//| STATIC mp_obj_t audiobusio_pdmin_deinit(mp_obj_t self_in) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiobusio_pdmin_deinit(self); @@ -153,14 +155,16 @@ STATIC void check_for_deinit(audiobusio_pdmin_obj_t *self) { raise_deinited_error(); } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context.""" +//| ... +//| STATIC mp_obj_t audiobusio_pdmin_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiobusio_pdmin_deinit(args[0]); @@ -169,17 +173,18 @@ STATIC mp_obj_t audiobusio_pdmin_obj___exit__(size_t n_args, const mp_obj_t *arg STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiobusio_pdmin___exit___obj, 4, 4, audiobusio_pdmin_obj___exit__); -//|def record(self, destination: Any, destination_length: Any) -> Any: -//|"""Records destination_length bytes of samples to destination. This is -//|blocking. +//| def record(self, destination: Any, destination_length: Any) -> Any: +//| """Records destination_length bytes of samples to destination. This is +//| blocking. //| -//|An IOError 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. +//| An IOError 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.""" +//| ... //| -//|:return: The number of samples recorded. If this is less than ``destination_length``, -//|some samples were missed due to processing time.""" -//|... STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destination, mp_obj_t destination_length) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_obj); check_for_deinit(self); @@ -210,10 +215,10 @@ STATIC mp_obj_t audiobusio_pdmin_obj_record(mp_obj_t self_obj, mp_obj_t destinat } MP_DEFINE_CONST_FUN_OBJ_3(audiobusio_pdmin_record_obj, audiobusio_pdmin_obj_record); -//|sample_rate: Any = -//|"""The actual sample_rate of the recording. This may not match the constructed -//|sample rate due to internal clock limitations.""" -//|... +//| sample_rate: Any = ... +//| """The actual sample_rate of the recording. This may not match the constructed +//| sample rate due to internal clock limitations.""" +//| STATIC mp_obj_t audiobusio_pdmin_obj_get_sample_rate(mp_obj_t self_in) { audiobusio_pdmin_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiobusio/__init__.c b/shared-bindings/audiobusio/__init__.c index f7e3a0766..c5c387361 100644 --- a/shared-bindings/audiobusio/__init__.c +++ b/shared-bindings/audiobusio/__init__.c @@ -34,7 +34,7 @@ #include "shared-bindings/audiobusio/I2SOut.h" #include "shared-bindings/audiobusio/PDMIn.h" -//| :mod:`audiobusio` --- Support for audio input and output over digital bus +//| """:mod:`audiobusio` --- Support for audio input and output over digital bus //| ========================================================================= //| //| .. module:: audiobusio @@ -56,7 +56,7 @@ //| //| All libraries 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. +//| context manager.""" //| STATIC const mp_rom_map_elem_t audiobusio_module_globals_table[] = { diff --git a/shared-bindings/audiocore/RawSample.c b/shared-bindings/audiocore/RawSample.c index fdedfe959..6091fbfc0 100644 --- a/shared-bindings/audiocore/RawSample.c +++ b/shared-bindings/audiocore/RawSample.c @@ -35,45 +35,52 @@ #include "shared-bindings/audiocore/RawSample.h" #include "supervisor/shared/translate.h" -//|class RawSample: -//|""".. currentmodule:: audiocore + + + + + + +//| class RawSample: +//| """.. currentmodule:: audiocore //| -//|:class:`RawSample` -- A raw audio sample buffer -//|======================================================== +//| :class:`RawSample` -- A raw audio sample buffer +//| ======================================================== //| -//|An in-memory sound sample""" +//| An in-memory sound sample""" //| -//|def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): -//|"""Create a RawSample based on the given buffer of signed values. If channel_count is more than -//|1 then each channel's samples should alternate. In other words, for a two channel buffer, the -//|first sample will be for channel 1, the second sample will be for channel two, the third for -//|channel 1 and so on. +//| def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): +//| """Create a RawSample based on the given buffer of signed values. If channel_count is more than +//| 1 then each channel's samples should alternate. In other words, for a two channel buffer, the +//| first sample will be for channel 1, the second sample will be for channel two, the third for +//| channel 1 and so on. //| -//|:param array.array buffer: An `array.array` with samples -//|:param int channel_count: The number of channels in the buffer -//|:param int sample_rate: The desired playback sample rate +//| :param array.array buffer: An `array.array` with samples +//| :param int channel_count: The number of channels in the buffer +//| :param int sample_rate: The desired playback sample rate //| -//|Simple 8ksps 440 Hz sin wave:: +//| Simple 8ksps 440 Hz sin wave:: //| -//|import audiocore -//|import audioio -//|import board -//|import array -//|import time -//|import math +//| import audiocore +//| import audioio +//| import board +//| import array +//| import time +//| import math //| -//|# Generate one period of sine wav. -//|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 / 18) * (2 ** 15)) +//| # Generate one period of sine wav. +//| 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 / 18) * (2 ** 15)) +//| +//| dac = audioio.AudioOut(board.SPEAKER) +//| sine_wave = audiocore.RawSample(sine_wave) +//| dac.play(sine_wave, loop=True) +//| time.sleep(1) +//| dac.stop()""" +//| ... //| -//|dac = audioio.AudioOut(board.SPEAKER) -//|sine_wave = audiocore.RawSample(sine_wave) -//|dac.play(sine_wave, loop=True) -//|time.sleep(1) -//|dac.stop()""" -//|... STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_channel_count, ARG_sample_rate }; static const mp_arg_t allowed_args[] = { @@ -105,9 +112,10 @@ STATIC mp_obj_t audioio_rawsample_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the AudioOut and releases any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the AudioOut and releases any hardware resources for reuse.""" +//| ... +//| STATIC mp_obj_t audioio_rawsample_deinit(mp_obj_t self_in) { audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_rawsample_deinit(self); @@ -121,15 +129,17 @@ STATIC void check_for_deinit(audioio_rawsample_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_rawsample_deinit(args[0]); @@ -137,12 +147,12 @@ STATIC mp_obj_t audioio_rawsample_obj___exit__(size_t n_args, const mp_obj_t *ar } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_rawsample___exit___obj, 4, 4, audioio_rawsample_obj___exit__); -//|sample_rate: Any = -//|"""32 bit value that dictates how quickly samples are played in Hertz (cycles per second). -//|When the sample is looped, this can change the pitch output without changing the underlying -//|sample. This will not change the sample rate of any active playback. Call ``play`` again to -//|change it.""" -//|... +//| sample_rate: Any = ... +//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second). +//| When the sample is looped, this can change the pitch output without changing the underlying +//| sample. This will not change the sample rate of any active playback. Call ``play`` again to +//| change it.""" +//| STATIC mp_obj_t audioio_rawsample_obj_get_sample_rate(mp_obj_t self_in) { audioio_rawsample_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiocore/WaveFile.c b/shared-bindings/audiocore/WaveFile.c index 9116e71f0..65b42fb6c 100644 --- a/shared-bindings/audiocore/WaveFile.c +++ b/shared-bindings/audiocore/WaveFile.c @@ -33,43 +33,45 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class WaveFile: -//|""".. currentmodule:: audiocore +//| class WaveFile: +//| """.. currentmodule:: audiocore //| -//|:class:`WaveFile` -- Load a wave file for audio playback -//|======================================================== +//| :class:`WaveFile` -- Load a wave file for audio playback +//| ======================================================== //| -//|A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must -//|be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating -//|an internal buffer.""" -//|def __init__(self, file: typing.BinaryIO, buffer: bytearray): -//|"""Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. +//| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must +//| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating +//| an internal buffer.""" //| -//|:param typing.BinaryIO file: Already opened wave file -//|:param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally. +//| def __init__(self, file: typing.BinaryIO, buffer: bytearray): +//| """Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| +//| :param typing.BinaryIO file: Already opened wave file +//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two 512 byte buffers are allocated internally. //| -//|Playing a wave file from flash:: //| -//|import board -//|import audiocore -//|import audioio -//|import digitalio +//| Playing a wave file from flash:: //| -//|# Required for CircuitPlayground Express -//|speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//|speaker_enable.switch_to_output(value=True) +//| import board +//| import audiocore +//| import audioio +//| import digitalio //| -//|data = open("cplay-5.1-16bit-16khz.wav", "rb") -//|wav = audiocore.WaveFile(data) -//|a = audioio.AudioOut(board.A0) +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) +//| +//| data = open("cplay-5.1-16bit-16khz.wav", "rb") +//| wav = audiocore.WaveFile(data) +//| a = audioio.AudioOut(board.A0) +//| +//| print("playing") +//| a.play(wav) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... //| -//|print("playing") -//|a.play(wav) -//|while a.playing: -//|pass -//|print("stopped")""" -//|... STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 2, false); @@ -92,9 +94,9 @@ STATIC mp_obj_t audioio_wavefile_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the WaveFile and releases all memory resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the WaveFile and releases all memory resources for reuse.""" +//| ... STATIC mp_obj_t audioio_wavefile_deinit(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_wavefile_deinit(self); @@ -108,15 +110,17 @@ STATIC void check_for_deinit(audioio_wavefile_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_wavefile_deinit(args[0]); @@ -124,11 +128,11 @@ STATIC mp_obj_t audioio_wavefile_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_wavefile___exit___obj, 4, 4, audioio_wavefile_obj___exit__); -//|sample_rate: Any = -//|"""32 bit value that dictates how quickly samples are loaded into the DAC -//|in Hertz (cycles per second). When the sample is looped, this can change -//|the pitch output without changing the underlying sample.""" -//|... +//| sample_rate: Any = ... +//| """32 bit value that dictates how quickly samples are loaded into the DAC +//| in Hertz (cycles per second). When the sample is looped, this can change +//| the pitch output without changing the underlying sample.""" +//| STATIC mp_obj_t audioio_wavefile_obj_get_sample_rate(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -151,9 +155,9 @@ const mp_obj_property_t audioio_wavefile_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|bits_per_sample: Any = -//|"""Bits per sample. (read only)""" -//|... +//| bits_per_sample: Any = ... +//| """Bits per sample. (read only)""" +//| STATIC mp_obj_t audioio_wavefile_obj_get_bits_per_sample(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -167,10 +171,9 @@ const mp_obj_property_t audioio_wavefile_bits_per_sample_obj = { (mp_obj_t)&mp_const_none_obj, (mp_obj_t)&mp_const_none_obj}, }; - -//|channel_count: Any = -//|"""Number of audio channels. (read only)""" -//|... +//| channel_count: Any = ... +//| """Number of audio channels. (read only)""" +//| STATIC mp_obj_t audioio_wavefile_obj_get_channel_count(mp_obj_t self_in) { audioio_wavefile_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiocore/__init__.c b/shared-bindings/audiocore/__init__.c index cf05112cb..38f91d8ee 100644 --- a/shared-bindings/audiocore/__init__.c +++ b/shared-bindings/audiocore/__init__.c @@ -35,7 +35,7 @@ #include "shared-bindings/audiocore/WaveFile.h" //#include "shared-bindings/audiomixer/Mixer.h" -//| :mod:`audiocore` --- Support for audio samples and mixer +//| """:mod:`audiocore` --- Support for audio samples and mixer //| ======================================================== //| //| .. module:: audiocore @@ -50,7 +50,7 @@ //| :maxdepth: 3 //| //| RawSample -//| WaveFile +//| WaveFile""" //| STATIC const mp_rom_map_elem_t audiocore_module_globals_table[] = { -- cgit v1.2.3 From d65e85104431b354737d11b5ec9a29387d390cfd Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 30 Apr 2020 13:06:09 -0400 Subject: Did audioio, audiomixer, audiomp3 --- shared-bindings/audioio/AudioOut.c | 164 +++++++++++++++++--------------- shared-bindings/audioio/__init__.c | 4 +- shared-bindings/audiomixer/Mixer.c | 139 ++++++++++++++------------- shared-bindings/audiomixer/MixerVoice.c | 48 +++++----- shared-bindings/audiomixer/__init__.c | 4 +- shared-bindings/audiomp3/MP3Decoder.c | 111 ++++++++++----------- shared-bindings/audiomp3/__init__.c | 4 +- 7 files changed, 247 insertions(+), 227 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c index 28c345d16..84e5e4422 100644 --- a/shared-bindings/audioio/AudioOut.c +++ b/shared-bindings/audioio/AudioOut.c @@ -36,64 +36,65 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class AudioOut: -//|""".. currentmodule:: audioio +//| class AudioOut: +//| """.. currentmodule:: audioio //| -//|:class:`AudioOut` -- Output an analog audio signal -//|======================================================== +//| :class:`AudioOut` -- Output an analog audio signal +//| ======================================================== //| -//|AudioOut can be used to output an analog audio signal on a given pin.""" +//| AudioOut can be used to output an analog audio signal on a given pin.""" //| -//|def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): -//|"""Create a AudioOut object associated with the given pin(s). This allows you to -//|play audio signals out on the given pin(s). +//| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): +//| """Create a AudioOut object associated with the given pin(s). This allows you to +//| play audio signals out on the given pin(s). //| -//|:param ~microcontroller.Pin left_channel: The pin to output the left channel to -//|:param ~microcontroller.Pin right_channel: The pin to output the right channel to -//|:param int quiescent_value: The output value when no signal is present. Samples should start -//|and end with this value to prevent audible popping. +//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to +//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to +//| :param int quiescent_value: The output value when no signal is present. Samples should start +//| and end with this value to prevent audible popping. //| -//|Simple 8ksps 440 Hz sin wave:: +//| Simple 8ksps 440 Hz sin wave:: //| -//|import audiocore -//|import audioio -//|import board -//|import array -//|import time -//|import math +//| import audiocore +//| import audioio +//| import board +//| import array +//| import time +//| import math //| -//|# Generate one period of sine wav. -//|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 / 18) * (2 ** 15) + 2 ** 15) +//| # Generate one period of sine wav. +//| 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 / 18) * (2 ** 15) + 2 ** 15) //| -//|dac = audioio.AudioOut(board.SPEAKER) -//|sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) -//|dac.play(sine_wave, loop=True) -//|time.sleep(1) -//|dac.stop() +//| dac = audioio.AudioOut(board.SPEAKER) +//| sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) +//| dac.play(sine_wave, loop=True) +//| time.sleep(1) +//| dac.stop() //| -//|Playing a wave file from flash:: +//| Playing a wave file from flash:: //| -//|import board -//|import audioio -//|import digitalio +//| import board +//| import audioio +//| import digitalio //| -//|# Required for CircuitPlayground Express -//|speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//|speaker_enable.switch_to_output(value=True) +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) //| -//|data = open("cplay-5.1-16bit-16khz.wav", "rb") -//|wav = audiocore.WaveFile(data) -//|a = audioio.AudioOut(board.A0) +//| data = open("cplay-5.1-16bit-16khz.wav", "rb") +//| wav = audiocore.WaveFile(data) +//| a = audioio.AudioOut(board.A0) +//| +//| print("playing") +//| a.play(wav) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... //| -//|print("playing") -//|a.play(wav) -//|while a.playing: -//|pass -//|print("stopped")""" -//|... STATIC mp_obj_t audioio_audioout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_left_channel, ARG_right_channel, ARG_quiescent_value }; static const mp_arg_t allowed_args[] = { @@ -115,9 +116,10 @@ STATIC mp_obj_t audioio_audioout_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the AudioOut and releases any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the AudioOut and releases any hardware resources for reuse.""" +//| ... +//| STATIC mp_obj_t audioio_audioout_deinit(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audioio_audioout_deinit(self); @@ -130,15 +132,17 @@ STATIC void check_for_deinit(audioio_audioout_obj_t *self) { raise_deinited_error(); } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audioio_audioout_deinit(args[0]); @@ -147,16 +151,17 @@ STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *arg STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audioio_audioout___exit___obj, 4, 4, audioio_audioout_obj___exit__); -//|def play(self, sample: Any, *, loop: Any = False) -> Any: -//|"""Plays the sample once when loop=False and continuously when loop=True. -//|Does not block. Use `playing` to block. +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """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`, or `audiomixer.Mixer`. //| -//|Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. +//| The sample itself should consist of 16 bit samples. Microcontrollers with a lower output +//| resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit +//| DAC that ignores the lowest 6 bits when playing 16 bit samples.""" +//| ... //| -//|The sample itself should consist of 16 bit samples. Microcontrollers with a lower output -//|resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit -//|DAC that ignores the lowest 6 bits when playing 16 bit samples.""" -//|... STATIC mp_obj_t audioio_audioout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -175,9 +180,10 @@ STATIC mp_obj_t audioio_audioout_obj_play(size_t n_args, const mp_obj_t *pos_arg } MP_DEFINE_CONST_FUN_OBJ_KW(audioio_audioout_play_obj, 1, audioio_audioout_obj_play); -//|def stop(self, ) -> Any: -//|"""Stops playback and resets to the start of the sample.""" -//|... +//| def stop(self, ) -> Any: +//| """Stops playback and resets to the start of the sample.""" +//| ... +//| STATIC mp_obj_t audioio_audioout_obj_stop(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -186,9 +192,9 @@ STATIC mp_obj_t audioio_audioout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_stop_obj, audioio_audioout_obj_stop); -//|playing: Any = -//|"""True when an audio sample is being output even if `paused`. (read-only)""" -//|... +//| playing: Any = ... +//| """True when an audio sample is being output even if `paused`. (read-only)""" +//| STATIC mp_obj_t audioio_audioout_obj_get_playing(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -203,9 +209,10 @@ const mp_obj_property_t audioio_audioout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|def pause(self, ) -> Any: -//|"""Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" -//|... +//| def pause(self, ) -> Any: +//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//| ... +//| STATIC mp_obj_t audioio_audioout_obj_pause(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -218,9 +225,10 @@ STATIC mp_obj_t audioio_audioout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_pause_obj, audioio_audioout_obj_pause); -//|def resume(self, ) -> Any: -//|"""Resumes sample playback after :py:func:`pause`.""" -//|... +//| def resume(self, ) -> Any: +//| """Resumes sample playback after :py:func:`pause`.""" +//| ... +//| STATIC mp_obj_t audioio_audioout_obj_resume(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -233,9 +241,9 @@ STATIC mp_obj_t audioio_audioout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_resume_obj, audioio_audioout_obj_resume); -//|paused: Any = -//|"""True when playback is paused. (read-only)""" -//|... +//| paused: Any = ... +//| """True when playback is paused. (read-only)""" +//| STATIC mp_obj_t audioio_audioout_obj_get_paused(mp_obj_t self_in) { audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audioio/__init__.c b/shared-bindings/audioio/__init__.c index 02a5fe1ee..bc2e26cfc 100644 --- a/shared-bindings/audioio/__init__.c +++ b/shared-bindings/audioio/__init__.c @@ -42,7 +42,7 @@ #include "shared-bindings/audiomixer/Mixer.h" #endif -//| :mod:`audioio` --- Support for audio input and output +//| """:mod:`audioio` --- Support for audio input and output //| ====================================================== //| //| .. module:: audioio @@ -68,7 +68,7 @@ //| //| For compatibility with CircuitPython 4.x, some builds allow the items in //| `audiocore` to be imported from `audioio`. This will be removed for all -//| boards in a future build of CircuitPython. +//| boards in a future build of CircuitPython.""" //| STATIC const mp_rom_map_elem_t audioio_module_globals_table[] = { diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c index 93b1d3635..966581d45 100644 --- a/shared-bindings/audiomixer/Mixer.c +++ b/shared-bindings/audiomixer/Mixer.c @@ -38,50 +38,51 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class Mixer: -//|""".. currentmodule:: audiomixer +//| class Mixer: +//| """.. currentmodule:: audiomixer //| -//|:class:`Mixer` -- Mixes one or more audio samples together -//|=========================================================== +//| :class:`Mixer` -- Mixes one or more audio samples together +//| =========================================================== //| -//|Mixer mixes multiple samples into one sample.""" +//| Mixer mixes multiple samples into one sample.""" //| -//|def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): -//|"""Create a Mixer object that can mix multiple channels with the same sample rate. -//|Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects. +//| def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): +//| """Create a Mixer object that can mix multiple channels with the same sample rate. +//| Samples are accessed and controlled with the mixer's `audiomixer.MixerVoice` objects. //| -//|:param int voice_count: The maximum number of voices to mix -//|:param int buffer_size: The total size in bytes of the buffers to mix into -//|:param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo. -//|:param int bits_per_sample: The bits per sample of the samples being played -//|:param bool samples_signed: Samples are signed (True) or unsigned (False) -//|:param int sample_rate: The sample rate to be used for all samples +//| :param int voice_count: The maximum number of voices to mix +//| :param int buffer_size: The total size in bytes of the buffers to mix into +//| :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo. +//| :param int bits_per_sample: The bits per sample of the samples being played +//| :param bool samples_signed: Samples are signed (True) or unsigned (False) +//| :param int sample_rate: The sample rate to be used for all samples //| -//|Playing a wave file from flash:: +//| Playing a wave file from flash:: //| -//|import board -//|import audioio -//|import audiocore -//|import audiomixer -//|import digitalio +//| import board +//| import audioio +//| import audiocore +//| import audiomixer +//| import digitalio //| -//|a = audioio.AudioOut(board.A0) -//|music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb")) -//|drum = audiocore.WaveFile(open("drum.wav", "rb")) -//|mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1, -//|bits_per_sample=16, samples_signed=True) +//| a = audioio.AudioOut(board.A0) +//| music = audiocore.WaveFile(open("cplay-5.1-16bit-16khz.wav", "rb")) +//| drum = audiocore.WaveFile(open("drum.wav", "rb")) +//| mixer = audiomixer.Mixer(voice_count=2, sample_rate=16000, channel_count=1, +//| bits_per_sample=16, samples_signed=True) +//| +//| print("playing") +//| # Have AudioOut play our Mixer source +//| a.play(mixer) +//| # Play the first sample voice +//| mixer.voice[0].play(music) +//| while mixer.playing: +//| # Play the second sample voice +//| mixer.voice[1].play(drum) +//| time.sleep(1) +//| print("stopped")""" +//| ... //| -//|print("playing") -//|# Have AudioOut play our Mixer source -//|a.play(mixer) -//|# Play the first sample voice -//|mixer.voice[0].play(music) -//|while mixer.playing: -//|# Play the second sample voice -//|mixer.voice[1].play(drum) -//|time.sleep(1) -//|print("stopped")""" -//|... STATIC mp_obj_t audiomixer_mixer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice_count, ARG_buffer_size, ARG_channel_count, ARG_bits_per_sample, ARG_samples_signed, ARG_sample_rate }; static const mp_arg_t allowed_args[] = { @@ -125,9 +126,10 @@ STATIC mp_obj_t audiomixer_mixer_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the Mixer and releases any hardware resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the Mixer and releases any hardware resources for reuse.""" +//| ... +//| STATIC mp_obj_t audiomixer_mixer_deinit(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiomixer_mixer_deinit(self); @@ -141,15 +143,17 @@ STATIC void check_for_deinit(audiomixer_mixer_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t audiomixer_mixer_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiomixer_mixer_deinit(args[0]); @@ -157,9 +161,9 @@ STATIC mp_obj_t audiomixer_mixer_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiomixer_mixer___exit___obj, 4, 4, audiomixer_mixer_obj___exit__); -//|playing: Any = -//|"""True when any voice is being output. (read-only)""" -//|... +//| playing: Any = ... +//| """True when any voice is being output. (read-only)""" +//| STATIC mp_obj_t audiomixer_mixer_obj_get_playing(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -174,9 +178,9 @@ const mp_obj_property_t audiomixer_mixer_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|sample_rate: Any = -//|"""32 bit value that dictates how quickly samples are played in Hertz (cycles per second).""" -//|... +//| sample_rate: Any = ... +//| """32 bit value that dictates how quickly samples are played in Hertz (cycles per second).""" +//| STATIC mp_obj_t audiomixer_mixer_obj_get_sample_rate(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -191,14 +195,13 @@ const mp_obj_property_t audiomixer_mixer_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|voice: Any = -//|"""A tuple of the mixer's `audiomixer.MixerVoice` object(s). +//| voice: Any = ... +//| """A tuple of the mixer's `audiomixer.MixerVoice` object(s). //| -//|.. code-block:: python +//| .. code-block:: python //| -//|>>> mixer.voice -//|(,)""" -//|... +//| >>> mixer.voice +//| (,)""" STATIC mp_obj_t audiomixer_mixer_obj_get_voice(mp_obj_t self_in) { audiomixer_mixer_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -213,14 +216,15 @@ const mp_obj_property_t audiomixer_mixer_voice_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|def play(self, sample: Any, *, voice: Any = 0, loop: Any = False) -> Any: -//|"""Plays the sample once when loop=False and continuously when loop=True. -//|Does not block. Use `playing` to block. +//| def play(self, sample: Any, *, voice: Any = 0, loop: Any = False) -> Any: +//| """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`, or `audiomixer.Mixer`. +//| Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. +//| +//| The sample must match the Mixer's encoding settings given in the constructor.""" +//| ... //| -//|The sample must match the Mixer's encoding settings given in the constructor.""" -//|... STATIC mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_voice, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -245,9 +249,10 @@ STATIC mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_arg } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixer_play_obj, 1, audiomixer_mixer_obj_play); -//|def stop_voice(self, voice: Any = 0) -> Any: -//|"""Stops playback of the sample on the given voice.""" -//|... +//| def stop_voice(self, voice: Any = 0) -> Any: +//| """Stops playback of the sample on the given voice.""" +//| ... +//| STATIC mp_obj_t audiomixer_mixer_obj_stop_voice(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/audiomixer/MixerVoice.c b/shared-bindings/audiomixer/MixerVoice.c index 299600dd1..257d9507b 100644 --- a/shared-bindings/audiomixer/MixerVoice.c +++ b/shared-bindings/audiomixer/MixerVoice.c @@ -37,18 +37,18 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class MixerVoice: -//|""".. currentmodule:: audiomixer +//| class MixerVoice: +//| """.. currentmodule:: audiomixer //| -//|:class:`MixerVoice` -- Voice objects used with Mixer -//|===================================================== +//| :class:`MixerVoice` -- Voice objects used with Mixer +//| ===================================================== //| -//|Used to access and control samples with `audiomixer.Mixer`.""" +//| Used to access and control samples with `audiomixer.Mixer`.""" //| -//|def __init__(self, ): +//| def __init__(self, ): +//| """MixerVoice instance object(s) created by `audiomixer.Mixer`.""" +//| ... //| -//|"""MixerVoice instance object(s) created by `audiomixer.Mixer`.""" -//|... // TODO: support mono or stereo voices STATIC mp_obj_t audiomixer_mixervoice_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { audiomixer_mixervoice_obj_t *self = m_new_obj(audiomixer_mixervoice_obj_t); @@ -59,14 +59,15 @@ STATIC mp_obj_t audiomixer_mixervoice_make_new(const mp_obj_type_t *type, size_t return MP_OBJ_FROM_PTR(self); } -//|def play(self, sample: Any, *, loop: Any = False) -> Any: -//|"""Plays the sample once when ``loop=False``, and continuously when ``loop=True``. -//|Does not block. Use `playing` to block. +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """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`, `audiomixer.Mixer` or `audiocore.RawSample`. +//| Sample must be an `audiocore.WaveFile`, `audiomixer.Mixer` or `audiocore.RawSample`. +//| +//| The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor.""" +//| ... //| -//|The sample must match the `audiomixer.Mixer`'s encoding settings given in the constructor.""" -//|... STATIC mp_obj_t audiomixer_mixervoice_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; static const mp_arg_t allowed_args[] = { @@ -83,9 +84,10 @@ STATIC mp_obj_t audiomixer_mixervoice_obj_play(size_t n_args, const mp_obj_t *po } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixervoice_play_obj, 1, audiomixer_mixervoice_obj_play); -//|def stop(self, ) -> Any: -//|"""Stops playback of the sample on this voice.""" -//|... +//| def stop(self, ) -> Any: +//| """Stops playback of the sample on this voice.""" +//| ... +//| STATIC mp_obj_t audiomixer_mixervoice_obj_stop(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_voice }; static const mp_arg_t allowed_args[] = { @@ -101,9 +103,9 @@ STATIC mp_obj_t audiomixer_mixervoice_obj_stop(size_t n_args, const mp_obj_t *po } MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixervoice_stop_obj, 1, audiomixer_mixervoice_obj_stop); -//|level(): Any = -//|"""The volume level of a voice, as a floating point number between 0 and 1.""" -//|... +//| level: Any = ... +//| """The volume level of a voice, as a floating point number between 0 and 1.""" +//| STATIC mp_obj_t audiomixer_mixervoice_obj_get_level(mp_obj_t self_in) { return mp_obj_new_float(common_hal_audiomixer_mixervoice_get_level(self_in)); } @@ -137,9 +139,9 @@ const mp_obj_property_t audiomixer_mixervoice_level_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|playing: Any = -//|"""True when this voice is being output. (read-only)""" -//|... +//| playing: Any = ... +//| """True when this voice is being output. (read-only)""" +//| STATIC mp_obj_t audiomixer_mixervoice_obj_get_playing(mp_obj_t self_in) { audiomixer_mixervoice_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/audiomixer/__init__.c b/shared-bindings/audiomixer/__init__.c index 79bab440e..c90a4a0e6 100644 --- a/shared-bindings/audiomixer/__init__.c +++ b/shared-bindings/audiomixer/__init__.c @@ -32,7 +32,7 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/audiomixer/Mixer.h" -//| :mod:`audiomixer` --- Support for audio mixer +//| """:mod:`audiomixer` --- Support for audio mixer //| ======================================================== //| //| .. module:: audiomixer @@ -46,7 +46,7 @@ //| :maxdepth: 3 //| //| Mixer -//| MixerVoice +//| MixerVoice""" //| STATIC const mp_rom_map_elem_t audiomixer_module_globals_table[] = { diff --git a/shared-bindings/audiomp3/MP3Decoder.c b/shared-bindings/audiomp3/MP3Decoder.c index 7c011b65f..d9c85bbf6 100644 --- a/shared-bindings/audiomp3/MP3Decoder.c +++ b/shared-bindings/audiomp3/MP3Decoder.c @@ -34,42 +34,44 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//|class MP3: -//|""".. currentmodule:: audiomp3 +//| class MP3: +//| """.. currentmodule:: audiomp3 //| -//|:class:`MP3Decoder` -- Load a mp3 file for audio playback -//|========================================================= +//| :class:`MP3Decoder` -- Load a mp3 file for audio playback +//| ========================================================= //| -//|An object that decodes MP3 files for playback on an audio device.""" +//| An object that decodes MP3 files for playback on an audio device.""" //| -//|def __init__(self, file: typing.BinaryIO, buffer: bytearray): -//|"""Load a .mp3 file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. +//| def __init__(self, file: typing.BinaryIO, buffer: bytearray): //| -//|:param typing.BinaryIO file: Already opened mp3 file -//|:param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file. +//| """Load a .mp3 file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| +//| :param typing.BinaryIO file: Already opened mp3 file +//| :param bytearray buffer: Optional pre-allocated buffer, that will be split in half and used for double-buffering of the data. If not provided, two buffers are allocated internally. The specific buffer size required depends on the mp3 file. //| -//|Playing a mp3 file from flash:: //| -//|import board -//|import audiomp3 -//|import audioio -//|import digitalio +//| Playing a mp3 file from flash:: //| -//|# Required for CircuitPlayground Express -//|speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//|speaker_enable.switch_to_output(value=True) +//| import board +//| import audiomp3 +//| import audioio +//| import digitalio //| -//|data = open("cplay-16bit-16khz-64kbps.mp3", "rb") -//|mp3 = audiomp3.MP3Decoder(data) -//|a = audioio.AudioOut(board.A0) +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) +//| +//| data = open("cplay-16bit-16khz-64kbps.mp3", "rb") +//| mp3 = audiomp3.MP3Decoder(data) +//| a = audioio.AudioOut(board.A0) +//| +//| print("playing") +//| a.play(mp3) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... //| -//|print("playing") -//|a.play(mp3) -//|while a.playing: -//|pass -//|print("stopped")""" -//|... STATIC mp_obj_t audiomp3_mp3file_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 2, false); @@ -92,9 +94,10 @@ STATIC mp_obj_t audiomp3_mp3file_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//|def deinit(self, ) -> Any: -//|"""Deinitialises the MP3 and releases all memory resources for reuse.""" -//|... +//| def deinit(self, ) -> Any: +//| """Deinitialises the MP3 and releases all memory resources for reuse.""" +//| ... +//| STATIC mp_obj_t audiomp3_mp3file_deinit(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_audiomp3_mp3file_deinit(self); @@ -108,15 +111,17 @@ STATIC void check_for_deinit(audiomp3_mp3file_obj_t *self) { } } -//|def __enter__(self, ) -> Any: -//|"""No-op used by Context Managers.""" -//|... +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... +//| // Provided by context manager helper. -//|def __exit__(self, ) -> Any: -//|"""Automatically deinitializes the hardware when exiting a context. See -//|:ref:`lifetime-and-contextmanagers` for more info.""" -//|... +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... +//| STATIC mp_obj_t audiomp3_mp3file_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiomp3_mp3file_deinit(args[0]); @@ -124,9 +129,9 @@ STATIC mp_obj_t audiomp3_mp3file_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiomp3_mp3file___exit___obj, 4, 4, audiomp3_mp3file_obj___exit__); -//|file: Any = -//|"""File to play back.""" -//|... +//| file: Any = ... +//| """File to play back.""" +//| STATIC mp_obj_t audiomp3_mp3file_obj_get_file(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -154,11 +159,11 @@ const mp_obj_property_t audiomp3_mp3file_file_obj = { -//|sample_rate: Any = -//|"""32 bit value that dictates how quickly samples are loaded into the DAC -//|in Hertz (cycles per second). When the sample is looped, this can change -//|the pitch output without changing the underlying sample.""" -//|... +//| sample_rate: Any = ... +//| """32 bit value that dictates how quickly samples are loaded into the DAC +//| in Hertz (cycles per second). When the sample is looped, this can change +//| the pitch output without changing the underlying sample.""" +//| STATIC mp_obj_t audiomp3_mp3file_obj_get_sample_rate(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -181,9 +186,9 @@ const mp_obj_property_t audiomp3_mp3file_sample_rate_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|bits_per_sample: Any = -//|"""Bits per sample. (read only)""" -//|... +//| bits_per_sample: Any = ... +//| """Bits per sample. (read only)""" +//| STATIC mp_obj_t audiomp3_mp3file_obj_get_bits_per_sample(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -198,9 +203,9 @@ const mp_obj_property_t audiomp3_mp3file_bits_per_sample_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|channel_count: Any = -//|"""Number of audio channels. (read only)""" -//|... +//| channel_count: Any = ... +//| """Number of audio channels. (read only)""" +//| STATIC mp_obj_t audiomp3_mp3file_obj_get_channel_count(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -215,9 +220,9 @@ const mp_obj_property_t audiomp3_mp3file_channel_count_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//|rms_level: Any = -//|"""The RMS audio level of a recently played moment of audio. (read only)""" -//|... +//| rms_level: Any = ... +//| """The RMS audio level of a recently played moment of audio. (read only)""" +//| STATIC mp_obj_t audiomp3_mp3file_obj_get_rms_level(mp_obj_t self_in) { audiomp3_mp3file_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); diff --git a/shared-bindings/audiomp3/__init__.c b/shared-bindings/audiomp3/__init__.c index fb2187669..50b29da52 100644 --- a/shared-bindings/audiomp3/__init__.c +++ b/shared-bindings/audiomp3/__init__.c @@ -31,7 +31,7 @@ #include "shared-bindings/audiomp3/MP3Decoder.h" -//| :mod:`audiomp3` --- Support for MP3-compressed audio files +//| """:mod:`audiomp3` --- Support for MP3-compressed audio files //| ========================================================== //| //| .. module:: audiomp3 @@ -44,7 +44,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| MP3Decoder +//| MP3Decoder""" //| STATIC const mp_rom_map_elem_t audiomp3_module_globals_table[] = { -- cgit v1.2.3 From 0e465e63b98c3825298219e2144a145208aaff7f Mon Sep 17 00:00:00 2001 From: dherrada Date: Fri, 1 May 2020 18:23:27 -0400 Subject: Did audiopwmio, bitbangio, and _bleio --- shared-bindings/_bleio/Adapter.c | 151 +++++++++++---------- shared-bindings/_bleio/Address.c | 71 +++++----- shared-bindings/_bleio/Attribute.c | 58 ++++---- shared-bindings/_bleio/Characteristic.c | 148 ++++++++++---------- shared-bindings/_bleio/CharacteristicBuffer.c | 81 +++++------ shared-bindings/_bleio/Connection.c | 105 +++++++-------- shared-bindings/_bleio/Descriptor.c | 72 +++++----- shared-bindings/_bleio/PacketBuffer.c | 73 +++++----- shared-bindings/_bleio/ScanEntry.c | 54 ++++---- shared-bindings/_bleio/ScanResults.c | 31 ++--- shared-bindings/_bleio/Service.c | 51 ++++--- shared-bindings/_bleio/UUID.c | 67 +++++----- shared-bindings/_bleio/__init__.c | 38 +++--- shared-bindings/audiopwmio/PWMAudioOut.c | 186 +++++++++++++------------- shared-bindings/audiopwmio/__init__.c | 4 +- shared-bindings/bitbangio/I2C.c | 152 ++++++++++----------- shared-bindings/bitbangio/OneWire.c | 80 +++++------ shared-bindings/bitbangio/SPI.c | 127 +++++++++--------- shared-bindings/bitbangio/__init__.c | 4 +- 19 files changed, 758 insertions(+), 795 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c index 921667f0f..6fb5c323d 100644 --- a/shared-bindings/_bleio/Adapter.c +++ b/shared-bindings/_bleio/Adapter.c @@ -47,35 +47,35 @@ #define INTERVAL_MAX_STRING "40.959375" #define WINDOW_DEFAULT (0.1f) -//| .. currentmodule:: _bleio +//| class Adapter: +//| """.. currentmodule:: _bleio //| -//| :class:`Adapter` --- BLE adapter -//| ---------------------------------------------------- +//| :class:`Adapter` --- BLE adapter +//| ---------------------------------------------------- //| -//| The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices. -//| This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP). +//| The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices. +//| This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP). //| -//| Discovery of other devices happens during a scanning process that listens for small packets of -//| information, known as advertisements, that are broadcast unencrypted. The advertising packets -//| have two different uses. The first is to broadcast a small piece of data to anyone who cares and -//| and nothing more. These are known as Beacons. The second class of advertisement is to promote -//| additional functionality available after the devices establish a connection. For example, a -//| BLE keyboard may advertise that it can provide key information, but not what the key info is. +//| Discovery of other devices happens during a scanning process that listens for small packets of +//| information, known as advertisements, that are broadcast unencrypted. The advertising packets +//| have two different uses. The first is to broadcast a small piece of data to anyone who cares and +//| and nothing more. These are known as Beacons. The second class of advertisement is to promote +//| additional functionality available after the devices establish a connection. For example, a +//| BLE keyboard may advertise that it can provide key information, but not what the key info is. //| -//| The built-in BLE adapter can do both parts of this process: it can scan for other device -//| advertisements and it can advertise its own data. Furthermore, Adapters can accept incoming -//| connections and also initiate connections. +//| The built-in BLE adapter can do both parts of this process: it can scan for other device +//| advertisements and it can advertise its own data. Furthermore, Adapters can accept incoming +//| connections and also initiate connections.""" //| -//| .. class:: Adapter() -//| -//| You cannot create an instance of `_bleio.Adapter`. -//| Use `_bleio.adapter` to access the sole instance available. +//| def __init__(self, ): +//| """You cannot create an instance of `_bleio.Adapter`. +//| Use `_bleio.adapter` to access the sole instance available.""" +//| ... //| -//| .. attribute:: enabled -//| -//| State of the BLE adapter. +//| enabled: Any = ... +//| """State of the BLE adapter.""" //| STATIC mp_obj_t bleio_adapter_get_enabled(mp_obj_t self) { return mp_obj_new_bool(common_hal_bleio_adapter_get_enabled(self)); @@ -98,9 +98,8 @@ const mp_obj_property_t bleio_adapter_enabled_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: address -//| -//| MAC address of the BLE adapter. (read-only) +//| address: Any = ... +//| """MAC address of the BLE adapter. (read-only)""" //| STATIC mp_obj_t bleio_adapter_get_address(mp_obj_t self) { return MP_OBJ_FROM_PTR(common_hal_bleio_adapter_get_address(self)); @@ -115,11 +114,10 @@ const mp_obj_property_t bleio_adapter_address_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: name -//| -//| name of the BLE adapter used once connected. -//| The name is "CIRCUITPY" + the last four hex digits of ``adapter.address``, -//| to make it easy to distinguish multiple CircuitPython boards. +//| name: Any = ... +//| """name of the BLE adapter used once connected. +//| The name is "CIRCUITPY" + the last four hex digits of ``adapter.address``, +//| to make it easy to distinguish multiple CircuitPython boards.""" //| STATIC mp_obj_t bleio_adapter_get_name(mp_obj_t self) { return MP_OBJ_FROM_PTR(common_hal_bleio_adapter_get_name(self)); @@ -140,18 +138,18 @@ const mp_obj_property_t bleio_adapter_name_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. method:: start_advertising(data, *, scan_response=None, connectable=True, interval=0.1) -//| -//| Starts advertising until `stop_advertising` is called or if connectable, another device -//| connects to us. +//| def start_advertising(self, data: buf, *, scan_response: buf = None, connectable: bool = True, interval: float = 0.1) -> Any: +//| """Starts advertising until `stop_advertising` is called or if connectable, another device +//| connects to us. //| -//| .. warning: If data is longer than 31 bytes, then this will automatically advertise as an -//| extended advertisement that older BLE 4.x clients won't be able to scan for. +//| .. warning: If data is longer than 31 bytes, then this will automatically advertise as an +//| extended advertisement that older BLE 4.x clients won't be able to scan for. //| -//| :param buf data: advertising data packet bytes -//| :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed. -//| :param bool connectable: If `True` then other devices are allowed to connect to this peripheral. -//| :param float interval: advertising interval, in seconds +//| :param buf data: advertising data packet bytes +//| :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed. +//| :param bool connectable: If `True` then other devices are allowed to connect to this peripheral. +//| :param float interval: advertising interval, in seconds""" +//| ... //| STATIC mp_obj_t bleio_adapter_start_advertising(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -198,9 +196,10 @@ STATIC mp_obj_t bleio_adapter_start_advertising(mp_uint_t n_args, const mp_obj_t } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_adapter_start_advertising_obj, 2, bleio_adapter_start_advertising); -//| .. method:: stop_advertising() +//| def stop_advertising(self, ) -> Any: +//| """Stop sending advertising packets.""" +//| ... //| -//| Stop sending advertising packets. STATIC mp_obj_t bleio_adapter_stop_advertising(mp_obj_t self_in) { bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -210,25 +209,25 @@ STATIC mp_obj_t bleio_adapter_stop_advertising(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_advertising_obj, bleio_adapter_stop_advertising); -//| .. method:: start_scan(prefixes=b"", \*, buffer_size=512, extended=False, timeout=None, interval=0.1, window=0.1, minimum_rssi=-80, active=True) +//| def start_scan(self, prefixes: sequence = b"", *, buffer_size: int = 512, extended: bool = False, timeout: float = None, interval: float = 0.1, window: float = 0.1, minimum_rssi: int = -80, active: bool = True) -> Any: +//| """Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are +//| filtered and returned separately. //| -//| Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are -//| filtered and returned separately. -//| -//| :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets -//| with. A packet without an advertising structure that matches one of the prefixes is -//| ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated. -//| :param int buffer_size: the maximum number of advertising bytes to buffer. -//| :param bool extended: When True, support extended advertising packets. Increasing buffer_size is recommended when this is set. -//| :param float timeout: the scan timeout in seconds. If None, will scan until `stop_scan` is called. -//| :param float interval: the interval (in seconds) between the start of two consecutive scan windows -//| Must be in the range 0.0025 - 40.959375 seconds. -//| :param float window: the duration (in seconds) to scan a single BLE channel. -//| window must be <= interval. -//| :param int minimum_rssi: the minimum rssi of entries to return. -//| :param bool active: retrieve scan responses for scannable advertisements. -//| :returns: an iterable of `_bleio.ScanEntry` objects -//| :rtype: iterable +//| :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets +//| with. A packet without an advertising structure that matches one of the prefixes is +//| ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated. +//| :param int buffer_size: the maximum number of advertising bytes to buffer. +//| :param bool extended: When True, support extended advertising packets. Increasing buffer_size is recommended when this is set. +//| :param float timeout: the scan timeout in seconds. If None, will scan until `stop_scan` is called. +//| :param float interval: the interval (in seconds) between the start of two consecutive scan windows +//| Must be in the range 0.0025 - 40.959375 seconds. +//| :param float window: the duration (in seconds) to scan a single BLE channel. +//| window must be <= interval. +//| :param int minimum_rssi: the minimum rssi of entries to return. +//| :param bool active: retrieve scan responses for scannable advertisements. +//| :returns: an iterable of `_bleio.ScanEntry` objects +//| :rtype: iterable""" +//| ... //| STATIC mp_obj_t bleio_adapter_start_scan(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_prefixes, ARG_buffer_size, ARG_extended, ARG_timeout, ARG_interval, ARG_window, ARG_minimum_rssi, ARG_active }; @@ -283,9 +282,10 @@ STATIC mp_obj_t bleio_adapter_start_scan(size_t n_args, const mp_obj_t *pos_args } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_adapter_start_scan_obj, 1, bleio_adapter_start_scan); -//| .. method:: stop_scan() +//| def stop_scan(self, ) -> Any: +//| """Stop the current scan.""" +//| ... //| -//| Stop the current scan. STATIC mp_obj_t bleio_adapter_stop_scan(mp_obj_t self_in) { bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -295,10 +295,9 @@ STATIC mp_obj_t bleio_adapter_stop_scan(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_scan_obj, bleio_adapter_stop_scan); -//| .. attribute:: connected -//| -//| True when the adapter is connected to another device regardless of who initiated the -//| connection. (read-only) +//| connected: Any = ... +//| """True when the adapter is connected to another device regardless of who initiated the +//| connection. (read-only)""" //| STATIC mp_obj_t bleio_adapter_get_connected(mp_obj_t self) { return mp_obj_new_bool(common_hal_bleio_adapter_get_connected(self)); @@ -313,10 +312,9 @@ const mp_obj_property_t bleio_adapter_connected_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: connections -//| -//| Tuple of active connections including those initiated through -//| :py:meth:`_bleio.Adapter.connect`. (read-only) +//| connections: Any = ... +//| """Tuple of active connections including those initiated through +//| :py:meth:`_bleio.Adapter.connect`. (read-only)""" //| STATIC mp_obj_t bleio_adapter_get_connections(mp_obj_t self) { return common_hal_bleio_adapter_get_connections(self); @@ -330,12 +328,12 @@ const mp_obj_property_t bleio_adapter_connections_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. method:: connect(address, *, timeout) -//| -//| Attempts a connection to the device with the given address. +//| def connect(self, address: Address, *, timeout: float/int) -> Any: +//| """Attempts a connection to the device with the given address. //| -//| :param Address address: The address of the peripheral to connect to -//| :param float/int timeout: Try to connect for timeout seconds. +//| :param Address address: The address of the peripheral to connect to +//| :param float/int timeout: Try to connect for timeout seconds.""" +//| ... //| STATIC mp_obj_t bleio_adapter_connect(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -360,9 +358,10 @@ STATIC mp_obj_t bleio_adapter_connect(mp_uint_t n_args, const mp_obj_t *pos_args } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_adapter_connect_obj, 2, bleio_adapter_connect); -//| .. method:: erase_bonding() +//| def erase_bonding(self, ) -> Any: +//| """Erase all bonding information stored in flash memory.""" +//| ... //| -//| Erase all bonding information stored in flash memory. STATIC mp_obj_t bleio_adapter_erase_bonding(mp_obj_t self_in) { bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Address.c b/shared-bindings/_bleio/Address.c index c31eb604b..2071bd3b2 100644 --- a/shared-bindings/_bleio/Address.c +++ b/shared-bindings/_bleio/Address.c @@ -34,22 +34,23 @@ #include "shared-bindings/_bleio/Address.h" #include "shared-module/_bleio/Address.h" -//| .. currentmodule:: _bleio +//| class Address: +//| """.. currentmodule:: _bleio //| -//| :class:`Address` -- BLE address -//| ========================================================= +//| :class:`Address` -- BLE address +//| ========================================================= //| -//| Encapsulates the address of a BLE device. +//| Encapsulates the address of a BLE device.""" //| -//| .. class:: Address(address, address_type) +//| def __init__(self, address: buf, address_type: Any): +//| """Create a new Address object encapsulating the address value. +//| The value itself can be one of: //| -//| Create a new Address object encapsulating the address value. -//| The value itself can be one of: -//| -//| :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes. -//| :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`, -//| `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`. +//| :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes. +//| :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`, +//| `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`.""" +//| ... //| STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_address_type }; @@ -81,9 +82,8 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| .. attribute:: address_bytes -//| -//| The bytes that make up the device address (read-only). +//| address_bytes: Any = ... +//| """The bytes that make up the device address (read-only). //| //| Note that the ``bytes`` object returned is in little-endian order: //| The least significant byte is ``address_bytes[0]``. So the address will @@ -97,7 +97,7 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args, //| >>> _bleio.adapter.address //|
//| >>> _bleio.adapter.address.address_bytes -//| b'5\xa8\xed\xf5\x1d\xc8' +//| b'5\xa8\xed\xf5\x1d\xc8'""" //| STATIC mp_obj_t bleio_address_get_address_bytes(mp_obj_t self_in) { bleio_address_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -113,12 +113,11 @@ const mp_obj_property_t bleio_address_address_bytes_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: type -//| -//| The address type (read-only). +//| type: Any = ... +//| """The address type (read-only). //| //| One of the integer values: `PUBLIC`, `RANDOM_STATIC`, `RANDOM_PRIVATE_RESOLVABLE`, -//| or `RANDOM_PRIVATE_NON_RESOLVABLE`. +//| or `RANDOM_PRIVATE_NON_RESOLVABLE`.""" //| STATIC mp_obj_t bleio_address_get_type(mp_obj_t self_in) { bleio_address_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -134,9 +133,9 @@ const mp_obj_property_t bleio_address_type_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __eq__(other) -//| -//| Two Address objects are equal if their addresses and address types are equal. +//| def __eq__(self, other: Any) -> Any: +//| """Two Address objects are equal if their addresses and address types are equal.""" +//| ... //| STATIC mp_obj_t bleio_address_binary_op(mp_binary_op_t op, mp_obj_t lhs_in, mp_obj_t rhs_in) { switch (op) { @@ -160,9 +159,9 @@ STATIC mp_obj_t bleio_address_binary_op(mp_binary_op_t op, mp_obj_t lhs_in, mp_o } } -//| .. method:: __hash__() -//| -//| Returns a hash for the Address data. +//| def __hash__(self, ) -> Any: +//| """Returns a hash for the Address data.""" +//| ... //| STATIC mp_obj_t bleio_address_unary_op(mp_unary_op_t op, mp_obj_t self_in) { switch (op) { @@ -193,22 +192,18 @@ STATIC void bleio_address_print(const mp_print_t *print, mp_obj_t self_in, mp_pr buf[5], buf[4], buf[3], buf[2], buf[1], buf[0]); } -//| .. data:: PUBLIC -//| -//| A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits). -//| -//| .. data:: RANDOM_STATIC -//| -//| A randomly generated address that does not change often. It may never change or may change after -//| a power cycle. -//| -//| .. data:: RANDOM_PRIVATE_RESOLVABLE +//| PUBLIC: Any = ... +//| """A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits).""" //| -//| An address that is usable when the peer knows the other device's secret Identity Resolving Key (IRK). +//| RANDOM_STATIC: Any = ... +//| """A randomly generated address that does not change often. It may never change or may change after +//| a power cycle.""" //| -//| .. data:: RANDOM_PRIVATE_NON_RESOLVABLE +//| RANDOM_PRIVATE_RESOLVABLE: Any = ... +//| """An address that is usable when the peer knows the other device's secret Identity Resolving Key (IRK).""" //| -//| A randomly generated address that changes on every connection. +//| RANDOM_PRIVATE_NON_RESOLVABLE: Any = ... +//| """A randomly generated address that changes on every connection.""" //| STATIC const mp_rom_map_elem_t bleio_address_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_address_bytes), MP_ROM_PTR(&bleio_address_address_bytes_obj) }, diff --git a/shared-bindings/_bleio/Attribute.c b/shared-bindings/_bleio/Attribute.c index 2d8b15b9f..72fd13d1c 100644 --- a/shared-bindings/_bleio/Attribute.c +++ b/shared-bindings/_bleio/Attribute.c @@ -29,52 +29,44 @@ #include "shared-bindings/_bleio/Characteristic.h" #include "shared-bindings/_bleio/UUID.h" -// - -//| .. currentmodule:: _bleio -//| -//| :class:`Attribute` -- BLE Attribute -//| ========================================================= +//| class Attribute: +//| """.. currentmodule:: _bleio //| -//| Definitions associated with all BLE attributes: characteristics, descriptors, etc. -//| :py:class:`~_bleio.Attribute` is, notionally, a superclass of -//| :py:class:`~Characteristic` and :py:class:`~Descriptor`, -//| but is not defined as a Python superclass of those classes. +//| :class:`Attribute` -- BLE Attribute +//| ========================================================= //| -//| .. class:: Attribute() +//| Definitions associated with all BLE attributes: characteristics, descriptors, etc. +//| :py:class:`~_bleio.Attribute` is, notionally, a superclass of +//| :py:class:`~Characteristic` and :py:class:`~Descriptor`, +//| but is not defined as a Python superclass of those classes.""" //| -//| You cannot create an instance of :py:class:`~_bleio.Attribute`. +//| def __init__(self, ): +//| """You cannot create an instance of :py:class:`~_bleio.Attribute`.""" +//| ... //| STATIC const mp_rom_map_elem_t bleio_attribute_locals_dict_table[] = { -//| .. data:: NO_ACCESS -//| -//| security mode: access not allowed -//| -//| .. data:: OPEN -//| -//| security_mode: no security (link is not encrypted) -//| -//| .. data:: ENCRYPT_NO_MITM -//| -//| security_mode: unauthenticated encryption, without man-in-the-middle protection -//| -//| .. data:: ENCRYPT_WITH_MITM -//| -//| security_mode: authenticated encryption, with man-in-the-middle protection +//| NO_ACCESS: Any = ... +//| """security mode: access not allowed""" //| -//| .. data:: LESC_ENCRYPT_WITH_MITM +//| OPEN: Any = ... +//| """security_mode: no security (link is not encrypted)""" //| -//| security_mode: LESC encryption, with man-in-the-middle protection +//| ENCRYPT_NO_MITM: Any = ... +//| """security_mode: unauthenticated encryption, without man-in-the-middle protection""" //| -//| .. data:: SIGNED_NO_MITM +//| ENCRYPT_WITH_MITM: Any = ... +//| """security_mode: authenticated encryption, with man-in-the-middle protection""" //| -//| security_mode: unauthenticated data signing, without man-in-the-middle protection +//| LESC_ENCRYPT_WITH_MITM: Any = ... +//| """security_mode: LESC encryption, with man-in-the-middle protection""" //| -//| .. data:: SIGNED_WITH_MITM +//| SIGNED_NO_MITM: Any = ... +//| """security_mode: unauthenticated data signing, without man-in-the-middle protection""" //| -//| security_mode: authenticated data signing, without man-in-the-middle protection +//| SIGNED_WITH_MITM: Any = ... +//| """security_mode: authenticated data signing, without man-in-the-middle protection""" //| { MP_ROM_QSTR(MP_QSTR_NO_ACCESS), MP_ROM_INT(SECURITY_MODE_NO_ACCESS) }, { MP_ROM_QSTR(MP_QSTR_OPEN), MP_ROM_INT(SECURITY_MODE_OPEN) }, diff --git a/shared-bindings/_bleio/Characteristic.c b/shared-bindings/_bleio/Characteristic.c index e55191f7c..f8f18d0bd 100644 --- a/shared-bindings/_bleio/Characteristic.c +++ b/shared-bindings/_bleio/Characteristic.c @@ -33,45 +33,46 @@ #include "shared-bindings/_bleio/Service.h" #include "shared-bindings/_bleio/UUID.h" -//| .. currentmodule:: _bleio -//| -//| :class:`Characteristic` -- BLE service characteristic -//| ========================================================= -//| -//| Stores information about a BLE service characteristic and allows reading -//| and writing of the characteristic's value. -//| -//| .. class:: Characteristic -//| -//| There is no regular constructor for a Characteristic. A new local Characteristic can be created -//| and attached to a Service by calling `add_to_service()`. -//| Remote Characteristic objects are created by `Connection.discover_remote_services()` -//| as part of remote Services. -//| - -//| .. method:: add_to_service(service, uuid, *, properties=0, read_perm=Attribute.OPEN, write_perm=Attribute.OPEN, max_length=20, fixed_length=False, initial_value=None) -//| -//| Create a new Characteristic object, and add it to this Service. -//| -//| :param Service service: The service that will provide this characteristic -//| :param UUID uuid: The uuid of the characteristic -//| :param int properties: The properties of the characteristic, -//| specified as a bitmask of these values bitwise-or'd together: -//| `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`. -//| :param int read_perm: Specifies whether the characteristic can be read by a client, and if so, which -//| security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`, -//| `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`, -//| `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`. -//| :param int write_perm: Specifies whether the characteristic can be written by a client, and if so, which -//| security mode is required. Values allowed are the same as ``read_perm``. -//| :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is -//| is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum -//| number of data bytes that fit in a single BLE 4.x ATT packet. -//| :param bool fixed_length: True if the characteristic value is of fixed length. -//| :param buf initial_value: The initial value for this characteristic. If not given, will be -//| filled with zeros. -//| -//| :return: the new Characteristic. +//| class Characteristic: +//| """.. currentmodule:: _bleio +//| +//| :class:`Characteristic` -- BLE service characteristic +//| ========================================================= +//| +//| Stores information about a BLE service characteristic and allows reading +//| and writing of the characteristic's value.""" +//| +//| def __init__(self, ): +//| """There is no regular constructor for a Characteristic. A new local Characteristic can be created +//| and attached to a Service by calling `add_to_service()`. +//| Remote Characteristic objects are created by `Connection.discover_remote_services()` +//| as part of remote Services.""" +//| ... +//| + +//| def add_to_service(self, service: Service, uuid: UUID, *, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: buf = None) -> Any: +//| """Create a new Characteristic object, and add it to this Service. +//| +//| :param Service service: The service that will provide this characteristic +//| :param UUID uuid: The uuid of the characteristic +//| :param int properties: The properties of the characteristic, +//| specified as a bitmask of these values bitwise-or'd together: +//| `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`. +//| :param int read_perm: Specifies whether the characteristic can be read by a client, and if so, which +//| security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`, +//| `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`, +//| `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`. +//| :param int write_perm: Specifies whether the characteristic can be written by a client, and if so, which +//| security mode is required. Values allowed are the same as ``read_perm``. +//| :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is +//| is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum +//| number of data bytes that fit in a single BLE 4.x ATT packet. +//| :param bool fixed_length: True if the characteristic value is of fixed length. +//| :param buf initial_value: The initial value for this characteristic. If not given, will be +//| filled with zeros. +//| +//| :return: the new Characteristic.""" +//| ... //| STATIC mp_obj_t bleio_characteristic_add_to_service(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { // class is arg[0], which we can ignore. @@ -145,11 +146,10 @@ STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_characteristic_add_to_service_obj, -//| .. attribute:: properties -//| -//| An int bitmask representing which properties are set, specified as bitwise or'ing of +//| properties: Any = ... +//| """An int bitmask representing which properties are set, specified as bitwise or'ing of //| of these possible values. -//| `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`. +//| `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`.""" //| STATIC mp_obj_t bleio_characteristic_get_properties(mp_obj_t self_in) { bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -165,11 +165,10 @@ const mp_obj_property_t bleio_characteristic_properties_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: uuid -//| -//| The UUID of this characteristic. (read-only) +//| uuid: Any = ... +//| """The UUID of this characteristic. (read-only) //| -//| Will be ``None`` if the 128-bit UUID for this characteristic is not known. +//| Will be ``None`` if the 128-bit UUID for this characteristic is not known.""" //| STATIC mp_obj_t bleio_characteristic_get_uuid(mp_obj_t self_in) { bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -186,9 +185,8 @@ const mp_obj_property_t bleio_characteristic_uuid_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: value -//| -//| The value of this characteristic. +//| value: Any = ... +//| """The value of this characteristic.""" //| STATIC mp_obj_t bleio_characteristic_get_value(mp_obj_t self_in) { bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -218,9 +216,8 @@ const mp_obj_property_t bleio_characteristic_value_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: descriptors -//| -//| A tuple of :py:class:`Descriptor` that describe this characteristic. (read-only) +//| descriptors: Any = ... +//| """A tuple of :py:class:`Descriptor` that describe this characteristic. (read-only)""" //| STATIC mp_obj_t bleio_characteristic_get_descriptors(mp_obj_t self_in) { bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -249,9 +246,8 @@ const mp_obj_property_t bleio_characteristic_descriptors_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: service (read-only) -//| -//| The Service this Characteristic is a part of. +//| service: Any = ... +//| """The Service this Characteristic is a part of.""" //| STATIC mp_obj_t bleio_characteristic_get_service(mp_obj_t self_in) { bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -267,12 +263,12 @@ const mp_obj_property_t bleio_characteristic_service_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. method:: set_cccd(*, notify=False, indicate=False) +//| def set_cccd(self, *, notify: bool = False, indicate: float = False) -> Any: +//| """Set the remote characteristic's CCCD to enable or disable notification and indication. //| -//| Set the remote characteristic's CCCD to enable or disable notification and indication. -//| -//| :param bool notify: True if Characteristic should receive notifications of remote writes -//| :param float indicate: True if Characteristic should receive indications of remote writes +//| :param bool notify: True if Characteristic should receive notifications of remote writes +//| :param float indicate: True if Characteristic should receive indications of remote writes""" +//| ... //| STATIC mp_obj_t bleio_characteristic_set_cccd(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -300,29 +296,23 @@ STATIC const mp_rom_map_elem_t bleio_characteristic_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_set_cccd), MP_ROM_PTR(&bleio_characteristic_set_cccd_obj) }, // Bitmask constants to represent properties -//| .. data:: BROADCAST -//| -//| property: allowed in advertising packets -//| -//| .. data:: INDICATE -//| -//| property: server will indicate to the client when the value is set and wait for a response -//| -//| .. data:: NOTIFY -//| -//| property: server will notify the client when the value is set -//| -//| .. data:: READ +//| BROADCAST: Any = ... +//| """property: allowed in advertising packets""" //| -//| property: clients may read this characteristic +//| INDICATE: Any = ... +//| """property: server will indicate to the client when the value is set and wait for a response""" //| -//| .. data:: WRITE +//| NOTIFY: Any = ... +//| """property: server will notify the client when the value is set""" //| -//| property: clients may write this characteristic; a response will be sent back +//| READ: Any = ... +//| """property: clients may read this characteristic""" //| -//| .. data:: WRITE_NO_RESPONSE +//| WRITE: Any = ... +//| """property: clients may write this characteristic; a response will be sent back""" //| -//| property: clients may write this characteristic; no response will be sent back +//| WRITE_NO_RESPONSE: Any = ... +//| """property: clients may write this characteristic; no response will be sent back""" //| { MP_ROM_QSTR(MP_QSTR_BROADCAST), MP_ROM_INT(CHAR_PROP_BROADCAST) }, { MP_ROM_QSTR(MP_QSTR_INDICATE), MP_ROM_INT(CHAR_PROP_INDICATE) }, diff --git a/shared-bindings/_bleio/CharacteristicBuffer.c b/shared-bindings/_bleio/CharacteristicBuffer.c index fc95d0d50..f38f650d9 100644 --- a/shared-bindings/_bleio/CharacteristicBuffer.c +++ b/shared-bindings/_bleio/CharacteristicBuffer.c @@ -41,24 +41,26 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self } } -//| .. currentmodule:: _bleio +//| class CharacteristicBuffer: +//| """.. currentmodule:: _bleio //| -//| :class:`CharacteristicBuffer` -- BLE Service incoming values buffer. -//| ===================================================================== +//| :class:`CharacteristicBuffer` -- BLE Service incoming values buffer. +//| ===================================================================== //| -//| Accumulates a Characteristic's incoming values in a FIFO buffer. +//| Accumulates a Characteristic's incoming values in a FIFO buffer.""" //| -//| .. class:: CharacteristicBuffer(characteristic, *, timeout=1, buffer_size=64) +//| def __init__(self, characteristic: Characteristic, *, timeout: int = 1, buffer_size: int = 64): //| -//| Monitor the given Characteristic. Each time a new value is written to the Characteristic -//| add the newly-written bytes to a FIFO buffer. +//| """Monitor the given Characteristic. Each time a new value is written to the Characteristic +//| add the newly-written bytes to a FIFO buffer. //| -//| :param Characteristic characteristic: The Characteristic to monitor. -//| It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic -//| in a remote Service that a Central has connected to. -//| :param int timeout: the timeout in seconds to wait for the first character and between subsequent characters. -//| :param int buffer_size: Size of ring buffer that stores incoming data coming from client. -//| Must be >= 1. +//| :param Characteristic characteristic: The Characteristic to monitor. +//| It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic +//| in a remote Service that a Central has connected to. +//| :param int timeout: the timeout in seconds to wait for the first character and between subsequent characters. +//| :param int buffer_size: Size of ring buffer that stores incoming data coming from client. +//| Must be >= 1.""" +//| ... //| STATIC mp_obj_t bleio_characteristic_buffer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_characteristic, ARG_timeout, ARG_buffer_size, }; @@ -103,29 +105,29 @@ STATIC void check_for_deinit(bleio_characteristic_buffer_obj_t *self) { // These are standard stream methods. Code is in py/stream.c. // -//| .. method:: read(nbytes=None) +//| def read(self, nbytes: Any = None) -> Any: +//| """Read characters. If ``nbytes`` is specified then read at most that many +//| bytes. Otherwise, read everything that arrives until the connection +//| times out. Providing the number of bytes expected is highly recommended +//| because it will be faster. //| -//| Read characters. If ``nbytes`` is specified then read at most that many -//| bytes. Otherwise, read everything that arrives until the connection -//| times out. Providing the number of bytes expected is highly recommended -//| because it will be faster. +//| :return: Data read +//| :rtype: bytes or None""" +//| ... //| -//| :return: Data read -//| :rtype: bytes or None +//| def readinto(self, buf: Any) -> Any: +//| """Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. //| -//| .. method:: readinto(buf) +//| :return: number of bytes read and stored into ``buf`` +//| :rtype: int or None (on a non-blocking error)""" +//| ... //| -//| Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. +//| def readline(self, ) -> Any: +//| """Read a line, ending in a newline character. //| -//| :return: number of bytes read and stored into ``buf`` -//| :rtype: int or None (on a non-blocking error) -//| -//| .. method:: readline() -//| -//| Read a line, ending in a newline character. -//| -//| :return: the line read -//| :rtype: int or None +//| :return: the line read +//| :rtype: int or None""" +//| ... //| // These three methods are used by the shared stream methods. @@ -170,9 +172,8 @@ STATIC mp_uint_t bleio_characteristic_buffer_ioctl(mp_obj_t self_in, mp_uint_t r return ret; } -//| .. attribute:: in_waiting -//| -//| The number of bytes in the input buffer, available to be read +//| in_waiting: Any = ... +//| """The number of bytes in the input buffer, available to be read""" //| STATIC mp_obj_t bleio_characteristic_buffer_obj_get_in_waiting(mp_obj_t self_in) { bleio_characteristic_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -188,9 +189,9 @@ const mp_obj_property_t bleio_characteristic_buffer_in_waiting_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: reset_input_buffer() -//| -//| Discard any unread characters in the input buffer. +//| def reset_input_buffer(self, ) -> Any: +//| """Discard any unread characters in the input buffer.""" +//| ... //| STATIC mp_obj_t bleio_characteristic_buffer_obj_reset_input_buffer(mp_obj_t self_in) { bleio_characteristic_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -200,9 +201,9 @@ STATIC mp_obj_t bleio_characteristic_buffer_obj_reset_input_buffer(mp_obj_t self } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_characteristic_buffer_reset_input_buffer_obj, bleio_characteristic_buffer_obj_reset_input_buffer); -//| .. method:: deinit() -//| -//| Disable permanently. +//| def deinit(self, ) -> Any: +//| """Disable permanently.""" +//| ... //| STATIC mp_obj_t bleio_characteristic_buffer_deinit(mp_obj_t self_in) { bleio_characteristic_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Connection.c b/shared-bindings/_bleio/Connection.c index c157af365..2165f12b8 100644 --- a/shared-bindings/_bleio/Connection.c +++ b/shared-bindings/_bleio/Connection.c @@ -42,28 +42,29 @@ #include "shared-bindings/_bleio/Characteristic.h" #include "shared-bindings/_bleio/Service.h" -//| .. currentmodule:: _bleio +//| class Connection: +//| """.. currentmodule:: _bleio //| -//| :class:`Connection` -- A BLE connection -//| ========================================================= +//| :class:`Connection` -- A BLE connection +//| ========================================================= //| -//| A BLE connection to another device. Used to discover and interact with services on the other -//| device. +//| A BLE connection to another device. Used to discover and interact with services on the other +//| device. //| -//| Usage:: +//| Usage:: //| -//| import _bleio +//| import _bleio //| -//| my_entry = None -//| for entry in _bleio.adapter.scan(2.5): -//| if entry.name is not None and entry.name == 'InterestingPeripheral': -//| my_entry = entry -//| break +//| my_entry = None +//| for entry in _bleio.adapter.scan(2.5): +//| if entry.name is not None and entry.name == 'InterestingPeripheral': +//| my_entry = entry +//| break //| -//| if not my_entry: -//| raise Exception("'InterestingPeripheral' not found") +//| if not my_entry: +//| raise Exception("'InterestingPeripheral' not found") //| -//| connection = _bleio.adapter.connect(my_entry.address, timeout=10) +//| connection = _bleio.adapter.connect(my_entry.address, timeout=10)""" //| void bleio_connection_ensure_connected(bleio_connection_obj_t *self) { @@ -72,15 +73,15 @@ void bleio_connection_ensure_connected(bleio_connection_obj_t *self) { } } -//| .. class:: Connection() +//| def __init__(self, ): +//| """Connections cannot be made directly. Instead, to initiate a connection use `Adapter.connect`. +//| Connections may also be made when another device initiates a connection. To use a Connection +//| created by a peer, read the `Adapter.connections` property. +//| ... //| -//| Connections cannot be made directly. Instead, to initiate a connection use `Adapter.connect`. -//| Connections may also be made when another device initiates a connection. To use a Connection -//| created by a peer, read the `Adapter.connections` property. -//| -//| .. method:: disconnect() -//| -//| Disconnects from the remote peripheral. Does nothing if already disconnected. +//| def disconnect(self, ) -> Any: +//| ""Disconnects from the remote peripheral. Does nothing if already disconnected.""" +//| ... //| STATIC mp_obj_t bleio_connection_disconnect(mp_obj_t self_in) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -91,9 +92,9 @@ STATIC mp_obj_t bleio_connection_disconnect(mp_obj_t self_in) { STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_connection_disconnect_obj, bleio_connection_disconnect); -//| .. method:: pair(*, bond=True) -//| -//| Pair to the peer to improve security. +//| def pair(self, *, bond: Any = True) -> Any: +//| """Pair to the peer to improve security.""" +//| ... //| STATIC mp_obj_t bleio_connection_pair(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -113,29 +114,29 @@ STATIC mp_obj_t bleio_connection_pair(mp_uint_t n_args, const mp_obj_t *pos_args } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection_pair); -//| .. method:: discover_remote_services(service_uuids_whitelist=None) -//| -//| Do BLE discovery for all services or for the given service UUIDS, -//| to find their handles and characteristics, and return the discovered services. -//| `Connection.connected` must be True. +//| def discover_remote_services(self, service_uuids_whitelist: iterable = None) -> Any: +//| """Do BLE discovery for all services or for the given service UUIDS, +//| to find their handles and characteristics, and return the discovered services. +//| `Connection.connected` must be True. //| -//| :param iterable service_uuids_whitelist: +//| :param iterable service_uuids_whitelist: //| -//| an iterable of :py:class:~`UUID` objects for the services provided by the peripheral -//| that you want to use. +//| an iterable of :py:class:~`UUID` objects for the services provided by the peripheral +//| that you want to use. //| -//| The peripheral may provide more services, but services not listed are ignored -//| and will not be returned. +//| The peripheral may provide more services, but services not listed are ignored +//| and will not be returned. //| -//| If service_uuids_whitelist is None, then all services will undergo discovery, which can be -//| slow. +//| If service_uuids_whitelist is None, then all services will undergo discovery, which can be +//| slow. //| -//| If the service UUID is 128-bit, or its characteristic UUID's are 128-bit, you -//| you must have already created a :py:class:~`UUID` object for that UUID in order for the -//| service or characteristic to be discovered. Creating the UUID causes the UUID to be -//| registered for use. (This restriction may be lifted in the future.) +//| If the service UUID is 128-bit, or its characteristic UUID's are 128-bit, you +//| you must have already created a :py:class:~`UUID` object for that UUID in order for the +//| service or characteristic to be discovered. Creating the UUID causes the UUID to be +//| registered for use. (This restriction may be lifted in the future.) //| -//| :return: A tuple of `_bleio.Service` objects provided by the remote peripheral. +//| :return: A tuple of `_bleio.Service` objects provided by the remote peripheral.""" +//| ... //| STATIC mp_obj_t bleio_connection_discover_remote_services(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -156,9 +157,8 @@ STATIC mp_obj_t bleio_connection_discover_remote_services(mp_uint_t n_args, cons } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_discover_remote_services_obj, 1, bleio_connection_discover_remote_services); -//| .. attribute:: connected -//| -//| True if connected to the remote peer. +//| connected: Any = ... +//| """True if connected to the remote peer.""" //| STATIC mp_obj_t bleio_connection_get_connected(mp_obj_t self_in) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -175,9 +175,8 @@ const mp_obj_property_t bleio_connection_connected_obj = { }; -//| .. attribute:: paired -//| -//| True if paired to the remote peer. +//| paired: Any = ... +//| """True if paired to the remote peer.""" //| STATIC mp_obj_t bleio_connection_get_paired(mp_obj_t self_in) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -194,17 +193,15 @@ const mp_obj_property_t bleio_connection_paired_obj = { }; -//| .. attribute:: connection_interval -//| -//| Time between transmissions in milliseconds. Will be multiple of 1.25ms. Lower numbers +//| connection_interval: Any = ... +//| """Time between transmissions in milliseconds. Will be multiple of 1.25ms. Lower numbers //| increase speed and decrease latency but increase power consumption. //| //| When setting connection_interval, the peer may reject the new interval and //| `connection_interval` will then remain the same. //| //| Apple has additional guidelines that dictate should be a multiple of 15ms except if HID is -//| available. When HID is available Apple devices may accept 11.25ms intervals. -//| +//| available. When HID is available Apple devices may accept 11.25ms intervals.""" //| STATIC mp_obj_t bleio_connection_get_connection_interval(mp_obj_t self_in) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Descriptor.c b/shared-bindings/_bleio/Descriptor.c index f7b6b5bbf..00b3bacf5 100644 --- a/shared-bindings/_bleio/Descriptor.c +++ b/shared-bindings/_bleio/Descriptor.c @@ -33,41 +33,42 @@ #include "shared-bindings/_bleio/Descriptor.h" #include "shared-bindings/_bleio/UUID.h" -//| .. currentmodule:: _bleio +//| class Descriptor: +//| """.. currentmodule:: _bleio //| -//| :class:`Descriptor` -- BLE descriptor -//| ========================================================= +//| :class:`Descriptor` -- BLE descriptor +//| ========================================================= //| -//| Stores information about a BLE descriptor. -//| Descriptors are attached to BLE characteristics and provide contextual -//| information about the characteristic. +//| Stores information about a BLE descriptor. +//| Descriptors are attached to BLE characteristics and provide contextual +//| information about the characteristic.""" //| -//| .. class:: Descriptor +//| def __init__(self, ): +//| """There is no regular constructor for a Descriptor. A new local Descriptor can be created +//| and attached to a Characteristic by calling `add_to_characteristic()`. +//| Remote Descriptor objects are created by `Connection.discover_remote_services()` +//| as part of remote Characteristics in the remote Services that are discovered. //| -//| There is no regular constructor for a Descriptor. A new local Descriptor can be created -//| and attached to a Characteristic by calling `add_to_characteristic()`. -//| Remote Descriptor objects are created by `Connection.discover_remote_services()` -//| as part of remote Characteristics in the remote Services that are discovered. +//| .. classmethod:: add_to_characteristic(characteristic, uuid, *, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=b'') //| -//| .. classmethod:: add_to_characteristic(characteristic, uuid, *, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=b'') +//| Create a new Descriptor object, and add it to this Service. //| -//| Create a new Descriptor object, and add it to this Service. +//| :param Characteristic characteristic: The characteristic that will hold this descriptor +//| :param UUID uuid: The uuid of the descriptor +//| :param int read_perm: Specifies whether the descriptor can be read by a client, and if so, which +//| security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`, +//| `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`, +//| `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`. +//| :param int write_perm: Specifies whether the descriptor can be written by a client, and if so, which +//| security mode is required. Values allowed are the same as ``read_perm``. +//| :param int max_length: Maximum length in bytes of the descriptor value. The maximum allowed is +//| is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum +//| number of data bytes that fit in a single BLE 4.x ATT packet. +//| :param bool fixed_length: True if the descriptor value is of fixed length. +//| :param buf initial_value: The initial value for this descriptor. //| -//| :param Characteristic characteristic: The characteristic that will hold this descriptor -//| :param UUID uuid: The uuid of the descriptor -//| :param int read_perm: Specifies whether the descriptor can be read by a client, and if so, which -//| security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`, -//| `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`, -//| `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`. -//| :param int write_perm: Specifies whether the descriptor can be written by a client, and if so, which -//| security mode is required. Values allowed are the same as ``read_perm``. -//| :param int max_length: Maximum length in bytes of the descriptor value. The maximum allowed is -//| is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum -//| number of data bytes that fit in a single BLE 4.x ATT packet. -//| :param bool fixed_length: True if the descriptor value is of fixed length. -//| :param buf initial_value: The initial value for this descriptor. -//| -//| :return: the new Descriptor. +//| :return: the new Descriptor.""" +//| ... //| STATIC mp_obj_t bleio_descriptor_add_to_characteristic(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { // class is arg[0], which we can ignore. @@ -135,9 +136,8 @@ STATIC mp_obj_t bleio_descriptor_add_to_characteristic(size_t n_args, const mp_o STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_descriptor_add_to_characteristic_fun_obj, 3, bleio_descriptor_add_to_characteristic); STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_descriptor_add_to_characteristic_obj, MP_ROM_PTR(&bleio_descriptor_add_to_characteristic_fun_obj)); -//| .. attribute:: uuid -//| -//| The descriptor uuid. (read-only) +//| uuid: Any = ... +//| """The descriptor uuid. (read-only)""" //| STATIC mp_obj_t bleio_descriptor_get_uuid(mp_obj_t self_in) { bleio_descriptor_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -154,9 +154,8 @@ const mp_obj_property_t bleio_descriptor_uuid_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: characteristic (read-only) -//| -//| The Characteristic this Descriptor is a part of. +//| characteristic: Any = ... +//| """The Characteristic this Descriptor is a part of.""" //| STATIC mp_obj_t bleio_descriptor_get_characteristic(mp_obj_t self_in) { bleio_descriptor_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -172,9 +171,8 @@ const mp_obj_property_t bleio_descriptor_characteristic_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: value -//| -//| The value of this descriptor. +//| value: Any = ... +//| """The value of this descriptor.""" //| STATIC mp_obj_t bleio_descriptor_get_value(mp_obj_t self_in) { bleio_descriptor_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/PacketBuffer.c b/shared-bindings/_bleio/PacketBuffer.c index 9e3666044..14efa022b 100644 --- a/shared-bindings/_bleio/PacketBuffer.c +++ b/shared-bindings/_bleio/PacketBuffer.c @@ -35,29 +35,30 @@ #include "shared-bindings/_bleio/UUID.h" #include "shared-bindings/util.h" -//| .. currentmodule:: _bleio +//| class PacketBuffer: +//| """.. currentmodule:: _bleio //| -//| :class:`PacketBuffer` -- Packet-oriented characteristic usage. -//| ===================================================================== +//| :class:`PacketBuffer` -- Packet-oriented characteristic usage. +//| ===================================================================== //| -//| Accumulates a Characteristic's incoming packets in a FIFO buffer and facilitates packet aware -//| outgoing writes. A packet's size is either the characteristic length or the maximum transmission -//| unit (MTU), whichever is smaller. The MTU can change so check `packet_size` before creating a -//| buffer to store data. +//| Accumulates a Characteristic's incoming packets in a FIFO buffer and facilitates packet aware +//| outgoing writes. A packet's size is either the characteristic length or the maximum transmission +//| unit (MTU), whichever is smaller. The MTU can change so check `packet_size` before creating a +//| buffer to store data. //| -//| When we're the server, we ignore all connections besides the first to subscribe to -//| notifications. +//| When we're the server, we ignore all connections besides the first to subscribe to +//| notifications.""" //| -//| .. class:: PacketBuffer(characteristic, *, buffer_size) +//| def __init__(self, characteristic: Characteristic, *, buffer_size: int): +//| """Monitor the given Characteristic. Each time a new value is written to the Characteristic +//| add the newly-written bytes to a FIFO buffer. //| -//| Monitor the given Characteristic. Each time a new value is written to the Characteristic -//| add the newly-written bytes to a FIFO buffer. -//| -//| :param Characteristic characteristic: The Characteristic to monitor. -//| It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic -//| in a remote Service that a Central has connected to. -//| :param int buffer_size: Size of ring buffer (in packets of the Characteristic's maximum -//| length) that stores incoming packets coming from the peer. +//| :param Characteristic characteristic: The Characteristic to monitor. +//| It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic +//| in a remote Service that a Central has connected to. +//| :param int buffer_size: Size of ring buffer (in packets of the Characteristic's maximum +//| length) that stores incoming packets coming from the peer.""" +//| ... //| STATIC mp_obj_t bleio_packet_buffer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_characteristic, ARG_buffer_size }; @@ -94,13 +95,13 @@ STATIC void check_for_deinit(bleio_packet_buffer_obj_t *self) { } } -//| .. method:: readinto(buf) -//| -//| Reads a single BLE packet into the ``buf``. Raises an exception if the next packet is longer -//| than the given buffer. Use `packet_size` to read the maximum length of a single packet. +//| def readinto(self, buf: Any) -> Any: +//| """Reads a single BLE packet into the ``buf``. Raises an exception if the next packet is longer +//| than the given buffer. Use `packet_size` to read the maximum length of a single packet. //| -//| :return: number of bytes read and stored into ``buf`` -//| :rtype: int +//| :return: number of bytes read and stored into ``buf`` +//| :rtype: int""" +//| ... //| STATIC mp_obj_t bleio_packet_buffer_readinto(mp_obj_t self_in, mp_obj_t buffer_obj) { bleio_packet_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -118,12 +119,12 @@ STATIC mp_obj_t bleio_packet_buffer_readinto(mp_obj_t self_in, mp_obj_t buffer_o } STATIC MP_DEFINE_CONST_FUN_OBJ_2(bleio_packet_buffer_readinto_obj, bleio_packet_buffer_readinto); -//| .. method:: write(data, *, header=None) -//| -//| Writes all bytes from data into the same outgoing packet. The bytes from header are included -//| before data when the pending packet is currently empty. +//| def write(self, data: Any, *, header: Any = None) -> Any: +//| """Writes all bytes from data into the same outgoing packet. The bytes from header are included +//| before data when the pending packet is currently empty. //| -//| This does not block until the data is sent. It only blocks until the data is pending. +//| This does not block until the data is sent. It only blocks until the data is pending.""" +//| ... //| // TODO: Add a kwarg `merge=False` to dictate whether subsequent writes are merged into a pending // one. @@ -155,10 +156,9 @@ STATIC mp_obj_t bleio_packet_buffer_write(mp_uint_t n_args, const mp_obj_t *pos_ } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_packet_buffer_write_obj, 1, bleio_packet_buffer_write); -//| .. method:: deinit() -//| -//| Disable permanently. -//| +//| def deinit(self, ) -> Any: +//| """Disable permanently.""" +//| ... STATIC mp_obj_t bleio_packet_buffer_deinit(mp_obj_t self_in) { bleio_packet_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); common_hal_bleio_packet_buffer_deinit(self); @@ -166,10 +166,9 @@ STATIC mp_obj_t bleio_packet_buffer_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_packet_buffer_deinit_obj, bleio_packet_buffer_deinit); -//| .. attribute:: packet_size -//| -//| Maximum size of each packet in bytes. This is the minimum of the Characteristic length and -//| the negotiated Maximum Transfer Unit (MTU). +//| packet_size: Any = ... +//| """Maximum size of each packet in bytes. This is the minimum of the Characteristic length and +//| the negotiated Maximum Transfer Unit (MTU).""" //| STATIC mp_obj_t bleio_packet_buffer_get_packet_size(mp_obj_t self_in) { bleio_packet_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/ScanEntry.c b/shared-bindings/_bleio/ScanEntry.c index d03cd6fb5..a92b247be 100644 --- a/shared-bindings/_bleio/ScanEntry.c +++ b/shared-bindings/_bleio/ScanEntry.c @@ -35,25 +35,26 @@ #include "shared-bindings/_bleio/UUID.h" #include "shared-module/_bleio/ScanEntry.h" -//| .. currentmodule:: _bleio +//| class ScanEntry: +//| """.. currentmodule:: _bleio //| -//| :class:`ScanEntry` -- BLE scan data -//| ========================================================= +//| :class:`ScanEntry` -- BLE scan data +//| ========================================================= //| -//| Encapsulates information about a device that was received during scanning. It can be -//| advertisement or scan response data. This object may only be created by a `_bleio.ScanResults`: -//| it has no user-visible constructor. +//| Encapsulates information about a device that was received during scanning. It can be +//| advertisement or scan response data. This object may only be created by a `_bleio.ScanResults`: +//| it has no user-visible constructor.""" //| -//| .. class:: ScanEntry() +//| def __init__(self, ): +//| """Cannot be instantiated directly. Use `_bleio.Adapter.start_scan`.""" +//| ... //| -//| Cannot be instantiated directly. Use `_bleio.Adapter.start_scan`. -//| -//| .. method:: matches(prefixes, *, all=True) -//| -//| Returns True if the ScanEntry matches all prefixes when ``all`` is True. This is stricter -//| than the scan filtering which accepts any advertisements that match any of the prefixes -//| where all is False. +//| def matches(self, prefixes: Any, *, all: Any = True) -> Any: +//| """Returns True if the ScanEntry matches all prefixes when ``all`` is True. This is stricter +//| than the scan filtering which accepts any advertisements that match any of the prefixes +//| where all is False.""" +//| ... //| STATIC mp_obj_t bleio_scanentry_matches(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -74,9 +75,8 @@ STATIC mp_obj_t bleio_scanentry_matches(mp_uint_t n_args, const mp_obj_t *pos_ar } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_scanentry_matches_obj, 2, bleio_scanentry_matches); -//| .. attribute:: address -//| -//| The address of the device (read-only), of type `_bleio.Address`. +//| address: Any = ... +//| """The address of the device (read-only), of type `_bleio.Address`.""" //| STATIC mp_obj_t bleio_scanentry_get_address(mp_obj_t self_in) { bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -91,9 +91,8 @@ const mp_obj_property_t bleio_scanentry_address_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: advertisement_bytes -//| -//| All the advertisement data present in the packet, returned as a ``bytes`` object. (read-only) +//| advertisement_bytes: Any = ... +//| """All the advertisement data present in the packet, returned as a ``bytes`` object. (read-only)""" //| STATIC mp_obj_t scanentry_get_advertisement_bytes(mp_obj_t self_in) { bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -108,9 +107,8 @@ const mp_obj_property_t bleio_scanentry_advertisement_bytes_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: rssi -//| -//| The signal strength of the device at the time of the scan, in integer dBm. (read-only) +//| rssi: Any = ... +//| """The signal strength of the device at the time of the scan, in integer dBm. (read-only)""" //| STATIC mp_obj_t scanentry_get_rssi(mp_obj_t self_in) { bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -125,9 +123,8 @@ const mp_obj_property_t bleio_scanentry_rssi_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: connectable -//| -//| True if the device can be connected to. (read-only) +//| connectable: Any = ... +//| """True if the device can be connected to. (read-only)""" //| STATIC mp_obj_t scanentry_get_connectable(mp_obj_t self_in) { bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -142,9 +139,8 @@ const mp_obj_property_t bleio_scanentry_connectable_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: scan_response -//| -//| True if the entry was a scan response. (read-only) +//| scan_response: Any = ... +//| """True if the entry was a scan response. (read-only)""" //| STATIC mp_obj_t scanentry_get_scan_response(mp_obj_t self_in) { bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/ScanResults.c b/shared-bindings/_bleio/ScanResults.c index dcece3d5d..4b274fc68 100644 --- a/shared-bindings/_bleio/ScanResults.c +++ b/shared-bindings/_bleio/ScanResults.c @@ -32,13 +32,14 @@ #include "py/runtime.h" #include "shared-bindings/_bleio/ScanResults.h" -//| .. currentmodule:: _bleio +//| class ScanResults: +//| """.. currentmodule:: _bleio //| -//| :class:`ScanResults` -- An Iterator over BLE scanning results -//| =============================================================== +//| :class:`ScanResults` -- An Iterator over BLE scanning results +//| =============================================================== //| -//| Iterates over advertising data received while scanning. This object is always created -//| by a `_bleio.Adapter`: it has no user-visible constructor. +//| Iterates over advertising data received while scanning. This object is always created +//| by a `_bleio.Adapter`: it has no user-visible constructor.""" //| STATIC mp_obj_t scanresults_iternext(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &bleio_scanresults_type)); @@ -50,18 +51,18 @@ STATIC mp_obj_t scanresults_iternext(mp_obj_t self_in) { return MP_OBJ_STOP_ITERATION; } -//| .. class:: ScanResults() +//| def __init__(self, ): +//| """Cannot be instantiated directly. Use `_bleio.Adapter.start_scan`.""" +//| ... //| -//| Cannot be instantiated directly. Use `_bleio.Adapter.start_scan`. +//| def __iter__(self, ) -> Any: +//| """Returns itself since it is the iterator.""" +//| ... //| -//| .. method:: __iter__() -//| -//| Returns itself since it is the iterator. -//| -//| .. method:: __next__() -//| -//| Returns the next `_bleio.ScanEntry`. Blocks if none have been received and scanning is still -//| active. Raises `StopIteration` if scanning is finished and no other results are available. +//| def __next__(self, ) -> Any: +//| """Returns the next `_bleio.ScanEntry`. Blocks if none have been received and scanning is still +//| active. Raises `StopIteration` if scanning is finished and no other results are available.""" +//| ... //| const mp_obj_type_t bleio_scanresults_type = { diff --git a/shared-bindings/_bleio/Service.c b/shared-bindings/_bleio/Service.c index bc242bc36..3526ce189 100644 --- a/shared-bindings/_bleio/Service.c +++ b/shared-bindings/_bleio/Service.c @@ -32,25 +32,26 @@ #include "shared-bindings/_bleio/Service.h" #include "shared-bindings/_bleio/UUID.h" -//| .. currentmodule:: _bleio +//| class Service: +//| """.. currentmodule:: _bleio //| -//| :class:`Service` -- BLE GATT Service -//| ========================================================= +//| :class:`Service` -- BLE GATT Service +//| ========================================================= //| -//| Stores information about a BLE service and its characteristics. +//| Stores information about a BLE service and its characteristics.""" //| -//| .. class:: Service(uuid, *, secondary=False) +//| def __init__(self, uuid: UUID, *, secondary: bool = False): +//| """Create a new Service identified by the specified UUID. It can be accessed by all +//| connections. This is known as a Service server. Client Service objects are created via +//| `Connection.discover_remote_services`. //| -//| Create a new Service identified by the specified UUID. It can be accessed by all -//| connections. This is known as a Service server. Client Service objects are created via -//| `Connection.discover_remote_services`. +//| To mark the Service as secondary, pass `True` as :py:data:`secondary`. //| -//| To mark the Service as secondary, pass `True` as :py:data:`secondary`. +//| :param UUID uuid: The uuid of the service +//| :param bool secondary: If the service is a secondary one //| -//| :param UUID uuid: The uuid of the service -//| :param bool secondary: If the service is a secondary one -// -//| :return: the new Service +//| :return: the new Service""" +//| ... //| STATIC mp_obj_t bleio_service_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_uuid, ARG_secondary }; @@ -77,10 +78,9 @@ STATIC mp_obj_t bleio_service_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(service); } -//| .. attribute:: characteristics -//| -//| A tuple of :py:class:`Characteristic` designating the characteristics that are offered by -//| this service. (read-only) +//| characteristics: Any = ... +//| """A tuple of :py:class:`Characteristic` designating the characteristics that are offered by +//| this service. (read-only)""" //| STATIC mp_obj_t bleio_service_get_characteristics(mp_obj_t self_in) { bleio_service_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -97,9 +97,8 @@ const mp_obj_property_t bleio_service_characteristics_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: remote -//| -//| True if this is a service provided by a remote device. (read-only) +//| remote: Any = ... +//| """True if this is a service provided by a remote device. (read-only)""" //| STATIC mp_obj_t bleio_service_get_remote(mp_obj_t self_in) { bleio_service_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -115,9 +114,8 @@ const mp_obj_property_t bleio_service_remote_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: secondary -//| -//| True if this is a secondary service. (read-only) +//| secondary: Any = ... +//| """True if this is a secondary service. (read-only)""" //| STATIC mp_obj_t bleio_service_get_secondary(mp_obj_t self_in) { bleio_service_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -133,11 +131,10 @@ const mp_obj_property_t bleio_service_secondary_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: uuid -//| -//| The UUID of this service. (read-only) +//| uuid: Any = ... +//| """The UUID of this service. (read-only) //| -//| Will be ``None`` if the 128-bit UUID for this service is not known. +//| Will be ``None`` if the 128-bit UUID for this service is not known.""" //| STATIC mp_obj_t bleio_service_get_uuid(mp_obj_t self_in) { bleio_service_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/UUID.c b/shared-bindings/_bleio/UUID.c index dd3415902..d4b0f84ca 100644 --- a/shared-bindings/_bleio/UUID.c +++ b/shared-bindings/_bleio/UUID.c @@ -33,28 +33,28 @@ #include "py/runtime.h" #include "shared-bindings/_bleio/UUID.h" -//| .. currentmodule:: _bleio +//| class UUID: +//| """.. currentmodule:: _bleio //| -//| :class:`UUID` -- BLE UUID -//| ========================================================= +//| :class:`UUID` -- BLE UUID +//| ========================================================= //| -//| A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more. +//| A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more.""" //| - -//| .. class:: UUID(value) -//| -//| Create a new UUID or UUID object encapsulating the uuid value. -//| The value can be one of: +//| def __init__(self, value: Any): +//| """Create a new UUID or UUID object encapsulating the uuid value. +//| The value can be one of: //| -//| - an `int` value in range 0 to 0xFFFF (Bluetooth SIG 16-bit UUID) -//| - a buffer object (bytearray, bytes) of 16 bytes in little-endian order (128-bit UUID) -//| - a string of hex digits of the form 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' +//| - an `int` value in range 0 to 0xFFFF (Bluetooth SIG 16-bit UUID) +//| - a buffer object (bytearray, bytes) of 16 bytes in little-endian order (128-bit UUID) +//| - a string of hex digits of the form 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' //| -//| Creating a 128-bit UUID registers the UUID with the onboard BLE software, and provides a -//| temporary 16-bit UUID that can be used in place of the full 128-bit UUID. +//| Creating a 128-bit UUID registers the UUID with the onboard BLE software, and provides a +//| temporary 16-bit UUID that can be used in place of the full 128-bit UUID. //| -//| :param value: The uuid value to encapsulate -//| :type value: int or typing.ByteString +//| :param value: The uuid value to encapsulate +//| :type value: int or typing.ByteString""" +//| ... //| STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -125,11 +125,10 @@ STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, co return MP_OBJ_FROM_PTR(self); } -//| .. attribute:: uuid16 -//| -//| The 16-bit part of the UUID. (read-only) +//| uuid16: Any = ... +//| """The 16-bit part of the UUID. (read-only) //| -//| :type: int +//| :type: int""" //| STATIC mp_obj_t bleio_uuid_get_uuid16(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -145,12 +144,11 @@ const mp_obj_property_t bleio_uuid_uuid16_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: uuid128 -//| -//| The 128-bit value of the UUID +//| uuid128: Any = ... +//| """The 128-bit value of the UUID //| Raises AttributeError if this is a 16-bit UUID. (read-only) //| -//| :type: bytes +//| :type: bytes""" //| STATIC mp_obj_t bleio_uuid_get_uuid128(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -172,12 +170,11 @@ const mp_obj_property_t bleio_uuid_uuid128_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: size -//| -//| 128 if this UUID represents a 128-bit vendor-specific UUID. 16 if this UUID represents a +//| size: Any = ... +//| """128 if this UUID represents a 128-bit vendor-specific UUID. 16 if this UUID represents a //| 16-bit Bluetooth SIG assigned UUID. (read-only) 32-bit UUIDs are not currently supported. //| -//| :type: int +//| :type: int""" //| STATIC mp_obj_t bleio_uuid_get_size(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -194,9 +191,9 @@ const mp_obj_property_t bleio_uuid_size_obj = { }; -//| .. method:: pack_into(buffer, offset=0) -//| -//| Packs the UUID into the given buffer at the given offset. +//| def pack_into(self, buffer: Any, offset: Any = 0) -> Any: +//| """Packs the UUID into the given buffer at the given offset.""" +//| ... //| STATIC mp_obj_t bleio_uuid_pack_into(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -256,11 +253,9 @@ STATIC mp_obj_t bleio_uuid_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| - -//| .. method:: __eq__(other) -//| -//| Two UUID objects are equal if their values match and they are both 128-bit or both 16-bit. +//| def __eq__(self, other: Any) -> Any: +//| """Two UUID objects are equal if their values match and they are both 128-bit or both 16-bit.""" +//| ... //| STATIC mp_obj_t bleio_uuid_binary_op(mp_binary_op_t op, mp_obj_t lhs_in, mp_obj_t rhs_in) { switch (op) { diff --git a/shared-bindings/_bleio/__init__.c b/shared-bindings/_bleio/__init__.c index dd401398c..da7bfdd81 100644 --- a/shared-bindings/_bleio/__init__.c +++ b/shared-bindings/_bleio/__init__.c @@ -41,7 +41,7 @@ #include "shared-bindings/_bleio/Service.h" #include "shared-bindings/_bleio/UUID.h" -//| :mod:`_bleio` --- Bluetooth Low Energy (BLE) communication +//| """:mod:`_bleio` --- Bluetooth Low Energy (BLE) communication //| ================================================================ //| //| .. module:: _bleio @@ -79,13 +79,14 @@ //| .. attribute:: adapter //| //| BLE Adapter used to manage device discovery and connections. -//| This object is the sole instance of `_bleio.Adapter`. +//| This object is the sole instance of `_bleio.Adapter`.""" //| -//| .. class:: BluetoothError(Exception) -//| -//| Catch all exception for Bluetooth related errors. -//| + +//| class BluetoothError: +//| def __init__(self, Exception: Any): +//| """Catch all exception for Bluetooth related errors.""" +//| ... MP_DEFINE_BLEIO_EXCEPTION(BluetoothError, Exception) NORETURN void mp_raise_bleio_BluetoothError(const compressed_string_t* fmt, ...) { @@ -95,10 +96,10 @@ NORETURN void mp_raise_bleio_BluetoothError(const compressed_string_t* fmt, ...) va_end(argptr); nlr_raise(exception); } - -//| .. class:: ConnectionError(BluetoothError) -//| -//| Raised when a connection is unavailable. +//| class ConnectionError: +//| def __init__(self, BluetoothError: Any): +//| """Raised when a connection is unavailable.""" +//| ... //| MP_DEFINE_BLEIO_EXCEPTION(ConnectionError, bleio_BluetoothError) NORETURN void mp_raise_bleio_ConnectionError(const compressed_string_t* fmt, ...) { @@ -109,19 +110,20 @@ NORETURN void mp_raise_bleio_ConnectionError(const compressed_string_t* fmt, ... nlr_raise(exception); } -//| .. class:: RoleError(BluetoothError) -//| -//| Raised when a resource is used as the mismatched role. For example, if a local CCCD is -//| attempted to be set but they can only be set when remote. +//| class RoleError: +//| def __init__(self, BluetoothError: Any): +//| """Raised when a resource is used as the mismatched role. For example, if a local CCCD is +//| attempted to be set but they can only be set when remote.""" +//| ... //| MP_DEFINE_BLEIO_EXCEPTION(RoleError, bleio_BluetoothError) NORETURN void mp_raise_bleio_RoleError(const compressed_string_t* msg) { mp_raise_msg(&mp_type_bleio_RoleError, msg); } - -//| .. class:: SecurityError(BluetoothError) -//| -//| Raised when a security related error occurs. +//| class SecurityError: +//| def __init__(self, BluetoothError: Any): +//| """Raised when a security related error occurs.""" +//| ... //| MP_DEFINE_BLEIO_EXCEPTION(SecurityError, bleio_BluetoothError) NORETURN void mp_raise_bleio_SecurityError(const compressed_string_t* fmt, ...) { diff --git a/shared-bindings/audiopwmio/PWMAudioOut.c b/shared-bindings/audiopwmio/PWMAudioOut.c index 9fa2b1578..17f82e3f6 100644 --- a/shared-bindings/audiopwmio/PWMAudioOut.c +++ b/shared-bindings/audiopwmio/PWMAudioOut.c @@ -36,66 +36,67 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: audiopwmio -//| -//| :class:`PWMAudioOut` -- Output an analog audio signal -//| ======================================================== -//| -//| AudioOut can be used to output an analog audio signal on a given pin. -//| -//| .. class:: PWMAudioOut(left_channel, *, right_channel=None, quiescent_value=0x8000) -//| -//| Create a PWMAudioOut object associated with the given pin(s). This allows you to -//| play audio signals out on the given pin(s). In contrast to mod:`audioio`, -//| the pin(s) specified are digital pins, and are driven with a device-dependent PWM -//| signal. -//| -//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to -//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to -//| :param int quiescent_value: The output value when no signal is present. Samples should start -//| and end with this value to prevent audible popping. -//| -//| Simple 8ksps 440 Hz sin wave:: -//| -//| import audiocore -//| import audiopwmio -//| import board -//| import array -//| import time -//| import math -//| -//| # Generate one period of sine wav. -//| 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 / 18) * (2 ** 15) + 2 ** 15) -//| -//| dac = audiopwmio.PWMAudioOut(board.SPEAKER) -//| sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) -//| dac.play(sine_wave, loop=True) -//| time.sleep(1) -//| dac.stop() -//| -//| Playing a wave file from flash:: -//| -//| import board -//| import audiocore -//| import audiopwmio -//| import digitalio -//| -//| # Required for CircuitPlayground Express -//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) -//| speaker_enable.switch_to_output(value=True) -//| -//| data = open("cplay-5.1-16bit-16khz.wav", "rb") -//| wav = audiocore.WaveFile(data) -//| a = audiopwmio.PWMAudioOut(board.SPEAKER) -//| -//| print("playing") -//| a.play(wav) -//| while a.playing: -//| pass -//| print("stopped") +//| class PWMAudioOut: +//| """.. currentmodule:: audiopwmio +//| +//| :class:`PWMAudioOut` -- Output an analog audio signal +//| ======================================================== +//| +//| AudioOut can be used to output an analog audio signal on a given pin.""" +//| +//| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): +//| """Create a PWMAudioOut object associated with the given pin(s). This allows you to +//| play audio signals out on the given pin(s). In contrast to mod:`audioio`, +//| the pin(s) specified are digital pins, and are driven with a device-dependent PWM +//| signal. +//| +//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to +//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to +//| :param int quiescent_value: The output value when no signal is present. Samples should start +//| and end with this value to prevent audible popping. +//| +//| Simple 8ksps 440 Hz sin wave:: +//| +//| import audiocore +//| import audiopwmio +//| import board +//| import array +//| import time +//| import math +//| +//| # Generate one period of sine wav. +//| 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 / 18) * (2 ** 15) + 2 ** 15) +//| +//| dac = audiopwmio.PWMAudioOut(board.SPEAKER) +//| sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) +//| dac.play(sine_wave, loop=True) +//| time.sleep(1) +//| dac.stop() +//| +//| Playing a wave file from flash:: +//| +//| import board +//| import audiocore +//| import audiopwmio +//| import digitalio +//| +//| # Required for CircuitPlayground Express +//| speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) +//| speaker_enable.switch_to_output(value=True) +//| +//| data = open("cplay-5.1-16bit-16khz.wav", "rb") +//| wav = audiocore.WaveFile(data) +//| a = audiopwmio.PWMAudioOut(board.SPEAKER) +//| +//| print("playing") +//| a.play(wav) +//| while a.playing: +//| pass +//| print("stopped")""" +//| ... //| STATIC mp_obj_t audiopwmio_pwmaudioout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_left_channel, ARG_right_channel, ARG_quiescent_value }; @@ -118,9 +119,9 @@ STATIC mp_obj_t audiopwmio_pwmaudioout_make_new(const mp_obj_type_t *type, size_ return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the PWMAudioOut and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the PWMAudioOut and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t audiopwmio_pwmaudioout_deinit(mp_obj_t self_in) { audiopwmio_pwmaudioout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -134,17 +135,16 @@ STATIC void check_for_deinit(audiopwmio_pwmaudioout_obj_t *self) { raise_deinited_error(); } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. -//| +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... STATIC mp_obj_t audiopwmio_pwmaudioout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; common_hal_audiopwmio_pwmaudioout_deinit(args[0]); @@ -153,16 +153,16 @@ STATIC mp_obj_t audiopwmio_pwmaudioout_obj___exit__(size_t n_args, const mp_obj_ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(audiopwmio_pwmaudioout___exit___obj, 4, 4, audiopwmio_pwmaudioout_obj___exit__); -//| .. method:: play(sample, *, loop=False) +//| def play(self, sample: Any, *, loop: Any = False) -> Any: +//| """Plays the sample once when loop=False and continuously when loop=True. +//| Does not block. Use `playing` to block. //| -//| 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`, or `audiomixer.Mixer`. //| -//| Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, or `audiomixer.Mixer`. -//| -//| The sample itself should consist of 16 bit samples. Microcontrollers with a lower output -//| resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit -//| DAC that ignores the lowest 6 bits when playing 16 bit samples. +//| The sample itself should consist of 16 bit samples. Microcontrollers with a lower output +//| resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit +//| DAC that ignores the lowest 6 bits when playing 16 bit samples.""" +//| ... //| STATIC mp_obj_t audiopwmio_pwmaudioout_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_sample, ARG_loop }; @@ -182,9 +182,9 @@ STATIC mp_obj_t audiopwmio_pwmaudioout_obj_play(size_t n_args, const mp_obj_t *p } MP_DEFINE_CONST_FUN_OBJ_KW(audiopwmio_pwmaudioout_play_obj, 1, audiopwmio_pwmaudioout_obj_play); -//| .. method:: stop() -//| -//| Stops playback and resets to the start of the sample. +//| def stop(self, ) -> Any: +//| """Stops playback and resets to the start of the sample.""" +//| ... //| STATIC mp_obj_t audiopwmio_pwmaudioout_obj_stop(mp_obj_t self_in) { audiopwmio_pwmaudioout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -194,9 +194,8 @@ STATIC mp_obj_t audiopwmio_pwmaudioout_obj_stop(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiopwmio_pwmaudioout_stop_obj, audiopwmio_pwmaudioout_obj_stop); -//| .. attribute:: playing -//| -//| True when an audio sample is being output even if `paused`. (read-only) +//| playing: Any = ... +//| """True when an audio sample is being output even if `paused`. (read-only)""" //| STATIC mp_obj_t audiopwmio_pwmaudioout_obj_get_playing(mp_obj_t self_in) { audiopwmio_pwmaudioout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -212,9 +211,9 @@ const mp_obj_property_t audiopwmio_pwmaudioout_playing_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: pause() -//| -//| Stops playback temporarily while remembering the position. Use `resume` to resume playback. +//| def pause(self, ) -> Any: +//| """Stops playback temporarily while remembering the position. Use `resume` to resume playback.""" +//| ... //| STATIC mp_obj_t audiopwmio_pwmaudioout_obj_pause(mp_obj_t self_in) { audiopwmio_pwmaudioout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -228,9 +227,9 @@ STATIC mp_obj_t audiopwmio_pwmaudioout_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiopwmio_pwmaudioout_pause_obj, audiopwmio_pwmaudioout_obj_pause); -//| .. method:: resume() -//| -//| Resumes sample playback after :py:func:`pause`. +//| def resume(self, ) -> Any: +//| """Resumes sample playback after :py:func:`pause`.""" +//| ... //| STATIC mp_obj_t audiopwmio_pwmaudioout_obj_resume(mp_obj_t self_in) { audiopwmio_pwmaudioout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -244,9 +243,8 @@ STATIC mp_obj_t audiopwmio_pwmaudioout_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(audiopwmio_pwmaudioout_resume_obj, audiopwmio_pwmaudioout_obj_resume); -//| .. attribute:: paused -//| -//| True when playback is paused. (read-only) +//| paused: Any = ... +//| """True when playback is paused. (read-only)""" //| STATIC mp_obj_t audiopwmio_pwmaudioout_obj_get_paused(mp_obj_t self_in) { audiopwmio_pwmaudioout_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/audiopwmio/__init__.c b/shared-bindings/audiopwmio/__init__.c index 8a2b202b3..74d22b45e 100644 --- a/shared-bindings/audiopwmio/__init__.c +++ b/shared-bindings/audiopwmio/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/audiopwmio/__init__.h" #include "shared-bindings/audiopwmio/PWMAudioOut.h" -//| :mod:`audiopwmio` --- Support for audio input and output +//| """:mod:`audiopwmio` --- Support for audio input and output //| ======================================================== //| //| .. module:: audiopwmio @@ -55,7 +55,7 @@ //| :ref:`lifetime-and-contextmanagers` for more info. //| //| Since CircuitPython 5, `Mixer`, `RawSample` and `WaveFile` are moved -//| to :mod:`audiocore`. +//| to :mod:`audiocore`.""" //| STATIC const mp_rom_map_elem_t audiopwmio_module_globals_table[] = { diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index 3c4f13777..a682e050e 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -37,21 +37,22 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: bitbangio +//| class I2C: +//| """.. currentmodule:: bitbangio //| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------ +//| :class:`I2C` --- Two wire serial protocol +//| ------------------------------------------""" //| -//| .. class:: I2C(scl, sda, *, frequency=400000, timeout) +//| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int): +//| """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. //| -//| 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. -//| -//| :param ~microcontroller.Pin scl: The clock pin -//| :param ~microcontroller.Pin sda: The data pin -//| :param int frequency: The clock frequency of the bus -//| :param int timeout: The maximum clock stretching timeout in microseconds +//| :param ~microcontroller.Pin scl: The clock pin +//| :param ~microcontroller.Pin sda: The data pin +//| :param int frequency: The clock frequency of the bus +//| :param int timeout: The maximum clock stretching timeout in microseconds""" +//| ... //| STATIC mp_obj_t bitbangio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_scl, ARG_sda, ARG_frequency, ARG_timeout }; @@ -73,9 +74,9 @@ STATIC mp_obj_t bitbangio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, return (mp_obj_t)self; } -//| .. method:: deinit() -//| -//| Releases control of the underlying hardware so other classes can use it. +//| def deinit(self, ) -> Any: +//| """Releases control of the underlying hardware so other classes can use it.""" +//| ... //| STATIC mp_obj_t bitbangio_i2c_obj_deinit(mp_obj_t self_in) { bitbangio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -90,16 +91,16 @@ STATIC void check_for_deinit(bitbangio_i2c_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used in Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used in Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware on context exit. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t bitbangio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -114,11 +115,11 @@ static void check_lock(bitbangio_i2c_obj_t *self) { } } -//| .. method:: scan() -//| -//| 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 scan(self, ) -> Any: +//| """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.""" +//| ... //| STATIC mp_obj_t bitbangio_i2c_scan(mp_obj_t self_in) { bitbangio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -136,9 +137,9 @@ STATIC mp_obj_t bitbangio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_scan_obj, bitbangio_i2c_scan); -//| .. method:: try_lock() -//| -//| Attempts to grab the I2C lock. Returns True on success. +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the I2C lock. Returns True on success.""" +//| ... //| STATIC mp_obj_t bitbangio_i2c_obj_try_lock(mp_obj_t self_in) { bitbangio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -147,9 +148,9 @@ STATIC mp_obj_t bitbangio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_try_lock_obj, bitbangio_i2c_obj_try_lock); -//| .. method:: unlock() -//| -//| Releases the I2C lock. +//| def unlock(self, ) -> Any: +//| """Releases the I2C lock.""" +//| ... //| STATIC mp_obj_t bitbangio_i2c_obj_unlock(mp_obj_t self_in) { bitbangio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -159,20 +160,20 @@ STATIC mp_obj_t bitbangio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_unlock_obj, bitbangio_i2c_obj_unlock); -//| .. method:: readfrom_into(address, buffer, *, start=0, end=None) -//| -//| Read into ``buffer`` from the slave specified by ``address``. -//| The number of bytes read will be the length of ``buffer``. -//| At least one byte must be read. +//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any: +//| """Read into ``buffer`` from the slave specified 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. +//| 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 bytearray buffer: buffer to write into -//| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include +//| :param int address: 7-bit device address +//| :param bytearray buffer: buffer to write into +//| :param int start: Index to start writing at +//| :param int end: Index to write up to but not include""" +//| ... //| // Shared arg parsing for readfrom_into and writeto_then_readfrom. STATIC void readfrom(bitbangio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end) { @@ -211,25 +212,25 @@ STATIC mp_obj_t bitbangio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_a } MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_readfrom_into_obj, 3, bitbangio_i2c_readfrom_into); -//| .. method:: writeto(address, buffer, *, start=0, end=None, stop=True) +//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any: +//| """Write the bytes from ``buffer`` to the slave specified by ``address`` and then transmits a +//| stop bit. Use `writeto_then_readfrom` when needing a write, no stop and repeated start +//| before a read. //| -//| Write the bytes from ``buffer`` to the slave specified 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]``. This will not cause an allocation like +//| ``buffer[start:end]`` will so it saves memory. //| -//| If ``start`` or ``end`` is provided, then the buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. +//| Writing a buffer or slice of length zero is permitted, as it can be used +//| to poll for the existence of a device. //| -//| 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 bytearray buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include -//| :param bool stop: If true, output an I2C stop condition after the buffer is written. -//| Deprecated. Will be removed in 6.x and act as stop=True. +//| :param int address: 7-bit device address +//| :param bytearray buffer: buffer containing the bytes to write +//| :param int start: Index to start writing from +//| :param int end: Index to read up to but not include +//| :param bool stop: If true, output an I2C stop condition after the buffer is written. +//| Deprecated. Will be removed in 6.x and act as stop=True.""" +//| ... //| // Shared arg parsing for writeto and writeto_then_readfrom. STATIC void writeto(bitbangio_i2c_obj_t *self, mp_int_t address, mp_obj_t buffer, int32_t start, mp_int_t end, bool stop) { @@ -271,23 +272,22 @@ STATIC mp_obj_t bitbangio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, m STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_writeto_obj, 1, bitbangio_i2c_writeto); -//| .. method:: writeto_then_readfrom(address, out_buffer, in_buffer, *, out_start=0, out_end=None, in_start=0, in_end=None) -//| -//| Write the bytes from ``out_buffer`` to the slave specified 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. +//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any: +//| """Write the bytes from ``out_buffer`` to the slave specified 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 ``start`` or ``end`` is provided, then the corresponding buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]`` -//| will so it saves memory. +//| If ``start`` or ``end`` is provided, then the corresponding 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 bytearray out_buffer: buffer containing the bytes to write -//| :param bytearray in_buffer: buffer to write into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)`` +//| :param int address: 7-bit device address +//| :param bytearray out_buffer: buffer containing the bytes to write +//| :param bytearray in_buffer: buffer to write into +//| :param int out_start: Index to start writing from +//| :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` +//| :param int in_start: Index to start writing at +//| :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)``""" //| STATIC mp_obj_t bitbangio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/bitbangio/OneWire.c b/shared-bindings/bitbangio/OneWire.c index 95bbd0679..1c9405bd8 100644 --- a/shared-bindings/bitbangio/OneWire.c +++ b/shared-bindings/bitbangio/OneWire.c @@ -34,33 +34,35 @@ #include "shared-bindings/bitbangio/OneWire.h" #include "shared-bindings/util.h" -//| .. currentmodule:: bitbangio +//| class OneWire: +//| """.. currentmodule:: bitbangio //| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| =============================================================== +//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol +//| =============================================================== //| -//| :class:`~bitbangio.OneWire` implements the timing-sensitive foundation of -//| the Maxim (formerly Dallas Semi) OneWire protocol. +//| :class:`~bitbangio.OneWire` implements the timing-sensitive foundation of +//| the Maxim (formerly Dallas Semi) OneWire protocol. //| -//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126 +//| Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126""" //| -//| .. class:: OneWire(pin) +//| def __init__(self, pin: microcontroller.Pin): //| -//| Create a OneWire object associated with the given pin. The object -//| implements the lowest level timing-sensitive bits of the protocol. +//| """Create a OneWire object associated with the given pin. The object +//| implements the lowest level timing-sensitive bits of the protocol. //| -//| :param ~microcontroller.Pin pin: Pin to read pulses from. +//| :param ~microcontroller.Pin pin: Pin to read pulses from. //| -//| Read a short series of pulses:: +//| Read a short series of pulses:: //| -//| import bitbangio -//| import board +//| import bitbangio +//| import board //| -//| onewire = bitbangio.OneWire(board.D7) -//| onewire.reset() -//| onewire.write_bit(True) -//| onewire.write_bit(False) -//| print(onewire.read_bit()) +//| onewire = bitbangio.OneWire(board.D7) +//| onewire.reset() +//| onewire.write_bit(True) +//| onewire.write_bit(False) +//| print(onewire.read_bit())""" +//| ... //| STATIC mp_obj_t bitbangio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin }; @@ -79,9 +81,9 @@ STATIC mp_obj_t bitbangio_onewire_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialize the OneWire bus and release any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialize the OneWire bus and release any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t bitbangio_onewire_deinit(mp_obj_t self_in) { bitbangio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -96,16 +98,16 @@ STATIC void check_for_deinit(bitbangio_onewire_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t bitbangio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -114,9 +116,9 @@ STATIC mp_obj_t bitbangio_onewire_obj___exit__(size_t n_args, const mp_obj_t *ar } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitbangio_onewire___exit___obj, 4, 4, bitbangio_onewire_obj___exit__); -//| .. method:: reset() -//| -//| Reset the OneWire bus +//| def reset(self, ) -> Any: +//| """Reset the OneWire bus""" +//| ... //| STATIC mp_obj_t bitbangio_onewire_obj_reset(mp_obj_t self_in) { bitbangio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -126,12 +128,12 @@ STATIC mp_obj_t bitbangio_onewire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_onewire_reset_obj, bitbangio_onewire_obj_reset); -//| .. method:: read_bit() -//| -//| Read in a bit +//| def read_bit(self, ) -> Any: +//| """Read in a bit //| -//| :returns: bit state read -//| :rtype: bool +//| :returns: bit state read +//| :rtype: bool""" +//| ... //| STATIC mp_obj_t bitbangio_onewire_obj_read_bit(mp_obj_t self_in) { bitbangio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -141,9 +143,9 @@ STATIC mp_obj_t bitbangio_onewire_obj_read_bit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_onewire_read_bit_obj, bitbangio_onewire_obj_read_bit); -//| .. method:: write_bit(value) -//| -//| Write out a bit based on value. +//| def write_bit(self, value: Any) -> Any: +//| """Write out a bit based on value.""" +//| ... //| STATIC mp_obj_t bitbangio_onewire_obj_write_bit(mp_obj_t self_in, mp_obj_t bool_obj) { bitbangio_onewire_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index b1a94c184..38e0926e8 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -39,26 +39,27 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: bitbangio +//| class SPI: +//| """.. currentmodule:: bitbangio //| -//| :class:`SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//| :class:`SPI` -- a 3-4 wire serial protocol +//| ----------------------------------------------- //| -//| SPI is a serial protocol that has exclusive pins for data in and out of the -//| master. It is typically faster than :py:class:`~bitbangio.I2C` because a -//| separate pin is used to control the active slave 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 slave -//| select line. (This is common because multiple slaves can share the `!clock`, -//| `!MOSI` and `!MISO` lines and therefore the hardware.) +//| SPI is a serial protocol that has exclusive pins for data in and out of the +//| master. It is typically faster than :py:class:`~bitbangio.I2C` because a +//| separate pin is used to control the active slave 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 slave +//| select line. (This is common because multiple slaves can share the `!clock`, +//| `!MOSI` and `!MISO` lines and therefore the hardware.)""" //| -//| .. class:: SPI(clock, MOSI=None, MISO=None) +//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): +//| """Construct an SPI object on the given pins. //| -//| Construct an SPI object on the given pins. -//| -//| :param ~microcontroller.Pin clock: the pin to use for the clock. -//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. -//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin. +//| :param ~microcontroller.Pin clock: the pin to use for the clock. +//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin. +//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin.""" +//| ... //| // TODO(tannewt): Support LSB SPI. @@ -82,9 +83,9 @@ STATIC mp_obj_t bitbangio_spi_make_new(const mp_obj_type_t *type, size_t n_args, return (mp_obj_t)self; } -//| .. method:: deinit() -//| -//| Turn off the SPI bus. +//| def deinit(self, ) -> Any: +//| """Turn off the SPI bus.""" +//| ... //| STATIC mp_obj_t bitbangio_spi_obj_deinit(mp_obj_t self_in) { bitbangio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -99,16 +100,16 @@ STATIC void check_for_deinit(bitbangio_spi_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t bitbangio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -124,15 +125,15 @@ static void check_lock(bitbangio_spi_obj_t *self) { } } -//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8) -//| -//| Configures the SPI bus. Only valid when locked. +//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: +//| """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 +//| :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""" +//| ... //| STATIC mp_obj_t bitbangio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; @@ -166,12 +167,12 @@ STATIC mp_obj_t bitbangio_spi_configure(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_spi_configure_obj, 1, bitbangio_spi_configure); -//| .. method:: try_lock() +//| def try_lock(self, ) -> Any: +//| """Attempts to grab the SPI lock. Returns True on success. //| -//| Attempts to grab the SPI lock. Returns True on success. -//| -//| :return: True when lock has been grabbed -//| :rtype: bool +//| :return: True when lock has been grabbed +//| :rtype: bool""" +//| ... //| STATIC mp_obj_t bitbangio_spi_obj_try_lock(mp_obj_t self_in) { bitbangio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -180,9 +181,9 @@ STATIC mp_obj_t bitbangio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_try_lock_obj, bitbangio_spi_obj_try_lock); -//| .. method:: unlock() -//| -//| Releases the SPI lock. +//| def unlock(self, ) -> Any: +//| """Releases the SPI lock.""" +//| ... //| STATIC mp_obj_t bitbangio_spi_obj_unlock(mp_obj_t self_in) { bitbangio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -192,10 +193,10 @@ STATIC mp_obj_t bitbangio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_unlock_obj, bitbangio_spi_obj_unlock); -//| .. method:: write(buf) -//| -//| Write the data contained in ``buf``. Requires the SPI being locked. -//| If the buffer is empty, nothing happens. +//| def write(self, buf: Any) -> Any: +//| """Write the data contained in ``buf``. Requires the SPI being locked. +//| If the buffer is empty, nothing happens.""" +//| ... //| // TODO(tannewt): Add support for start and end kwargs. STATIC mp_obj_t bitbangio_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { @@ -216,11 +217,11 @@ STATIC mp_obj_t bitbangio_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { MP_DEFINE_CONST_FUN_OBJ_2(bitbangio_spi_write_obj, bitbangio_spi_write); -//| .. method:: readinto(buf) -//| -//| Read into the buffer specified by ``buf`` while writing zeroes. -//| Requires the SPI being locked. -//| If the number of bytes to read is 0, nothing happens. +//| def readinto(self, buf: Any) -> Any: +//| """Read into the buffer specified by ``buf`` while writing zeroes. +//| Requires the SPI being locked. +//| If the number of bytes to read is 0, nothing happens.""" +//| ... //| // TODO(tannewt): Add support for start and end kwargs. STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *args) { @@ -240,19 +241,19 @@ STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitbangio_spi_readinto_obj, 2, 2, bitbangio_spi_readinto); -//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None) -//| -//| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. -//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//| must be equal. -//| If buffer slice lengths are both 0, nothing happens. +//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: +//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` +//| must be equal. +//| If buffer slice lengths are both 0, nothing happens. //| -//| :param bytearray buffer_out: Write out the data in this buffer -//| :param bytearray buffer_in: Read data into this buffer -//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` -//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` +//| :param bytearray buffer_out: Write out the data in this buffer +//| :param bytearray buffer_in: Read data into this buffer +//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` +//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``""" +//| ... //| STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/bitbangio/__init__.c b/shared-bindings/bitbangio/__init__.c index 3123fb199..e9600a7e6 100644 --- a/shared-bindings/bitbangio/__init__.c +++ b/shared-bindings/bitbangio/__init__.c @@ -40,7 +40,7 @@ #include "py/runtime.h" -//| :mod:`bitbangio` --- Digital protocols implemented by the CPU +//| """:mod:`bitbangio` --- Digital protocols implemented by the CPU //| ============================================================= //| //| .. module:: bitbangio @@ -81,7 +81,7 @@ //| 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. +//| resets hardware after a program finishes.""" //| STATIC const mp_rom_map_elem_t bitbangio_module_globals_table[] = { -- cgit v1.2.3 From bfa5cd9c13e308df5462653a53fe99eeb0543bc3 Mon Sep 17 00:00:00 2001 From: Daniel Pollard Date: Tue, 5 May 2020 15:23:38 +1000 Subject: refactor countio based on feedback --- locale/ID.po | 7 +- locale/circuitpython.pot | 7 +- locale/de_DE.po | 7 +- locale/en_US.po | 7 +- locale/en_x_pirate.po | 7 +- locale/es.po | 7 +- locale/fil.po | 7 +- locale/fr.po | 7 +- locale/it_IT.po | 7 +- locale/ko.po | 7 +- locale/pl.po | 7 +- locale/pt_BR.po | 7 +- locale/zh_Latn_pinyin.po | 7 +- ports/atmel-samd/common-hal/countio/Counter.c | 83 ++++++++++++++ ports/atmel-samd/common-hal/countio/Counter.h | 19 ++++ ports/atmel-samd/common-hal/countio/__init__.c | 1 + ports/atmel-samd/eic_handler.c | 7 ++ ports/atmel-samd/eic_handler.h | 1 + ports/cxd56/mpconfigport.mk | 2 +- ports/litex/mpconfigport.mk | 2 +- ports/mimxrt10xx/mpconfigport.mk | 2 +- ports/nrf/mpconfigport.mk | 2 + ports/stm/mpconfigport.mk | 3 + py/circuitpy_defns.mk | 5 + py/circuitpy_mpconfig.h | 8 ++ py/circuitpy_mpconfig.mk | 11 ++ shared-bindings/countio/Counter.c | 152 +++++++++++++++++++++++++ shared-bindings/countio/Counter.h | 18 +++ shared-bindings/countio/__init__.c | 48 ++++++++ shared-bindings/countio/__init__.h | 9 ++ 30 files changed, 448 insertions(+), 16 deletions(-) create mode 100644 ports/atmel-samd/common-hal/countio/Counter.c create mode 100644 ports/atmel-samd/common-hal/countio/Counter.h create mode 100644 ports/atmel-samd/common-hal/countio/__init__.c create mode 100644 shared-bindings/countio/Counter.c create mode 100644 shared-bindings/countio/Counter.h create mode 100644 shared-bindings/countio/__init__.c create mode 100644 shared-bindings/countio/__init__.h (limited to 'shared-bindings') diff --git a/locale/ID.po b/locale/ID.po index ac10df5bf..e303c7ca5 100644 --- a/locale/ID.po +++ b/locale/ID.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -245,6 +245,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Sebuah channel hardware interrupt sedang digunakan" @@ -1209,6 +1210,10 @@ msgstr "" msgid "Pin does not have ADC capabilities" msgstr "Pin tidak mempunya kemampuan untuk ADC (Analog Digital Converter)" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/circuitpython.pot b/locale/circuitpython.pot index 4b18bfd47..aa82bfe29 100644 --- a/locale/circuitpython.pot +++ b/locale/circuitpython.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -244,6 +244,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "" @@ -1197,6 +1198,10 @@ msgstr "" msgid "Pin does not have ADC capabilities" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/de_DE.po b/locale/de_DE.po index 6cf4b7d47..f7ef9bfeb 100644 --- a/locale/de_DE.po +++ b/locale/de_DE.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-07-27 11:55-0700\n" "Last-Translator: Pascal Deneaux\n" "Language-Team: Sebastian Plamauer, Pascal Deneaux\n" @@ -246,6 +246,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "3-arg pow() wird nicht unterstützt" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Ein Hardware Interrupt Kanal wird schon benutzt" @@ -1212,6 +1213,10 @@ msgstr "Zugang verweigert" msgid "Pin does not have ADC capabilities" msgstr "Pin hat keine ADC Funktionalität" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/en_US.po b/locale/en_US.po index 428a9c475..c72e6d0c9 100644 --- a/locale/en_US.po +++ b/locale/en_US.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-07-27 11:55-0700\n" "Last-Translator: \n" "Language-Team: \n" @@ -244,6 +244,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "" @@ -1197,6 +1198,10 @@ msgstr "" msgid "Pin does not have ADC capabilities" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/en_x_pirate.po b/locale/en_x_pirate.po index aacc176f5..1c523bb61 100644 --- a/locale/en_x_pirate.po +++ b/locale/en_x_pirate.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-07-27 11:55-0700\n" "Last-Translator: \n" "Language-Team: @sommersoft, @MrCertainly\n" @@ -246,6 +246,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Avast! A hardware interrupt channel be used already" @@ -1201,6 +1202,10 @@ msgstr "" msgid "Pin does not have ADC capabilities" msgstr "Belay that! Th' Pin be not ADC capable" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/es.po b/locale/es.po index db60c9d37..fe5086a99 100644 --- a/locale/es.po +++ b/locale/es.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-08-24 22:56-0500\n" "Last-Translator: \n" "Language-Team: \n" @@ -246,6 +246,7 @@ msgstr "0.0 a una potencia compleja" msgid "3-arg pow() not supported" msgstr "pow() con 3 argumentos no soportado" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "El canal EXTINT ya está siendo utilizado" @@ -1211,6 +1212,10 @@ msgstr "Permiso denegado" msgid "Pin does not have ADC capabilities" msgstr "Pin no tiene capacidad ADC" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/fil.po b/locale/fil.po index 6d577823f..f1178c8ca 100644 --- a/locale/fil.po +++ b/locale/fil.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-12-20 22:15-0800\n" "Last-Translator: Timothy \n" "Language-Team: fil\n" @@ -247,6 +247,7 @@ msgstr "0.0 para sa complex power" msgid "3-arg pow() not supported" msgstr "3-arg pow() hindi suportado" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Isang channel ng hardware interrupt ay ginagamit na" @@ -1217,6 +1218,10 @@ msgstr "Walang pahintulot" msgid "Pin does not have ADC capabilities" msgstr "Ang pin ay walang kakayahan sa ADC" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/fr.po b/locale/fr.po index 4d07eda19..ab12be1b6 100644 --- a/locale/fr.po +++ b/locale/fr.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: 0.1\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2019-04-14 20:05+0100\n" "Last-Translator: Pierrick Couturier \n" "Language-Team: fr\n" @@ -248,6 +248,7 @@ msgstr "0.0 à une puissance complexe" msgid "3-arg pow() not supported" msgstr "pow() non supporté avec 3 arguments" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Un canal d'interruptions matérielles est déjà utilisé" @@ -1231,6 +1232,10 @@ msgstr "Permission refusée" msgid "Pin does not have ADC capabilities" msgstr "La broche ne peut être utilisée pour l'ADC" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/it_IT.po b/locale/it_IT.po index 0c0825e5e..826b37889 100644 --- a/locale/it_IT.po +++ b/locale/it_IT.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-10-02 16:27+0200\n" "Last-Translator: Enrico Paganin \n" "Language-Team: \n" @@ -246,6 +246,7 @@ msgstr "0.0 elevato alla potenza di un numero complesso" msgid "3-arg pow() not supported" msgstr "pow() con tre argmomenti non supportata" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Un canale di interrupt hardware è già in uso" @@ -1226,6 +1227,10 @@ msgstr "Permesso negato" msgid "Pin does not have ADC capabilities" msgstr "Il pin non ha capacità di ADC" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/ko.po b/locale/ko.po index 3e3ac1cf6..f6bff27ce 100644 --- a/locale/ko.po +++ b/locale/ko.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2019-05-06 14:22-0700\n" "Last-Translator: \n" "Language-Team: LANGUAGE \n" @@ -246,6 +246,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "" @@ -1201,6 +1202,10 @@ msgstr "" msgid "Pin does not have ADC capabilities" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/pl.po b/locale/pl.po index 8cc3c30b7..fa19bfc19 100644 --- a/locale/pl.po +++ b/locale/pl.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2019-03-19 18:37-0700\n" "Last-Translator: Radomir Dopieralski \n" "Language-Team: pl\n" @@ -245,6 +245,7 @@ msgstr "0.0 do potęgi zespolonej" msgid "3-arg pow() not supported" msgstr "3-argumentowy pow() jest niewspierany" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Kanał przerwań sprzętowych w użyciu" @@ -1202,6 +1203,10 @@ msgstr "Odmowa dostępu" msgid "Pin does not have ADC capabilities" msgstr "Nóżka nie obsługuje ADC" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/pt_BR.po b/locale/pt_BR.po index d833169c0..bf56405c6 100644 --- a/locale/pt_BR.po +++ b/locale/pt_BR.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2018-10-02 21:14-0000\n" "Last-Translator: \n" "Language-Team: \n" @@ -246,6 +246,7 @@ msgstr "" msgid "3-arg pow() not supported" msgstr "" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Um canal de interrupção de hardware já está em uso" @@ -1212,6 +1213,10 @@ msgstr "Permissão negada" msgid "Pin does not have ADC capabilities" msgstr "O pino não tem recursos de ADC" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/locale/zh_Latn_pinyin.po b/locale/zh_Latn_pinyin.po index e7d6df02f..52337cdb4 100644 --- a/locale/zh_Latn_pinyin.po +++ b/locale/zh_Latn_pinyin.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: circuitpython-cn\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2020-04-27 18:34-0700\n" +"POT-Creation-Date: 2020-05-05 14:57+1000\n" "PO-Revision-Date: 2019-04-13 10:10-0700\n" "Last-Translator: hexthat\n" "Language-Team: Chinese Hanyu Pinyin\n" @@ -251,6 +251,7 @@ msgstr "0.0 dào fùzá diànyuán" msgid "3-arg pow() not supported" msgstr "bù zhīchí 3-arg pow ()" +#: ports/atmel-samd/common-hal/countio/Counter.c #: ports/atmel-samd/common-hal/rotaryio/IncrementalEncoder.c msgid "A hardware interrupt channel is already in use" msgstr "Yìngjiàn zhōngduàn tōngdào yǐ zài shǐyòng zhōng" @@ -1216,6 +1217,10 @@ msgstr "Quánxiàn bèi jùjué" msgid "Pin does not have ADC capabilities" msgstr "Pin méiyǒu ADC nénglì" +#: ports/atmel-samd/common-hal/countio/Counter.c +msgid "Pin must support hardware interrupts" +msgstr "" + #: ports/stm/common-hal/pulseio/PulseIn.c msgid "Pin number already reserved by EXTI" msgstr "" diff --git a/ports/atmel-samd/common-hal/countio/Counter.c b/ports/atmel-samd/common-hal/countio/Counter.c new file mode 100644 index 000000000..db5b325b8 --- /dev/null +++ b/ports/atmel-samd/common-hal/countio/Counter.c @@ -0,0 +1,83 @@ + +#include "common-hal/countio/Counter.h" + +#include "atmel_start_pins.h" + +#include "eic_handler.h" +#include "samd/external_interrupts.h" +#include "py/runtime.h" +#include "supervisor/shared/translate.h" + +void common_hal_countio_counter_construct(countio_counter_obj_t* self, + const mcu_pin_obj_t* pin_a) { + if (!pin_a->has_extint) { + mp_raise_RuntimeError(translate("Pin must support hardware interrupts")); + } + + + if (eic_get_enable()) { + if (!eic_channel_free(pin_a->extint_channel)) { + mp_raise_RuntimeError(translate("A hardware interrupt channel is already in use")); + } + } else { + turn_on_external_interrupt_controller(); + } + + // These default settings apply when the EIC isn't yet enabled. + self->eic_channel_a = pin_a->extint_channel; + + self->pin_a = pin_a->number; + + gpio_set_pin_function(self->pin_a, GPIO_PIN_FUNCTION_A); + gpio_set_pin_pull_mode(self->pin_a, GPIO_PULL_UP); + + set_eic_channel_data(self->eic_channel_a, (void*) self); + + self->count = 0; + + + claim_pin(pin_a); + + + set_eic_handler(self->eic_channel_a, EIC_HANDLER_COUNTER); + turn_on_eic_channel(self->eic_channel_a, EIC_CONFIG_SENSE0_FALL_Val); + +} + +bool common_hal_countio_counter_deinited(countio_counter_obj_t* self) { + return self->pin_a == NO_PIN; +} + +void common_hal_countio_counter_deinit(countio_counter_obj_t* self) { + if (common_hal_countio_counter_deinited(self)) { + return; + } + + set_eic_handler(self->eic_channel_a, EIC_HANDLER_NO_INTERRUPT); + turn_off_eic_channel(self->eic_channel_a); + + + reset_pin_number(self->pin_a); + self->pin_a = NO_PIN; + +} + +mp_int_t common_hal_countio_counter_get_count(countio_counter_obj_t* self) { + return self->count; +} + +void common_hal_countio_counter_set_count(countio_counter_obj_t* self, + mp_int_t new_count) { + self->count = new_count; +} + +void common_hal_countio_counter_reset(countio_counter_obj_t* self){ + self->count = 0; +} + +void counter_interrupt_handler(uint8_t channel) { + countio_counter_obj_t* self = get_eic_channel_data(channel); + + self->count += 1; + +} diff --git a/ports/atmel-samd/common-hal/countio/Counter.h b/ports/atmel-samd/common-hal/countio/Counter.h new file mode 100644 index 000000000..724c73415 --- /dev/null +++ b/ports/atmel-samd/common-hal/countio/Counter.h @@ -0,0 +1,19 @@ + +#ifndef MICROPY_INCLUDED_ATMEL_SAMD_COMMON_HAL_COUNTIO_COUNTER_H +#define MICROPY_INCLUDED_ATMEL_SAMD_COMMON_HAL_COUNTIO_COUNTER_H + +#include "common-hal/microcontroller/Pin.h" + +#include "py/obj.h" + +typedef struct { + mp_obj_base_t base; + uint8_t pin_a; + uint8_t eic_channel_a:4; + mp_int_t count; +} countio_counter_obj_t; + + +void counter_interrupt_handler(uint8_t channel); + +#endif // MICROPY_INCLUDED_ATMEL_SAMD_COMMON_HAL_COUNTIO_COUNT_H diff --git a/ports/atmel-samd/common-hal/countio/__init__.c b/ports/atmel-samd/common-hal/countio/__init__.c new file mode 100644 index 000000000..b95b20d15 --- /dev/null +++ b/ports/atmel-samd/common-hal/countio/__init__.c @@ -0,0 +1 @@ +//No countio module functions diff --git a/ports/atmel-samd/eic_handler.c b/ports/atmel-samd/eic_handler.c index 30ecaa7ca..7f26bdefb 100644 --- a/ports/atmel-samd/eic_handler.c +++ b/ports/atmel-samd/eic_handler.c @@ -27,6 +27,7 @@ #include "common-hal/pulseio/PulseIn.h" #include "common-hal/ps2io/Ps2.h" #include "common-hal/rotaryio/IncrementalEncoder.h" +#include "common-hal/countio/Counter.h" #include "shared-bindings/microcontroller/__init__.h" //#include "samd/external_interrupts.h" #include "eic_handler.h" @@ -59,6 +60,12 @@ void shared_eic_handler(uint8_t channel) { break; #endif +#if CIRCUITPY_COUNTIO + case EIC_HANDLER_COUNTER: + counter_interrupt_handler(channel); + break; +#endif + default: break; } diff --git a/ports/atmel-samd/eic_handler.h b/ports/atmel-samd/eic_handler.h index 71b0fce67..08da7ea34 100644 --- a/ports/atmel-samd/eic_handler.h +++ b/ports/atmel-samd/eic_handler.h @@ -30,6 +30,7 @@ #define EIC_HANDLER_PULSEIN 0x1 #define EIC_HANDLER_INCREMENTAL_ENCODER 0x2 #define EIC_HANDLER_PS2 0x3 +#define EIC_HANDLER_COUNTER 0x04 void set_eic_handler(uint8_t channel, uint8_t eic_handler); void shared_eic_handler(uint8_t channel); diff --git a/ports/cxd56/mpconfigport.mk b/ports/cxd56/mpconfigport.mk index ad3d0e72d..8aeae1de5 100644 --- a/ports/cxd56/mpconfigport.mk +++ b/ports/cxd56/mpconfigport.mk @@ -18,5 +18,5 @@ CIRCUITPY_NEOPIXEL_WRITE = 0 CIRCUITPY_NVM = 0 CIRCUITPY_DISPLAYIO = 0 CIRCUITPY_FREQUENCYIO = 0 - +CIRCUITPY_COUNTIO = 0 INTERNAL_LIBM = 1 diff --git a/ports/litex/mpconfigport.mk b/ports/litex/mpconfigport.mk index 0a82f4161..004930ba7 100644 --- a/ports/litex/mpconfigport.mk +++ b/ports/litex/mpconfigport.mk @@ -25,7 +25,7 @@ CIRCUITPY_NVM = 0 CIRCUITPY_PULSEIO = 0 CIRCUITPY_ROTARYIO = 0 CIRCUITPY_RTC = 0 - +CIRCUITPY_COUNTIO = 0 # Enable USB support CIRCUITPY_USB_HID = 1 CIRCUITPY_USB_MIDI = 1 diff --git a/ports/mimxrt10xx/mpconfigport.mk b/ports/mimxrt10xx/mpconfigport.mk index 5881ac302..e9e554142 100644 --- a/ports/mimxrt10xx/mpconfigport.mk +++ b/ports/mimxrt10xx/mpconfigport.mk @@ -26,5 +26,5 @@ CIRCUITPY_FREQUENCYIO = 0 CIRCUITPY_I2CSLAVE = 0 CIRCUITPY_NVM = 0 CIRCUITPY_ROTARYIO = 0 - +CIRCUITPY_COUNTIO = 0 LONGINT_IMPL = MPZ diff --git a/ports/nrf/mpconfigport.mk b/ports/nrf/mpconfigport.mk index 410d3750e..7939a175b 100644 --- a/ports/nrf/mpconfigport.mk +++ b/ports/nrf/mpconfigport.mk @@ -54,6 +54,8 @@ CIRCUITPY_FREQUENCYIO = 0 CIRCUITPY_RGBMATRIX ?= 1 CIRCUITPY_FRAMEBUFFERIO ?= 1 +CIRCUITPY_COUNTIO = 0 + # nRF52840-specific ifeq ($(MCU_CHIP),nrf52840) diff --git a/ports/stm/mpconfigport.mk b/ports/stm/mpconfigport.mk index 5ef1e8e7b..ee8b2e160 100644 --- a/ports/stm/mpconfigport.mk +++ b/ports/stm/mpconfigport.mk @@ -8,6 +8,7 @@ ifeq ($(MCU_SERIES),F4) CIRCUITPY_AUDIOBUSIO = 0 CIRCUITPY_AUDIOIO = 0 CIRCUITPY_ROTARYIO = 0 + CIRCUITPY_COUNTIO = 0 CIRCUITPY_RTC = 0 CIRCUITPY_FREQUENCYIO = 0 CIRCUITPY_I2CSLAVE = 0 @@ -26,6 +27,7 @@ ifeq ($(MCU_SERIES),H7) CIRCUITPY_NVM = 0 CIRCUITPY_AUDIOBUSIO = 0 CIRCUITPY_AUDIOIO = 0 + CIRCUITPY_COUNTIO = 0 CIRCUITPY_ROTARYIO = 0 CIRCUITPY_RTC = 0 CIRCUITPY_FREQUENCYIO = 0 @@ -46,6 +48,7 @@ ifeq ($(MCU_SERIES),F7) CIRCUITPY_AUDIOBUSIO = 0 CIRCUITPY_AUDIOIO = 0 CIRCUITPY_ROTARYIO = 0 + CIRCUITPY_COUNTIO = 0 CIRCUITPY_RTC = 0 CIRCUITPY_FREQUENCYIO = 0 CIRCUITPY_I2CSLAVE = 0 diff --git a/py/circuitpy_defns.mk b/py/circuitpy_defns.mk index ec8e6c3e9..a253f2fa8 100644 --- a/py/circuitpy_defns.mk +++ b/py/circuitpy_defns.mk @@ -136,6 +136,9 @@ endif ifeq ($(CIRCUITPY_BUSIO),1) SRC_PATTERNS += busio/% bitbangio/OneWire.% endif +ifeq ($(CIRCUITPY_COUNTIO),1) +SRC_PATTERNS += countio/% +endif ifeq ($(CIRCUITPY_DIGITALIO),1) SRC_PATTERNS += digitalio/% endif @@ -263,6 +266,8 @@ SRC_COMMON_HAL_ALL = \ busio/SPI.c \ busio/UART.c \ busio/__init__.c \ + countio/Counter.c \ + countio/__init__.c \ digitalio/DigitalInOut.c \ digitalio/__init__.c \ displayio/ParallelBus.c \ diff --git a/py/circuitpy_mpconfig.h b/py/circuitpy_mpconfig.h index 29a4d524c..a3ab4da94 100644 --- a/py/circuitpy_mpconfig.h +++ b/py/circuitpy_mpconfig.h @@ -314,6 +314,13 @@ extern const struct _mp_obj_module_t busio_module; #define BUSIO_MODULE #endif +#if CIRCUITPY_COUNTIO +extern const struct _mp_obj_module_t countio_module; +#define COUNTIO_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_countio), (mp_obj_t)&countio_module }, +#else +#define COUNTIO_MODULE +#endif + #if CIRCUITPY_DIGITALIO extern const struct _mp_obj_module_t digitalio_module; #define DIGITALIO_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_digitalio), (mp_obj_t)&digitalio_module }, @@ -630,6 +637,7 @@ extern const struct _mp_obj_module_t ustack_module; BLEIO_MODULE \ BOARD_MODULE \ BUSIO_MODULE \ + COUNTIO_MODULE \ DIGITALIO_MODULE \ DISPLAYIO_MODULE \ FONTIO_MODULE \ diff --git a/py/circuitpy_mpconfig.mk b/py/circuitpy_mpconfig.mk index 30ab720d7..7ef87a7ea 100644 --- a/py/circuitpy_mpconfig.mk +++ b/py/circuitpy_mpconfig.mk @@ -109,6 +109,12 @@ CIRCUITPY_DIGITALIO = 1 endif CFLAGS += -DCIRCUITPY_DIGITALIO=$(CIRCUITPY_DIGITALIO) +ifndef CIRCUITPY_COUNTIO +CIRCUITPY_COUNTIO = 1 +endif +CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO) + + ifndef CIRCUITPY_DISPLAYIO CIRCUITPY_DISPLAYIO = $(CIRCUITPY_FULL_BUILD) endif @@ -207,6 +213,11 @@ CIRCUITPY_ROTARYIO = 1 endif CFLAGS += -DCIRCUITPY_ROTARYIO=$(CIRCUITPY_ROTARYIO) +ifndef CIRCUITPY_COUNTIO +CIRCUITPY_COUNTIO = 1 +endif +CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO) + ifndef CIRCUITPY_RTC CIRCUITPY_RTC = 1 endif diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c new file mode 100644 index 000000000..c10294199 --- /dev/null +++ b/shared-bindings/countio/Counter.c @@ -0,0 +1,152 @@ + +#include + +#include "lib/utils/context_manager_helpers.h" +#include "py/objproperty.h" +#include "py/runtime.h" +#include "py/runtime0.h" +#include "shared-bindings/microcontroller/Pin.h" +#include "shared-bindings/countio/Counter.h" +#include "shared-bindings/util.h" + +//| .. currentmodule:: countio +//| +//| :class:`Counter` -- Track the count of edge transistions (pulses) on a given pin +//| ==================================================================================== +//| +//| Counter will keep track of the number of edge transistions (pulses) on a given pin +//| +//| .. class:: Counter(pin_a) +//| +//| Create an Counter object associated with the given pin. It tracks the number of +//| pulses relative when the object is contructed. +//| +//| :param ~microcontroller.Pin pin_a: Pin to read pulses from. +//| +//| +//| For example:: +//| +//| import countio +//| import time +//| from board import * +//| +//| pin_counter = countio.Counter(board.D1) +//| +//| while True: +//| count = pin_counter.count +//| if count == None 10: +//| pin_counter.reset() +//| print(pin_counter.count) +//| +STATIC mp_obj_t countio_counter_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { + enum { ARG_pin_a }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_pin_a, MP_ARG_REQUIRED | MP_ARG_OBJ } + + }; + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + const mcu_pin_obj_t* pin_a = validate_obj_is_free_pin(args[ARG_pin_a].u_obj); + + + countio_counter_obj_t *self = m_new_obj(countio_counter_obj_t); + self->base.type = &countio_counter_type; + + common_hal_countio_counter_construct(self, pin_a); + + return MP_OBJ_FROM_PTR(self); +} + +//| .. method:: deinit() +//| +//| Deinitializes the Counter and releases any hardware resources for reuse. +//| +STATIC mp_obj_t countio_counter_deinit(mp_obj_t self_in) { + countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); + common_hal_countio_counter_deinit(self); + return mp_const_none; +} +STATIC MP_DEFINE_CONST_FUN_OBJ_1(countio_counter_deinit_obj, countio_counter_deinit); + +STATIC void check_for_deinit(countio_counter_obj_t *self) { + if (common_hal_countio_counter_deinited(self)) { + raise_deinited_error(); + } +} + +//| .. method:: __enter__() +//| +//| No-op used by Context Managers. +//| +// Provided by context manager helper. + +//| .. method:: __exit__() +//| +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. +//| +STATIC mp_obj_t countio_counter_obj___exit__(size_t n_args, const mp_obj_t *args) { + (void)n_args; + common_hal_countio_counter_deinit(args[0]); + return mp_const_none; +} +STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(countio_counter___exit___obj, 4, 4, countio_counter_obj___exit__); + + +//| .. attribute:: count +//| +//| The current count in terms of pulses. +//| +//| +STATIC mp_obj_t countio_counter_obj_get_count(mp_obj_t self_in) { + countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); + check_for_deinit(self); + + return mp_obj_new_int(common_hal_countio_counter_get_count(self)); +} +MP_DEFINE_CONST_FUN_OBJ_1(countio_counter_get_count_obj, countio_counter_obj_get_count); + +STATIC mp_obj_t countio_counter_obj_set_count(mp_obj_t self_in, mp_obj_t new_count) { + countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); + check_for_deinit(self); + + common_hal_countio_counter_set_count(self, mp_obj_get_int(new_count)); + return mp_const_none; +} +MP_DEFINE_CONST_FUN_OBJ_2(countio_counter_set_count_obj, countio_counter_obj_set_count); + +const mp_obj_property_t countio_counter_count_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&countio_counter_get_count_obj, + (mp_obj_t)&countio_counter_set_count_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + +STATIC mp_obj_t countio_counter_reset(mp_obj_t self_in){ + countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); + check_for_deinit(self); + //set the position to zero for reset + common_hal_countio_counter_reset(self); + return mp_const_none; +} + + +MP_DEFINE_CONST_FUN_OBJ_1(countio_counter_reset_obj, countio_counter_reset); + +STATIC const mp_rom_map_elem_t countio_counter_locals_dict_table[] = { + // Methods + { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&countio_counter_deinit_obj) }, + { MP_ROM_QSTR(MP_QSTR___enter__), MP_ROM_PTR(&default___enter___obj) }, + { MP_ROM_QSTR(MP_QSTR___exit__), MP_ROM_PTR(&countio_counter___exit___obj) }, + { MP_ROM_QSTR(MP_QSTR_count), MP_ROM_PTR(&countio_counter_count_obj) }, + { MP_ROM_QSTR(MP_QSTR_reset), MP_ROM_PTR(&countio_counter_reset_obj) }, +}; +STATIC MP_DEFINE_CONST_DICT(countio_counter_locals_dict, countio_counter_locals_dict_table); + +const mp_obj_type_t countio_counter_type = { + { &mp_type_type }, + .name = MP_QSTR_Counter, + .make_new = countio_counter_make_new, + .locals_dict = (mp_obj_dict_t*)&countio_counter_locals_dict, +}; diff --git a/shared-bindings/countio/Counter.h b/shared-bindings/countio/Counter.h new file mode 100644 index 000000000..15adbbe2a --- /dev/null +++ b/shared-bindings/countio/Counter.h @@ -0,0 +1,18 @@ +#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_COUNTIO_COUNTER_H +#define MICROPY_INCLUDED_SHARED_BINDINGS_COUNTIO_COUNTER_H + +#include "common-hal/microcontroller/Pin.h" +#include "common-hal/countio/Counter.h" + +extern const mp_obj_type_t countio_counter_type; + +extern void common_hal_countio_counter_construct(countio_counter_obj_t* self, + const mcu_pin_obj_t* pin_a); +extern void common_hal_countio_counter_deinit(countio_counter_obj_t* self); +extern bool common_hal_countio_counter_deinited(countio_counter_obj_t* self); +extern mp_int_t common_hal_countio_counter_get_count(countio_counter_obj_t* self); +extern void common_hal_countio_counter_set_count(countio_counter_obj_t* self, + mp_int_t new_count); +extern void common_hal_countio_counter_reset(countio_counter_obj_t* self); + +#endif // MICROPY_INCLUDED_SHARED_BINDINGS_COUNTIO_COUNTER_H diff --git a/shared-bindings/countio/__init__.c b/shared-bindings/countio/__init__.c new file mode 100644 index 000000000..8929bf7ed --- /dev/null +++ b/shared-bindings/countio/__init__.c @@ -0,0 +1,48 @@ + +#include + +#include "py/obj.h" +#include "py/runtime.h" + +#include "shared-bindings/microcontroller/Pin.h" +#include "shared-bindings/countio/__init__.h" +#include "shared-bindings/countio/Counter.h" + +//| :mod:`countio` --- Support for edge counting +//| ======================================================== +//| +//| .. module:: countio +//| :synopsis: Support for edge counting +//| :platform: SAMD +//| +//| The `countio` module contains logic to read and count edge transistions +//| +//| Libraries +//| +//| .. toctree:: +//| :maxdepth: 3 +//| +//| Counter +//| + +//| .. warning:: This module is not available in some SAMD21 (aka M0) builds. See the +//| :ref:`module-support-matrix` for more info. +//| + +//| 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. +//| + +STATIC const mp_rom_map_elem_t countio_module_globals_table[] = { + { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_countio) }, + { MP_ROM_QSTR(MP_QSTR_Counter), MP_ROM_PTR(&countio_counter_type) }, +}; + +STATIC MP_DEFINE_CONST_DICT(countio_module_globals, countio_module_globals_table); + +const mp_obj_module_t countio_module = { + .base = { &mp_type_module }, + .globals = (mp_obj_dict_t*)&countio_module_globals, +}; diff --git a/shared-bindings/countio/__init__.h b/shared-bindings/countio/__init__.h new file mode 100644 index 000000000..35ae9f035 --- /dev/null +++ b/shared-bindings/countio/__init__.h @@ -0,0 +1,9 @@ + +#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_COUNTIO___INIT___H +#define MICROPY_INCLUDED_SHARED_BINDINGS_COUNTIO___INIT___H + +#include "py/obj.h" + +// Nothing now. + +#endif // MICROPY_INCLUDED_SHARED_BINDINGS_COUNTIO___INIT___H -- cgit v1.2.3 From 8961dd9fe74a3ba6e55bfb1b8132a93de920a1dc Mon Sep 17 00:00:00 2001 From: Daniel Pollard Date: Wed, 6 May 2020 09:05:14 +1000 Subject: changed build variables as per advice --- py/circuitpy_mpconfig.mk | 4 ++-- shared-bindings/countio/Counter.c | 5 ++--- 2 files changed, 4 insertions(+), 5 deletions(-) (limited to 'shared-bindings') diff --git a/py/circuitpy_mpconfig.mk b/py/circuitpy_mpconfig.mk index 7ef87a7ea..be1e0ad9a 100644 --- a/py/circuitpy_mpconfig.mk +++ b/py/circuitpy_mpconfig.mk @@ -110,7 +110,7 @@ endif CFLAGS += -DCIRCUITPY_DIGITALIO=$(CIRCUITPY_DIGITALIO) ifndef CIRCUITPY_COUNTIO -CIRCUITPY_COUNTIO = 1 +CIRCUITPY_COUNTIO ?= 1 endif CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO) @@ -214,7 +214,7 @@ endif CFLAGS += -DCIRCUITPY_ROTARYIO=$(CIRCUITPY_ROTARYIO) ifndef CIRCUITPY_COUNTIO -CIRCUITPY_COUNTIO = 1 +CIRCUITPY_COUNTIO = $(CIRCUITPY_FULL_BUILD) endif CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO) diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c index c10294199..efa3387a6 100644 --- a/shared-bindings/countio/Counter.c +++ b/shared-bindings/countio/Counter.c @@ -31,10 +31,9 @@ //| from board import * //| //| pin_counter = countio.Counter(board.D1) -//| +//| #reset the count after 100 counts //| while True: -//| count = pin_counter.count -//| if count == None 10: +//| if pin_counter.count == 100: //| pin_counter.reset() //| print(pin_counter.count) //| -- cgit v1.2.3 From 84c806a4bebb72b8deaae8cb5cada9d5ab7aa41b Mon Sep 17 00:00:00 2001 From: Daniel Pollard Date: Thu, 7 May 2020 12:42:46 +1000 Subject: updated descriptions and build variable --- py/circuitpy_mpconfig.mk | 2 +- shared-bindings/countio/Counter.c | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'shared-bindings') diff --git a/py/circuitpy_mpconfig.mk b/py/circuitpy_mpconfig.mk index be1e0ad9a..95e3512f1 100644 --- a/py/circuitpy_mpconfig.mk +++ b/py/circuitpy_mpconfig.mk @@ -110,7 +110,7 @@ endif CFLAGS += -DCIRCUITPY_DIGITALIO=$(CIRCUITPY_DIGITALIO) ifndef CIRCUITPY_COUNTIO -CIRCUITPY_COUNTIO ?= 1 +CIRCUITPY_COUNTIO = 1 endif CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO) diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c index efa3387a6..1777acc8a 100644 --- a/shared-bindings/countio/Counter.c +++ b/shared-bindings/countio/Counter.c @@ -11,15 +11,15 @@ //| .. currentmodule:: countio //| -//| :class:`Counter` -- Track the count of edge transistions (pulses) on a given pin +//| :class:`Counter` -- Track the count of falling edge transistions (pulses) on a given pin //| ==================================================================================== //| -//| Counter will keep track of the number of edge transistions (pulses) on a given pin +//| Counter will keep track of the number of falling edge transistions (pulses) on a given pin //| //| .. class:: Counter(pin_a) //| //| Create an Counter object associated with the given pin. It tracks the number of -//| pulses relative when the object is contructed. +//| falling pulses relative when the object is constructed. //| //| :param ~microcontroller.Pin pin_a: Pin to read pulses from. //| -- cgit v1.2.3 From 2ebe3035dff0ce66b2fe65eb91d6889c4ba93b5c Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 7 May 2020 10:54:09 -0400 Subject: Did board, digitalio, displayio --- shared-bindings/board/__init__.c | 33 +++-- shared-bindings/digitalio/DigitalInOut.c | 109 +++++++-------- shared-bindings/digitalio/Direction.c | 25 ++-- shared-bindings/digitalio/DriveMode.c | 27 ++-- shared-bindings/digitalio/Pull.c | 29 ++-- shared-bindings/digitalio/__init__.c | 4 +- shared-bindings/displayio/Bitmap.c | 65 +++++---- shared-bindings/displayio/ColorConverter.c | 31 +++-- shared-bindings/displayio/Display.c | 216 ++++++++++++++--------------- shared-bindings/displayio/EPaperDisplay.c | 128 ++++++++--------- shared-bindings/displayio/FourWire.c | 57 ++++---- shared-bindings/displayio/Group.c | 115 ++++++++------- shared-bindings/displayio/I2CDisplay.c | 47 ++++--- shared-bindings/displayio/OnDiskBitmap.c | 79 ++++++----- shared-bindings/displayio/Palette.c | 58 ++++---- shared-bindings/displayio/ParallelBus.c | 58 ++++---- shared-bindings/displayio/Shape.c | 31 +++-- shared-bindings/displayio/TileGrid.c | 107 +++++++------- shared-bindings/displayio/__init__.c | 18 +-- 19 files changed, 610 insertions(+), 627 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c index 3dda59fb8..501879be8 100644 --- a/shared-bindings/board/__init__.c +++ b/shared-bindings/board/__init__.c @@ -29,7 +29,7 @@ #include "shared-bindings/board/__init__.h" -//| :mod:`board` --- Board specific pin names +//| """:mod:`board` --- Board specific pin names //| ======================================================== //| //| .. module:: board @@ -39,11 +39,11 @@ //| board so don't expect portability when using this module. //| //| .. warning:: The board module varies by board. The APIs documented here may or may not be -//| available on a specific board. +//| available on a specific board.""" -//| .. function:: I2C() -//| -//| Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton. +//| def I2C() -> Any: +//| """Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton.""" +//| ... //| #if BOARD_I2C @@ -65,10 +65,10 @@ mp_obj_t board_i2c(void) { MP_DEFINE_CONST_FUN_OBJ_0(board_i2c_obj, board_i2c); -//| .. function:: SPI() -//| -//| Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a -//| singleton. +//| def SPI() -> Any: +//| """Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a +//| singleton.""" +//| ... //| #if BOARD_SPI mp_obj_t board_spi(void) { @@ -89,15 +89,14 @@ mp_obj_t board_spi(void) { #endif MP_DEFINE_CONST_FUN_OBJ_0(board_spi_obj, board_spi); -//| .. function:: UART() -//| -//| Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. -//| -//| The object created uses the default parameter values for `busio.UART`. If you need to set -//| parameters that are not changeable after creation, such as ``receiver_buffer_size``, -//| do not use `board.UART()`; instead create a `busio.UART` object explicitly with the -//| desired parameters. +//| def UART() -> Any: +//| """Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. //| +//| The object created uses the default parameter values for `busio.UART`. If you need to set +//| parameters that are not changeable after creation, such as ``receiver_buffer_size``, +//| do not use `board.UART()`; instead create a `busio.UART` object explicitly with the +//| desired parameters.""" +//| ... //| #if BOARD_UART mp_obj_t board_uart(void) { diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 39da00cf7..5fffb3f65 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -43,23 +43,23 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: digitalio +//| class DigitalInOut: +//| """.. currentmodule:: digitalio //| -//| :class:`DigitalInOut` -- digital input and output -//| ========================================================= +//| :class:`DigitalInOut` -- digital input and output +//| ========================================================= //| -//| A DigitalInOut is used to digitally control I/O pins. For analog control of -//| a pin, see the :py:class:`analogio.AnalogIn` and -//| :py:class:`analogio.AnalogOut` classes. +//| A DigitalInOut is used to digitally control I/O pins. For analog control of +//| a pin, see the :py:class:`analogio.AnalogIn` and +//| :py:class:`analogio.AnalogOut` classes.""" //| - -//| .. class:: DigitalInOut(pin) -//| -//| Create a new DigitalInOut object associated with the pin. Defaults to input -//| with no pull. Use :py:meth:`switch_to_input` and -//| :py:meth:`switch_to_output` to change the direction. +//| def __init__(self, pin: microcontroller.Pin): +//| """Create a new DigitalInOut object associated with the pin. Defaults to input +//| with no pull. Use :py:meth:`switch_to_input` and +//| :py:meth:`switch_to_output` to change the direction. //| -//| :param ~microcontroller.Pin pin: The pin to control +//| :param ~microcontroller.Pin pin: The pin to control""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -74,9 +74,9 @@ STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Turn off the DigitalInOut and release the pin for other use. +//| def deinit(self, ) -> Any: +//| """Turn off the DigitalInOut and release the pin for other use.""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -85,16 +85,16 @@ STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalinout_obj_deinit); -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -109,14 +109,13 @@ STATIC void check_for_deinit(digitalio_digitalinout_obj_t *self) { } } +//| def switch_to_output(self, value: bool = False, drive_mode: digitalio.DriveMode = digitalio.DriveMode.PUSH_PULL) -> Any: +//| """Set the drive mode and value and then switch to writing out digital +//| values. //| -//| .. method:: switch_to_output(value=False, drive_mode=digitalio.DriveMode.PUSH_PULL) -//| -//| Set the drive mode and value and then switch to writing out digital -//| values. -//| -//| :param bool value: default value to set upon switching -//| :param ~digitalio.DriveMode drive_mode: drive mode for the output +//| :param bool value: default value to set upon switching +//| :param ~digitalio.DriveMode drive_mode: drive mode for the output""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_value, ARG_drive_mode }; @@ -139,22 +138,22 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digitalio_digitalinout_switch_to_output); -//| .. method:: switch_to_input(pull=None) -//| -//| Set the pull and then switch to read in digital values. +//| def switch_to_input(self, pull: Pull = None) -> Any: +//| """Set the pull and then switch to read in digital values. //| -//| :param Pull pull: pull configuration for the input +//| :param Pull pull: pull configuration for the input //| -//| Example usage:: +//| Example usage:: //| -//| import digitalio -//| import board +//| import digitalio +//| import board //| -//| switch = digitalio.DigitalInOut(board.SLIDE_SWITCH) -//| switch.switch_to_input(pull=digitalio.Pull.UP) -//| # Or, after switch_to_input -//| switch.pull = digitalio.Pull.UP -//| print(switch.value) +//| switch = digitalio.DigitalInOut(board.SLIDE_SWITCH) +//| switch.switch_to_input(pull=digitalio.Pull.UP) +//| # Or, after switch_to_input +//| switch.pull = digitalio.Pull.UP +//| print(switch.value)""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pull }; @@ -178,14 +177,13 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_o } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_input_obj, 1, digitalio_digitalinout_switch_to_input); -//| .. attribute:: direction -//| -//| The direction of the pin. +//| direction: Any = ... +//| """The direction of the pin. //| //| Setting this will use the defaults from the corresponding //| :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If //| you want to set pull, value or drive mode prior to switching, then use -//| those methods instead. +//| those methods instead.""" //| typedef struct { mp_obj_base_t base; @@ -225,9 +223,8 @@ const mp_obj_property_t digitalio_digitalio_direction_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: value -//| -//| The digital logic level of the pin. +//| value: Any = ... +//| """The digital logic level of the pin.""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_value(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -256,12 +253,11 @@ const mp_obj_property_t digitalio_digitalinout_value_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: drive_mode -//| -//| The pin drive mode. One of: +//| drive_mode: Any = ... +//| """The pin drive mode. One of: //| //| - `digitalio.DriveMode.PUSH_PULL` -//| - `digitalio.DriveMode.OPEN_DRAIN` +//| - `digitalio.DriveMode.OPEN_DRAIN`""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -301,15 +297,14 @@ const mp_obj_property_t digitalio_digitalio_drive_mode_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: pull -//| -//| The pin pull direction. One of: +//| pull: Any = ... +//| """The pin pull direction. One of: //| //| - `digitalio.Pull.UP` //| - `digitalio.Pull.DOWN` //| - `None` //| -//| :raises AttributeError: if `direction` is :py:data:`~digitalio.Direction.OUTPUT`. +//| :raises AttributeError: if `direction` is :py:data:`~digitalio.Direction.OUTPUT`.""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_pull(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/digitalio/Direction.c b/shared-bindings/digitalio/Direction.c index c8188fc89..0586e95de 100644 --- a/shared-bindings/digitalio/Direction.c +++ b/shared-bindings/digitalio/Direction.c @@ -38,23 +38,22 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/digitalio/DigitalInOut.h" -//| .. currentmodule:: digitalio +//| class Direction: +//| """.. currentmodule:: digitalio //| -//| :class:`Direction` -- defines the direction of a digital pin -//| ============================================================= +//| :class:`Direction` -- defines the direction of a digital pin +//| =============================================================""" //| -//| .. class:: Direction +//| def __init__(self, ): +//| """Enum-like class to define which direction the digital values are +//| going.""" +//| ... //| -//| Enum-like class to define which direction the digital values are -//| going. +//| INPUT: Any = ... +//| """Read digital data in""" //| -//| .. data:: INPUT -//| -//| Read digital data in -//| -//| .. data:: OUTPUT -//| -//| Write digital data out +//| OUTPUT: Any = ... +//| """Write digital data out""" //| const mp_obj_type_t digitalio_direction_type; diff --git a/shared-bindings/digitalio/DriveMode.c b/shared-bindings/digitalio/DriveMode.c index 51e1e2ee5..23745b046 100644 --- a/shared-bindings/digitalio/DriveMode.c +++ b/shared-bindings/digitalio/DriveMode.c @@ -26,24 +26,23 @@ #include "shared-bindings/digitalio/DriveMode.h" -//| .. currentmodule:: digitalio +//| class DriveMode: +//| """.. currentmodule:: digitalio //| -//| :class:`DriveMode` -- defines the drive mode of a digital pin -//| ============================================================= +//| :class:`DriveMode` -- defines the drive mode of a digital pin +//| =============================================================""" //| -//| .. class:: DriveMode +//| def __init__(self, ): +//| """Enum-like class to define the drive mode used when outputting +//| digital values.""" +//| ... //| -//| Enum-like class to define the drive mode used when outputting -//| digital values. +//| PUSH_PULL: Any = ... +//| """Output both high and low digital values""" //| -//| .. data:: PUSH_PULL -//| -//| Output both high and low digital values -//| -//| .. data:: OPEN_DRAIN -//| -//| Output low digital values but go into high z for digital high. This is -//| useful for i2c and other protocols that share a digital line. +//| OPEN_DRAIN: Any = ... +//| """Output low digital values but go into high z for digital high. This is +//| useful for i2c and other protocols that share a digital line.""" //| const mp_obj_type_t digitalio_drive_mode_type; diff --git a/shared-bindings/digitalio/Pull.c b/shared-bindings/digitalio/Pull.c index 813268db7..1e64d0788 100644 --- a/shared-bindings/digitalio/Pull.c +++ b/shared-bindings/digitalio/Pull.c @@ -26,25 +26,24 @@ #include "shared-bindings/digitalio/Pull.h" -//| .. currentmodule:: digitalio +//| class Pull: +//| """.. currentmodule:: digitalio //| -//| :class:`Pull` -- defines the pull of a digital input pin -//| ============================================================= +//| :class:`Pull` -- defines the pull of a digital input pin +//| =============================================================""" //| -//| .. class:: Pull +//| def __init__(self, ): +//| """Enum-like class to define the pull value, if any, used while reading +//| digital values in.""" +//| ... //| -//| Enum-like class to define the pull value, if any, used while reading -//| digital values in. +//| UP: Any = ... +//| """When the input line isn't being driven the pull up can pull the state +//| of the line high so it reads as true.""" //| -//| .. data:: UP -//| -//| When the input line isn't being driven the pull up can pull the state -//| of the line high so it reads as true. -//| -//| .. data:: DOWN -//| -//| When the input line isn't being driven the pull down can pull the -//| state of the line low so it reads as false. +//| DOWN: Any = ... +//| """When the input line isn't being driven the pull down can pull the +//| state of the line low so it reads as false.""" //| const mp_obj_type_t digitalio_pull_type; diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c index 1632262d2..5a11436a2 100644 --- a/shared-bindings/digitalio/__init__.c +++ b/shared-bindings/digitalio/__init__.c @@ -38,7 +38,7 @@ #include "py/runtime.h" -//| :mod:`digitalio` --- Basic digital pin support +//| """:mod:`digitalio` --- Basic digital pin support //| ================================================= //| //| .. module:: digitalio @@ -86,7 +86,7 @@ //| led.value = True //| time.sleep(0.1) //| led.value = False -//| time.sleep(0.1) +//| time.sleep(0.1)""" //| STATIC const mp_rom_map_elem_t digitalio_module_globals_table[] = { diff --git a/shared-bindings/displayio/Bitmap.c b/shared-bindings/displayio/Bitmap.c index 391f3e595..d15c3b107 100644 --- a/shared-bindings/displayio/Bitmap.c +++ b/shared-bindings/displayio/Bitmap.c @@ -36,22 +36,23 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Bitmap: +//| """.. currentmodule:: displayio //| -//| :class:`Bitmap` -- Stores values in a 2D array -//| ========================================================================== +//| :class:`Bitmap` -- Stores values in a 2D array +//| ========================================================================== //| -//| Stores values of a certain size in a 2D array +//| Stores values of a certain size in a 2D array""" //| -//| .. class:: Bitmap(width, height, value_count) +//| def __init__(self, width: int, height: int, value_count: int): +//| """Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to +//| index into a corresponding palette. This enables differently colored sprites to share the +//| underlying Bitmap. value_count is used to minimize the memory used to store the Bitmap. //| -//| Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to -//| index into a corresponding palette. This enables differently colored sprites to share the -//| underlying Bitmap. value_count is used to minimize the memory used to store the Bitmap. -//| -//| :param int width: The number of values wide -//| :param int height: The number of values high -//| :param int value_count: The number of possible pixel values. +//| :param int width: The number of values wide +//| :param int height: The number of values high +//| :param int value_count: The number of possible pixel values.""" +//| ... //| STATIC mp_obj_t displayio_bitmap_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 3, 3, false); @@ -77,9 +78,8 @@ STATIC mp_obj_t displayio_bitmap_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. attribute:: width -//| -//| Width of the bitmap. (read only) +//| width: Any = ... +//| """Width of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_bitmap_obj_get_width(mp_obj_t self_in) { displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in); @@ -96,9 +96,8 @@ const mp_obj_property_t displayio_bitmap_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Height of the bitmap. (read only) +//| height: Any = ... +//| """Height of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_bitmap_obj_get_height(mp_obj_t self_in) { displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in); @@ -115,23 +114,23 @@ const mp_obj_property_t displayio_bitmap_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __getitem__(index) +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the value at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| Returns the value at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. +//| This allows you to:: //| -//| This allows you to:: +//| print(bitmap[0,1])""" +//| ... //| -//| print(bitmap[0,1]) +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the value at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| .. method:: __setitem__(index, value) +//| This allows you to:: //| -//| Sets the value at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. -//| -//| This allows you to:: -//| -//| bitmap[0,1] = 3 +//| bitmap[0,1] = 3""" +//| ... //| STATIC mp_obj_t bitmap_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value_obj) { if (value_obj == mp_const_none) { @@ -178,9 +177,9 @@ STATIC mp_obj_t bitmap_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t val return mp_const_none; } -//| .. method:: fill(value) -//| -//| Fills the bitmap with the supplied palette index value. +//| def fill(self, value: Any) -> Any: +//| """Fills the bitmap with the supplied palette index value.""" +//| ... //| STATIC mp_obj_t displayio_bitmap_obj_fill(mp_obj_t self_in, mp_obj_t value_obj) { displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/ColorConverter.c b/shared-bindings/displayio/ColorConverter.c index db2d1b6e2..1d6e5a0cc 100644 --- a/shared-bindings/displayio/ColorConverter.c +++ b/shared-bindings/displayio/ColorConverter.c @@ -36,18 +36,20 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class ColorConverter: +//| """.. currentmodule:: displayio //| -//| :class:`ColorConverter` -- Converts one color format to another -//| ========================================================================================= +//| :class:`ColorConverter` -- Converts one color format to another +//| ========================================================================================= //| -//| Converts one color format to another. +//| Converts one color format to another.""" //| -//| .. class:: ColorConverter(*, dither=False) +//| def __init__(self, *, dither: bool = False): +//| """Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 +//| currently. +//| :param bool dither: Adds random noise to dither the output image""" +//| ... //| -//| Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 -//| currently. -//| :param bool dither: Adds random noise to dither the output image // TODO(tannewt): Add support for other color formats. //| @@ -68,9 +70,9 @@ STATIC mp_obj_t displayio_colorconverter_make_new(const mp_obj_type_t *type, siz return MP_OBJ_FROM_PTR(self); } -//| .. method:: convert(color) -//| -//| Converts the given RGB888 color to RGB565 +//| def convert(self, color: Any) -> Any: +//| """Converts the given RGB888 color to RGB565""" +//| ... //| STATIC mp_obj_t displayio_colorconverter_obj_convert(mp_obj_t self_in, mp_obj_t color_obj) { displayio_colorconverter_t *self = MP_OBJ_TO_PTR(self_in); @@ -87,10 +89,9 @@ STATIC mp_obj_t displayio_colorconverter_obj_convert(mp_obj_t self_in, mp_obj_t } MP_DEFINE_CONST_FUN_OBJ_2(displayio_colorconverter_convert_obj, displayio_colorconverter_obj_convert); -//| .. attribute:: dither -//| -//| When true the color converter dithers the output by adding random noise when -//| truncating to display bitdepth +//| dither: Any = ... +//| """When true the color converter dithers the output by adding random noise when +//| truncating to display bitdepth""" //| STATIC mp_obj_t displayio_colorconverter_obj_get_dither(mp_obj_t self_in) { displayio_colorconverter_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c index a22b2add2..12abec1c8 100644 --- a/shared-bindings/displayio/Display.c +++ b/shared-bindings/displayio/Display.c @@ -39,73 +39,74 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio -//| -//| :class:`Display` -- Manage updating a display over a display bus -//| ========================================================================== -//| -//| This initializes a display and connects it into CircuitPython. Unlike other -//| objects in CircuitPython, Display objects live until `displayio.release_displays()` -//| is called. This is done so that CircuitPython can use the display itself. -//| -//| Most people should not use this class directly. Use a specific display driver instead that will -//| contain the initialization sequence at minimum. -//| -//| .. class:: Display(display_bus, init_sequence, *, width, height, colstart=0, rowstart=0, rotation=0, color_depth=16, grayscale=False, pixels_in_byte_share_row=True, bytes_per_cell=1, reverse_pixels_in_byte=False, set_column_command=0x2a, set_row_command=0x2b, write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness_command=None, brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False, auto_refresh=True, native_frames_per_second=60) -//| -//| Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). -//| -//| The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a -//| command byte followed by a byte to determine the parameter count and if a delay is need after. -//| When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds. -//| The remaining 7 bits are the parameter count excluding any delay byte. The third through final -//| bytes are the remaining command parameters. The next byte will begin a new command definition. -//| Here is a portion of ILI9341 init code: -//| -//| .. code-block:: python -//| -//| init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma -//| b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms) -//| b"\x29\x80\x78"# Display on then delay 0x78 (120ms) -//| ) -//| display = displayio.Display(display_bus, init_sequence, width=320, height=240) -//| -//| The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and -//| 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. Multiple byte literals -//| (b"") are merged together on load. The parens are needed to allow byte literals on subsequent -//| lines. -//| -//| The initialization sequence should always leave the display memory access inline with the scan -//| of the display to minimize tearing artifacts. -//| -//| :param display_bus: The bus that the display is connected to -//| :type display_bus: displayio.FourWire or displayio.ParallelBus -//| :param buffer init_sequence: Byte-packed initialization sequence. -//| :param int width: Width in pixels -//| :param int height: Height in pixels -//| :param int colstart: The index if the first visible column -//| :param int rowstart: The index if the first visible row -//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) -//| :param int color_depth: The number of bits of color per pixel transmitted. (Some displays -//| support 18 bit but 16 is easier to transmit. The last bit is extrapolated.) -//| :param bool grayscale: True if the display only shows a single color. -//| :param bool pixels_in_byte_share_row: True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column. -//| :param int bytes_per_cell: Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row. -//| :param bool reverse_pixels_in_byte: Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.) -//| :param bool reverse_bytes_in_word: Reverses the order of bytes within a word when color_depth == 16 -//| :param int set_column_command: Command used to set the start and end columns to update -//| :param int set_row_command: Command used so set the start and end rows to update -//| :param int write_ram_command: Command used to write pixels values into the update region. Ignored if data_as_commands is set. -//| :param int set_vertical_scroll: Command used to set the first row to show -//| :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight -//| :param int brightness_command: Command to set display brightness. Usually available in OLED controllers. -//| :param bool brightness: Initial display brightness. This value is ignored if auto_brightness is True. -//| :param bool auto_brightness: If True, brightness is controlled via an ambient light sensor or other mechanism. -//| :param bool single_byte_bounds: Display column and row commands use single bytes -//| :param bool data_as_commands: Treat all init and boundary data as SPI commands. Certain displays require this. -//| :param bool auto_refresh: Automatically refresh the screen -//| :param int native_frames_per_second: Number of display refreshes per second that occur with the given init_sequence. -//| :param bool backlight_on_high: If True, pulling the backlight pin high turns the backlight on. +//| class Display: +//| """.. currentmodule:: displayio +//| +//| :class:`Display` -- Manage updating a display over a display bus +//| ========================================================================== +//| +//| This initializes a display and connects it into CircuitPython. Unlike other +//| objects in CircuitPython, Display objects live until `displayio.release_displays()` +//| is called. This is done so that CircuitPython can use the display itself. +//| +//| Most people should not use this class directly. Use a specific display driver instead that will +//| contain the initialization sequence at minimum.""" +//| +//| def __init__(self, display_bus: Any, init_sequence: buffer, *, width: int, height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, color_depth: int = 16, grayscale: bool = False, pixels_in_byte_share_row: bool = True, bytes_per_cell: int = 1, reverse_pixels_in_byte: bool = False, set_column_command: int = 0x2a, set_row_command: int = 0x2b, write_ram_command: int = 0x2c, set_vertical_scroll: int = 0, backlight_pin: microcontroller.Pin = None, brightness_command: int = None, brightness: bool = 1.0, auto_brightness: bool = False, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60): +//| """Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). +//| +//| The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a +//| command byte followed by a byte to determine the parameter count and if a delay is need after. +//| When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds. +//| The remaining 7 bits are the parameter count excluding any delay byte. The third through final +//| bytes are the remaining command parameters. The next byte will begin a new command definition. +//| Here is a portion of ILI9341 init code: +//| +//| .. code-block:: python +//| +//| init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma +//| b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms) +//| b"\x29\x80\x78"# Display on then delay 0x78 (120ms) +//| ) +//| display = displayio.Display(display_bus, init_sequence, width=320, height=240) +//| +//| The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and +//| 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. Multiple byte literals +//| (b"") are merged together on load. The parens are needed to allow byte literals on subsequent +//| lines. +//| +//| The initialization sequence should always leave the display memory access inline with the scan +//| of the display to minimize tearing artifacts. +//| +//| :param display_bus: The bus that the display is connected to +//| :type display_bus: displayio.FourWire or displayio.ParallelBus +//| :param buffer init_sequence: Byte-packed initialization sequence. +//| :param int width: Width in pixels +//| :param int height: Height in pixels +//| :param int colstart: The index if the first visible column +//| :param int rowstart: The index if the first visible row +//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) +//| :param int color_depth: The number of bits of color per pixel transmitted. (Some displays +//| support 18 bit but 16 is easier to transmit. The last bit is extrapolated.) +//| :param bool grayscale: True if the display only shows a single color. +//| :param bool pixels_in_byte_share_row: True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column. +//| :param int bytes_per_cell: Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row. +//| :param bool reverse_pixels_in_byte: Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.) +//| :param bool reverse_bytes_in_word: Reverses the order of bytes within a word when color_depth == 16 +//| :param int set_column_command: Command used to set the start and end columns to update +//| :param int set_row_command: Command used so set the start and end rows to update +//| :param int write_ram_command: Command used to write pixels values into the update region. Ignored if data_as_commands is set. +//| :param int set_vertical_scroll: Command used to set the first row to show +//| :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight +//| :param int brightness_command: Command to set display brightness. Usually available in OLED controllers. +//| :param bool brightness: Initial display brightness. This value is ignored if auto_brightness is True. +//| :param bool auto_brightness: If True, brightness is controlled via an ambient light sensor or other mechanism. +//| :param bool single_byte_bounds: Display column and row commands use single bytes +//| :param bool data_as_commands: Treat all init and boundary data as SPI commands. Certain displays require this. +//| :param bool auto_refresh: Automatically refresh the screen +//| :param int native_frames_per_second: Number of display refreshes per second that occur with the given init_sequence. +//| :param bool backlight_on_high: If True, pulling the backlight pin high turns the backlight on.""" +//| ... //| STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_display_bus, ARG_init_sequence, ARG_width, ARG_height, ARG_colstart, ARG_rowstart, ARG_rotation, ARG_color_depth, ARG_grayscale, ARG_pixels_in_byte_share_row, ARG_bytes_per_cell, ARG_reverse_pixels_in_byte, ARG_reverse_bytes_in_word, ARG_set_column_command, ARG_set_row_command, ARG_write_ram_command, ARG_set_vertical_scroll, ARG_backlight_pin, ARG_brightness_command, ARG_brightness, ARG_auto_brightness, ARG_single_byte_bounds, ARG_data_as_commands, ARG_auto_refresh, ARG_native_frames_per_second, ARG_backlight_on_high }; @@ -190,12 +191,13 @@ static displayio_display_obj_t* native_display(mp_obj_t display_obj) { return MP_OBJ_TO_PTR(native_display); } -//| .. method:: show(group) +//| def show(self, group: Group) -> Any: +//| """Switches to displaying the given group of layers. When group is None, the default +//| CircuitPython terminal will be shown. //| -//| Switches to displaying the given group of layers. When group is None, the default -//| CircuitPython terminal will be shown. +//| :param Group group: The group to show.""" +//| ... //| -//| :param Group group: The group to show. STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) { displayio_display_obj_t *self = native_display(self_in); displayio_group_t* group = NULL; @@ -211,21 +213,21 @@ STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) } MP_DEFINE_CONST_FUN_OBJ_2(displayio_display_show_obj, displayio_display_obj_show); -//| .. method:: refresh(*, target_frames_per_second=60, minimum_frames_per_second=1) -//| -//| When auto refresh is off, waits for the target frame rate and then refreshes the display, -//| returning True. If the call has taken too long since the last refresh call for the given -//| target frame rate, then the refresh returns False immediately without updating the screen to -//| hopefully help getting caught up. +//| def refresh(self, *, target_frames_per_second: int = 60, minimum_frames_per_second: int = 1) -> Any: +//| """When auto refresh is off, waits for the target frame rate and then refreshes the display, +//| returning True. If the call has taken too long since the last refresh call for the given +//| target frame rate, then the refresh returns False immediately without updating the screen to +//| hopefully help getting caught up. //| -//| If the time since the last successful refresh is below the minimum frame rate, then an -//| exception will be raised. Set minimum_frames_per_second to 0 to disable. +//| If the time since the last successful refresh is below the minimum frame rate, then an +//| exception will be raised. Set minimum_frames_per_second to 0 to disable. //| -//| When auto refresh is on, updates the display immediately. (The display will also update -//| without calls to this.) +//| When auto refresh is on, updates the display immediately. (The display will also update +//| without calls to this.) //| -//| :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated. -//| :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second. +//| :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated. +//| :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second.""" +//| ... //| STATIC mp_obj_t displayio_display_obj_refresh(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_target_frames_per_second, ARG_minimum_frames_per_second }; @@ -246,9 +248,8 @@ STATIC mp_obj_t displayio_display_obj_refresh(size_t n_args, const mp_obj_t *pos } MP_DEFINE_CONST_FUN_OBJ_KW(displayio_display_refresh_obj, 1, displayio_display_obj_refresh); -//| .. attribute:: auto_refresh -//| -//| True when the display is refreshed automatically. +//| auto_refresh: Any = ... +//| """True when the display is refreshed automatically.""" //| STATIC mp_obj_t displayio_display_obj_get_auto_refresh(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -272,11 +273,10 @@ const mp_obj_property_t displayio_display_auto_refresh_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: brightness -//| -//| The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When +//| brightness: Any = ... +//| """The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When //| `auto_brightness` is True, the value of `brightness` will change automatically. -//| If `brightness` is set, `auto_brightness` will be disabled and will be set to False. +//| If `brightness` is set, `auto_brightness` will be disabled and will be set to False.""" //| STATIC mp_obj_t displayio_display_obj_get_brightness(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -310,12 +310,11 @@ const mp_obj_property_t displayio_display_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: auto_brightness -//| -//| True when the display brightness is adjusted automatically, based on an ambient +//| auto_brightness: Any = ... +//| """True when the display brightness is adjusted automatically, based on an ambient //| light sensor or other method. Note that some displays may have this set to True by default, //| but not actually implement automatic brightness adjustment. `auto_brightness` is set to False -//| if `brightness` is set manually. +//| if `brightness` is set manually.""" //| STATIC mp_obj_t displayio_display_obj_get_auto_brightness(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -342,9 +341,8 @@ const mp_obj_property_t displayio_display_auto_brightness_obj = { -//| .. attribute:: width -//| -//| Gets the width of the board +//| width: Any = ... +//| Gets the width of the board //| //| STATIC mp_obj_t displayio_display_obj_get_width(mp_obj_t self_in) { @@ -360,9 +358,8 @@ const mp_obj_property_t displayio_display_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Gets the height of the board +//| height: Any = ... +//| """Gets the height of the board""" //| //| STATIC mp_obj_t displayio_display_obj_get_height(mp_obj_t self_in) { @@ -378,9 +375,8 @@ const mp_obj_property_t displayio_display_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: rotation -//| -//| The rotation of the display as an int in degrees. +//| rotation: Any = ... +//| """The rotation of the display as an int in degrees.""" //| STATIC mp_obj_t displayio_display_obj_get_rotation(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -402,9 +398,8 @@ const mp_obj_property_t displayio_display_rotation_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: bus -//| -//| The bus being used by the display +//| bus: Any = ... +//| """The bus being used by the display""" //| //| STATIC mp_obj_t displayio_display_obj_get_bus(mp_obj_t self_in) { @@ -421,12 +416,13 @@ const mp_obj_property_t displayio_display_bus_obj = { }; -//| .. method:: fill_row(y, buffer) +//| def fill_row(self, y: int, buffer: bytearray) -> Any: +//| """Extract the pixels from a single row //| -//| Extract the pixels from a single row +//| :param int y: The top edge of the area +//| :param bytearray buffer: The buffer in which to place the pixel data""" +//| ... //| -//| :param int y: The top edge of the area -//| :param bytearray buffer: The buffer in which to place the pixel data STATIC mp_obj_t displayio_display_obj_fill_row(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_y, ARG_buffer }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/displayio/EPaperDisplay.c b/shared-bindings/displayio/EPaperDisplay.c index 1459c1680..8b03ddc06 100644 --- a/shared-bindings/displayio/EPaperDisplay.c +++ b/shared-bindings/displayio/EPaperDisplay.c @@ -39,55 +39,56 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class EPaperDisplay: +//| """.. currentmodule:: displayio //| -//| :class:`EPaperDisplay` -- Manage updating an epaper display over a display bus -//| ============================================================================== +//| :class:`EPaperDisplay` -- Manage updating an epaper display over a display bus +//| ============================================================================== //| -//| This initializes an epaper display and connects it into CircuitPython. Unlike other -//| objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()` -//| is called. This is done so that CircuitPython can use the display itself. +//| This initializes an epaper display and connects it into CircuitPython. Unlike other +//| objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()` +//| is called. This is done so that CircuitPython can use the display itself. //| -//| Most people should not use this class directly. Use a specific display driver instead that will -//| contain the startup and shutdown sequences at minimum. +//| Most people should not use this class directly. Use a specific display driver instead that will +//| contain the startup and shutdown sequences at minimum.""" //| -//| .. class:: EPaperDisplay(display_bus, start_sequence, stop_sequence, *, width, height, ram_width, ram_height, colstart=0, rowstart=0, rotation=0, set_column_window_command=None, set_row_window_command=None, single_byte_bounds=False, write_black_ram_command, black_bits_inverted=False, write_color_ram_command=None, color_bits_inverted=False, highlight_color=0x000000, refresh_display_command, refresh_time=40, busy_pin=None, busy_state=True, seconds_per_frame=180, always_toggle_chip_select=False) +//| def __init__(self, display_bus: Any, start_sequence: buffer, stop_sequence: buffer, *, width: int, height: int, ram_width: int, ram_height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, set_column_window_command: int = None, set_row_window_command: int = None, single_byte_bounds: Any = False, write_black_ram_command: int, black_bits_inverted: bool = False, write_color_ram_command: int = None, color_bits_inverted: bool = False, highlight_color: int = 0x000000, refresh_display_command: int, refresh_time: float = 40, busy_pin: microcontroller.Pin = None, busy_state: bool = True, seconds_per_frame: float = 180, always_toggle_chip_select: bool = False): +//| """Create a EPaperDisplay object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). //| -//| Create a EPaperDisplay object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). +//| The ``start_sequence`` and ``stop_sequence`` are bitpacked to minimize the ram impact. Every +//| command begins with a command byte followed by a byte to determine the parameter count and if +//| a delay is need after. When the top bit of the second byte is 1, the next byte will be the +//| delay time in milliseconds. The remaining 7 bits are the parameter count excluding any delay +//| byte. The third through final bytes are the remaining command parameters. The next byte will +//| begin a new command definition. //| -//| The ``start_sequence`` and ``stop_sequence`` are bitpacked to minimize the ram impact. Every -//| command begins with a command byte followed by a byte to determine the parameter count and if -//| a delay is need after. When the top bit of the second byte is 1, the next byte will be the -//| delay time in milliseconds. The remaining 7 bits are the parameter count excluding any delay -//| byte. The third through final bytes are the remaining command parameters. The next byte will -//| begin a new command definition. -//| -//| :param display_bus: The bus that the display is connected to -//| :type display_bus: displayio.FourWire or displayio.ParallelBus -//| :param buffer start_sequence: Byte-packed initialization sequence. -//| :param buffer stop_sequence: Byte-packed initialization sequence. -//| :param int width: Width in pixels -//| :param int height: Height in pixels -//| :param int ram_width: RAM width in pixels -//| :param int ram_height: RAM height in pixels -//| :param int colstart: The index if the first visible column -//| :param int rowstart: The index if the first visible row -//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) -//| :param int set_column_window_command: Command used to set the start and end columns to update -//| :param int set_row_window_command: Command used so set the start and end rows to update -//| :param int set_current_column_command: Command used to set the current column location -//| :param int set_current_row_command: Command used to set the current row location -//| :param int write_black_ram_command: Command used to write pixels values into the update region -//| :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise, 1 means to show black. -//| :param int write_color_ram_command: Command used to write pixels values into the update region -//| :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1 means to show color. -//| :param int highlight_color: RGB888 of source color to highlight with third ePaper color. -//| :param int refresh_display_command: Command used to start a display refresh -//| :param float refresh_time: Time it takes to refresh the display before the stop_sequence should be sent. Ignored when busy_pin is provided. -//| :param microcontroller.Pin busy_pin: Pin used to signify the display is busy -//| :param bool busy_state: State of the busy pin when the display is busy -//| :param float seconds_per_frame: Minimum number of seconds between screen refreshes -//| :param bool always_toggle_chip_select: When True, chip select is toggled every byte +//| :param display_bus: The bus that the display is connected to +//| :type display_bus: displayio.FourWire or displayio.ParallelBus +//| :param buffer start_sequence: Byte-packed initialization sequence. +//| :param buffer stop_sequence: Byte-packed initialization sequence. +//| :param int width: Width in pixels +//| :param int height: Height in pixels +//| :param int ram_width: RAM width in pixels +//| :param int ram_height: RAM height in pixels +//| :param int colstart: The index if the first visible column +//| :param int rowstart: The index if the first visible row +//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) +//| :param int set_column_window_command: Command used to set the start and end columns to update +//| :param int set_row_window_command: Command used so set the start and end rows to update +//| :param int set_current_column_command: Command used to set the current column location +//| :param int set_current_row_command: Command used to set the current row location +//| :param int write_black_ram_command: Command used to write pixels values into the update region +//| :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise, 1 means to show black. +//| :param int write_color_ram_command: Command used to write pixels values into the update region +//| :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1 means to show color. +//| :param int highlight_color: RGB888 of source color to highlight with third ePaper color. +//| :param int refresh_display_command: Command used to start a display refresh +//| :param float refresh_time: Time it takes to refresh the display before the stop_sequence should be sent. Ignored when busy_pin is provided. +//| :param microcontroller.Pin busy_pin: Pin used to signify the display is busy +//| :param bool busy_state: State of the busy pin when the display is busy +//| :param float seconds_per_frame: Minimum number of seconds between screen refreshes +//| :param bool always_toggle_chip_select: When True, chip select is toggled every byte""" +//| ... //| STATIC mp_obj_t displayio_epaperdisplay_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_display_bus, ARG_start_sequence, ARG_stop_sequence, ARG_width, ARG_height, ARG_ram_width, ARG_ram_height, ARG_colstart, ARG_rowstart, ARG_rotation, ARG_set_column_window_command, ARG_set_row_window_command, ARG_set_current_column_command, ARG_set_current_row_command, ARG_write_black_ram_command, ARG_black_bits_inverted, ARG_write_color_ram_command, ARG_color_bits_inverted, ARG_highlight_color, ARG_refresh_display_command, ARG_refresh_time, ARG_busy_pin, ARG_busy_state, ARG_seconds_per_frame, ARG_always_toggle_chip_select }; @@ -170,12 +171,13 @@ static displayio_epaperdisplay_obj_t* native_display(mp_obj_t display_obj) { return MP_OBJ_TO_PTR(native_display); } -//| .. method:: show(group) +//| def show(self, group: Group) -> Any: +//| """Switches to displaying the given group of layers. When group is None, the default +//| CircuitPython terminal will be shown. //| -//| Switches to displaying the given group of layers. When group is None, the default -//| CircuitPython terminal will be shown. +//| :param Group group: The group to show.""" +//| ... //| -//| :param Group group: The group to show. STATIC mp_obj_t displayio_epaperdisplay_obj_show(mp_obj_t self_in, mp_obj_t group_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); displayio_group_t* group = NULL; @@ -191,10 +193,10 @@ STATIC mp_obj_t displayio_epaperdisplay_obj_show(mp_obj_t self_in, mp_obj_t grou } MP_DEFINE_CONST_FUN_OBJ_2(displayio_epaperdisplay_show_obj, displayio_epaperdisplay_obj_show); -//| .. method:: refresh() -//| -//| Refreshes the display immediately or raises an exception if too soon. Use -//| ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur. +//| def refresh(self, ) -> Any: +//| """Refreshes the display immediately or raises an exception if too soon. Use +//| ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur.""" +//| ... //| STATIC mp_obj_t displayio_epaperdisplay_obj_refresh(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -206,10 +208,8 @@ STATIC mp_obj_t displayio_epaperdisplay_obj_refresh(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_epaperdisplay_refresh_obj, displayio_epaperdisplay_obj_refresh); -//| .. attribute:: time_to_refresh -//| -//| Time, in fractional seconds, until the ePaper display can be refreshed. -//| +//| time_to_refresh: Any = ... +//| """Time, in fractional seconds, until the ePaper display can be refreshed.""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_time_to_refresh(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -224,10 +224,8 @@ const mp_obj_property_t displayio_epaperdisplay_time_to_refresh_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: width -//| -//| Gets the width of the display in pixels -//| +//| width: Any = ... +//| """Gets the width of the display in pixels""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_width(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -242,10 +240,8 @@ const mp_obj_property_t displayio_epaperdisplay_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Gets the height of the display in pixels -//| +//| height: Any = ... +//| """Gets the height of the display in pixels""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_height(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -260,10 +256,8 @@ const mp_obj_property_t displayio_epaperdisplay_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: bus -//| -//| The bus being used by the display -//| +//| bus: Any = ... +//| """The bus being used by the display""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_bus(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c index 6ad162411..649045039 100644 --- a/shared-bindings/displayio/FourWire.c +++ b/shared-bindings/displayio/FourWire.c @@ -38,31 +38,32 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class FourWire: +//| """.. currentmodule:: displayio //| -//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol -//| ========================================================================== +//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol +//| ========================================================================== //| -//| Manage updating a display over SPI four wire protocol in the background while Python code runs. -//| It doesn't handle display initialization. +//| Manage updating a display over SPI four wire protocol in the background while Python code runs. +//| It doesn't handle display initialization.""" //| -//| .. class:: FourWire(spi_bus, *, command, chip_select, reset=None, baudrate=24000000, polarity=0, phase=0) +//| def __init__(self, spi_bus: busio.SPI, *, command: microcontroller.Pin, chip_select: microcontroller.Pin, reset: microcontroller.Pin = None, baudrate: int = 24000000, polarity: int = 0, phase: int = 0): +//| """Create a FourWire object associated with the given pins. //| -//| Create a FourWire object associated with the given pins. +//| The SPI bus and pins are then in use by the display until `displayio.release_displays()` is +//| called even after a reload. (It does this so CircuitPython can use the display after your code +//| is done.) So, the first time you initialize a display bus in code.py you should call +//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. //| -//| The SPI bus and pins are then in use by the display until `displayio.release_displays()` is -//| called even after a reload. (It does this so CircuitPython can use the display after your code -//| is done.) So, the first time you initialize a display bus in code.py you should call -//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. -//| -//| :param busio.SPI spi_bus: The SPI bus that make up the clock and data lines -//| :param microcontroller.Pin command: Data or command pin -//| :param microcontroller.Pin chip_select: Chip select pin -//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used -//| :param int baudrate: Maximum baudrate in Hz for the display on the bus -//| :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 busio.SPI spi_bus: The SPI bus that make up the clock and data lines +//| :param microcontroller.Pin command: Data or command pin +//| :param microcontroller.Pin chip_select: Chip select pin +//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used +//| :param int baudrate: Maximum baudrate in Hz for the display on the bus +//| :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.""" +//| ... //| STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_spi_bus, ARG_command, ARG_chip_select, ARG_reset, ARG_baudrate, ARG_polarity, ARG_phase }; @@ -100,10 +101,10 @@ STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_ return self; } -//| .. method:: reset() -//| -//| Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin -//| is available. +//| def reset(self, ) -> Any: +//| """Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin +//| is available.""" +//| ... //| STATIC mp_obj_t displayio_fourwire_obj_reset(mp_obj_t self_in) { displayio_fourwire_obj_t *self = self_in; @@ -115,10 +116,10 @@ STATIC mp_obj_t displayio_fourwire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_fourwire_reset_obj, displayio_fourwire_obj_reset); -//| .. method:: send(command, data, *, toggle_every_byte=False) -//| -//| Sends the given command value followed by the full set of data. Display state, such as -//| vertical scroll, set via ``send`` may or may not be reset once the code is done. +//| def send(self, command: Any, data: Any, *, toggle_every_byte: Any = False) -> Any: +//| """Sends the given command value followed by the full set of data. Display state, such as +//| vertical scroll, set via ``send`` may or may not be reset once the code is done.""" +//| ... //| STATIC mp_obj_t displayio_fourwire_obj_send(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_command, ARG_data, ARG_toggle_every_byte }; diff --git a/shared-bindings/displayio/Group.c b/shared-bindings/displayio/Group.c index dd7600eb9..36e137dc9 100644 --- a/shared-bindings/displayio/Group.c +++ b/shared-bindings/displayio/Group.c @@ -35,22 +35,23 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Group: +//| """.. currentmodule:: displayio //| -//| :class:`Group` -- Group together sprites and subgroups -//| ========================================================================== +//| :class:`Group` -- Group together sprites and subgroups +//| ========================================================================== //| -//| Manage a group of sprites and groups and how they are inter-related. +//| Manage a group of sprites and groups and how they are inter-related.""" //| -//| .. class:: Group(*, max_size=4, scale=1, x=0, y=0) +//| def __init__(self, *, max_size: int = 4, scale: int = 1, x: int = 0, y: int = 0): +//| """Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 +//| leads to a layer's pixel being 2x2 pixels when in the group. //| -//| Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 -//| leads to a layer's pixel being 2x2 pixels when in the group. -//| -//| :param int max_size: The maximum group size. -//| :param int scale: Scale of layer pixels in one dimension. -//| :param int x: Initial x position within the parent. -//| :param int y: Initial y position within the parent. +//| :param int max_size: The maximum group size. +//| :param int scale: Scale of layer pixels in one dimension. +//| :param int x: Initial x position within the parent. +//| :param int y: Initial y position within the parent.""" +//| ... //| STATIC mp_obj_t displayio_group_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_max_size, ARG_scale, ARG_x, ARG_y }; @@ -90,10 +91,9 @@ displayio_group_t* native_group(mp_obj_t group_obj) { return MP_OBJ_TO_PTR(native_group); } -//| .. attribute:: hidden -//| -//| True when the Group and all of it's layers are not visible. When False, the Group's layers -//| are visible if they haven't been hidden. +//| hidden: Any = ... +//| """True when the Group and all of it's layers are not visible. When False, the Group's layers +//| are visible if they haven't been hidden.""" //| STATIC mp_obj_t displayio_group_obj_get_hidden(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -116,10 +116,9 @@ const mp_obj_property_t displayio_group_hidden_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: scale -//| -//| Scales each pixel within the Group in both directions. For example, when scale=2 each pixel -//| will be represented by 2x2 pixels. +//| scale: Any = ... +//| """Scales each pixel within the Group in both directions. For example, when scale=2 each pixel +//| will be represented by 2x2 pixels.""" //| STATIC mp_obj_t displayio_group_obj_get_scale(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -146,9 +145,8 @@ const mp_obj_property_t displayio_group_scale_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: x -//| -//| X position of the Group in the parent. +//| x: Any = ... +//| """X position of the Group in the parent.""" //| STATIC mp_obj_t displayio_group_obj_get_x(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -172,9 +170,8 @@ const mp_obj_property_t displayio_group_x_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: y -//| -//| Y position of the Group in the parent. +//| y: Any = ... +//| """Y position of the Group in the parent.""" //| STATIC mp_obj_t displayio_group_obj_get_y(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -198,9 +195,9 @@ const mp_obj_property_t displayio_group_y_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: append(layer) -//| -//| Append a layer to the group. It will be drawn above other layers. +//| def append(self, layer: Any) -> Any: +//| """Append a layer to the group. It will be drawn above other layers.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_append(mp_obj_t self_in, mp_obj_t layer) { displayio_group_t *self = native_group(self_in); @@ -209,9 +206,9 @@ STATIC mp_obj_t displayio_group_obj_append(mp_obj_t self_in, mp_obj_t layer) { } MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_append_obj, displayio_group_obj_append); -//| .. method:: insert(index, layer) -//| -//| Insert a layer into the group. +//| def insert(self, index: Any, layer: Any) -> Any: +//| """Insert a layer into the group.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_insert(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t layer) { displayio_group_t *self = native_group(self_in); @@ -222,9 +219,9 @@ STATIC mp_obj_t displayio_group_obj_insert(mp_obj_t self_in, mp_obj_t index_obj, MP_DEFINE_CONST_FUN_OBJ_3(displayio_group_insert_obj, displayio_group_obj_insert); -//| .. method:: index(layer) -//| -//| Returns the index of the first copy of layer. Raises ValueError if not found. +//| def index(self, layer: Any) -> Any: +//| """Returns the index of the first copy of layer. Raises ValueError if not found.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_index(mp_obj_t self_in, mp_obj_t layer) { displayio_group_t *self = native_group(self_in); @@ -236,9 +233,9 @@ STATIC mp_obj_t displayio_group_obj_index(mp_obj_t self_in, mp_obj_t layer) { } MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_index_obj, displayio_group_obj_index); -//| .. method:: pop(i=-1) -//| -//| Remove the ith item and return it. +//| def pop(self, i: Any = -1) -> Any: +//| """Remove the ith item and return it.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_pop(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_i }; @@ -259,9 +256,9 @@ STATIC mp_obj_t displayio_group_obj_pop(size_t n_args, const mp_obj_t *pos_args, MP_DEFINE_CONST_FUN_OBJ_KW(displayio_group_pop_obj, 1, displayio_group_obj_pop); -//| .. method:: remove(layer) -//| -//| Remove the first copy of layer. Raises ValueError if it is not present. +//| def remove(self, layer: Any) -> Any: +//| """Remove the first copy of layer. Raises ValueError if it is not present.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_remove(mp_obj_t self_in, mp_obj_t layer) { mp_obj_t index = displayio_group_obj_index(self_in, layer); @@ -272,9 +269,9 @@ STATIC mp_obj_t displayio_group_obj_remove(mp_obj_t self_in, mp_obj_t layer) { } MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_remove_obj, displayio_group_obj_remove); -//| .. method:: __len__() -//| -//| Returns the number of layers in a Group +//| def __len__(self, ) -> Any: +//| """Returns the number of layers in a Group""" +//| ... //| STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -286,29 +283,29 @@ STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| .. method:: __getitem__(index) -//| -//| Returns the value at the given index. -//| -//| This allows you to:: -//| -//| print(group[0]) +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the value at the given index. //| -//| .. method:: __setitem__(index, value) +//| This allows you to:: //| -//| Sets the value at the given index. +//| print(group[0])""" +//| ... //| -//| This allows you to:: +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the value at the given index. //| -//| group[0] = sprite +//| This allows you to:: //| -//| .. method:: __delitem__(index) +//| group[0] = sprite""" +//| ... //| -//| Deletes the value at the given index. +//| def __delitem__(self, index: Any) -> Any: +//| """Deletes the value at the given index. //| -//| This allows you to:: +//| This allows you to:: //| -//| del group[0] +//| del group[0]""" +//| ... //| STATIC mp_obj_t group_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value) { displayio_group_t *self = native_group(self_in); diff --git a/shared-bindings/displayio/I2CDisplay.c b/shared-bindings/displayio/I2CDisplay.c index 963e8377c..e2402dc49 100644 --- a/shared-bindings/displayio/I2CDisplay.c +++ b/shared-bindings/displayio/I2CDisplay.c @@ -38,26 +38,27 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class I2CDisplay: +//| """.. currentmodule:: displayio //| -//| :class:`I2CDisplay` -- Manage updating a display over I2C -//| ========================================================================== +//| :class:`I2CDisplay` -- Manage updating a display over I2C +//| ========================================================================== //| -//| Manage updating a display over I2C in the background while Python code runs. -//| It doesn't handle display initialization. +//| Manage updating a display over I2C in the background while Python code runs. +//| It doesn't handle display initialization.""" //| -//| .. class:: I2CDisplay(i2c_bus, *, device_address, reset=None) +//| def __init__(self, i2c_bus: busio.I2C, *, device_address: int, reset: microcontroller.Pin = None): +//| """Create a I2CDisplay object associated with the given I2C bus and reset pin. //| -//| Create a I2CDisplay object associated with the given I2C bus and reset pin. +//| The I2C bus and pins are then in use by the display until `displayio.release_displays()` is +//| called even after a reload. (It does this so CircuitPython can use the display after your code +//| is done.) So, the first time you initialize a display bus in code.py you should call +//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. //| -//| The I2C bus and pins are then in use by the display until `displayio.release_displays()` is -//| called even after a reload. (It does this so CircuitPython can use the display after your code -//| is done.) So, the first time you initialize a display bus in code.py you should call -//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. -//| -//| :param busio.I2C i2c_bus: The I2C bus that make up the clock and data lines -//| :param int device_address: The I2C address of the device -//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used +//| :param busio.I2C i2c_bus: The I2C bus that make up the clock and data lines +//| :param int device_address: The I2C address of the device +//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used""" +//| ... //| STATIC mp_obj_t displayio_i2cdisplay_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_i2c_bus, ARG_device_address, ARG_reset }; @@ -80,10 +81,10 @@ STATIC mp_obj_t displayio_i2cdisplay_make_new(const mp_obj_type_t *type, size_t return self; } -//| .. method:: reset() -//| -//| Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin -//| is available. +//| def reset(self, ) -> Any: +//| """Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin +//| is available.""" +//| ... //| STATIC mp_obj_t displayio_i2cdisplay_obj_reset(mp_obj_t self_in) { displayio_i2cdisplay_obj_t *self = self_in; @@ -95,10 +96,10 @@ STATIC mp_obj_t displayio_i2cdisplay_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_i2cdisplay_reset_obj, displayio_i2cdisplay_obj_reset); -//| .. method:: send(command, data) -//| -//| Sends the given command value followed by the full set of data. Display state, such as -//| vertical scroll, set via ``send`` may or may not be reset once the code is done. +//| def send(self, command: Any, data: Any) -> Any: +//| """Sends the given command value followed by the full set of data. Display state, such as +//| vertical scroll, set via ``send`` may or may not be reset once the code is done.""" +//| ... //| STATIC mp_obj_t displayio_i2cdisplay_obj_send(mp_obj_t self, mp_obj_t command_obj, mp_obj_t data_obj) { mp_int_t command_int = MP_OBJ_SMALL_INT_VALUE(command_obj); diff --git a/shared-bindings/displayio/OnDiskBitmap.c b/shared-bindings/displayio/OnDiskBitmap.c index 57179947e..95c890c3b 100644 --- a/shared-bindings/displayio/OnDiskBitmap.c +++ b/shared-bindings/displayio/OnDiskBitmap.c @@ -33,51 +33,52 @@ #include "supervisor/shared/translate.h" #include "shared-bindings/displayio/OnDiskBitmap.h" -//| .. currentmodule:: displayio +//| class OnDiskBitmap: +//| """.. currentmodule:: displayio //| -//| :class:`OnDiskBitmap` -- Loads pixels straight from disk -//| ========================================================================== +//| :class:`OnDiskBitmap` -- Loads pixels straight from disk +//| ========================================================================== //| -//| Loads values straight from disk. This minimizes memory use but can lead to -//| much slower pixel load times. These load times may result in frame tearing where only part of -//| the image is visible. +//| Loads values straight from disk. This minimizes memory use but can lead to +//| much slower pixel load times. These load times may result in frame tearing where only part of +//| the image is visible. //| -//| It's easiest to use on a board with a built in display such as the `Hallowing M0 Express -//| `_. +//| It's easiest to use on a board with a built in display such as the `Hallowing M0 Express +//| `_. //| -//| .. code-block:: Python +//| .. code-block:: Python //| -//| import board -//| import displayio -//| import time -//| import pulseio +//| import board +//| import displayio +//| import time +//| import pulseio //| -//| board.DISPLAY.auto_brightness = False -//| board.DISPLAY.brightness = 0 -//| splash = displayio.Group() -//| board.DISPLAY.show(splash) +//| board.DISPLAY.auto_brightness = False +//| board.DISPLAY.brightness = 0 +//| splash = displayio.Group() +//| board.DISPLAY.show(splash) //| -//| with open("/sample.bmp", "rb") as f: -//| odb = displayio.OnDiskBitmap(f) -//| face = displayio.TileGrid(odb, pixel_shader=displayio.ColorConverter()) -//| splash.append(face) -//| # Wait for the image to load. -//| board.DISPLAY.refresh(target_frames_per_second=60) +//| with open("/sample.bmp", "rb") as f: +//| odb = displayio.OnDiskBitmap(f) +//| face = displayio.TileGrid(odb, pixel_shader=displayio.ColorConverter()) +//| splash.append(face) +//| # Wait for the image to load. +//| board.DISPLAY.refresh(target_frames_per_second=60) //| -//| # Fade up the backlight -//| for i in range(100): -//| board.DISPLAY.brightness = 0.01 * i -//| time.sleep(0.05) +//| # Fade up the backlight +//| for i in range(100): +//| board.DISPLAY.brightness = 0.01 * i +//| time.sleep(0.05) //| -//| # Wait forever -//| while True: -//| pass +//| # Wait forever +//| while True: +//| pass""" //| -//| .. class:: OnDiskBitmap(file) +//| def __init__(self, file: file): +//| """Create an OnDiskBitmap object with the given file. //| -//| Create an OnDiskBitmap object with the given file. -//| -//| :param file file: The open bitmap file +//| :param file file: The open bitmap file""" +//| ... //| STATIC mp_obj_t displayio_ondiskbitmap_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -93,9 +94,8 @@ STATIC mp_obj_t displayio_ondiskbitmap_make_new(const mp_obj_type_t *type, size_ return MP_OBJ_FROM_PTR(self); } -//| .. attribute:: width -//| -//| Width of the bitmap. (read only) +//| width: Any = ... +//| """Width of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_ondiskbitmap_obj_get_width(mp_obj_t self_in) { displayio_ondiskbitmap_t *self = MP_OBJ_TO_PTR(self_in); @@ -113,9 +113,8 @@ const mp_obj_property_t displayio_ondiskbitmap_width_obj = { }; -//| .. attribute:: height -//| -//| Height of the bitmap. (read only) +//| height: Any = ... +//| """Height of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_ondiskbitmap_obj_get_height(mp_obj_t self_in) { displayio_ondiskbitmap_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/Palette.c b/shared-bindings/displayio/Palette.c index 67a7db85b..5df11d2b1 100644 --- a/shared-bindings/displayio/Palette.c +++ b/shared-bindings/displayio/Palette.c @@ -36,19 +36,27 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio + + + + + + +//| class Palette: +//| """.. currentmodule:: displayio //| -//| :class:`Palette` -- Stores a mapping from bitmap pixel palette_indexes to display colors -//| ========================================================================================= +//| :class:`Palette` -- Stores a mapping from bitmap pixel palette_indexes to display colors +//| ========================================================================================= //| -//| Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to -//| save memory. +//| Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to +//| save memory.""" //| -//| .. class:: Palette(color_count) +//| def __init__(self, color_count: int): +//| """Create a Palette object to store a set number of colors. //| -//| Create a Palette object to store a set number of colors. +//| :param int color_count: The number of colors in the Palette""" +//| ... //| -//| :param int color_count: The number of colors in the Palette // TODO(tannewt): Add support for other color formats. // TODO(tannewt): Add support for 8-bit alpha blending. //| @@ -67,9 +75,9 @@ STATIC mp_obj_t displayio_palette_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| .. method:: __len__() -//| -//| Returns the number of colors in a Palette +//| def __len__(self, ) -> Any: +//| """Returns the number of colors in a Palette""" +//| ... //| STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { displayio_palette_t *self = MP_OBJ_TO_PTR(self_in); @@ -81,21 +89,21 @@ STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| .. method:: __setitem__(index, value) -//| -//| Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1. +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1. //| -//| The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value). -//| Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray, -//| or a tuple or list of 3 integers. +//| The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value). +//| Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray, +//| or a tuple or list of 3 integers. //| -//| This allows you to:: +//| This allows you to:: //| -//| palette[0] = 0xFFFFFF # set using an integer -//| palette[1] = b'\xff\xff\x00' # set using 3 bytes -//| palette[2] = b'\xff\xff\x00\x00' # set using 4 bytes -//| palette[3] = bytearray(b'\x00\x00\xFF') # set using a bytearay of 3 or 4 bytes -//| palette[4] = (10, 20, 30) # set using a tuple of 3 integers +//| palette[0] = 0xFFFFFF # set using an integer +//| palette[1] = b'\xff\xff\x00' # set using 3 bytes +//| palette[2] = b'\xff\xff\x00\x00' # set using 4 bytes +//| palette[3] = bytearray(b'\x00\x00\xFF') # set using a bytearay of 3 or 4 bytes +//| palette[4] = (10, 20, 30) # set using a tuple of 3 integers""" +//| ... //| STATIC mp_obj_t palette_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t value) { if (value == MP_OBJ_NULL) { @@ -144,7 +152,7 @@ STATIC mp_obj_t palette_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t val return mp_const_none; } -//| .. method:: make_transparent(palette_index) +//| def make_transparent(self, palette_index: Any) -> Any: ... //| STATIC mp_obj_t displayio_palette_obj_make_transparent(mp_obj_t self_in, mp_obj_t palette_index_obj) { displayio_palette_t *self = MP_OBJ_TO_PTR(self_in); @@ -158,7 +166,7 @@ STATIC mp_obj_t displayio_palette_obj_make_transparent(mp_obj_t self_in, mp_obj_ } MP_DEFINE_CONST_FUN_OBJ_2(displayio_palette_make_transparent_obj, displayio_palette_obj_make_transparent); -//| .. method:: make_opaque(palette_index) +//| def make_opaque(self, palette_index: Any) -> Any: ... //| STATIC mp_obj_t displayio_palette_obj_make_opaque(mp_obj_t self_in, mp_obj_t palette_index_obj) { displayio_palette_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/ParallelBus.c b/shared-bindings/displayio/ParallelBus.c index bdafdaef6..cedcf1de5 100644 --- a/shared-bindings/displayio/ParallelBus.c +++ b/shared-bindings/displayio/ParallelBus.c @@ -37,31 +37,32 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class ParallelBus: +//| """.. currentmodule:: displayio //| -//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus -//| ============================================================================== +//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus +//| ============================================================================== //| -//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This -//| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle -//| display initialization. +//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This +//| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle +//| display initialization.""" //| -//| .. class:: ParallelBus(*, data0, command, chip_select, write, read, reset) +//| def __init__(self, *, data0: microcontroller.Pin, command: microcontroller.Pin, chip_select: microcontroller.Pin, write: microcontroller.Pin, read: microcontroller.Pin, reset: microcontroller.Pin): +//| """Create a ParallelBus object associated with the given pins. The bus is inferred from data0 +//| by implying the next 7 additional pins on a given GPIO port. //| -//| Create a ParallelBus object associated with the given pins. The bus is inferred from data0 -//| by implying the next 7 additional pins on a given GPIO port. +//| The parallel bus and pins are then in use by the display until `displayio.release_displays()` +//| is called even after a reload. (It does this so CircuitPython can use the display after your +//| code is done.) So, the first time you initialize a display bus in code.py you should call +//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. //| -//| The parallel bus and pins are then in use by the display until `displayio.release_displays()` -//| is called even after a reload. (It does this so CircuitPython can use the display after your -//| code is done.) So, the first time you initialize a display bus in code.py you should call -//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. -//| -//| :param microcontroller.Pin data0: The first data pin. The rest are implied -//| :param microcontroller.Pin command: Data or command pin -//| :param microcontroller.Pin chip_select: Chip select pin -//| :param microcontroller.Pin write: Write pin -//| :param microcontroller.Pin read: Read pin -//| :param microcontroller.Pin reset: Reset pin +//| :param microcontroller.Pin data0: The first data pin. The rest are implied +//| :param microcontroller.Pin command: Data or command pin +//| :param microcontroller.Pin chip_select: Chip select pin +//| :param microcontroller.Pin write: Write pin +//| :param microcontroller.Pin read: Read pin +//| :param microcontroller.Pin reset: Reset pin""" +//| ... //| STATIC mp_obj_t displayio_parallelbus_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_data0, ARG_command, ARG_chip_select, ARG_write, ARG_read, ARG_reset }; @@ -90,11 +91,12 @@ STATIC mp_obj_t displayio_parallelbus_make_new(const mp_obj_type_t *type, size_t return self; } -//| .. method:: reset() -//| -//| Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin -//| is available. +//| def reset(self, ) -> Any: +//| """Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin +//| is available.""" +//| ... //| + STATIC mp_obj_t displayio_parallelbus_obj_reset(mp_obj_t self_in) { displayio_parallelbus_obj_t *self = self_in; @@ -105,10 +107,10 @@ STATIC mp_obj_t displayio_parallelbus_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_parallelbus_reset_obj, displayio_parallelbus_obj_reset); -//| .. method:: send(command, data) -//| -//| Sends the given command value followed by the full set of data. Display state, such as -//| vertical scroll, set via ``send`` may or may not be reset once the code is done. +//| def send(self, command: Any, data: Any) -> Any: +//| """Sends the given command value followed by the full set of data. Display state, such as +//| vertical scroll, set via ``send`` may or may not be reset once the code is done.""" +//| ... //| STATIC mp_obj_t displayio_parallelbus_obj_send(mp_obj_t self, mp_obj_t command_obj, mp_obj_t data_obj) { mp_int_t command_int = MP_OBJ_SMALL_INT_VALUE(command_obj); diff --git a/shared-bindings/displayio/Shape.c b/shared-bindings/displayio/Shape.c index 7c7b10501..0f22bb2a3 100644 --- a/shared-bindings/displayio/Shape.c +++ b/shared-bindings/displayio/Shape.c @@ -34,22 +34,23 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Shape: +//| """.. currentmodule:: displayio //| -//| :class:`Shape` -- Represents a shape by defining its bounds on each row -//| ========================================================================== +//| :class:`Shape` -- Represents a shape by defining its bounds on each row +//| ========================================================================== //| -//| Represents any shape made by defining boundaries that may be mirrored. +//| Represents any shape made by defining boundaries that may be mirrored.""" //| -//| .. class:: Shape(width, height, *, mirror_x=False, mirror_y=False) +//| def __init__(self, width: int, height: int, *, mirror_x: bool = False, mirror_y: bool = False): +//| """Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the +//| column boundaries of the shape on each row. Each row's boundary defaults to the full row. //| -//| Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the -//| column boundaries of the shape on each row. Each row's boundary defaults to the full row. -//| -//| :param int width: The number of pixels wide -//| :param int height: The number of pixels high -//| :param bool mirror_x: When true the left boundary is mirrored to the right. -//| :param bool mirror_y: When true the top boundary is mirrored to the bottom. +//| :param int width: The number of pixels wide +//| :param int height: The number of pixels high +//| :param bool mirror_x: When true the left boundary is mirrored to the right. +//| :param bool mirror_y: When true the top boundary is mirrored to the bottom.""" +//| ... //| STATIC mp_obj_t displayio_shape_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_width, ARG_height, ARG_mirror_x, ARG_mirror_y }; @@ -83,9 +84,9 @@ STATIC mp_obj_t displayio_shape_make_new(const mp_obj_type_t *type, size_t n_arg } -//| .. method:: set_boundary(y, start_x, end_x) -//| -//| Loads pre-packed data into the given row. +//| def set_boundary(self, y: Any, start_x: Any, end_x: Any) -> Any: +//| """Loads pre-packed data into the given row.""" +//| ... //| STATIC mp_obj_t displayio_shape_obj_set_boundary(size_t n_args, const mp_obj_t *args) { (void) n_args; diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index 288eb4b23..e7410e4b6 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -40,33 +40,33 @@ #include "shared-bindings/displayio/Shape.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class TileGrid: +//| """.. currentmodule:: displayio //| -//| :class:`TileGrid` -- A grid of tiles sourced out of one bitmap -//| ========================================================================== +//| :class:`TileGrid` -- A grid of tiles sourced out of one bitmap +//| ========================================================================== //| -//| Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids -//| can share bitmaps and pixel shaders. +//| Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids +//| can share bitmaps and pixel shaders. //| -//| A single tile grid is also known as a Sprite. +//| A single tile grid is also known as a Sprite.""" //| -//| .. class:: TileGrid(bitmap, *, pixel_shader, width=1, height=1, tile_width=None, tile_height=None, default_tile=0, x=0, y=0) +//| def __init__(self, bitmap: displayio.Bitmap, *, pixel_shader: displayio.Palette, width: int = 1, height: int = 1, tile_width: int = None, tile_height: int = None, default_tile: int = 0, x: int = 0, y: int = 0): +//| """Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to +//| convert the value and its location to a display native pixel color. This may be a simple color +//| palette lookup, a gradient, a pattern or a color transformer. //| -//| Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to -//| convert the value and its location to a display native pixel color. This may be a simple color -//| palette lookup, a gradient, a pattern or a color transformer. +//| tile_width and tile_height match the height of the bitmap by default. //| -//| tile_width and tile_height match the height of the bitmap by default. -//| -//| :param displayio.Bitmap bitmap: The bitmap storing one or more tiles. -//| :param displayio.Palette pixel_shader: The pixel shader that produces colors from values -//| :param int width: Width of the grid in tiles. -//| :param int height: Height of the grid in tiles. -//| :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. -//| :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. -//| :param int default_tile: Default tile index to show. -//| :param int x: Initial x position of the left edge within the parent. -//| :param int y: Initial y position of the top edge within the parent. +//| :param displayio.Bitmap bitmap: The bitmap storing one or more tiles. +//| :param displayio.Palette pixel_shader: The pixel shader that produces colors from values +//| :param int width: Width of the grid in tiles. +//| :param int height: Height of the grid in tiles. +//| :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. +//| :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. +//| :param int default_tile: Default tile index to show. +//| :param int x: Initial x position of the left edge within the parent. +//| :param int y: Initial y position of the top edge within the parent.""" //| STATIC mp_obj_t displayio_tilegrid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_bitmap, ARG_pixel_shader, ARG_width, ARG_height, ARG_tile_width, ARG_tile_height, ARG_default_tile, ARG_x, ARG_y }; @@ -144,9 +144,8 @@ static displayio_tilegrid_t* native_tilegrid(mp_obj_t tilegrid_obj) { mp_obj_assert_native_inited(native_tilegrid); return MP_OBJ_TO_PTR(native_tilegrid); } -//| .. attribute:: hidden -//| -//| True when the TileGrid is hidden. This may be False even when a part of a hidden Group. +//| hidden: Any = ... +//| """True when the TileGrid is hidden. This may be False even when a part of a hidden Group.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_hidden(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -169,9 +168,8 @@ const mp_obj_property_t displayio_tilegrid_hidden_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: x -//| -//| X position of the left edge in the parent. +//| x: Any = ... +//| """X position of the left edge in the parent.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_x(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -195,9 +193,8 @@ const mp_obj_property_t displayio_tilegrid_x_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: y -//| -//| Y position of the top edge in the parent. +//| y: Any = ... +//| """Y position of the top edge in the parent.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_y(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -221,9 +218,8 @@ const mp_obj_property_t displayio_tilegrid_y_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: flip_x -//| -//| If true, the left edge rendered will be the right edge of the right-most tile. +//| flip_x: Any = ... +//| """If true, the left edge rendered will be the right edge of the right-most tile.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_flip_x(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -246,9 +242,8 @@ const mp_obj_property_t displayio_tilegrid_flip_x_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: flip_y -//| -//| If true, the top edge rendered will be the bottom edge of the bottom-most tile. +//| flip_y: Any = ... +//| """If true, the top edge rendered will be the bottom edge of the bottom-most tile.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_flip_y(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -272,10 +267,9 @@ const mp_obj_property_t displayio_tilegrid_flip_y_obj = { }; -//| .. attribute:: transpose_xy -//| -//| If true, the TileGrid's axis will be swapped. When combined with mirroring, any 90 degree -//| rotation can be achieved along with the corresponding mirrored version. +//| transpose_xy: Any = ... +//| """If true, the TileGrid's axis will be swapped. When combined with mirroring, any 90 degree +//| rotation can be achieved along with the corresponding mirrored version.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_transpose_xy(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -298,9 +292,8 @@ const mp_obj_property_t displayio_tilegrid_transpose_xy_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: pixel_shader -//| -//| The pixel shader of the tilegrid. +//| pixel_shader: Any = ... +//| """The pixel shader of the tilegrid.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_pixel_shader(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -327,27 +320,27 @@ const mp_obj_property_t displayio_tilegrid_pixel_shader_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __getitem__(index) -//| -//| Returns the tile index at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. -//| -//| This allows you to:: +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the tile index at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| print(grid[0]) +//| This allows you to:: //| -//| .. method:: __setitem__(index, tile_index) +//| print(grid[0])""" +//| ... //| -//| Sets the tile index at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. +//| def __setitem__(self, index: Any, tile_index: Any) -> Any: +//| """Sets the tile index at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| This allows you to:: +//| This allows you to:: //| -//| grid[0] = 10 +//| grid[0] = 10 //| -//| or:: +//| or:: //| -//| grid[0,0] = 10 +//| grid[0,0] = 10""" +//| ... //| STATIC mp_obj_t tilegrid_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value_obj) { displayio_tilegrid_t *self = native_tilegrid(self_in); diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index f78325593..37c025329 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -43,7 +43,7 @@ #include "shared-bindings/displayio/Shape.h" #include "shared-bindings/displayio/TileGrid.h" -//| :mod:`displayio` --- Native display driving +//| """:mod:`displayio` --- Native display driving //| ========================================================================= //| //| .. module:: displayio @@ -69,18 +69,18 @@ //| Palette //| ParallelBus //| Shape -//| TileGrid +//| TileGrid""" //| -//| .. function:: release_displays() +//| def release_displays() -> Any: +//| """Releases any actively used displays so their busses and pins can be used again. This will also +//| release the builtin display on boards that have one. You will need to reinitialize it yourself +//| afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing. //| -//| Releases any actively used displays so their busses and pins can be used again. This will also -//| release the builtin display on boards that have one. You will need to reinitialize it yourself -//| afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing. -//| -//| Use this once in your code.py if you initialize a display. Place it right before the -//| initialization so the display is active as long as possible. +//| Use this once in your code.py if you initialize a display. Place it right before the +//| initialization so the display is active as long as possible.""" +//| ... //| STATIC mp_obj_t displayio_release_displays(void) { common_hal_displayio_release_displays(); -- cgit v1.2.3 From a3d5adb43c897d591baabaaf1e7ef83deedbd3ce Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 7 May 2020 11:56:46 -0400 Subject: Did _eve, fontio, framebufferio, and frequencyio --- shared-bindings/_eve/__init__.c | 441 +++++++++++---------- shared-bindings/fontio/BuiltinFont.c | 38 +- shared-bindings/fontio/Glyph.c | 29 +- shared-bindings/fontio/__init__.c | 4 +- shared-bindings/framebufferio/FramebufferDisplay.c | 109 +++-- shared-bindings/framebufferio/__init__.c | 4 +- shared-bindings/frequencyio/FrequencyIn.c | 106 ++--- shared-bindings/frequencyio/__init__.c | 4 +- 8 files changed, 371 insertions(+), 364 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_eve/__init__.c b/shared-bindings/_eve/__init__.c index 9bc790f5d..0e78cea16 100644 --- a/shared-bindings/_eve/__init__.c +++ b/shared-bindings/_eve/__init__.c @@ -34,7 +34,20 @@ #include "shared-module/_eve/__init__.h" #include "shared-bindings/_eve/__init__.h" -//| :mod:`_eve` --- low-level BridgeTek EVE bindings + + + + + + + + + + + + + +//| """:mod:`_eve` --- low-level BridgeTek EVE bindings //| ================================================ //| //| .. module:: _eve @@ -43,7 +56,7 @@ //| //| The `_eve` module provides a class _EVE which //| contains methods for constructing EVE command -//| buffers and appending basic graphics commands. +//| buffers and appending basic graphics commands.""" //| typedef struct _mp_obj__EVE_t { @@ -63,11 +76,11 @@ STATIC mp_obj_t _register(mp_obj_t self, mp_obj_t o) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(register_obj, _register); -//| .. method:: flush() -//| -//| Send any queued drawing commands directly to the hardware. +//| def flush(self, ) -> Any: +//| """Send any queued drawing commands directly to the hardware. //| -//| :param int width: The width of the grid in tiles, or 1 for sprites. +//| :param int width: The width of the grid in tiles, or 1 for sprites.""" +//| ... //| STATIC mp_obj_t _flush(mp_obj_t self) { common_hal__eve_flush(EVEHAL(self)); @@ -75,11 +88,11 @@ STATIC mp_obj_t _flush(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(flush_obj, _flush); -//| .. method:: cc(b) -//| -//| Append bytes to the command FIFO. +//| def cc(self, b: bytes) -> Any: +//| """Append bytes to the command FIFO. //| -//| :param bytes b: The bytes to add +//| :param bytes b: The bytes to add""" +//| ... //| STATIC mp_obj_t _cc(mp_obj_t self, mp_obj_t b) { mp_buffer_info_t buffer_info; @@ -91,14 +104,14 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(cc_obj, _cc); //{ -//| .. method:: AlphaFunc(func, ref) -//| -//| Set the alpha test function +//| def AlphaFunc(self, func: int, ref: int) -> Any: +//| """Set the alpha test function //| //| :param int func: specifies the test function, one of ``NEVER``, ``LESS``, ``LEQUAL``, ``GREATER``, ``GEQUAL``, ``EQUAL``, ``NOTEQUAL``, or ``ALWAYS``. Range 0-7. The initial value is ALWAYS(7) //| :param int ref: specifies the reference value for the alpha test. Range 0-255. The initial value is 0 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _alphafunc(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -109,14 +122,14 @@ STATIC mp_obj_t _alphafunc(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(alphafunc_obj, _alphafunc); -//| .. method:: Begin(prim) -//| -//| Begin drawing a graphics primitive +//| def Begin(self, prim: int) -> Any: +//| """Begin drawing a graphics primitive //| //| :param int prim: graphics primitive. //| -//| Valid primitives are ``BITMAPS``, ``POINTS``, ``LINES``, ``LINE_STRIP``, ``EDGE_STRIP_R``, ``EDGE_STRIP_L``, ``EDGE_STRIP_A``, ``EDGE_STRIP_B`` and ``RECTS``. -//| +//| Valid primitives are ``BITMAPS``, ``POINTS``, ``LINES``, ``LINE_STRIP``, ``EDGE_STRIP_R``, ``EDGE_STRIP_L``, ``EDGE_STRIP_A``, ``EDGE_STRIP_B`` and ``RECTS``.""" +//| ... +//| STATIC mp_obj_t _begin(mp_obj_t self, mp_obj_t a0) { uint32_t prim = mp_obj_get_int_truncated(a0); @@ -125,11 +138,11 @@ STATIC mp_obj_t _begin(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(begin_obj, _begin); -//| .. method:: BitmapExtFormat(format) +//| def BitmapExtFormat(self, format: int) -> Any: +//| """Set the bitmap format //| -//| Set the bitmap format -//| -//| :param int format: bitmap pixel format. +//| :param int format: bitmap pixel format.""" +//| ... //| STATIC mp_obj_t _bitmapextformat(mp_obj_t self, mp_obj_t a0) { @@ -139,13 +152,13 @@ STATIC mp_obj_t _bitmapextformat(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(bitmapextformat_obj, _bitmapextformat); -//| .. method:: BitmapHandle(handle) -//| -//| Set the bitmap handle +//| def BitmapHandle(self, handle: int) -> Any: +//| """Set the bitmap handle //| //| :param int handle: bitmap handle. Range 0-31. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaphandle(mp_obj_t self, mp_obj_t a0) { @@ -155,12 +168,12 @@ STATIC mp_obj_t _bitmaphandle(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(bitmaphandle_obj, _bitmaphandle); -//| .. method:: BitmapLayoutH(linestride, height) -//| -//| Set the source bitmap memory format and layout for the current handle. high bits for large bitmaps +//| def BitmapLayoutH(self, linestride: int, height: int) -> Any: +//| """Set the source bitmap memory format and layout for the current handle. high bits for large bitmaps //| //| :param int linestride: high part of bitmap line stride, in bytes. Range 0-7 -//| :param int height: high part of bitmap height, in lines. Range 0-3 +//| :param int height: high part of bitmap height, in lines. Range 0-3""" +//| ... //| STATIC mp_obj_t _bitmaplayouth(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -171,13 +184,13 @@ STATIC mp_obj_t _bitmaplayouth(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(bitmaplayouth_obj, _bitmaplayouth); -//| .. method:: BitmapLayout(format, linestride, height) -//| -//| Set the source bitmap memory format and layout for the current handle +//| def BitmapLayout(self, format: int, linestride: int, height: int) -> Any: +//| """Set the source bitmap memory format and layout for the current handle //| //| :param int format: bitmap pixel format, or GLFORMAT to use BITMAP_EXT_FORMAT instead. Range 0-31 //| :param int linestride: bitmap line stride, in bytes. Range 0-1023 -//| :param int height: bitmap height, in lines. Range 0-511 +//| :param int height: bitmap height, in lines. Range 0-511""" +//| ... //| STATIC mp_obj_t _bitmaplayout(size_t n_args, const mp_obj_t *args) { @@ -189,12 +202,12 @@ STATIC mp_obj_t _bitmaplayout(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitmaplayout_obj, 4, 4, _bitmaplayout); -//| .. method:: BitmapSizeH(width, height) -//| -//| Set the screen drawing of bitmaps for the current handle. high bits for large bitmaps +//| def BitmapSizeH(self, width: int, height: int) -> Any: +//| """Set the screen drawing of bitmaps for the current handle. high bits for large bitmaps //| //| :param int width: high part of drawn bitmap width, in pixels. Range 0-3 -//| :param int height: high part of drawn bitmap height, in pixels. Range 0-3 +//| :param int height: high part of drawn bitmap height, in pixels. Range 0-3""" +//| ... //| STATIC mp_obj_t _bitmapsizeh(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -205,15 +218,15 @@ STATIC mp_obj_t _bitmapsizeh(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(bitmapsizeh_obj, _bitmapsizeh); -//| .. method:: BitmapSize(filter, wrapx, wrapy, width, height) -//| -//| Set the screen drawing of bitmaps for the current handle +//| def BitmapSize(self, filter: int, wrapx: int, wrapy: int, width: int, height: int) -> Any: +//| """Set the screen drawing of bitmaps for the current handle //| //| :param int filter: bitmap filtering mode, one of ``NEAREST`` or ``BILINEAR``. Range 0-1 //| :param int wrapx: bitmap :math:`x` wrap mode, one of ``REPEAT`` or ``BORDER``. Range 0-1 //| :param int wrapy: bitmap :math:`y` wrap mode, one of ``REPEAT`` or ``BORDER``. Range 0-1 //| :param int width: drawn bitmap width, in pixels. Range 0-511 -//| :param int height: drawn bitmap height, in pixels. Range 0-511 +//| :param int height: drawn bitmap height, in pixels. Range 0-511""" +//| ... //| STATIC mp_obj_t _bitmapsize(size_t n_args, const mp_obj_t *args) { @@ -227,11 +240,11 @@ STATIC mp_obj_t _bitmapsize(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitmapsize_obj, 6, 6, _bitmapsize); -//| .. method:: BitmapSource(addr) +//| def BitmapSource(self, addr: int) -> Any: +//| """Set the source address for bitmap graphics //| -//| Set the source address for bitmap graphics -//| -//| :param int addr: Bitmap start address, pixel-aligned. May be in SRAM or flash. Range 0-16777215 +//| :param int addr: Bitmap start address, pixel-aligned. May be in SRAM or flash. Range 0-16777215""" +//| ... //| STATIC mp_obj_t _bitmapsource(mp_obj_t self, mp_obj_t a0) { @@ -241,14 +254,14 @@ STATIC mp_obj_t _bitmapsource(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(bitmapsource_obj, _bitmapsource); -//| .. method:: BitmapSwizzle(r, g, b, a) -//| -//| Set the source for the r,g,b and a channels of a bitmap +//| def BitmapSwizzle(self, r: int, g: int, b: int, a: int) -> Any: +//| """Set the source for the r,g,b and a channels of a bitmap //| //| :param int r: red component source channel. Range 0-7 //| :param int g: green component source channel. Range 0-7 //| :param int b: blue component source channel. Range 0-7 -//| :param int a: alpha component source channel. Range 0-7 +//| :param int a: alpha component source channel. Range 0-7""" +//| ... //| STATIC mp_obj_t _bitmapswizzle(size_t n_args, const mp_obj_t *args) { @@ -261,16 +274,16 @@ STATIC mp_obj_t _bitmapswizzle(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitmapswizzle_obj, 5, 5, _bitmapswizzle); -//| .. method:: BitmapTransformA(p, v) -//| -//| Set the :math:`a` component of the bitmap transform matrix +//| def BitmapTransformA(self, p: Any, v: int) -> Any: +//| """Set the :math:`a` component of the bitmap transform matrix //| //| :param int p: precision control: 0 is 8.8, 1 is 1.15. Range 0-1. The initial value is 0 //| :param int v: The :math:`a` component of the bitmap transform matrix, in signed 8.8 or 1.15 bit fixed-point form. Range 0-131071. The initial value is 256 //| //| The initial value is **p** = 0, **v** = 256. This represents the value 1.0. //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaptransforma(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -281,16 +294,16 @@ STATIC mp_obj_t _bitmaptransforma(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(bitmaptransforma_obj, _bitmaptransforma); -//| .. method:: BitmapTransformB(p, v) -//| -//| Set the :math:`b` component of the bitmap transform matrix +//| def BitmapTransformB(self, p: Any, v: int) -> Any: +//| """Set the :math:`b` component of the bitmap transform matrix //| //| :param int p: precision control: 0 is 8.8, 1 is 1.15. Range 0-1. The initial value is 0 //| :param int v: The :math:`b` component of the bitmap transform matrix, in signed 8.8 or 1.15 bit fixed-point form. Range 0-131071. The initial value is 0 //| //| The initial value is **p** = 0, **v** = 0. This represents the value 0.0. //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaptransformb(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -301,13 +314,13 @@ STATIC mp_obj_t _bitmaptransformb(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(bitmaptransformb_obj, _bitmaptransformb); -//| .. method:: BitmapTransformC(v) -//| -//| Set the :math:`c` component of the bitmap transform matrix +//| def BitmapTransformC(self, v: int) -> Any: +//| """Set the :math:`c` component of the bitmap transform matrix //| //| :param int v: The :math:`c` component of the bitmap transform matrix, in signed 15.8 bit fixed-point form. Range 0-16777215. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaptransformc(mp_obj_t self, mp_obj_t a0) { @@ -317,16 +330,16 @@ STATIC mp_obj_t _bitmaptransformc(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(bitmaptransformc_obj, _bitmaptransformc); -//| .. method:: BitmapTransformD(p, v) -//| -//| Set the :math:`d` component of the bitmap transform matrix +//| def BitmapTransformD(self, p: Any, v: int) -> Any: +//| """Set the :math:`d` component of the bitmap transform matrix //| //| :param int p: precision control: 0 is 8.8, 1 is 1.15. Range 0-1. The initial value is 0 //| :param int v: The :math:`d` component of the bitmap transform matrix, in signed 8.8 or 1.15 bit fixed-point form. Range 0-131071. The initial value is 0 //| //| The initial value is **p** = 0, **v** = 0. This represents the value 0.0. //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaptransformd(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -337,16 +350,16 @@ STATIC mp_obj_t _bitmaptransformd(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(bitmaptransformd_obj, _bitmaptransformd); -//| .. method:: BitmapTransformE(p, v) -//| -//| Set the :math:`e` component of the bitmap transform matrix +//| def BitmapTransformE(self, p: Any, v: int) -> Any: +//| """Set the :math:`e` component of the bitmap transform matrix //| //| :param int p: precision control: 0 is 8.8, 1 is 1.15. Range 0-1. The initial value is 0 //| :param int v: The :math:`e` component of the bitmap transform matrix, in signed 8.8 or 1.15 bit fixed-point form. Range 0-131071. The initial value is 256 //| //| The initial value is **p** = 0, **v** = 256. This represents the value 1.0. //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaptransforme(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -357,13 +370,13 @@ STATIC mp_obj_t _bitmaptransforme(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(bitmaptransforme_obj, _bitmaptransforme); -//| .. method:: BitmapTransformF(v) -//| -//| Set the :math:`f` component of the bitmap transform matrix +//| def BitmapTransformF(self, v: int) -> Any: +//| """Set the :math:`f` component of the bitmap transform matrix //| //| :param int v: The :math:`f` component of the bitmap transform matrix, in signed 15.8 bit fixed-point form. Range 0-16777215. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _bitmaptransformf(mp_obj_t self, mp_obj_t a0) { @@ -373,14 +386,14 @@ STATIC mp_obj_t _bitmaptransformf(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(bitmaptransformf_obj, _bitmaptransformf); -//| .. method:: BlendFunc(src, dst) -//| -//| Set pixel arithmetic +//| def BlendFunc(self, src: int, dst: int) -> Any: +//| """Set pixel arithmetic //| //| :param int src: specifies how the source blending factor is computed. One of ``ZERO``, ``ONE``, ``SRC_ALPHA``, ``DST_ALPHA``, ``ONE_MINUS_SRC_ALPHA`` or ``ONE_MINUS_DST_ALPHA``. Range 0-7. The initial value is SRC_ALPHA(2) //| :param int dst: specifies how the destination blending factor is computed, one of the same constants as **src**. Range 0-7. The initial value is ONE_MINUS_SRC_ALPHA(4) //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _blendfunc(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -391,11 +404,11 @@ STATIC mp_obj_t _blendfunc(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(blendfunc_obj, _blendfunc); -//| .. method:: Call(dest) -//| -//| Execute a sequence of commands at another location in the display list +//| def Call(self, dest: int) -> Any: +//| """Execute a sequence of commands at another location in the display list //| -//| :param int dest: display list address. Range 0-65535 +//| :param int dest: display list address. Range 0-65535""" +//| ... //| STATIC mp_obj_t _call(mp_obj_t self, mp_obj_t a0) { @@ -405,13 +418,13 @@ STATIC mp_obj_t _call(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(call_obj, _call); -//| .. method:: Cell(cell) -//| -//| Set the bitmap cell number for the vertex2f command +//| def Cell(self, cell: int) -> Any: +//| """Set the bitmap cell number for the vertex2f command //| //| :param int cell: bitmap cell number. Range 0-127. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _cell(mp_obj_t self, mp_obj_t a0) { @@ -421,13 +434,13 @@ STATIC mp_obj_t _cell(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(cell_obj, _cell); -//| .. method:: ClearColorA(alpha) -//| -//| Set clear value for the alpha channel +//| def ClearColorA(self, alpha: int) -> Any: +//| """Set clear value for the alpha channel //| //| :param int alpha: alpha value used when the color buffer is cleared. Range 0-255. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _clearcolora(mp_obj_t self, mp_obj_t a0) { @@ -437,15 +450,15 @@ STATIC mp_obj_t _clearcolora(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(clearcolora_obj, _clearcolora); -//| .. method:: ClearColorRGB(red, green, blue) -//| -//| Set clear values for red, green and blue channels +//| def ClearColorRGB(self, red: int, green: int, blue: int) -> Any: +//| """Set clear values for red, green and blue channels //| //| :param int red: red value used when the color buffer is cleared. Range 0-255. The initial value is 0 //| :param int green: green value used when the color buffer is cleared. Range 0-255. The initial value is 0 //| :param int blue: blue value used when the color buffer is cleared. Range 0-255. The initial value is 0 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _clearcolorrgb(size_t n_args, const mp_obj_t *args) { @@ -457,13 +470,13 @@ STATIC mp_obj_t _clearcolorrgb(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(clearcolorrgb_obj, 4, 4, _clearcolorrgb); -//| .. method:: Clear(c, s, t) -//| -//| Clear buffers to preset values +//| def Clear(self, c: int, s: int, t: int) -> Any: +//| """Clear buffers to preset values //| //| :param int c: clear color buffer. Range 0-1 //| :param int s: clear stencil buffer. Range 0-1 -//| :param int t: clear tag buffer. Range 0-1 +//| :param int t: clear tag buffer. Range 0-1""" +//| ... //| STATIC mp_obj_t _clear(size_t n_args, const mp_obj_t *args) { @@ -475,13 +488,13 @@ STATIC mp_obj_t _clear(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(clear_obj, 1, 4, _clear); -//| .. method:: ClearStencil(s) -//| -//| Set clear value for the stencil buffer +//| def ClearStencil(self, s: int) -> Any: +//| """Set clear value for the stencil buffer //| //| :param int s: value used when the stencil buffer is cleared. Range 0-255. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _clearstencil(mp_obj_t self, mp_obj_t a0) { @@ -491,13 +504,12 @@ STATIC mp_obj_t _clearstencil(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(clearstencil_obj, _clearstencil); -//| .. method:: ClearTag(s) -//| -//| Set clear value for the tag buffer +//| def ClearTag(self, s: int) -> Any: +//| """Set clear value for the tag buffer //| //| :param int s: value used when the tag buffer is cleared. Range 0-255. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" //| STATIC mp_obj_t _cleartag(mp_obj_t self, mp_obj_t a0) { @@ -507,13 +519,13 @@ STATIC mp_obj_t _cleartag(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(cleartag_obj, _cleartag); -//| .. method:: ColorA(alpha) -//| -//| Set the current color alpha +//| def ColorA(self, alpha: int) -> Any: +//| """Set the current color alpha //| //| :param int alpha: alpha for the current color. Range 0-255. The initial value is 255 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _colora(mp_obj_t self, mp_obj_t a0) { @@ -523,16 +535,16 @@ STATIC mp_obj_t _colora(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(colora_obj, _colora); -//| .. method:: ColorMask(r, g, b, a) -//| -//| Enable and disable writing of frame buffer color components +//| def ColorMask(self, r: int, g: int, b: int, a: int) -> Any: +//| """Enable and disable writing of frame buffer color components //| //| :param int r: allow updates to the frame buffer red component. Range 0-1. The initial value is 1 //| :param int g: allow updates to the frame buffer green component. Range 0-1. The initial value is 1 //| :param int b: allow updates to the frame buffer blue component. Range 0-1. The initial value is 1 //| :param int a: allow updates to the frame buffer alpha component. Range 0-1. The initial value is 1 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _colormask(size_t n_args, const mp_obj_t *args) { @@ -545,15 +557,15 @@ STATIC mp_obj_t _colormask(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(colormask_obj, 5, 5, _colormask); -//| .. method:: ColorRGB(red, green, blue) -//| -//| Set the drawing color +//| def ColorRGB(self, red: int, green: int, blue: int) -> Any: +//| """Set the drawing color //| //| :param int red: red value for the current color. Range 0-255. The initial value is 255 //| :param int green: green for the current color. Range 0-255. The initial value is 255 //| :param int blue: blue for the current color. Range 0-255. The initial value is 255 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _colorrgb(size_t n_args, const mp_obj_t *args) { @@ -565,9 +577,8 @@ STATIC mp_obj_t _colorrgb(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(colorrgb_obj, 4, 4, _colorrgb); -//| .. method:: Display() -//| -//| End the display list +//| def Display(self, ) -> Any: ... +//| """End the display list""" //| STATIC mp_obj_t _display(mp_obj_t self) { @@ -577,12 +588,12 @@ STATIC mp_obj_t _display(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(display_obj, _display); -//| .. method:: End() +//| def End(self, ) -> Any: +//| """End drawing a graphics primitive //| -//| End drawing a graphics primitive +//| :meth:`Vertex2ii` and :meth:`Vertex2f` calls are ignored until the next :meth:`Begin`.""" +//| ... //| -//| :meth:`Vertex2ii` and :meth:`Vertex2f` calls are ignored until the next :meth:`Begin`. -//| STATIC mp_obj_t _end(mp_obj_t self) { @@ -591,11 +602,11 @@ STATIC mp_obj_t _end(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(end_obj, _end); -//| .. method:: Jump(dest) +//| def Jump(self, dest: int) -> Any: +//| """Execute commands at another location in the display list //| -//| Execute commands at another location in the display list -//| -//| :param int dest: display list address. Range 0-65535 +//| :param int dest: display list address. Range 0-65535""" +//| ... //| STATIC mp_obj_t _jump(mp_obj_t self, mp_obj_t a0) { @@ -605,13 +616,13 @@ STATIC mp_obj_t _jump(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(jump_obj, _jump); -//| .. method:: LineWidth(width) -//| -//| Set the width of rasterized lines +//| def LineWidth(self, width: int) -> Any: +//| """Set the width of rasterized lines //| //| :param int width: line width in :math:`1/16` pixel. Range 0-4095. The initial value is 16 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _linewidth(mp_obj_t self, mp_obj_t a0) { @@ -621,11 +632,11 @@ STATIC mp_obj_t _linewidth(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(linewidth_obj, _linewidth); -//| .. method:: Macro(m) +//| def Macro(self, m: int) -> Any: +//| """Execute a single command from a macro register //| -//| Execute a single command from a macro register -//| -//| :param int m: macro register to read. Range 0-1 +//| :param int m: macro register to read. Range 0-1""" +//| ... //| STATIC mp_obj_t _macro(mp_obj_t self, mp_obj_t a0) { @@ -635,9 +646,9 @@ STATIC mp_obj_t _macro(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(macro_obj, _macro); -//| .. method:: Nop() -//| -//| No operation +//| def Nop(self, ) -> Any: +//| """No operation""" +//| ... //| STATIC mp_obj_t _nop(mp_obj_t self) { @@ -647,13 +658,13 @@ STATIC mp_obj_t _nop(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(nop_obj, _nop); -//| .. method:: PaletteSource(addr) -//| -//| Set the base address of the palette +//| def PaletteSource(self, addr: int) -> Any: +//| """Set the base address of the palette //| //| :param int addr: Address in graphics SRAM, 2-byte aligned. Range 0-4194303. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _palettesource(mp_obj_t self, mp_obj_t a0) { @@ -663,13 +674,13 @@ STATIC mp_obj_t _palettesource(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(palettesource_obj, _palettesource); -//| .. method:: PointSize(size) -//| -//| Set the radius of rasterized points +//| def PointSize(self, size: int) -> Any: +//| """Set the radius of rasterized points //| //| :param int size: point radius in :math:`1/16` pixel. Range 0-8191. The initial value is 16 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _pointsize(mp_obj_t self, mp_obj_t a0) { @@ -679,9 +690,9 @@ STATIC mp_obj_t _pointsize(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(pointsize_obj, _pointsize); -//| .. method:: RestoreContext() -//| -//| Restore the current graphics context from the context stack +//| def RestoreContext(self, ) -> Any: +//| """Restore the current graphics context from the context stack""" +//| ... //| STATIC mp_obj_t _restorecontext(mp_obj_t self) { @@ -691,9 +702,9 @@ STATIC mp_obj_t _restorecontext(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(restorecontext_obj, _restorecontext); -//| .. method:: Return() -//| -//| Return from a previous call command +//| def Return(self, ) -> Any: +//| """Return from a previous call command""" +//| ... //| STATIC mp_obj_t _return(mp_obj_t self) { @@ -703,9 +714,9 @@ STATIC mp_obj_t _return(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(return_obj, _return); -//| .. method:: SaveContext() -//| -//| Push the current graphics context on the context stack +//| def SaveContext(self, ) -> Any: +//| """Push the current graphics context on the context stack""" +//| ... //| STATIC mp_obj_t _savecontext(mp_obj_t self) { @@ -715,14 +726,14 @@ STATIC mp_obj_t _savecontext(mp_obj_t self) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(savecontext_obj, _savecontext); -//| .. method:: ScissorSize(width, height) -//| -//| Set the size of the scissor clip rectangle +//| def ScissorSize(self, width: int, height: int) -> Any: +//| """Set the size of the scissor clip rectangle //| //| :param int width: The width of the scissor clip rectangle, in pixels. Range 0-4095. The initial value is hsize //| :param int height: The height of the scissor clip rectangle, in pixels. Range 0-4095. The initial value is 2048 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _scissorsize(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -733,14 +744,14 @@ STATIC mp_obj_t _scissorsize(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(scissorsize_obj, _scissorsize); -//| .. method:: ScissorXY(x, y) -//| -//| Set the top left corner of the scissor clip rectangle +//| def ScissorXY(self, x: int, y: int) -> Any: +//| """Set the top left corner of the scissor clip rectangle //| //| :param int x: The :math:`x` coordinate of the scissor clip rectangle, in pixels. Range 0-2047. The initial value is 0 //| :param int y: The :math:`y` coordinate of the scissor clip rectangle, in pixels. Range 0-2047. The initial value is 0 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _scissorxy(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -751,15 +762,15 @@ STATIC mp_obj_t _scissorxy(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(scissorxy_obj, _scissorxy); -//| .. method:: StencilFunc(func, ref, mask) -//| -//| Set function and reference value for stencil testing +//| def StencilFunc(self, func: int, ref: int, mask: int) -> Any: +//| """Set function and reference value for stencil testing //| //| :param int func: specifies the test function, one of ``NEVER``, ``LESS``, ``LEQUAL``, ``GREATER``, ``GEQUAL``, ``EQUAL``, ``NOTEQUAL``, or ``ALWAYS``. Range 0-7. The initial value is ALWAYS(7) //| :param int ref: specifies the reference value for the stencil test. Range 0-255. The initial value is 0 //| :param int mask: specifies a mask that is ANDed with the reference value and the stored stencil value. Range 0-255. The initial value is 255 //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _stencilfunc(size_t n_args, const mp_obj_t *args) { @@ -771,13 +782,13 @@ STATIC mp_obj_t _stencilfunc(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(stencilfunc_obj, 4, 4, _stencilfunc); -//| .. method:: StencilMask(mask) -//| -//| Control the writing of individual bits in the stencil planes +//| def StencilMask(self, mask: int) -> Any: +//| """Control the writing of individual bits in the stencil planes //| //| :param int mask: the mask used to enable writing stencil bits. Range 0-255. The initial value is 255 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _stencilmask(mp_obj_t self, mp_obj_t a0) { @@ -787,14 +798,14 @@ STATIC mp_obj_t _stencilmask(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(stencilmask_obj, _stencilmask); -//| .. method:: StencilOp(sfail, spass) -//| -//| Set stencil test actions +//| def StencilOp(self, sfail: int, spass: int) -> Any: +//| """Set stencil test actions //| //| :param int sfail: specifies the action to take when the stencil test fails, one of ``KEEP``, ``ZERO``, ``REPLACE``, ``INCR``, ``INCR_WRAP``, ``DECR``, ``DECR_WRAP``, and ``INVERT``. Range 0-7. The initial value is KEEP(1) //| :param int spass: specifies the action to take when the stencil test passes, one of the same constants as **sfail**. Range 0-7. The initial value is KEEP(1) //| -//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| These values are part of the graphics context and are saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _stencilop(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { @@ -805,13 +816,13 @@ STATIC mp_obj_t _stencilop(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(stencilop_obj, _stencilop); -//| .. method:: TagMask(mask) -//| -//| Control the writing of the tag buffer +//| def TagMask(self, mask: int) -> Any: +//| """Control the writing of the tag buffer //| //| :param int mask: allow updates to the tag buffer. Range 0-1. The initial value is 1 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _tagmask(mp_obj_t self, mp_obj_t a0) { @@ -821,13 +832,13 @@ STATIC mp_obj_t _tagmask(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(tagmask_obj, _tagmask); -//| .. method:: Tag(s) -//| -//| Set the current tag value +//| def Tag(self, s: int) -> Any: +//| """Set the current tag value //| //| :param int s: tag value. Range 0-255. The initial value is 255 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _tag(mp_obj_t self, mp_obj_t a0) { @@ -837,13 +848,13 @@ STATIC mp_obj_t _tag(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(tag_obj, _tag); -//| .. method:: VertexTranslateX(x) -//| -//| Set the vertex transformation's x translation component +//| def VertexTranslateX(self, x: int) -> Any: +//| """Set the vertex transformation's x translation component //| //| :param int x: signed x-coordinate in :math:`1/16` pixel. Range 0-131071. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _vertextranslatex(mp_obj_t self, mp_obj_t a0) { @@ -853,13 +864,13 @@ STATIC mp_obj_t _vertextranslatex(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(vertextranslatex_obj, _vertextranslatex); -//| .. method:: VertexTranslateY(y) -//| -//| Set the vertex transformation's y translation component +//| def VertexTranslateY(self, y: int) -> Any: +//| """Set the vertex transformation's y translation component //| //| :param int y: signed y-coordinate in :math:`1/16` pixel. Range 0-131071. The initial value is 0 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| @@ -870,13 +881,13 @@ STATIC mp_obj_t _vertextranslatey(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(vertextranslatey_obj, _vertextranslatey); -//| .. method:: VertexFormat(frac) -//| -//| Set the precision of vertex2f coordinates +//| def VertexFormat(self, frac: int) -> Any: +//| """Set the precision of vertex2f coordinates //| //| :param int frac: Number of fractional bits in X,Y coordinates, 0-4. Range 0-7. The initial value is 4 //| -//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`. +//| This value is part of the graphics context and is saved and restored by :meth:`SaveContext` and :meth:`RestoreContext`.""" +//| ... //| STATIC mp_obj_t _vertexformat(mp_obj_t self, mp_obj_t a0) { @@ -886,15 +897,15 @@ STATIC mp_obj_t _vertexformat(mp_obj_t self, mp_obj_t a0) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(vertexformat_obj, _vertexformat); -//| .. method:: Vertex2ii(x, y, handle, cell) -//| -//| :param int x: x-coordinate in pixels. Range 0-511 +//| def Vertex2ii(self, x: int, y: int, handle: int, cell: int) -> Any: +//| """:param int x: x-coordinate in pixels. Range 0-511 //| :param int y: y-coordinate in pixels. Range 0-511 //| :param int handle: bitmap handle. Range 0-31 //| :param int cell: cell number. Range 0-127 //| -//| This method is an alternative to :meth:`Vertex2f`. -//| +//| This method is an alternative to :meth:`Vertex2f`.""" +//| ... +//| STATIC mp_obj_t _vertex2ii(size_t n_args, const mp_obj_t *args) { uint32_t x = mp_obj_get_int_truncated(args[1]); @@ -961,12 +972,12 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(vertex2ii_obj, 3, 5, _vertex2ii); // Hand-written functions { -//| .. method:: Vertex2f(b) -//| -//| Draw a point. +//| def Vertex2f(self, b: Any) -> Any: +//| """Draw a point. //| //| :param float x: pixel x-coordinate -//| :param float y: pixel y-coordinate +//| :param float y: pixel y-coordinate""" +//| ... //| STATIC mp_obj_t _vertex2f(mp_obj_t self, mp_obj_t a0, mp_obj_t a1) { mp_float_t x = mp_obj_get_float(a0); @@ -980,14 +991,14 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_3(vertex2f_obj, _vertex2f); #define ADD_X(self, x) \ common_hal__eve_add(EVEHAL(self), sizeof(x), &(x)); -//| .. method:: cmd0(n) -//| -//| Append the command word n to the FIFO +//| def cmd0(self, n: int) -> Any: +//| """Append the command word n to the FIFO //| //| :param int n: The command code //| //| This method is used by the ``eve`` module to efficiently add -//| commands to the FIFO. +//| commands to the FIFO.""" +//| ... //| STATIC mp_obj_t _cmd0(mp_obj_t self, mp_obj_t n) { @@ -997,9 +1008,8 @@ STATIC mp_obj_t _cmd0(mp_obj_t self, mp_obj_t n) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(cmd0_obj, _cmd0); -//| .. method:: cmd(n, fmt, args) -//| -//| Append a command packet to the FIFO. +//| def cmd(self, n: int, fmt: str, args: tuple) -> Any: +//| """Append a command packet to the FIFO. //| //| :param int n: The command code //| :param str fmt: The command format `struct` layout @@ -1008,7 +1018,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(cmd0_obj, _cmd0); //| Supported format codes: h, H, i, I. //| //| This method is used by the ``eve`` module to efficiently add -//| commands to the FIFO. +//| commands to the FIFO.""" +//| ... //| STATIC mp_obj_t _cmd(size_t n_args, const mp_obj_t *args) { mp_obj_t self = args[0]; diff --git a/shared-bindings/fontio/BuiltinFont.c b/shared-bindings/fontio/BuiltinFont.c index 74bc4d29e..f60c9e36c 100644 --- a/shared-bindings/fontio/BuiltinFont.c +++ b/shared-bindings/fontio/BuiltinFont.c @@ -36,25 +36,25 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: fontio +//| class BuiltinFont: +//| """.. currentmodule:: fontio //| -//| :class:`BuiltinFont` -- A font built into CircuitPython -//| ========================================================================================= +//| :class:`BuiltinFont` -- A font built into CircuitPython +//| ========================================================================================= //| -//| A font built into CircuitPython. +//| A font built into CircuitPython.""" //| -//| .. class:: BuiltinFont() -//| -//| Creation not supported. Available fonts are defined when CircuitPython is built. See the -//| `Adafruit_CircuitPython_Bitmap_Font `_ -//| library for dynamically loaded fonts. +//| def __init__(self, ): +//| """Creation not supported. Available fonts are defined when CircuitPython is built. See the +//| `Adafruit_CircuitPython_Bitmap_Font `_ +//| library for dynamically loaded fonts.""" +//| ... //| -//| .. attribute:: bitmap -//| -//| Bitmap containing all font glyphs starting with ASCII and followed by unicode. Use +//| bitmap: Any = ... +//| """Bitmap containing all font glyphs starting with ASCII and followed by unicode. Use //| `get_glyph` in most cases. This is useful for use with `displayio.TileGrid` and -//| `terminalio.Terminal`. +//| `terminalio.Terminal`.""" //| STATIC mp_obj_t fontio_builtinfont_obj_get_bitmap(mp_obj_t self_in) { fontio_builtinfont_t *self = MP_OBJ_TO_PTR(self_in); @@ -69,9 +69,9 @@ const mp_obj_property_t fontio_builtinfont_bitmap_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: get_bounding_box() -//| -//| Returns the maximum bounds of all glyphs in the font in a tuple of two values: width, height. +//| def get_bounding_box(self, ) -> Any: +//| """Returns the maximum bounds of all glyphs in the font in a tuple of two values: width, height.""" +//| ... //| STATIC mp_obj_t fontio_builtinfont_obj_get_bounding_box(mp_obj_t self_in) { fontio_builtinfont_t *self = MP_OBJ_TO_PTR(self_in); @@ -81,9 +81,9 @@ STATIC mp_obj_t fontio_builtinfont_obj_get_bounding_box(mp_obj_t self_in) { MP_DEFINE_CONST_FUN_OBJ_1(fontio_builtinfont_get_bounding_box_obj, fontio_builtinfont_obj_get_bounding_box); -//| .. method:: get_glyph(codepoint) -//| -//| Returns a `fontio.Glyph` for the given codepoint or None if no glyph is available. +//| def get_glyph(self, codepoint: Any) -> Any: +//| """Returns a `fontio.Glyph` for the given codepoint or None if no glyph is available.""" +//| ... //| STATIC mp_obj_t fontio_builtinfont_obj_get_glyph(mp_obj_t self_in, mp_obj_t codepoint_obj) { fontio_builtinfont_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/fontio/Glyph.c b/shared-bindings/fontio/Glyph.c index a23284152..6235dbc46 100644 --- a/shared-bindings/fontio/Glyph.c +++ b/shared-bindings/fontio/Glyph.c @@ -28,23 +28,24 @@ #include -//| .. currentmodule:: fontio +//| class Glyph: +//| """.. currentmodule:: fontio //| -//| :class:`Glyph` -- Storage of glyph info -//| ========================================================================== +//| :class:`Glyph` -- Storage of glyph info +//| ==========================================================================""" //| -//| .. class:: Glyph(bitmap, tile_index, width, height, dx, dy, shift_x, shift_y) +//| def __init__(self, bitmap: displayio.Bitmap, tile_index: int, width: int, height: int, dx: int, dy: int, shift_x: int, shift_y: int): +//| """Named tuple used to capture a single glyph and its attributes. //| -//| Named tuple used to capture a single glyph and its attributes. -//| -//| :param displayio.Bitmap bitmap: the bitmap including the glyph -//| :param int tile_index: the tile index within the bitmap -//| :param int width: the width of the glyph's bitmap -//| :param int height: the height of the glyph's bitmap -//| :param int dx: x adjustment to the bitmap's position -//| :param int dy: y adjustment to the bitmap's position -//| :param int shift_x: the x difference to the next glyph -//| :param int shift_y: the y difference to the next glyph +//| :param displayio.Bitmap bitmap: the bitmap including the glyph +//| :param int tile_index: the tile index within the bitmap +//| :param int width: the width of the glyph's bitmap +//| :param int height: the height of the glyph's bitmap +//| :param int dx: x adjustment to the bitmap's position +//| :param int dy: y adjustment to the bitmap's position +//| :param int shift_x: the x difference to the next glyph +//| :param int shift_y: the y difference to the next glyph""" +//| ... //| const mp_obj_namedtuple_type_t fontio_glyph_type = { .base = { diff --git a/shared-bindings/fontio/__init__.c b/shared-bindings/fontio/__init__.c index cd0f5ab0f..478fc1806 100644 --- a/shared-bindings/fontio/__init__.c +++ b/shared-bindings/fontio/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/fontio/BuiltinFont.h" #include "shared-bindings/fontio/Glyph.h" -//| :mod:`fontio` --- Core font related data structures +//| """:mod:`fontio` --- Core font related data structures //| ========================================================================= //| //| .. module:: fontio @@ -48,7 +48,7 @@ //| :maxdepth: 3 //| //| BuiltinFont -//| Glyph +//| Glyph""" //| STATIC const mp_rom_map_elem_t fontio_module_globals_table[] = { diff --git a/shared-bindings/framebufferio/FramebufferDisplay.c b/shared-bindings/framebufferio/FramebufferDisplay.c index 9ff6cc12d..5e63b988e 100644 --- a/shared-bindings/framebufferio/FramebufferDisplay.c +++ b/shared-bindings/framebufferio/FramebufferDisplay.c @@ -40,23 +40,24 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: framebufferio +//| class FramebufferDisplay: +//| """.. currentmodule:: framebufferio //| -//| :class:`FramebufferDisplay` -- Manage updating a display with framebuffer in RAM -//| ================================================================================ +//| :class:`FramebufferDisplay` -- Manage updating a display with framebuffer in RAM +//| ================================================================================ //| -//| This initializes a display and connects it into CircuitPython. Unlike other -//| objects in CircuitPython, Display objects live until `displayio.release_displays()` -//| is called. This is done so that CircuitPython can use the display itself. +//| This initializes a display and connects it into CircuitPython. Unlike other +//| objects in CircuitPython, Display objects live until `displayio.release_displays()` +//| is called. This is done so that CircuitPython can use the display itself.""" //| -//| .. class:: FramebufferDisplay(framebuffer, *, rotation=0, auto_refresh=True) +//| def __init__(self, framebuffer: Any, *, rotation: int = 0, auto_refresh: bool = True): +//| """Create a Display object with the given framebuffer (a buffer, array, ulab.array, etc) //| -//| Create a Display object with the given framebuffer (a buffer, array, ulab.array, etc) -//| -//| :param framebuffer: The framebuffer that the display is connected to -//| :type framebuffer: any core object implementing the framebuffer protocol -//| :param bool auto_refresh: Automatically refresh the screen -//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) +//| :param framebuffer: The framebuffer that the display is connected to +//| :type framebuffer: any core object implementing the framebuffer protocol +//| :param bool auto_refresh: Automatically refresh the screen +//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270)""" +//| ... //| STATIC mp_obj_t framebufferio_framebufferdisplay_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_framebuffer, ARG_rotation, ARG_auto_refresh, NUM_ARGS }; @@ -96,12 +97,12 @@ static framebufferio_framebufferdisplay_obj_t* native_display(mp_obj_t display_o return MP_OBJ_TO_PTR(native_display); } -//| .. method:: show(group) -//| -//| Switches to displaying the given group of layers. When group is None, the default -//| CircuitPython terminal will be shown. +//| def show(self, group: Group) -> Any: +//| """Switches to displaying the given group of layers. When group is None, the default +//| CircuitPython terminal will be shown. //| -//| :param Group group: The group to show. +//| :param Group group: The group to show.""" +//| ... //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_show(mp_obj_t self_in, mp_obj_t group_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -118,21 +119,21 @@ STATIC mp_obj_t framebufferio_framebufferdisplay_obj_show(mp_obj_t self_in, mp_o } MP_DEFINE_CONST_FUN_OBJ_2(framebufferio_framebufferdisplay_show_obj, framebufferio_framebufferdisplay_obj_show); -//| .. method:: refresh(*, target_frames_per_second=60, minimum_frames_per_second=1) -//| -//| When auto refresh is off, waits for the target frame rate and then refreshes the display, -//| returning True. If the call has taken too long since the last refresh call for the given -//| target frame rate, then the refresh returns False immediately without updating the screen to -//| hopefully help getting caught up. +//| def refresh(self, *, target_frames_per_second: int = 60, minimum_frames_per_second: int = 1) -> Any: +//| """When auto refresh is off, waits for the target frame rate and then refreshes the display, +//| returning True. If the call has taken too long since the last refresh call for the given +//| target frame rate, then the refresh returns False immediately without updating the screen to +//| hopefully help getting caught up. //| -//| If the time since the last successful refresh is below the minimum frame rate, then an -//| exception will be raised. Set minimum_frames_per_second to 0 to disable. +//| If the time since the last successful refresh is below the minimum frame rate, then an +//| exception will be raised. Set minimum_frames_per_second to 0 to disable. //| -//| When auto refresh is on, updates the display immediately. (The display will also update -//| without calls to this.) +//| When auto refresh is on, updates the display immediately. (The display will also update +//| without calls to this.) //| -//| :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated. -//| :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second. +//| :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated. +//| :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second.""" +//| ... //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_refresh(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_target_frames_per_second, ARG_minimum_frames_per_second }; @@ -153,9 +154,8 @@ STATIC mp_obj_t framebufferio_framebufferdisplay_obj_refresh(size_t n_args, cons } MP_DEFINE_CONST_FUN_OBJ_KW(framebufferio_framebufferdisplay_refresh_obj, 1, framebufferio_framebufferdisplay_obj_refresh); -//| .. attribute:: auto_refresh -//| -//| True when the display is refreshed automatically. +//| auto_refresh: Any = ... +//| """True when the display is refreshed automatically.""" //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_auto_refresh(mp_obj_t self_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -179,11 +179,10 @@ const mp_obj_property_t framebufferio_framebufferdisplay_auto_refresh_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: brightness -//| -//| The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When +//| brightness: Any = ... +//| """The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When //| `auto_brightness` is True, the value of `brightness` will change automatically. -//| If `brightness` is set, `auto_brightness` will be disabled and will be set to False. +//| If `brightness` is set, `auto_brightness` will be disabled and will be set to False.""" //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_brightness(mp_obj_t self_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -217,12 +216,11 @@ const mp_obj_property_t framebufferio_framebufferdisplay_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: auto_brightness -//| -//| True when the display brightness is adjusted automatically, based on an ambient +//| auto_brightness: Any = ... +//| """True when the display brightness is adjusted automatically, based on an ambient //| light sensor or other method. Note that some displays may have this set to True by default, //| but not actually implement automatic brightness adjustment. `auto_brightness` is set to False -//| if `brightness` is set manually. +//| if `brightness` is set manually.""" //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_auto_brightness(mp_obj_t self_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -249,9 +247,8 @@ const mp_obj_property_t framebufferio_framebufferdisplay_auto_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: width -//| -//| Gets the width of the framebuffer +//| width: Any = ... +//| """Gets the width of the framebuffer""" //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_width(mp_obj_t self_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -266,9 +263,8 @@ const mp_obj_property_t framebufferio_framebufferdisplay_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Gets the height of the framebuffer +//| height: Any = ... +//| """Gets the height of the framebuffer""" //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_height(mp_obj_t self_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -283,9 +279,8 @@ const mp_obj_property_t framebufferio_framebufferdisplay_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: rotation -//| -//| The rotation of the display as an int in degrees. +//| rotation: Any = ... +//| """The rotation of the display as an int in degrees.""" //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_rotation(mp_obj_t self_in) { framebufferio_framebufferdisplay_obj_t *self = native_display(self_in); @@ -307,9 +302,8 @@ const mp_obj_property_t framebufferio_framebufferdisplay_rotation_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: framebuffer -//| -//| The framebuffer being used by the display +//| framebuffer: Any = ... +//| """The framebuffer being used by the display""" //| //| STATIC mp_obj_t framebufferio_framebufferdisplay_obj_get_framebuffer(mp_obj_t self_in) { @@ -326,12 +320,13 @@ const mp_obj_property_t framebufferio_framebufferframebuffer_obj = { }; -//| .. method:: fill_row(y, buffer) +//| def fill_row(self, y: int, buffer: bytearray) -> Any: +//| """Extract the pixels from a single row //| -//| Extract the pixels from a single row +//| :param int y: The top edge of the area +//| :param bytearray buffer: The buffer in which to place the pixel data""" +//| ... //| -//| :param int y: The top edge of the area -//| :param bytearray buffer: The buffer in which to place the pixel data STATIC mp_obj_t framebufferio_framebufferdisplay_obj_fill_row(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_y, ARG_buffer }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/framebufferio/__init__.c b/shared-bindings/framebufferio/__init__.c index 88f69bb2c..50725c515 100644 --- a/shared-bindings/framebufferio/__init__.c +++ b/shared-bindings/framebufferio/__init__.c @@ -28,7 +28,7 @@ #include "shared-bindings/framebufferio/__init__.h" #include "shared-bindings/framebufferio/FramebufferDisplay.h" -//| :mod:`framebufferio` --- Native framebuffer display driving +//| """:mod:`framebufferio` --- Native framebuffer display driving //| ========================================================================= //| //| .. module:: framebufferio @@ -46,7 +46,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| FramebufferDisplay +//| FramebufferDisplay""" //| #if CIRCUITPY_FRAMEBUFFERIO diff --git a/shared-bindings/frequencyio/FrequencyIn.c b/shared-bindings/frequencyio/FrequencyIn.c index 6743f8706..270fa87c3 100644 --- a/shared-bindings/frequencyio/FrequencyIn.c +++ b/shared-bindings/frequencyio/FrequencyIn.c @@ -35,43 +35,44 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: frequencyio +//| class FrequencyIn: +//| """.. currentmodule:: frequencyio //| -//| :class:`FrequencyIn` -- Read a frequency signal -//| ======================================================== +//| :class:`FrequencyIn` -- Read a frequency signal +//| ======================================================== //| -//| FrequencyIn is used to measure the frequency, in hertz, of a digital signal -//| on an incoming pin. Accuracy has shown to be within 10%, if not better. It -//| is recommended to utilize an average of multiple samples to smooth out readings. +//| FrequencyIn is used to measure the frequency, in hertz, of a digital signal +//| on an incoming pin. Accuracy has shown to be within 10%, if not better. It +//| is recommended to utilize an average of multiple samples to smooth out readings. //| -//| Frequencies below 1KHz are not currently detectable. +//| Frequencies below 1KHz are not currently detectable. //| -//| FrequencyIn will not determine pulse width (use ``PulseIn``). +//| FrequencyIn will not determine pulse width (use ``PulseIn``).""" //| -//| .. class:: FrequencyIn(pin, capture_period=10) +//| def __init__(self, pin: microcontroller.Pin, capture_period: int = 10): +//| """Create a FrequencyIn object associated with the given pin. //| -//| Create a FrequencyIn object associated with the given pin. +//| :param ~microcontroller.Pin pin: Pin to read frequency from. +//| :param int capture_period: Keyword argument to set the measurement period, in +//| milliseconds. Default is 10ms; range is 1ms - 500ms. //| -//| :param ~microcontroller.Pin pin: Pin to read frequency from. -//| :param int capture_period: Keyword argument to set the measurement period, in -//| milliseconds. Default is 10ms; range is 1ms - 500ms. +//| Read the incoming frequency from a pin:: //| -//| Read the incoming frequency from a pin:: +//| import frequencyio +//| import board //| -//| import frequencyio -//| import board +//| frequency = frequencyio.FrequencyIn(board.D11) //| -//| frequency = frequencyio.FrequencyIn(board.D11) +//| # Loop while printing the detected frequency +//| while True: +//| print(frequency.value) //| -//| # Loop while printing the detected frequency -//| while True: -//| print(frequency.value) -//| -//| # Optional clear() will reset the value -//| # to zero. Without this, if the incoming -//| # signal stops, the last reading will remain -//| # as the value. -//| frequency.clear() +//| # Optional clear() will reset the value +//| # to zero. Without this, if the incoming +//| # signal stops, the last reading will remain +//| # as the value. +//| frequency.clear()""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -96,9 +97,9 @@ STATIC mp_obj_t frequencyio_frequencyin_make_new(const mp_obj_type_t *type, size return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the FrequencyIn and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the FrequencyIn and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_deinit(mp_obj_t self_in) { frequencyio_frequencyin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -113,16 +114,16 @@ STATIC void check_for_deinit(frequencyio_frequencyin_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -131,9 +132,9 @@ STATIC mp_obj_t frequencyio_frequencyin_obj___exit__(size_t n_args, const mp_obj } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(frequencyio_frequencyin___exit___obj, 4, 4, frequencyio_frequencyin_obj___exit__); -//| .. method:: pause() -//| -//| Pause frequency capture. +//| def pause(self, ) -> Any: +//| """Pause frequency capture.""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_obj_pause(mp_obj_t self_in) { frequencyio_frequencyin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -144,9 +145,9 @@ STATIC mp_obj_t frequencyio_frequencyin_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(frequencyio_frequencyin_pause_obj, frequencyio_frequencyin_obj_pause); -//| .. method:: resume() -//| -//| Resumes frequency capture. +//| def resume(self, ) -> Any: +//| """Resumes frequency capture.""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_obj_resume(mp_obj_t self_in) { frequencyio_frequencyin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -157,9 +158,9 @@ STATIC mp_obj_t frequencyio_frequencyin_obj_resume(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(frequencyio_frequencyin_resume_obj, frequencyio_frequencyin_obj_resume); -//| .. method:: clear() -//| -//| Clears the last detected frequency capture value. +//| def clear(self, ) -> Any: +//| """Clears the last detected frequency capture value.""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_obj_clear(mp_obj_t self_in) { @@ -171,14 +172,13 @@ STATIC mp_obj_t frequencyio_frequencyin_obj_clear(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(frequencyio_frequencyin_clear_obj, frequencyio_frequencyin_obj_clear); -//| .. attribute:: capture_period -//| -//| The capture measurement period. Lower incoming frequencies will be measured +//| capture_period: Any = ... +//| """The capture measurement period. Lower incoming frequencies will be measured //| more accurately with longer capture periods. Higher frequencies are more //| accurate with shorter capture periods. //| -//| .. note:: When setting a new ``capture_period``, all previous capture information is -//| cleared with a call to ``clear()``. +//| .. note:: When setting a new ``capture_period``, all previous capture information is +//| cleared with a call to ``clear()``.""" //| STATIC mp_obj_t frequencyio_frequencyin_obj_get_capture_period(mp_obj_t self_in) { frequencyio_frequencyin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -204,9 +204,9 @@ const mp_obj_property_t frequencyio_frequencyin_capture_period_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __get__(index) -//| -//| Returns the value of the last frequency captured. +//| def __get__(self, index: Any) -> Any: +//| """Returns the value of the last frequency captured.""" +//| ... //| STATIC mp_obj_t frequencyio_frequencyin_obj_get_value(mp_obj_t self_in) { frequencyio_frequencyin_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/frequencyio/__init__.c b/shared-bindings/frequencyio/__init__.c index 48a026824..219d5f645 100644 --- a/shared-bindings/frequencyio/__init__.c +++ b/shared-bindings/frequencyio/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/frequencyio/__init__.h" #include "shared-bindings/frequencyio/FrequencyIn.h" -//| :mod:`frequencyio` --- Support for frequency based protocols +//| """:mod:`frequencyio` --- Support for frequency based protocols //| ============================================================= //| //| .. module:: frequencyio @@ -73,7 +73,7 @@ //| :py:data:`~frequencyio.FrequencyIn.capture_period`, and then sleep 0.1 seconds. //| CircuitPython will automatically turn off FrequencyIn capture when it resets all //| hardware after program completion. Use ``deinit()`` or a ``with`` statement -//| to do it yourself. +//| to do it yourself.""" //| STATIC const mp_rom_map_elem_t frequencyio_module_globals_table[] = { -- cgit v1.2.3 From 4f33a20d17c7b7688e5dd1ee37346ff2d4f4a340 Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 7 May 2020 15:10:44 -0400 Subject: Added gamepad, gamepadshift, and i2cslave --- shared-bindings/gamepad/GamePad.c | 110 +++++++++++----------- shared-bindings/gamepad/__init__.c | 4 +- shared-bindings/gamepadshift/GamePadShift.c | 41 +++++---- shared-bindings/gamepadshift/__init__.c | 4 +- shared-bindings/i2cslave/I2CSlave.c | 138 ++++++++++++++-------------- shared-bindings/i2cslave/__init__.c | 4 +- 6 files changed, 149 insertions(+), 152 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/gamepad/GamePad.c b/shared-bindings/gamepad/GamePad.c index d3c29019a..946a24dbf 100644 --- a/shared-bindings/gamepad/GamePad.c +++ b/shared-bindings/gamepad/GamePad.c @@ -34,65 +34,65 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: gamepad +//| class GamePad: +//| """.. currentmodule:: gamepad //| -//| :class:`GamePad` -- Scan buttons for presses -//| ============================================ +//| :class:`GamePad` -- Scan buttons for presses +//| ============================================ //| -//| Usage:: +//| Usage:: //| -//| import board -//| import digitalio -//| import gamepad -//| import time +//| import board +//| import digitalio +//| import gamepad +//| import time //| -//| B_UP = 1 << 0 -//| B_DOWN = 1 << 1 +//| B_UP = 1 << 0 +//| B_DOWN = 1 << 1 //| //| -//| pad = gamepad.GamePad( -//| digitalio.DigitalInOut(board.D10), -//| digitalio.DigitalInOut(board.D11), -//| ) +//| pad = gamepad.GamePad( +//| digitalio.DigitalInOut(board.D10), +//| digitalio.DigitalInOut(board.D11), +//| ) //| -//| y = 0 -//| while True: -//| buttons = pad.get_pressed() -//| if buttons & B_UP: -//| y -= 1 -//| print(y) -//| elif buttons & B_DOWN: -//| y += 1 -//| print(y) -//| time.sleep(0.1) -//| while buttons: -//| # Wait for all buttons to be released. +//| y = 0 +//| while True: //| buttons = pad.get_pressed() +//| if buttons & B_UP: +//| y -= 1 +//| print(y) +//| elif buttons & B_DOWN: +//| y += 1 +//| print(y) //| time.sleep(0.1) +//| while buttons: +//| # Wait for all buttons to be released. +//| buttons = pad.get_pressed() +//| time.sleep(0.1)""" //| -//| .. class:: GamePad([b1[, b2[, b3[, b4[, b5[, b6[, b7[, b8]]]]]]]]) -//| -//| Initializes button scanning routines. -//| -//| The ``b1``-``b8`` parameters are ``DigitalInOut`` objects, which -//| immediately get switched to input with a pull-up, (unless they already -//| were set to pull-down, in which case they remain so), and then scanned -//| regularly for button presses. The order is the same as the order of -//| bits returned by the ``get_pressed`` function. You can re-initialize -//| it with different keys, then the new object will replace the previous -//| one. -//| -//| The basic feature required here is the ability to poll the keys at -//| regular intervals (so that de-bouncing is consistent) and fast enough -//| (so that we don't miss short button presses) while at the same time -//| letting the user code run normally, call blocking functions and wait -//| on delays. -//| -//| They button presses are accumulated, until the ``get_pressed`` method -//| is called, at which point the button state is cleared, and the new -//| button presses start to be recorded. +//| def __init__(self, b1: Any, b2: Any, b3: Any, b4: Any, b5: Any, b6: Any, b7: Any, b8: Any): +//| """Initializes button scanning routines. +//| +//| The ``b1``-``b8`` parameters are ``DigitalInOut`` objects, which +//| immediately get switched to input with a pull-up, (unless they already +//| were set to pull-down, in which case they remain so), and then scanned +//| regularly for button presses. The order is the same as the order of +//| bits returned by the ``get_pressed`` function. You can re-initialize +//| it with different keys, then the new object will replace the previous +//| one. +//| +//| The basic feature required here is the ability to poll the keys at +//| regular intervals (so that de-bouncing is consistent) and fast enough +//| (so that we don't miss short button presses) while at the same time +//| letting the user code run normally, call blocking functions and wait +//| on delays. +//| +//| They button presses are accumulated, until the ``get_pressed`` method +//| is called, at which point the button state is cleared, and the new +//| button presses start to be recorded.""" +//| ... //| STATIC mp_obj_t gamepad_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -114,15 +114,15 @@ STATIC mp_obj_t gamepad_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(gamepad_singleton); } -//| .. method:: get_pressed() -//| -//| Get the status of buttons pressed since the last call and clear it. +//| def get_pressed(self, ) -> Any: +//| """Get the status of buttons pressed since the last call and clear it. //| //| Returns an 8-bit number, with bits that correspond to buttons, //| which have been pressed (or held down) since the last call to this //| function set to 1, and the remaining bits set to 0. Then it clears //| the button state, so that new button presses (or buttons that are -//| held down) can be recorded for the next call. +//| held down) can be recorded for the next call.""" +//| ... //| STATIC mp_obj_t gamepad_get_pressed(mp_obj_t self_in) { gamepad_obj_t* gamepad_singleton = MP_STATE_VM(gamepad_singleton); @@ -133,9 +133,9 @@ STATIC mp_obj_t gamepad_get_pressed(mp_obj_t self_in) { MP_DEFINE_CONST_FUN_OBJ_1(gamepad_get_pressed_obj, gamepad_get_pressed); -//| .. method:: deinit() -//| -//| Disable button scanning. +//| def deinit(self, ) -> Any: +//| """Disable button scanning.""" +//| ... //| STATIC mp_obj_t gamepad_deinit(mp_obj_t self_in) { common_hal_gamepad_gamepad_deinit(self_in); diff --git a/shared-bindings/gamepad/__init__.c b/shared-bindings/gamepad/__init__.c index cea0b4ee9..0c32fd6c1 100644 --- a/shared-bindings/gamepad/__init__.c +++ b/shared-bindings/gamepad/__init__.c @@ -29,7 +29,7 @@ #include "shared-bindings/gamepad/GamePad.h" #include "shared-bindings/util.h" -//| :mod:`gamepad` --- Button handling +//| """:mod:`gamepad` --- Button handling //| ================================== //| //| .. module:: gamepad @@ -39,7 +39,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| GamePad +//| GamePad""" //| STATIC const mp_rom_map_elem_t gamepad_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_gamepad) }, diff --git a/shared-bindings/gamepadshift/GamePadShift.c b/shared-bindings/gamepadshift/GamePadShift.c index 91203ad20..37be3d957 100644 --- a/shared-bindings/gamepadshift/GamePadShift.c +++ b/shared-bindings/gamepadshift/GamePadShift.c @@ -32,24 +32,25 @@ #include "shared-bindings/gamepadshift/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: gamepadshift +//| class GamePadShift: +//| """.. currentmodule:: gamepadshift //| -//| :class:`GamePadShift` -- Scan buttons for presses through a shift register -//| =========================================================================== +//| :class:`GamePadShift` -- Scan buttons for presses through a shift register +//| ===========================================================================""" //| -//| .. class:: GamePadShift(clock, data, latch) +//| def __init__(self, clock: Any, data: Any, latch: Any): +//| """Initializes button scanning routines. //| -//| Initializes button scanning routines. +//| The ``clock``, ``data`` and ``latch`` parameters are ``DigitalInOut`` +//| objects connected to the shift register controlling the buttons. //| -//| The ``clock``, ``data`` and ``latch`` parameters are ``DigitalInOut`` -//| objects connected to the shift register controlling the buttons. +//| They button presses are accumulated, until the ``get_pressed`` method +//| is called, at which point the button state is cleared, and the new +//| button presses start to be recorded. //| -//| They button presses are accumulated, until the ``get_pressed`` method -//| is called, at which point the button state is cleared, and the new -//| button presses start to be recorded. -//| -//| Only one gamepad (`gamepad.GamePad` or `gamepadshift.GamePadShift`) -//| may be used at a time. +//| Only one gamepad (`gamepad.GamePad` or `gamepadshift.GamePadShift`) +//| may be used at a time.""" +//| ... //| STATIC mp_obj_t gamepadshift_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -81,15 +82,15 @@ STATIC mp_obj_t gamepadshift_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(gamepad_singleton); } -//| .. method:: get_pressed() -//| -//| Get the status of buttons pressed since the last call and clear it. +//| def get_pressed(self, ) -> Any: +//| """Get the status of buttons pressed since the last call and clear it. //| //| Returns an 8-bit number, with bits that correspond to buttons, //| which have been pressed (or held down) since the last call to this //| function set to 1, and the remaining bits set to 0. Then it clears //| the button state, so that new button presses (or buttons that are -//| held down) can be recorded for the next call. +//| held down) can be recorded for the next call.""" +//| ... //| STATIC mp_obj_t gamepadshift_get_pressed(mp_obj_t self_in) { gamepadshift_obj_t* gamepad_singleton = MP_STATE_VM(gamepad_singleton); @@ -99,9 +100,9 @@ STATIC mp_obj_t gamepadshift_get_pressed(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(gamepadshift_get_pressed_obj, gamepadshift_get_pressed); -//| .. method:: deinit() -//| -//| Disable button scanning. +//| def deinit(self, ) -> Any: +//| """Disable button scanning.""" +//| ... //| STATIC mp_obj_t gamepadshift_deinit(mp_obj_t self_in) { common_hal_gamepadshift_gamepadshift_deinit(self_in); diff --git a/shared-bindings/gamepadshift/__init__.c b/shared-bindings/gamepadshift/__init__.c index 2d3667726..3763b0487 100644 --- a/shared-bindings/gamepadshift/__init__.c +++ b/shared-bindings/gamepadshift/__init__.c @@ -30,7 +30,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "shared-bindings/util.h" -//| :mod:`gamepadshift` --- Tracks button presses read through a shift register +//| """:mod:`gamepadshift` --- Tracks button presses read through a shift register //| =========================================================================== //| //| .. module:: gamepadshift @@ -40,7 +40,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| GamePadShift +//| GamePadShift""" //| STATIC const mp_rom_map_elem_t gamepadshift_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_gamepadshift) }, diff --git a/shared-bindings/i2cslave/I2CSlave.c b/shared-bindings/i2cslave/I2CSlave.c index e28eb3f25..5bab2af74 100644 --- a/shared-bindings/i2cslave/I2CSlave.c +++ b/shared-bindings/i2cslave/I2CSlave.c @@ -49,20 +49,21 @@ STATIC mp_obj_t mp_obj_new_i2cslave_i2c_slave_request(i2cslave_i2c_slave_obj_t * return (mp_obj_t)self; } -//| .. currentmodule:: i2cslave +//| class I2CSlave: +//| """.. currentmodule:: i2cslave //| -//| :class:`I2CSlave` --- Two wire serial protocol slave -//| ---------------------------------------------------- +//| :class:`I2CSlave` --- Two wire serial protocol slave +//| ----------------------------------------------------""" //| -//| .. class:: I2CSlave(scl, sda, addresses, smbus=False) +//| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, addresses: tuple, smbus: bool = False): +//| """I2C is a two-wire protocol for communicating between devices. +//| This implements the slave side. //| -//| I2C is a two-wire protocol for communicating between devices. -//| This implements the slave side. -//| -//| :param ~microcontroller.Pin scl: The clock pin -//| :param ~microcontroller.Pin sda: The data pin -//| :param tuple addresses: The I2C addresses to respond to (how many is hw dependent). -//| :param bool smbus: Use SMBUS timings if the hardware supports it +//| :param ~microcontroller.Pin scl: The clock pin +//| :param ~microcontroller.Pin sda: The data pin +//| :param tuple addresses: The I2C addresses to respond to (how many is hw dependent). +//| :param bool smbus: Use SMBUS timings if the hardware supports it""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { i2cslave_i2c_slave_obj_t *self = m_new_obj(i2cslave_i2c_slave_obj_t); @@ -104,9 +105,9 @@ STATIC mp_obj_t i2cslave_i2c_slave_make_new(const mp_obj_type_t *type, size_t n_ return (mp_obj_t)self; } -//| .. method:: deinit() -//| -//| Releases control of the underlying hardware so other classes can use it. +//| def deinit(self, ) -> Any: +//| """Releases control of the underlying hardware so other classes can use it.""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_obj_deinit(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_type)); @@ -116,16 +117,16 @@ STATIC mp_obj_t i2cslave_i2c_slave_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(i2cslave_i2c_slave_deinit_obj, i2cslave_i2c_slave_obj_deinit); -//| .. method:: __enter__() -//| -//| No-op used in Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used in Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware on context exit. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_obj___exit__(size_t n_args, const mp_obj_t *args) { mp_check_self(MP_OBJ_IS_TYPE(args[0], &i2cslave_i2c_slave_type)); @@ -135,13 +136,12 @@ STATIC mp_obj_t i2cslave_i2c_slave_obj___exit__(size_t n_args, const mp_obj_t *a } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(i2cslave_i2c_slave___exit___obj, 4, 4, i2cslave_i2c_slave_obj___exit__); -//| .. method:: request(timeout=-1) +//| def request(self, timeout: float = -1) -> Any: +//| """Wait for an I2C request from a master. //| -//| Wait for an I2C request from a master. -//| -//| :param float timeout: Timeout in seconds. Zero means wait forever, a negative value means check once -//| :return: I2C Slave Request or None if timeout=-1 and there's no request -//| :rtype: ~i2cslave.I2CSlaveRequest +//| :param float timeout: Timeout in seconds. Zero means wait forever, a negative value means check once +//| :return: I2C Slave Request or None if timeout=-1 and there's no request +//| :rtype: ~i2cslave.I2CSlaveRequest""" //| STATIC mp_obj_t i2cslave_i2c_slave_request(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_check_self(MP_OBJ_IS_TYPE(pos_args[0], &i2cslave_i2c_slave_type)); @@ -228,34 +228,33 @@ const mp_obj_type_t i2cslave_i2c_slave_type = { .locals_dict = (mp_obj_dict_t*)&i2cslave_i2c_slave_locals_dict, }; - -//| :class:`I2CSlaveRequest` --- I2C Slave Request -//| ---------------------------------------------- +//| class I2CSlaveRequest: +//| """:class:`I2CSlaveRequest` --- I2C Slave Request +//| ----------------------------------------------""" //| -//| .. class:: I2CSlaveRequest(slave, address, is_read, is_restart) +//| def __init__(self, slave: i2cslave.I2CSlave, address: int, is_read: bool, is_restart: bool): +//| """I2C transfer request from a master. +//| This cannot be instantiated directly, but is returned by :py:meth:`I2CSlave.request`. //| -//| I2C transfer request from a master. -//| This cannot be instantiated directly, but is returned by :py:meth:`I2CSlave.request`. -//| -//| :param ~i2cslave.I2CSlave slave: The I2C Slave receiving this request -//| :param int address: I2C address -//| :param bool is_read: I2C Master read request -//| :param bool is_restart: Repeated Start Condition +//| :param ~i2cslave.I2CSlave slave: The I2C Slave receiving this request +//| :param int address: I2C address +//| :param bool is_read: I2C Master read request +//| :param bool is_restart: Repeated Start Condition""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 4, 4, false); return mp_obj_new_i2cslave_i2c_slave_request(args[0], mp_obj_get_int(args[1]), mp_obj_is_true(args[2]), mp_obj_is_true(args[3])); } -//| .. method:: __enter__() -//| -//| No-op used in Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used in Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Close the request. +//| def __exit__(self, ) -> Any: +//| """Close the request.""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_obj___exit__(size_t n_args, const mp_obj_t *args) { mp_check_self(MP_OBJ_IS_TYPE(args[0], &i2cslave_i2c_slave_request_type)); @@ -265,9 +264,8 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_obj___exit__(size_t n_args, const mp_ } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(i2cslave_i2c_slave_request___exit___obj, 4, 4, i2cslave_i2c_slave_request_obj___exit__); -//| .. attribute:: address -//| -//| The I2C address of the request. +//| address: Any = ... +//| """The I2C address of the request.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_request_type)); @@ -276,9 +274,8 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_address_obj, i2cslave_i2c_slave_request_get_address); -//| .. attribute:: is_read -//| -//| The I2C master is reading from the device. +//| is_read: Any = ... +//| """The I2C master is reading from the device.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_request_type)); @@ -287,9 +284,8 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_is_read_obj, i2cslave_i2c_slave_request_get_is_read); -//| .. attribute:: is_restart -//| -//| Is Repeated Start Condition. +//| is_restart: Any = ... +//| """Is Repeated Start Condition.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_restart(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_request_type)); @@ -298,15 +294,15 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_restart(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_is_restart_obj, i2cslave_i2c_slave_request_get_is_restart); -//| .. method:: read(n=-1, ack=True) +//| def read(self, n: int = -1, ack: bool = True) -> Any: +//| """Read data. +//| If ack=False, the caller is responsible for calling :py:meth:`I2CSlaveRequest.ack`. //| -//| Read data. -//| If ack=False, the caller is responsible for calling :py:meth:`I2CSlaveRequest.ack`. -//| -//| :param int n: Number of bytes to read (negative means all) -//| :param bool ack: Whether or not to send an ACK after the n'th byte -//| :return: Bytes read -//| :rtype: bytearray +//| :param int n: Number of bytes to read (negative means all) +//| :param bool ack: Whether or not to send an ACK after the n'th byte +//| :return: Bytes read +//| :rtype: bytearray""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_read(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_check_self(MP_OBJ_IS_TYPE(pos_args[0], &i2cslave_i2c_slave_request_type)); @@ -359,12 +355,12 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_read(size_t n_args, const mp_obj_t *p } MP_DEFINE_CONST_FUN_OBJ_KW(i2cslave_i2c_slave_request_read_obj, 1, i2cslave_i2c_slave_request_read); -//| .. method:: write(buffer) -//| -//| Write the data contained in buffer. +//| def write(self, buffer: bytearray) -> Any: +//| """Write the data contained in buffer. //| -//| :param bytearray buffer: Write out the data in this buffer -//| :return: Number of bytes written +//| :param bytearray buffer: Write out the data in this buffer +//| :return: Number of bytes written""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_write(mp_obj_t self_in, mp_obj_t buf_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_request_type)); @@ -393,12 +389,12 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_write(mp_obj_t self_in, mp_obj_t buf_ } STATIC MP_DEFINE_CONST_FUN_OBJ_2(i2cslave_i2c_slave_request_write_obj, i2cslave_i2c_slave_request_write); -//| .. method:: ack(ack=True) -//| -//| Acknowledge or Not Acknowledge last byte received. -//| Use together with :py:meth:`I2CSlaveRequest.read` ack=False. +//| def ack(self, ack: bool = True) -> Any: +//| """Acknowledge or Not Acknowledge last byte received. +//| Use together with :py:meth:`I2CSlaveRequest.read` ack=False. //| -//| :param bool ack: Whether to send an ACK or NACK +//| :param bool ack: Whether to send an ACK or NACK""" +//| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_ack(uint n_args, const mp_obj_t *args) { mp_check_self(MP_OBJ_IS_TYPE(args[0], &i2cslave_i2c_slave_request_type)); diff --git a/shared-bindings/i2cslave/__init__.c b/shared-bindings/i2cslave/__init__.c index 1c692e54e..ffeb216fa 100644 --- a/shared-bindings/i2cslave/__init__.c +++ b/shared-bindings/i2cslave/__init__.c @@ -35,7 +35,7 @@ #include "py/runtime.h" -//| :mod:`i2cslave` --- Two wire serial protocol slave +//| """:mod:`i2cslave` --- Two wire serial protocol slave //| ================================================== //| //| .. module:: i2cslave @@ -101,7 +101,7 @@ //| //| Raspberry Pi in particular does not support this with its I2C hw block. //| This can be worked around by using the ``i2c-gpio`` bit banging driver. -//| Since the RPi firmware uses the hw i2c, it's not possible to emulate a HAT eeprom. +//| Since the RPi firmware uses the hw i2c, it's not possible to emulate a HAT eeprom.""" //| STATIC const mp_rom_map_elem_t i2cslave_module_globals_table[] = { -- cgit v1.2.3 From e31e9eeaa1e1dad1bd2243b7be76012aa2ee64b8 Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 7 May 2020 15:59:52 -0400 Subject: Did math, microcontroller, and multiterminal --- shared-bindings/math/__init__.c | 164 ++++++++++++++-------------- shared-bindings/microcontroller/Pin.c | 19 ++-- shared-bindings/microcontroller/Processor.c | 49 ++++----- shared-bindings/microcontroller/RunMode.c | 37 +++---- shared-bindings/microcontroller/__init__.c | 78 +++++++------ shared-bindings/multiterminal/__init__.c | 32 +++--- 6 files changed, 184 insertions(+), 195 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c index 0bf8047c9..755bf7589 100644 --- a/shared-bindings/math/__init__.c +++ b/shared-bindings/math/__init__.c @@ -38,7 +38,7 @@ #define MP_PI MICROPY_FLOAT_CONST(3.14159265358979323846) -//| :mod:`math` --- mathematical functions +//| """:mod:`math` --- mathematical functions //| ======================================================== //| //| .. module:: math @@ -46,7 +46,7 @@ //| :platform: SAMD21/SAMD51 //| //| The `math` module provides some basic mathematical functions for -//| working with floating-point numbers. +//| working with floating-point numbers.""" //| STATIC NORETURN void math_error(void) { @@ -86,117 +86,113 @@ STATIC NORETURN void math_error(void) { //| Constants //| --------- //| - //| .. data:: e + //| e: Any = ... + //| """base of the natural logarithm""" //| - //| base of the natural logarithm - //| - //| .. data:: pi - //| - //| the ratio of a circle's circumference to its diameter + //| pi: Any = ... + //| """the ratio of a circle's circumference to its diameter""" //| //| Functions //| --------- //| - //| .. function:: acos(x) - //| - //| Return the inverse cosine of ``x``. - //| - //| .. function:: asin(x) - //| - //| Return the inverse sine of ``x``. - //| - //| .. function:: atan(x) - //| - //| Return the inverse tangent of ``x``. - //| - //| .. function:: atan2(y,x) - //| - //| Return the principal value of the inverse tangent of ``y/x``. - //| - //| .. function:: ceil(x) - //| - //| Return an integer, being ``x`` rounded towards positive infinity. - //| - //| .. function:: copysign(x,y) - //| - //| Return ``x`` with the sign of ``y``. - //| - //| .. function:: cos(x) - //| - //| Return the cosine of ``x``. - //| - //| .. function:: degrees(x) - //| - //| Return radians ``x`` converted to degrees. - //| - //| .. function:: exp(x) - //| - //| Return the exponential of ``x``. - //| - //| .. function:: fabs(x) - //| - //| Return the absolute value of ``x``. - //| - //| .. function:: floor(x) - //| - //| Return an integer, being ``x`` rounded towards negative infinity. - //| - //| .. function:: fmod(x,y) - //| - //| Return the remainder of ``x/y``. - //| - //| .. function:: frexp(x) + //| def acos(x: Any) -> Any: + //| """Return the inverse cosine of ``x``.""" + //| ... //| - //| Decomposes a floating-point number into its mantissa and exponent. - //| The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` - //| exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise - //| the relation ``0.5 <= abs(m) < 1`` holds. + //| def asin(x: Any) -> Any: + //| """Return the inverse sine of ``x``.""" + //| ... //| - //| .. function:: isfinite(x) + //| def atan(x: Any) -> Any: + //| """Return the inverse tangent of ``x``.""" + //| ... //| - //| Return ``True`` if ``x`` is finite. + //| def atan2(y: Any, x: Any) -> Any: + //| """Return the principal value of the inverse tangent of ``y/x``.""" + //| ... //| - //| .. function:: isinf(x) + //| def ceil(x: Any) -> Any: + //| """Return an integer, being ``x`` rounded towards positive infinity.""" + //| ... //| - //| Return ``True`` if ``x`` is infinite. + //| def copysign(x: Any, y: Any) -> Any: + //| """Return ``x`` with the sign of ``y``.""" + //| ... //| - //| .. function:: isnan(x) + //| def cos(x: Any) -> Any: + //| """Return the cosine of ``x``.""" + //| ... //| - //| Return ``True`` if ``x`` is not-a-number + //| def degrees(x: Any) -> Any: + //| """Return radians ``x`` converted to degrees.""" + //| ... //| - //| .. function:: ldexp(x, exp) + //| def exp(x: Any) -> Any: + //| """Return the exponential of ``x``.""" + //| ... //| - //| Return ``x * (2**exp)``. + //| def fabs(x: Any) -> Any: + //| """Return the absolute value of ``x``.""" + //| ... //| - //| .. function:: modf(x) + //| def floor(x: Any) -> Any: + //| """Return an integer, being ``x`` rounded towards negative infinity.""" + //| ... //| - //| Return a tuple of two floats, being the fractional and integral parts of - //| ``x``. Both return values have the same sign as ``x``. + //| def fmod(x: Any, y: Any) -> Any: + //| """Return the remainder of ``x/y``.""" + //| ... //| - //| .. function:: pow(x, y) + //| def frexp(x: Any) -> Any: + //| """Decomposes a floating-point number into its mantissa and exponent. + //| The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` + //| exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise + //| the relation ``0.5 <= abs(m) < 1`` holds.""" + //| ... //| - //| Returns ``x`` to the power of ``y``. + //| def isfinite(x: Any) -> Any: + //| """Return ``True`` if ``x`` is finite.""" + //| ... //| - //| .. function:: radians(x) + //| def isinf(x: Any) -> Any: + //| """Return ``True`` if ``x`` is infinite.""" + //| ... //| - //| Return degrees ``x`` converted to radians. + //| def isnan(x: Any) -> Any: + //| """Return ``True`` if ``x`` is not-a-number""" + //| ... //| - //| .. function:: sin(x) + //| def ldexp(x: Any, exp: Any) -> Any: + //| """Return ``x * (2**exp)``.""" + //| ... //| - //| Return the sine of ``x``. + //| def modf(x: Any) -> Any: + //| """Return a tuple of two floats, being the fractional and integral parts of + //| ``x``. Both return values have the same sign as ``x``.""" + //| ... //| - //| .. function:: sqrt(x) + //| def pow(x: Any, y: Any) -> Any: + //| """Returns ``x`` to the power of ``y``.""" //| - //| Returns the square root of ``x``. + //| def radians(x: Any) -> Any: + //| """Return degrees ``x`` converted to radians.""" //| - //| .. function:: tan(x) + //| def sin(x: Any) -> Any: + //| """Return the sine of ``x``.""" + //| ... //| - //| Return the tangent of ``x``. + //| def sqrt(x: Any) -> Any: + //| """Returns the square root of ``x``.""" + //| ... //| - //| .. function:: trunc(x) + //| def tan(x: Any) -> Any: ... + //| """Return the tangent of ``x``.""" + //| ... //| - //| Return an integer, being ``x`` rounded towards 0. + //| def trunc(x: Any) -> Any: + //| """Return an integer, being ``x`` rounded towards 0.""" + //| ... //| MATH_FUN_1_ERRCOND(sqrt, sqrt, (x < (mp_float_t)0.0)) diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c index 67aecaf66..cad0d67b1 100644 --- a/shared-bindings/microcontroller/Pin.c +++ b/shared-bindings/microcontroller/Pin.c @@ -33,18 +33,19 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: microcontroller +//| class Pin: +//| """.. currentmodule:: microcontroller //| -//| :class:`Pin` --- Pin reference -//| ------------------------------------------ +//| :class:`Pin` --- Pin reference +//| ------------------------------------------ //| -//| Identifies an IO pin on the microcontroller. +//| Identifies an IO pin on the microcontroller.""" //| -//| .. class:: Pin() -//| -//| Identifies an IO pin on the microcontroller. They are fixed by the -//| hardware so they cannot be constructed on demand. Instead, use -//| `board` or `microcontroller.pin` to reference the desired pin. +//| def __init__(self, ): +//| """Identifies an IO pin on the microcontroller. They are fixed by the +//| hardware so they cannot be constructed on demand. Instead, use +//| `board` or `microcontroller.pin` to reference the desired pin.""" +//| ... //| static void get_pin_name(const mcu_pin_obj_t *self, qstr* package, qstr* module, qstr* name) { diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c index 023f063e0..dedb5a27c 100644 --- a/shared-bindings/microcontroller/Processor.c +++ b/shared-bindings/microcontroller/Processor.c @@ -34,29 +34,29 @@ #include "py/runtime.h" -//| .. currentmodule:: microcontroller +//| class Processor: +//| """.. currentmodule:: microcontroller //| -//| :class:`Processor` --- Microcontroller CPU information and control -//| ------------------------------------------------------------------ +//| :class:`Processor` --- Microcontroller CPU information and control +//| ------------------------------------------------------------------ //| -//| Get information about the microcontroller CPU and control it. +//| Get information about the microcontroller CPU and control it. //| -//| Usage:: +//| Usage:: //| -//| import microcontroller -//| print(microcontroller.cpu.frequency) -//| print(microcontroller.cpu.temperature) +//| import microcontroller +//| print(microcontroller.cpu.frequency) +//| print(microcontroller.cpu.temperature)""" //| -//| .. class:: Processor() -//| -//| You cannot create an instance of `microcontroller.Processor`. -//| Use `microcontroller.cpu` to access the sole instance available. +//| def __init__(self, ): +//| """You cannot create an instance of `microcontroller.Processor`. +//| Use `microcontroller.cpu` to access the sole instance available.""" +//| ... //| -//| .. attribute:: frequency -//| -//| The CPU operating frequency as an `int`, in Hertz. (read-only) +//| frequency: Any = ... +//| """The CPU operating frequency as an `int`, in Hertz. (read-only)""" //| STATIC mp_obj_t mcu_processor_get_frequency(mp_obj_t self) { return mp_obj_new_int_from_uint(common_hal_mcu_processor_get_frequency()); @@ -72,11 +72,10 @@ const mp_obj_property_t mcu_processor_frequency_obj = { }, }; -//| .. attribute:: temperature -//| -//| The on-chip temperature, in Celsius, as a float. (read-only) +//| temperature: Any = ... +//| """The on-chip temperature, in Celsius, as a float. (read-only) //| -//| Is `None` if the temperature is not available. +//| Is `None` if the temperature is not available.""" //| STATIC mp_obj_t mcu_processor_get_temperature(mp_obj_t self) { float temperature = common_hal_mcu_processor_get_temperature(); @@ -93,9 +92,8 @@ const mp_obj_property_t mcu_processor_temperature_obj = { }, }; -//| .. attribute:: uid -//| -//| The unique id (aka serial number) of the chip as a `bytearray`. (read-only) +//| uid: Any = ... +//| """The unique id (aka serial number) of the chip as a `bytearray`. (read-only)""" //| STATIC mp_obj_t mcu_processor_get_uid(mp_obj_t self) { uint8_t raw_id[COMMON_HAL_MCU_PROCESSOR_UID_LENGTH]; @@ -113,11 +111,10 @@ const mp_obj_property_t mcu_processor_uid_obj = { }, }; -//| .. attribute:: voltage -//| -//| The input voltage to the microcontroller, as a float. (read-only) +//| voltage: Any = ... +//| """The input voltage to the microcontroller, as a float. (read-only) //| -//| Is `None` if the voltage is not available. +//| Is `None` if the voltage is not available.""" //| STATIC mp_obj_t mcu_processor_get_voltage(mp_obj_t self) { float voltage = common_hal_mcu_processor_get_voltage(); diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c index 913242ad2..df3ff4186 100644 --- a/shared-bindings/microcontroller/RunMode.c +++ b/shared-bindings/microcontroller/RunMode.c @@ -26,34 +26,31 @@ #include "shared-bindings/microcontroller/RunMode.h" -//| .. currentmodule:: microcontroller +//| class RunMode: +//| """.. currentmodule:: microcontroller //| -//| :class:`RunMode` -- run state of the microcontroller -//| ============================================================= +//| :class:`RunMode` -- run state of the microcontroller +//| =============================================================""" //| -//| .. class:: RunMode() +//| def __init__(self, ): +//| """Enum-like class to define the run mode of the microcontroller and +//| CircuitPython.""" //| -//| Enum-like class to define the run mode of the microcontroller and -//| CircuitPython. +//| NORMAL: Any = ... +//| """Run CircuitPython as normal. //| -//| .. attribute:: NORMAL +//| :type microcontroller.RunMode:""" //| -//| Run CircuitPython as normal. +//| SAFE_MODE: Any = ... +//| """Run CircuitPython in safe mode. User code will not be run and the +//| file system will be writeable over USB. //| -//| :type microcontroller.RunMode: +//| :type microcontroller.RunMode:""" //| -//| .. attribute:: SAFE_MODE +//| BOOTLOADER: Any = ... +//| """Run the bootloader. //| -//| Run CircuitPython in safe mode. User code will not be run and the -//| file system will be writeable over USB. -//| -//| :type microcontroller.RunMode: -//| -//| .. attribute:: BOOTLOADER -//| -//| Run the bootloader. -//| -//| :type microcontroller.RunMode: +//| :type microcontroller.RunMode:""" //| const mp_obj_type_t mcu_runmode_type; diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c index 090c4564d..75b763980 100644 --- a/shared-bindings/microcontroller/__init__.c +++ b/shared-bindings/microcontroller/__init__.c @@ -42,7 +42,7 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| :mod:`microcontroller` --- Pin references and cpu functionality +//| """:mod:`microcontroller` --- Pin references and cpu functionality //| ================================================================ //| //| .. module:: microcontroller @@ -59,24 +59,23 @@ //| //| Pin //| Processor -//| RunMode +//| RunMode""" //| -//| .. data:: cpu -//| -//| CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency`` -//| (clock frequency). -//| This object is the sole instance of `microcontroller.Processor`. +//| cpu: Any = ... +//| """CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency`` +//| (clock frequency). +//| This object is the sole instance of `microcontroller.Processor`.""" //| -//| .. function:: delay_us(delay) -//| -//| Dedicated delay method used for very short delays. **Do not** do long delays -//| because this stops all other functions from completing. Think of this as an empty -//| ``while`` loop that runs for the specified ``(delay)`` time. If you have other -//| code or peripherals (e.g audio recording) that require specific timing or -//| processing while you are waiting, explore a different avenue such as using -//| `time.sleep()`. +//| def delay_us(delay: Any) -> Any: +//| """Dedicated delay method used for very short delays. **Do not** do long delays +//| because this stops all other functions from completing. Think of this as an empty +//| ``while`` loop that runs for the specified ``(delay)`` time. If you have other +//| code or peripherals (e.g audio recording) that require specific timing or +//| processing while you are waiting, explore a different avenue such as using +//| `time.sleep()`.""" +//| ... //| STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) { uint32_t delay = mp_obj_get_int(delay_obj); @@ -87,9 +86,9 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us); -//| .. function:: disable_interrupts() -//| -//| Disable all interrupts. Be very careful, this can stall everything. +//| def disable_interrupts() -> Any: +//| """Disable all interrupts. Be very careful, this can stall everything.""" +//| ... //| STATIC mp_obj_t mcu_disable_interrupts(void) { common_hal_mcu_disable_interrupts(); @@ -97,9 +96,9 @@ STATIC mp_obj_t mcu_disable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts); -//| .. function:: enable_interrupts() -//| -//| Enable the interrupts that were enabled at the last disable. +//| def enable_interrupts() -> Any: +//| """Enable the interrupts that were enabled at the last disable.""" +//| ... //| STATIC mp_obj_t mcu_enable_interrupts(void) { common_hal_mcu_enable_interrupts(); @@ -107,12 +106,12 @@ STATIC mp_obj_t mcu_enable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_enable_interrupts_obj, mcu_enable_interrupts); -//| .. function:: on_next_reset(run_mode) +//| def on_next_reset(run_mode: microcontroller.RunMode) -> Any: +//| """Configure the run mode used the next time the microcontroller is reset but +//| not powered down. //| -//| Configure the run mode used the next time the microcontroller is reset but -//| not powered down. -//| -//| :param ~microcontroller.RunMode run_mode: The next run mode +//| :param ~microcontroller.RunMode run_mode: The next run mode""" +//| ... //| STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) { mcu_runmode_t run_mode; @@ -132,14 +131,14 @@ STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_on_next_reset_obj, mcu_on_next_reset); -//| .. function:: reset() -//| -//| Reset the microcontroller. After reset, the microcontroller will enter the -//| run mode last set by `on_next_reset`. +//| def reset() -> Any: +//| """Reset the microcontroller. After reset, the microcontroller will enter the +//| run mode last set by `on_next_reset`. //| -//| .. warning:: This may result in file system corruption when connected to a -//| host computer. Be very careful when calling this! Make sure the device -//| "Safely removed" on Windows or "ejected" on Mac OSX and Linux. +//| .. warning:: This may result in file system corruption when connected to a +//| host computer. Be very careful when calling this! Make sure the device +//| "Safely removed" on Windows or "ejected" on Mac OSX and Linux.""" +//| ... //| STATIC mp_obj_t mcu_reset(void) { common_hal_mcu_reset(); @@ -148,22 +147,21 @@ STATIC mp_obj_t mcu_reset(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_reset_obj, mcu_reset); -//| .. data:: nvm -//| -//| Available non-volatile memory. -//| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise. +//| nvm: Any = ... +//| """Available non-volatile memory. +//| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise. //| -//| :type: nvm.ByteArray or None +//| :type: nvm.ByteArray or None""" //| -//| :mod:`microcontroller.pin` --- Microcontroller pin names +//| """:mod:`microcontroller.pin` --- Microcontroller pin names //| -------------------------------------------------------- //| //| .. module:: microcontroller.pin //| :synopsis: Microcontroller pin names //| :platform: SAMD21 //| -//| References to pins as named by the microcontroller +//| References to pins as named by the microcontroller""" //| const mp_obj_module_t mcu_pin_module = { .base = { &mp_type_module }, diff --git a/shared-bindings/multiterminal/__init__.c b/shared-bindings/multiterminal/__init__.c index 8de3c50d7..3a4065019 100644 --- a/shared-bindings/multiterminal/__init__.c +++ b/shared-bindings/multiterminal/__init__.c @@ -30,7 +30,7 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| :mod:`multiterminal` --- Manage additional terminal sources +//| """:mod:`multiterminal` --- Manage additional terminal sources //| =========================================================== //| //| .. module:: multiterminal @@ -39,25 +39,25 @@ //| //| The `multiterminal` module allows you to configure an additional serial //| terminal source. Incoming characters are accepted from both the internal -//| serial connection and the optional secondary connection. +//| serial connection and the optional secondary connection.""" //| -//| .. function:: get_secondary_terminal() -//| -//| Returns the current secondary terminal. +//| def get_secondary_terminal() -> Any: +//| """Returns the current secondary terminal.""" +//| ... //| STATIC mp_obj_t multiterminal_obj_get_secondary_terminal() { return common_hal_multiterminal_get_secondary_terminal(); } MP_DEFINE_CONST_FUN_OBJ_0(multiterminal_get_secondary_terminal_obj, multiterminal_obj_get_secondary_terminal); -//| .. function:: set_secondary_terminal(stream) -//| -//| Read additional input from the given stream and write out back to it. +//| def set_secondary_terminal(stream: stream) -> Any: +//| """Read additional input from the given stream and write out back to it. //| This doesn't replace the core stream (usually UART or native USB) but is //| mixed in instead. //| -//| :param stream stream: secondary stream +//| :param stream stream: secondary stream""" +//| ... //| STATIC mp_obj_t multiterminal_obj_set_secondary_terminal(mp_obj_t secondary_terminal) { mp_obj_t write_m[3]; @@ -73,9 +73,9 @@ STATIC mp_obj_t multiterminal_obj_set_secondary_terminal(mp_obj_t secondary_term } MP_DEFINE_CONST_FUN_OBJ_1(multiterminal_set_secondary_terminal_obj, multiterminal_obj_set_secondary_terminal); -//| .. function:: clear_secondary_terminal() -//| -//| Clears the secondary terminal. +//| def clear_secondary_terminal() -> Any: +//| """Clears the secondary terminal.""" +//| ... //| STATIC mp_obj_t multiterminal_obj_clear_secondary_terminal() { common_hal_multiterminal_clear_secondary_terminal(); @@ -83,11 +83,11 @@ STATIC mp_obj_t multiterminal_obj_clear_secondary_terminal() { } MP_DEFINE_CONST_FUN_OBJ_0(multiterminal_clear_secondary_terminal_obj, multiterminal_obj_clear_secondary_terminal); -//| .. function:: schedule_secondary_terminal_read(socket) -//| -//| In cases where the underlying OS is doing task scheduling, this notifies +//| def schedule_secondary_terminal_read(socket: Any) -> Any: +//| """In cases where the underlying OS is doing task scheduling, this notifies //| the OS when more data is available on the socket to read. This is useful -//| as a callback for lwip sockets. +//| as a callback for lwip sockets.""" +//| ... //| // TODO(tannewt): This is a funny API. Replace it with a direct call into the OS // by the lwip object. -- cgit v1.2.3 From d750096befe2e6d23b1d0d4796306382cfbbb198 Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 7 May 2020 18:40:46 -0400 Subject: Did neopixel, network, nvm --- shared-bindings/neopixel_write/__init__.c | 13 ++++++------ shared-bindings/network/__init__.c | 10 ++++----- shared-bindings/nvm/ByteArray.c | 34 +++++++++++++++++-------------- shared-bindings/nvm/__init__.c | 5 +++-- 4 files changed, 33 insertions(+), 29 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c index 1ee66337b..f18c7fdfd 100644 --- a/shared-bindings/neopixel_write/__init__.c +++ b/shared-bindings/neopixel_write/__init__.c @@ -31,7 +31,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "supervisor/shared/translate.h" -//| :mod:`neopixel_write` --- Low-level neopixel implementation +//| """:mod:`neopixel_write` --- Low-level neopixel implementation //| =========================================================== //| //| .. module:: neopixel_write @@ -53,15 +53,14 @@ //| pin = digitalio.DigitalInOut(board.NEOPIXEL) //| pin.direction = digitalio.Direction.OUTPUT //| pixel_off = bytearray([0, 0, 0]) -//| neopixel_write.neopixel_write(pin, pixel_off) +//| neopixel_write.neopixel_write(pin, pixel_off)""" //| -//| .. function:: neopixel_write(digitalinout, buf) -//| -//| Write buf out on the given DigitalInOut. +//| def neopixel_write(digitalinout: digitalio.DigitalInOut, buf: bytearray) -> Any: +//| """Write buf out on the given DigitalInOut. //| //| :param ~digitalio.DigitalInOut digitalinout: the DigitalInOut to output with -//| :param bytearray buf: The bytes to clock out. No assumption is made about color order -//| +//| :param bytearray buf: The bytes to clock out. No assumption is made about color order""" +//| ... STATIC mp_obj_t neopixel_write_neopixel_write_(mp_obj_t digitalinout_obj, mp_obj_t buf) { if (!MP_OBJ_IS_TYPE(digitalinout_obj, &digitalio_digitalinout_type)) { mp_raise_TypeError_varg(translate("Expected a %q"), digitalio_digitalinout_type.name); diff --git a/shared-bindings/network/__init__.c b/shared-bindings/network/__init__.c index 01763a73c..4f03781cf 100644 --- a/shared-bindings/network/__init__.c +++ b/shared-bindings/network/__init__.c @@ -38,7 +38,7 @@ #if CIRCUITPY_NETWORK -//| :mod:`network` --- Network Interface Management +//| """:mod:`network` --- Network Interface Management //| =============================================== //| //| .. module:: network @@ -47,11 +47,11 @@ //| //| This module provides a registry of configured NICs. //| It is used by the 'socket' module to look up a suitable -//| NIC when a socket is created. +//| NIC when a socket is created.""" //| -//| .. function:: route() -//| -//| Returns a list of all configured NICs. +//| def route() -> Any: +//| """Returns a list of all configured NICs.""" +//| ... //| STATIC mp_obj_t network_route(void) { diff --git a/shared-bindings/nvm/ByteArray.c b/shared-bindings/nvm/ByteArray.c index 31bedeacc..a28c2c4f9 100644 --- a/shared-bindings/nvm/ByteArray.c +++ b/shared-bindings/nvm/ByteArray.c @@ -31,29 +31,33 @@ #include "shared-bindings/nvm/ByteArray.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: nvm + + + +//| class ByteArray: +//| """.. currentmodule:: nvm //| -//| :class:`ByteArray` -- Presents a stretch of non-volatile memory as a bytearray. -//| ================================================================================ +//| :class:`ByteArray` -- Presents a stretch of non-volatile memory as a bytearray. +//| ================================================================================ //| -//| Non-volatile memory is available as a byte array that persists over reloads -//| and power cycles. Each assignment causes an erase and write cycle so its recommended to assign -//| all values to change at once. +//| Non-volatile memory is available as a byte array that persists over reloads +//| and power cycles. Each assignment causes an erase and write cycle so its recommended to assign +//| all values to change at once. //| -//| Usage:: +//| Usage:: //| -//| import microcontroller -//| microcontroller.nvm[0:3] = b"\xcc\x10\x00" +//| import microcontroller +//| microcontroller.nvm[0:3] = b\"\xcc\x10\x00\"""" //| -//| .. class:: ByteArray() -//| -//| Not currently dynamically supported. Access the sole instance through `microcontroller.nvm`. +//| def __init__(self, ): +//| """Not currently dynamically supported. Access the sole instance through `microcontroller.nvm`.""" +//| ... //| -//| .. method:: __len__() -//| -//| Return the length. This is used by (`len`) +//| def __len__(self, ) -> Any: +//| """Return the length. This is used by (`len`)""" +//| ... //| STATIC mp_obj_t nvm_bytearray_unary_op(mp_unary_op_t op, mp_obj_t self_in) { nvm_bytearray_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/nvm/__init__.c b/shared-bindings/nvm/__init__.c index 811855c09..3bd9a309b 100644 --- a/shared-bindings/nvm/__init__.c +++ b/shared-bindings/nvm/__init__.c @@ -31,7 +31,7 @@ #include "shared-bindings/nvm/__init__.h" #include "shared-bindings/nvm/ByteArray.h" -//| :mod:`nvm` --- Non-volatile memory +//| """:mod:`nvm` --- Non-volatile memory //| =========================================================== //| //| .. module:: nvm @@ -47,7 +47,8 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| ByteArray +//| ByteArray""" +//| STATIC const mp_rom_map_elem_t nvm_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_nvm) }, { MP_ROM_QSTR(MP_QSTR_ByteArray), MP_ROM_PTR(&nvm_bytearray_type) }, -- cgit v1.2.3 From 09530e5dc34d6fbcbf5fa85a1f7df9d47d8c8329 Mon Sep 17 00:00:00 2001 From: dherrada Date: Fri, 8 May 2020 16:03:39 -0400 Subject: Did os, _pixelbuf, _pew --- shared-bindings/_pew/PewPew.c | 40 ++++++------ shared-bindings/_pew/__init__.c | 4 +- shared-bindings/_pixelbuf/PixelBuf.c | 94 +++++++++++++-------------- shared-bindings/_pixelbuf/__init__.c | 14 ++-- shared-bindings/os/__init__.c | 120 +++++++++++++++++------------------ 5 files changed, 134 insertions(+), 138 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_pew/PewPew.c b/shared-bindings/_pew/PewPew.c index 3ff208761..37188d2b7 100644 --- a/shared-bindings/_pew/PewPew.c +++ b/shared-bindings/_pew/PewPew.c @@ -34,33 +34,33 @@ #include "shared-module/_pew/PewPew.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: _pew +//| class PewPew: +//| """.. currentmodule:: _pew //| -//| :class:`PewPew` -- LED matrix and button driver -//| =============================================== +//| :class:`PewPew` -- LED matrix and button driver +//| =============================================== //| -//| This is an internal module to be used by the ``pew.py`` library from -//| https://github.com/pewpew-game/pew-pewpew-standalone-10.x to handle the -//| LED matrix display and buttons on the ``pewpew10`` board. +//| This is an internal module to be used by the ``pew.py`` library from +//| https://github.com/pewpew-game/pew-pewpew-standalone-10.x to handle the +//| LED matrix display and buttons on the ``pewpew10`` board. //| -//| Usage:: +//| Usage:: //| -//| This singleton class is instantiated by the ``pew`` library, and -//| used internally by it. All user-visible interactions are done through -//| that library. +//| This singleton class is instantiated by the ``pew`` library, and +//| used internally by it. All user-visible interactions are done through +//| that library.""" //| -//| .. class:: PewPew(buffer, rows, cols, buttons) -//| -//| Initializes matrix scanning routines. +//| def __init__(self, buffer: Any, rows: Any, cols: Any, buttons: Any): +//| """Initializes matrix scanning routines. //| -//| The ``buffer`` is a 64 byte long ``bytearray`` that stores what should -//| be displayed on the matrix. ``rows`` and ``cols`` are both lists of -//| eight ``DigitalInputOutput`` objects that are connected to the matrix -//| rows and columns. ``buttons`` is a ``DigitalInputOutput`` object that -//| is connected to the common side of all buttons (the other sides of the -//| buttons are connected to rows of the matrix). +//| The ``buffer`` is a 64 byte long ``bytearray`` that stores what should +//| be displayed on the matrix. ``rows`` and ``cols`` are both lists of +//| eight ``DigitalInputOutput`` objects that are connected to the matrix +//| rows and columns. ``buttons`` is a ``DigitalInputOutput`` object that +//| is connected to the common side of all buttons (the other sides of the +//| buttons are connected to rows of the matrix).""" +//| ... //| STATIC mp_obj_t pewpew_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { diff --git a/shared-bindings/_pew/__init__.c b/shared-bindings/_pew/__init__.c index 6c5520ac5..b6aab6726 100644 --- a/shared-bindings/_pew/__init__.c +++ b/shared-bindings/_pew/__init__.c @@ -41,7 +41,7 @@ STATIC mp_obj_t get_pressed(void) { STATIC MP_DEFINE_CONST_FUN_OBJ_0(get_pressed_obj, get_pressed); -//| :mod:`_pew` --- LED matrix driver +//| """:mod:`_pew` --- LED matrix driver //| ================================== //| //| .. module:: _pew @@ -51,7 +51,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_0(get_pressed_obj, get_pressed); //| .. toctree:: //| :maxdepth: 3 //| -//| PewPew +//| PewPew""" //| STATIC const mp_rom_map_elem_t pew_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR__pew) }, diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 61b4c9ae0..1c0888802 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -44,31 +44,32 @@ extern const int32_t colorwheel(float pos); static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t* parsed); -//| .. currentmodule:: pixelbuf +//| class PixelBuf: +//| """.. currentmodule:: pixelbuf //| -//| :class:`PixelBuf` -- A fast RGB[W] pixel buffer for LED and similar devices -//| =========================================================================== +//| :class:`PixelBuf` -- A fast RGB[W] pixel buffer for LED and similar devices +//| =========================================================================== //| -//| :class:`~_pixelbuf.PixelBuf` implements an RGB[W] bytearray abstraction. +//| :class:`~_pixelbuf.PixelBuf` implements an RGB[W] bytearray abstraction.""" //| -//| .. class:: PixelBuf(size, *, byteorder="BGR", brightness=0, auto_write=False, header=b"", trailer=b"") +//| def __init__(self, size: int, *, byteorder: str = "BGR", brightness: float = 0, auto_write: bool = False, header: bytes = b"", trailer: bytes = b""): +//| """Create a PixelBuf object of the specified size, byteorder, and bits per pixel. //| -//| Create a PixelBuf object of the specified size, byteorder, and bits per pixel. +//| When brightness is less than 1.0, a second buffer will be used to store the color values +//| before they are adjusted for brightness. //| -//| When brightness is less than 1.0, a second buffer will be used to store the color values -//| before they are adjusted for brightness. +//| When ``P`` (pwm duration) is present as the 4th character of the byteorder +//| string, the 4th value in the tuple/list for a pixel is the individual pixel +//| brightness (0.0-1.0) and will enable a Dotstar compatible 1st byte in the +//| output buffer (``buf``). //| -//| When ``P`` (pwm duration) is present as the 4th character of the byteorder -//| string, the 4th value in the tuple/list for a pixel is the individual pixel -//| brightness (0.0-1.0) and will enable a Dotstar compatible 1st byte in the -//| output buffer (``buf``). -//| -//| :param ~int size: Number of pixelsx -//| :param ~str byteorder: Byte order string (such as "BGR" or "PBGR") -//| :param ~float brightness: Brightness (0 to 1.0, default 1.0) -//| :param ~bool auto_write: Whether to automatically write pixels (Default False) -//| :param bytes header: Sequence of bytes to always send before pixel values. -//| :param bytes trailer: Sequence of bytes to always send after pixel values. +//| :param ~int size: Number of pixelsx +//| :param ~str byteorder: Byte order string (such as "BGR" or "PBGR") +//| :param ~float brightness: Brightness (0 to 1.0, default 1.0) +//| :param ~bool auto_write: Whether to automatically write pixels (Default False) +//| :param bytes header: Sequence of bytes to always send before pixel values. +//| :param bytes trailer: Sequence of bytes to always send after pixel values.""" +//| ... //| STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, MP_OBJ_FUN_ARGS_MAX, true); @@ -156,9 +157,8 @@ static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t } } -//| .. attribute:: bpp -//| -//| The number of bytes per pixel in the buffer (read-only) +//| bpp: Any = ... +//| """The number of bytes per pixel in the buffer (read-only)""" //| STATIC mp_obj_t pixelbuf_pixelbuf_obj_get_bpp(mp_obj_t self_in) { return MP_OBJ_NEW_SMALL_INT(common_hal__pixelbuf_pixelbuf_get_bpp(self_in)); @@ -173,12 +173,11 @@ const mp_obj_property_t pixelbuf_pixelbuf_bpp_obj = { }; -//| .. attribute:: brightness -//| -//| Float value between 0 and 1. Output brightness. +//| brightness: Any = ... +//| """Float value between 0 and 1. Output brightness. //| //| When brightness is less than 1.0, a second buffer will be used to store the color values -//| before they are adjusted for brightness. +//| before they are adjusted for brightness.""" //| STATIC mp_obj_t pixelbuf_pixelbuf_obj_get_brightness(mp_obj_t self_in) { return mp_obj_new_float(common_hal__pixelbuf_pixelbuf_get_brightness(self_in)); @@ -205,9 +204,8 @@ const mp_obj_property_t pixelbuf_pixelbuf_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: auto_write -//| -//| Whether to automatically write the pixels after each update. +//| auto_write: Any = ... +//| """Whether to automatically write the pixels after each update.""" //| STATIC mp_obj_t pixelbuf_pixelbuf_obj_get_auto_write(mp_obj_t self_in) { return mp_obj_new_bool(common_hal__pixelbuf_pixelbuf_get_auto_write(self_in)); @@ -228,9 +226,8 @@ const mp_obj_property_t pixelbuf_pixelbuf_auto_write_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: byteorder -//| -//| byteorder string for the buffer (read-only) +//| byteorder: Any = ... +//| """byteorder string for the buffer (read-only)""" //| STATIC mp_obj_t pixelbuf_pixelbuf_obj_get_byteorder(mp_obj_t self_in) { return common_hal__pixelbuf_pixelbuf_get_byteorder_string(self_in); @@ -253,10 +250,10 @@ STATIC mp_obj_t pixelbuf_pixelbuf_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| .. method:: show() -//| -//| Transmits the color data to the pixels so that they are shown. This is done automatically -//| when `auto_write` is True. +//| def show(self, ) -> Any: +//| """Transmits the color data to the pixels so that they are shown. This is done automatically +//| when `auto_write` is True.""" +//| ... //| STATIC mp_obj_t pixelbuf_pixelbuf_show(mp_obj_t self_in) { @@ -265,9 +262,9 @@ STATIC mp_obj_t pixelbuf_pixelbuf_show(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(pixelbuf_pixelbuf_show_obj, pixelbuf_pixelbuf_show); -//| .. function:: fill(color) -//| -//| Fills the given pixelbuf with the given color. +//| def fill(color: Any) -> Any: +//| """Fills the given pixelbuf with the given color.""" +//| ... //| STATIC mp_obj_t pixelbuf_pixelbuf_fill(mp_obj_t self_in, mp_obj_t value) { @@ -277,17 +274,16 @@ STATIC mp_obj_t pixelbuf_pixelbuf_fill(mp_obj_t self_in, mp_obj_t value) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(pixelbuf_pixelbuf_fill_obj, pixelbuf_pixelbuf_fill); - -//| .. method:: __getitem__(index) -//| -//| Returns the pixel value at the given index as a tuple of (Red, Green, Blue[, White]) values -//| between 0 and 255. -//| -//| .. method:: __setitem__(index, value) +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the pixel value at the given index as a tuple of (Red, Green, Blue[, White]) values +//| between 0 and 255.""" +//| ... //| -//| Sets the pixel value at the given index. Value can either be a tuple of (Red, Green, Blue -//| [, White]) values between 0 and 255 or an integer where the red, green and blue values are -//| packed into the lower three bytes (0xRRGGBB). +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the pixel value at the given index. Value can either be a tuple of (Red, Green, Blue +//| [, White]) values between 0 and 255 or an integer where the red, green and blue values are +//| packed into the lower three bytes (0xRRGGBB).""" +//| ... //| STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t value) { if (value == MP_OBJ_NULL) { diff --git a/shared-bindings/_pixelbuf/__init__.c b/shared-bindings/_pixelbuf/__init__.c index 424ed23e4..3c04d436a 100644 --- a/shared-bindings/_pixelbuf/__init__.c +++ b/shared-bindings/_pixelbuf/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/_pixelbuf/PixelBuf.h" -//| :mod:`_pixelbuf` --- Fast RGB(W) pixel buffer and helpers +//| """:mod:`_pixelbuf` --- Fast RGB(W) pixel buffer and helpers //| =========================================================== //| .. module:: _pixelbuf @@ -50,13 +50,13 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| PixelBuf - - -//| .. function:: wheel(n) +//| PixelBuf""" //| -//| C implementation of the common wheel() function found in many examples. -//| Returns the colorwheel RGB value as an integer value for n (usable in :py:class:`PixelBuf`, neopixel, and dotstar). + +//| def wheel(n: Any) -> Any: +//| """C implementation of the common wheel() function found in many examples. +//| Returns the colorwheel RGB value as an integer value for n (usable in :py:class:`PixelBuf`, neopixel, and dotstar).""" +//| ... //| STATIC mp_obj_t pixelbuf_wheel(mp_obj_t n) { diff --git a/shared-bindings/os/__init__.c b/shared-bindings/os/__init__.c index f3b745aef..2a6b13c9b 100644 --- a/shared-bindings/os/__init__.c +++ b/shared-bindings/os/__init__.c @@ -37,7 +37,7 @@ #include "py/runtime.h" #include "shared-bindings/os/__init__.h" -//| :mod:`os` --- functions that an OS normally provides +//| """:mod:`os` --- functions that an OS normally provides //| ======================================================== //| //| .. module:: os @@ -46,22 +46,22 @@ //| //| The `os` module is a strict subset of the CPython `cpython:os` module. So, //| code written in CircuitPython will work in CPython but not necessarily the -//| other way around. +//| other way around.""" //| -//| .. function:: uname() -//| -//| Returns a named tuple of operating specific and CircuitPython port -//| specific information. +//| def uname() -> Any: +//| """Returns a named tuple of operating specific and CircuitPython port +//| specific information.""" +//| ... //| STATIC mp_obj_t os_uname(void) { return common_hal_os_uname(); } STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_uname_obj, os_uname); -//| .. function:: chdir(path) -//| -//| Change current directory. +//| def chdir(path: Any) -> Any: +//| """Change current directory.""" +//| ... //| mp_obj_t os_chdir(mp_obj_t path_in) { const char *path = mp_obj_str_get_str(path_in); @@ -70,18 +70,18 @@ mp_obj_t os_chdir(mp_obj_t path_in) { } MP_DEFINE_CONST_FUN_OBJ_1(os_chdir_obj, os_chdir); -//| .. function:: getcwd() -//| -//| Get the current directory. +//| def getcwd() -> Any: +//| """Get the current directory.""" +//| ... //| mp_obj_t os_getcwd(void) { return common_hal_os_getcwd(); } MP_DEFINE_CONST_FUN_OBJ_0(os_getcwd_obj, os_getcwd); -//| .. function:: listdir([dir]) -//| -//| With no argument, list the current directory. Otherwise list the given directory. +//| def listdir(dir: Any) -> Any: +//| """With no argument, list the current directory. Otherwise list the given directory.""" +//| ... //| mp_obj_t os_listdir(size_t n_args, const mp_obj_t *args) { const char* path; @@ -94,9 +94,9 @@ mp_obj_t os_listdir(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(os_listdir_obj, 0, 1, os_listdir); -//| .. function:: mkdir(path) -//| -//| Create a new directory. +//| def mkdir(path: Any) -> Any: +//| """Create a new directory.""" +//| ... //| mp_obj_t os_mkdir(mp_obj_t path_in) { const char *path = mp_obj_str_get_str(path_in); @@ -105,9 +105,9 @@ mp_obj_t os_mkdir(mp_obj_t path_in) { } MP_DEFINE_CONST_FUN_OBJ_1(os_mkdir_obj, os_mkdir); -//| .. function:: remove(path) -//| -//| Remove a file. +//| def remove(path: Any) -> Any: +//| """Remove a file.""" +//| ... //| mp_obj_t os_remove(mp_obj_t path_in) { const char *path = mp_obj_str_get_str(path_in); @@ -116,9 +116,9 @@ mp_obj_t os_remove(mp_obj_t path_in) { } MP_DEFINE_CONST_FUN_OBJ_1(os_remove_obj, os_remove); -//| .. function:: rmdir(path) -//| -//| Remove a directory. +//| def rmdir(path: Any) -> Any: +//| """Remove a directory.""" +//| ... //| mp_obj_t os_rename(mp_obj_t old_path_in, mp_obj_t new_path_in) { const char *old_path = mp_obj_str_get_str(old_path_in); @@ -128,9 +128,9 @@ mp_obj_t os_rename(mp_obj_t old_path_in, mp_obj_t new_path_in) { } MP_DEFINE_CONST_FUN_OBJ_2(os_rename_obj, os_rename); -//| .. function:: rename(old_path, new_path) -//| -//| Rename a file. +//| def rename(old_path: Any, new_path: Any) -> Any: +//| """Rename a file.""" +//| ... //| mp_obj_t os_rmdir(mp_obj_t path_in) { const char *path = mp_obj_str_get_str(path_in); @@ -139,14 +139,14 @@ mp_obj_t os_rmdir(mp_obj_t path_in) { } MP_DEFINE_CONST_FUN_OBJ_1(os_rmdir_obj, os_rmdir); -//| .. function:: stat(path) -//| -//| Get the status of a file or directory. +//| def stat(path: Any) -> Any: +//| """Get the status of a file or directory. //| -//| .. note:: On builds without long integers, the number of seconds -//| for contemporary dates will not fit in a small integer. -//| So the time fields return 946684800, -//| which is the number of seconds corresponding to 1999-12-31. +//| .. note:: On builds without long integers, the number of seconds +//| for contemporary dates will not fit in a small integer. +//| So the time fields return 946684800, +//| which is the number of seconds corresponding to 1999-12-31.""" +//| ... //| mp_obj_t os_stat(mp_obj_t path_in) { const char *path = mp_obj_str_get_str(path_in); @@ -154,26 +154,26 @@ mp_obj_t os_stat(mp_obj_t path_in) { } MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat); -//| .. function:: statvfs(path) +//| def statvfs(path: Any) -> Any: +//| """Get the status of a fileystem. //| -//| Get the status of a fileystem. +//| Returns a tuple with the filesystem information in the following order: //| -//| Returns a tuple with the filesystem information in the following order: +//| * ``f_bsize`` -- file system block size +//| * ``f_frsize`` -- fragment size +//| * ``f_blocks`` -- size of fs in f_frsize units +//| * ``f_bfree`` -- number of free blocks +//| * ``f_bavail`` -- number of free blocks for unpriviliged users +//| * ``f_files`` -- number of inodes +//| * ``f_ffree`` -- number of free inodes +//| * ``f_favail`` -- number of free inodes for unpriviliged users +//| * ``f_flag`` -- mount flags +//| * ``f_namemax`` -- maximum filename length //| -//| * ``f_bsize`` -- file system block size -//| * ``f_frsize`` -- fragment size -//| * ``f_blocks`` -- size of fs in f_frsize units -//| * ``f_bfree`` -- number of free blocks -//| * ``f_bavail`` -- number of free blocks for unpriviliged users -//| * ``f_files`` -- number of inodes -//| * ``f_ffree`` -- number of free inodes -//| * ``f_favail`` -- number of free inodes for unpriviliged users -//| * ``f_flag`` -- mount flags -//| * ``f_namemax`` -- maximum filename length -//| -//| Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail`` -//| and the ``f_flags`` parameter may return ``0`` as they can be unavailable -//| in a port-specific implementation. +//| Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail`` +//| and the ``f_flags`` parameter may return ``0`` as they can be unavailable +//| in a port-specific implementation.""" +//| ... //| mp_obj_t os_statvfs(mp_obj_t path_in) { const char *path = mp_obj_str_get_str(path_in); @@ -181,9 +181,9 @@ mp_obj_t os_statvfs(mp_obj_t path_in) { } MP_DEFINE_CONST_FUN_OBJ_1(os_statvfs_obj, os_statvfs); -//| .. function:: sync() -//| -//| Sync all filesystems. +//| def sync() -> Any: +//| """Sync all filesystems.""" +//| ... //| STATIC mp_obj_t os_sync(void) { for (mp_vfs_mount_t *vfs = MP_STATE_VM(vfs_mount_table); vfs != NULL; vfs = vfs->next) { @@ -194,10 +194,10 @@ STATIC mp_obj_t os_sync(void) { } MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync); -//| .. function:: urandom(size) -//| -//| Returns a string of *size* random bytes based on a hardware True Random -//| Number Generator. When not available, it will raise a NotImplementedError. +//| def urandom(size: Any) -> Any: +//| """Returns a string of *size* random bytes based on a hardware True Random +//| Number Generator. When not available, it will raise a NotImplementedError.""" +//| ... //| STATIC mp_obj_t os_urandom(mp_obj_t size_in) { mp_int_t size = mp_obj_get_int(size_in); @@ -229,9 +229,9 @@ STATIC const mp_rom_map_elem_t os_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR_urandom), MP_ROM_PTR(&os_urandom_obj) }, -//| .. data:: sep +//| """.. data:: sep //| -//| Separator used to delineate path components such as folder and file names. +//| Separator used to delineate path components such as folder and file names.""" //| { MP_ROM_QSTR(MP_QSTR_sep), MP_ROM_QSTR(MP_QSTR__slash_) }, }; -- cgit v1.2.3 From 206d0e598adb66e2b23a39a7d11e2f5087513205 Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Sat, 2 May 2020 02:21:35 -0700 Subject: Add vectorio: for drawing shapes vectorio builds on m4 express feather Concrete shapes are composed into a VectorShape which is put into a displayio Group for display. VectorShape provides transpose and x/y positioning for shape implementations. Included Shapes: * Circle - A radius; Circle is positioned at its axis in the VectorShape. - You can freely modify the radius to grow and shrink the circle in-place. * Polygon - An ordered list of points. - Beteween each successive point an edge is inferred. A final edge closing the shape is inferred between the last point and the first point. - You can modify the points in a Polygon. The points' coordinate system is relative to (0, 0) so if you'd like a top-center justified 10x20 rectangle you can do points [(-5, 0), (5, 0), (5, 20), (0, 20)] and your VectorShape x and y properties will position the rectangle relative to its top center point * Rectangle A width and a height. --- .../boards/feather_m4_express/mpconfigboard.mk | 3 + py/circuitpy_defns.mk | 8 + py/circuitpy_mpconfig.h | 6 + py/circuitpy_mpconfig.mk | 3 + shared-bindings/vectorio/Circle.c | 79 ++++++ shared-bindings/vectorio/Circle.h | 22 ++ shared-bindings/vectorio/Polygon.c | 139 ++++++++++ shared-bindings/vectorio/Polygon.h | 24 ++ shared-bindings/vectorio/Rectangle.c | 56 ++++ shared-bindings/vectorio/Rectangle.h | 15 ++ shared-bindings/vectorio/VectorShape.c | 213 ++++++++++++++++ shared-bindings/vectorio/VectorShape.h | 25 ++ shared-bindings/vectorio/__init__.c | 46 ++++ shared-module/displayio/Group.c | 35 ++- shared-module/displayio/display_core.c | 4 + shared-module/vectorio/Circle.c | 55 ++++ shared-module/vectorio/Circle.h | 17 ++ shared-module/vectorio/Polygon.c | 110 ++++++++ shared-module/vectorio/Polygon.h | 16 ++ shared-module/vectorio/Rectangle.c | 35 +++ shared-module/vectorio/Rectangle.h | 15 ++ shared-module/vectorio/VectorShape.c | 282 +++++++++++++++++++++ shared-module/vectorio/VectorShape.h | 51 ++++ shared-module/vectorio/__init__.c | 3 + shared-module/vectorio/__init__.h | 15 ++ 25 files changed, 1276 insertions(+), 1 deletion(-) create mode 100644 shared-bindings/vectorio/Circle.c create mode 100644 shared-bindings/vectorio/Circle.h create mode 100644 shared-bindings/vectorio/Polygon.c create mode 100644 shared-bindings/vectorio/Polygon.h create mode 100644 shared-bindings/vectorio/Rectangle.c create mode 100644 shared-bindings/vectorio/Rectangle.h create mode 100644 shared-bindings/vectorio/VectorShape.c create mode 100644 shared-bindings/vectorio/VectorShape.h create mode 100644 shared-bindings/vectorio/__init__.c create mode 100644 shared-module/vectorio/Circle.c create mode 100644 shared-module/vectorio/Circle.h create mode 100644 shared-module/vectorio/Polygon.c create mode 100644 shared-module/vectorio/Polygon.h create mode 100644 shared-module/vectorio/Rectangle.c create mode 100644 shared-module/vectorio/Rectangle.h create mode 100644 shared-module/vectorio/VectorShape.c create mode 100644 shared-module/vectorio/VectorShape.h create mode 100644 shared-module/vectorio/__init__.c create mode 100644 shared-module/vectorio/__init__.h (limited to 'shared-bindings') diff --git a/ports/atmel-samd/boards/feather_m4_express/mpconfigboard.mk b/ports/atmel-samd/boards/feather_m4_express/mpconfigboard.mk index 38dd47758..7cb53bd13 100644 --- a/ports/atmel-samd/boards/feather_m4_express/mpconfigboard.mk +++ b/ports/atmel-samd/boards/feather_m4_express/mpconfigboard.mk @@ -10,3 +10,6 @@ QSPI_FLASH_FILESYSTEM = 1 EXTERNAL_FLASH_DEVICE_COUNT = 1 EXTERNAL_FLASH_DEVICES = GD25Q16C LONGINT_IMPL = MPZ + +CIRCUITPY_VECTORIO = 1 + diff --git a/py/circuitpy_defns.mk b/py/circuitpy_defns.mk index e3892d98e..c6ea2b45b 100644 --- a/py/circuitpy_defns.mk +++ b/py/circuitpy_defns.mk @@ -145,6 +145,9 @@ endif ifeq ($(CIRCUITPY_DISPLAYIO),1) SRC_PATTERNS += displayio/% terminalio/% fontio/% endif +ifeq ($(CIRCUITPY_VECTORIO),1) +SRC_PATTERNS += vectorio/% +endif ifeq ($(CIRCUITPY_FRAMEBUFFERIO),1) SRC_PATTERNS += framebufferio/% endif @@ -358,6 +361,11 @@ SRC_SHARED_MODULE_ALL = \ displayio/Shape.c \ displayio/TileGrid.c \ displayio/__init__.c \ + vectorio/Circle.c \ + vectorio/Rectangle.c \ + vectorio/Polygon.c \ + vectorio/VectorShape.c \ + vectorio/__init__.c \ fontio/BuiltinFont.c \ fontio/__init__.c \ framebufferio/FramebufferDisplay.c \ diff --git a/py/circuitpy_mpconfig.h b/py/circuitpy_mpconfig.h index 6b7fc192f..f48a648c4 100644 --- a/py/circuitpy_mpconfig.h +++ b/py/circuitpy_mpconfig.h @@ -352,6 +352,11 @@ extern const struct _mp_obj_module_t framebufferio_module; #define FRAMEBUFFERIO_MODULE #endif +#if CIRCUITPY_VECTORIO +extern const struct _mp_obj_module_t vectorio_module; +#define VECTORIO_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_vectorio), (mp_obj_t)&vectorio_module }, +#endif + #if CIRCUITPY_FREQUENCYIO extern const struct _mp_obj_module_t frequencyio_module; #define FREQUENCYIO_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_frequencyio), (mp_obj_t)&frequencyio_module }, @@ -642,6 +647,7 @@ extern const struct _mp_obj_module_t ustack_module; DISPLAYIO_MODULE \ FONTIO_MODULE \ TERMINALIO_MODULE \ + VECTORIO_MODULE \ ERRNO_MODULE \ FRAMEBUFFERIO_MODULE \ FREQUENCYIO_MODULE \ diff --git a/py/circuitpy_mpconfig.mk b/py/circuitpy_mpconfig.mk index 105253aec..e9e3d8013 100644 --- a/py/circuitpy_mpconfig.mk +++ b/py/circuitpy_mpconfig.mk @@ -94,6 +94,9 @@ CFLAGS += -DCIRCUITPY_DISPLAYIO=$(CIRCUITPY_DISPLAYIO) CIRCUITPY_FRAMEBUFFERIO ?= 0 CFLAGS += -DCIRCUITPY_FRAMEBUFFERIO=$(CIRCUITPY_FRAMEBUFFERIO) +CIRCUITPY_VECTORIO ?= 0 +CFLAGS += -DCIRCUITPY_VECTORIO=$(CIRCUITPY_VECTORIO) + CIRCUITPY_FREQUENCYIO ?= $(CIRCUITPY_FULL_BUILD) CFLAGS += -DCIRCUITPY_FREQUENCYIO=$(CIRCUITPY_FREQUENCYIO) diff --git a/shared-bindings/vectorio/Circle.c b/shared-bindings/vectorio/Circle.c new file mode 100644 index 000000000..8f409bd65 --- /dev/null +++ b/shared-bindings/vectorio/Circle.c @@ -0,0 +1,79 @@ + +#include "shared-bindings/vectorio/Circle.h" + + +#include + +#include "py/objproperty.h" +#include "py/objtype.h" +#include "py/runtime.h" +#include "supervisor/shared/translate.h" + + +//| .. currentmodule:: vectorio +//| +//| :class:`Circle` -- Represents a circle by its radius +//| ========================================================================== +//| +//| .. class:: Circle(radius) +//| +//| :param int radius: The radius of the circle in pixels +//| +static mp_obj_t vectorio_circle_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { + enum { ARG_radius }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_radius, MP_ARG_REQUIRED | MP_ARG_INT }, + }; + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + mp_int_t radius = args[ARG_radius].u_int; + if (radius < 1) { + mp_raise_ValueError_varg(translate("%q must be >= 1"), MP_QSTR_radius); + } + + vectorio_circle_t *self = m_new_obj(vectorio_circle_t); + self->base.type = &vectorio_circle_type; + common_hal_vectorio_circle_construct(self, radius); + + return MP_OBJ_FROM_PTR(self); +} + + +//| .. attribute:: radius +//| +//| Update the radius of the circle +//| +STATIC mp_obj_t vectorio_circle_obj_get_radius(mp_obj_t self_in) { + vectorio_circle_t *self = MP_OBJ_TO_PTR(self_in); + return mp_obj_new_int(common_hal_vectorio_circle_get_radius(self)); +} +MP_DEFINE_CONST_FUN_OBJ_1(vectorio_circle_get_radius_obj, vectorio_circle_obj_get_radius); + +STATIC mp_obj_t vectorio_circle_obj_set_radius(mp_obj_t self_in, mp_obj_t radius) { + vectorio_circle_t *self = MP_OBJ_TO_PTR(self_in); + common_hal_vectorio_circle_set_radius(self, mp_obj_get_int(radius)); + return mp_const_none; +} +MP_DEFINE_CONST_FUN_OBJ_2(vectorio_circle_set_radius_obj, vectorio_circle_obj_set_radius); + +const mp_obj_property_t vectorio_circle_radius_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&vectorio_circle_get_radius_obj, + (mp_obj_t)&vectorio_circle_set_radius_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + + +STATIC const mp_rom_map_elem_t vectorio_circle_locals_dict_table[] = { + { MP_ROM_QSTR(MP_QSTR_radius), MP_ROM_PTR(&vectorio_circle_radius_obj) }, +}; +STATIC MP_DEFINE_CONST_DICT(vectorio_circle_locals_dict, vectorio_circle_locals_dict_table); + +const mp_obj_type_t vectorio_circle_type = { + { &mp_type_type }, + .name = MP_QSTR_Circle, + .make_new = vectorio_circle_make_new, + .locals_dict = (mp_obj_dict_t*)&vectorio_circle_locals_dict, +}; + diff --git a/shared-bindings/vectorio/Circle.h b/shared-bindings/vectorio/Circle.h new file mode 100644 index 000000000..e8fc048eb --- /dev/null +++ b/shared-bindings/vectorio/Circle.h @@ -0,0 +1,22 @@ +#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_CIRCLE_H +#define MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_CIRCLE_H + +#include "shared-module/vectorio/__init__.h" +#include "shared-module/vectorio/Circle.h" +#include "shared-module/displayio/area.h" + +extern const mp_obj_type_t vectorio_circle_type; + +void common_hal_vectorio_circle_construct(vectorio_circle_t *self, uint16_t radius); + +void common_hal_vectorio_circle_set_on_dirty(vectorio_circle_t *self, vectorio_event_t notification); + +uint32_t common_hal_vectorio_circle_get_pixel(void *circle, int16_t x, int16_t y); + +void common_hal_vectorio_circle_get_area(void *circle, displayio_area_t *out_area); + + +int16_t common_hal_vectorio_circle_get_radius(void *circle); +void common_hal_vectorio_circle_set_radius(void *circle, int16_t radius); + +#endif // MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_CIRCLE_H diff --git a/shared-bindings/vectorio/Polygon.c b/shared-bindings/vectorio/Polygon.c new file mode 100644 index 000000000..b8bb377ac --- /dev/null +++ b/shared-bindings/vectorio/Polygon.c @@ -0,0 +1,139 @@ + +#include "shared-module/vectorio/__init__.h" +#include "shared-bindings/vectorio/Polygon.h" + +#include + +#include "py/obj.h" +#include "py/objproperty.h" +#include "py/objtype.h" +#include "py/runtime.h" +#include "supervisor/shared/translate.h" + + +#define VECTORIO_POLYGON_DEBUG(...) (void)0 +// #define VECTORIO_POLYGON_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + + +// Converts a list of points tuples to a flat list of ints for speedier internal use. +// Also validates the points. +static mp_obj_t _to_points_list(mp_obj_t points_tuple_list) { + size_t len = 0; + mp_obj_t *items; + mp_obj_list_get(points_tuple_list, &len, &items); + VECTORIO_POLYGON_DEBUG("polygon_points_list len: %d\n", len); + + if ( len == 0 ) { + mp_raise_TypeError_varg(translate("empty %q list"), MP_QSTR_point); + } + + mp_obj_t points_list = mp_obj_new_list(0, NULL); + + for ( size_t i = 0; i < len; ++i) { + size_t tuple_len = 0; + mp_obj_t *tuple_items; + mp_obj_tuple_get(items[i], &tuple_len, &tuple_items); + + if (tuple_len != 2) { + mp_raise_ValueError_varg(translate("%q must be a tuple of length 2"), MP_QSTR_point); + } + int value; + if (!mp_obj_get_int_maybe(tuple_items[0], &value)) { + mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); + } + mp_obj_list_append(points_list, MP_OBJ_NEW_SMALL_INT(value)); + if (!mp_obj_get_int_maybe(tuple_items[1], &value)) { + mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); + } + mp_obj_list_append(points_list, MP_OBJ_NEW_SMALL_INT(value)); + } + return points_list; +} + + + +//| .. currentmodule:: vectorio +//| +//| :class:`Polygon` -- Represents a closed shape by ordered vertices +//| ========================================================================== +//| +//| .. class:: Polygon( List[ Tuple[ x, y ], ... ] ) +//| +//| :param [Point] points_array: Vertices for the polygon +//| +static mp_obj_t vectorio_polygon_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { + enum { ARG_points_list }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_points, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, + }; + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + if (!MP_OBJ_IS_TYPE(args[ARG_points_list].u_obj, &mp_type_list)) { + mp_raise_TypeError_varg(translate("%q list must be a list"), MP_QSTR_point); + } + mp_obj_t points_list = _to_points_list(args[ARG_points_list].u_obj); + + vectorio_polygon_t *self = m_new_obj(vectorio_polygon_t); + self->base.type = &vectorio_polygon_type; + + common_hal_vectorio_polygon_construct(self, points_list); + + return MP_OBJ_FROM_PTR(self); +} + + +//| .. attribute:: points +//| +//| Set a new look and shape for this polygon +//| +STATIC mp_obj_t vectorio_polygon_obj_get_points(mp_obj_t self_in) { + vectorio_polygon_t *self = MP_OBJ_TO_PTR(self_in); + mp_obj_t list = mp_obj_new_list(0, NULL); + + size_t len = 0; + mp_obj_t *items; + mp_obj_list_get(common_hal_vectorio_polygon_get_points(self), &len, &items); + + for (size_t i = 0; i < len; i += 2) { + mp_obj_t tuple[] = { items[i], items[i+1] }; + mp_obj_list_append( + list, + mp_obj_new_tuple(2, tuple) + ); + } + return list; +} +MP_DEFINE_CONST_FUN_OBJ_1(vectorio_polygon_get_points_obj, vectorio_polygon_obj_get_points); + +STATIC mp_obj_t vectorio_polygon_obj_set_points(mp_obj_t self_in, mp_obj_t points) { + vectorio_polygon_t *self = MP_OBJ_TO_PTR(self_in); + + mp_obj_t points_list = _to_points_list(points); + + common_hal_vectorio_polygon_set_points(self, points_list); + return mp_const_none; +} +MP_DEFINE_CONST_FUN_OBJ_2(vectorio_polygon_set_points_obj, vectorio_polygon_obj_set_points); + +const mp_obj_property_t vectorio_polygon_points_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&vectorio_polygon_get_points_obj, + (mp_obj_t)&vectorio_polygon_set_points_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + + + +STATIC const mp_rom_map_elem_t vectorio_polygon_locals_dict_table[] = { + { MP_ROM_QSTR(MP_QSTR_points), MP_ROM_PTR(&vectorio_polygon_points_obj) }, +}; +STATIC MP_DEFINE_CONST_DICT(vectorio_polygon_locals_dict, vectorio_polygon_locals_dict_table); + +const mp_obj_type_t vectorio_polygon_type = { + { &mp_type_type }, + .name = MP_QSTR_Polygon, + .make_new = vectorio_polygon_make_new, + .locals_dict = (mp_obj_dict_t*)&vectorio_polygon_locals_dict, +}; + diff --git a/shared-bindings/vectorio/Polygon.h b/shared-bindings/vectorio/Polygon.h new file mode 100644 index 000000000..5594fbec4 --- /dev/null +++ b/shared-bindings/vectorio/Polygon.h @@ -0,0 +1,24 @@ +#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_POLYGON_H +#define MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_POLYGON_H + +#include "shared-module/vectorio/Polygon.h" +#include "shared-module/displayio/area.h" +#include "shared-module/vectorio/__init__.h" + +extern const mp_obj_type_t vectorio_polygon_type; + +void common_hal_vectorio_polygon_construct(vectorio_polygon_t *self, mp_obj_t points_list); +void common_hal_vectorio_polygon_set_on_dirty(vectorio_polygon_t *self, vectorio_event_t notification); + + +uint32_t common_hal_vectorio_polygon_get_pixel(void *polygon, int16_t x, int16_t y); + +void common_hal_vectorio_polygon_get_area(void *polygon, displayio_area_t *out_area); + + + +mp_obj_t common_hal_vectorio_polygon_get_points(vectorio_polygon_t *self); +void common_hal_vectorio_polygon_set_points(vectorio_polygon_t *self, mp_obj_t points_list); + + +#endif // MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_POLYGON_H diff --git a/shared-bindings/vectorio/Rectangle.c b/shared-bindings/vectorio/Rectangle.c new file mode 100644 index 000000000..ea468f788 --- /dev/null +++ b/shared-bindings/vectorio/Rectangle.c @@ -0,0 +1,56 @@ + +#include "shared-bindings/vectorio/Rectangle.h" + +#include + +#include "py/objtype.h" +#include "py/runtime.h" +#include "supervisor/shared/translate.h" + + +//| .. currentmodule:: vectorio +//| +//| :class:`Rectangle` -- Represents a rectangle by defining its bounds +//| ========================================================================== +//| +//| .. class:: Rectangle(width, height) +//| +//| :param int width: The number of pixels wide +//| :param int height: The number of pixels high +//| +static mp_obj_t vectorio_rectangle_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { + enum { ARG_width, ARG_height }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_width, MP_ARG_REQUIRED | MP_ARG_INT }, + { MP_QSTR_height, MP_ARG_REQUIRED | MP_ARG_INT }, + }; + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + mp_int_t width = args[ARG_width].u_int; + if (width < 1) { + mp_raise_ValueError_varg(translate("%q must be >= 1"), MP_QSTR_width); + } + mp_int_t height = args[ARG_height].u_int; + if (height < 1) { + mp_raise_ValueError_varg(translate("%q must be >= 1"), MP_QSTR_height); + } + + vectorio_rectangle_t *self = m_new_obj(vectorio_rectangle_t); + self->base.type = &vectorio_rectangle_type; + common_hal_vectorio_rectangle_construct(self, width, height); + + return MP_OBJ_FROM_PTR(self); +} + + +STATIC const mp_rom_map_elem_t vectorio_rectangle_locals_dict_table[] = { +}; +STATIC MP_DEFINE_CONST_DICT(vectorio_rectangle_locals_dict, vectorio_rectangle_locals_dict_table); + +const mp_obj_type_t vectorio_rectangle_type = { + { &mp_type_type }, + .name = MP_QSTR_Rectangle, + .make_new = vectorio_rectangle_make_new, + .locals_dict = (mp_obj_dict_t*)&vectorio_rectangle_locals_dict, +}; diff --git a/shared-bindings/vectorio/Rectangle.h b/shared-bindings/vectorio/Rectangle.h new file mode 100644 index 000000000..bb461ed9d --- /dev/null +++ b/shared-bindings/vectorio/Rectangle.h @@ -0,0 +1,15 @@ +#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_RECTANGLE_H +#define MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_RECTANGLE_H + +#include "shared-module/vectorio/Rectangle.h" +#include "shared-module/displayio/area.h" + +extern const mp_obj_type_t vectorio_rectangle_type; + +void common_hal_vectorio_rectangle_construct(vectorio_rectangle_t *self, uint32_t width, uint32_t height); + +uint32_t common_hal_vectorio_rectangle_get_pixel(void *rectangle, int16_t x, int16_t y); + +void common_hal_vectorio_rectangle_get_area(void *rectangle, displayio_area_t *out_area); + +#endif // MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_RECTANGLE_H diff --git a/shared-bindings/vectorio/VectorShape.c b/shared-bindings/vectorio/VectorShape.c new file mode 100644 index 000000000..8f99577b4 --- /dev/null +++ b/shared-bindings/vectorio/VectorShape.c @@ -0,0 +1,213 @@ + +#include "shared-module/vectorio/__init__.h" +#include "shared-bindings/vectorio/VectorShape.h" +#include "shared-bindings/vectorio/Circle.h" +#include "shared-bindings/vectorio/Polygon.h" +#include "shared-bindings/vectorio/Rectangle.h" + +#include "shared-bindings/displayio/ColorConverter.h" +#include "shared-bindings/displayio/Palette.h" + +#include + +#include "lib/utils/context_manager_helpers.h" + +#include "py/binary.h" +#include "py/objproperty.h" +#include "py/objtype.h" +#include "py/runtime.h" +#include "supervisor/shared/translate.h" + + +//| .. currentmodule:: vectorio +//| +//| :class:`VectorShape` -- Binds a vector shape to a location and pixel color +//| ========================================================================== +//| +//| .. class:: VectorShape( shape, pixel_shader, x=0, y=0) +//| +//| :param vectorio.Polygon shape: The shape to draw. +//| :param displayio.Palette pixel_shader: The pixel shader that produces colors from values +//| :param int x: Initial x position of the center axis of the shape within the parent. +//| :param int y: Initial y position of the center axis of the shape within the parent. +//| +STATIC mp_obj_t vectorio_vector_shape_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { + enum { ARG_shape, ARG_pixel_shader, ARG_x, ARG_y, ARG_transpose_xy }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_shape, MP_ARG_OBJ | MP_ARG_KW_ONLY | MP_ARG_REQUIRED }, + { MP_QSTR_pixel_shader, MP_ARG_OBJ | MP_ARG_KW_ONLY | MP_ARG_REQUIRED }, + { MP_QSTR_x, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} }, + { MP_QSTR_y, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} }, + { MP_QSTR_transpose_xy, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} }, + }; + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + mp_obj_t pixel_shader = args[ARG_pixel_shader].u_obj; + if (!MP_OBJ_IS_TYPE(pixel_shader, &displayio_colorconverter_type) && + !MP_OBJ_IS_TYPE(pixel_shader, &displayio_palette_type)) { + mp_raise_TypeError_varg(translate("unsupported %q type"), MP_QSTR_pixel_shader); + } + + int16_t x = args[ARG_x].u_int; + int16_t y = args[ARG_y].u_int; + + mp_obj_t shape = args[ARG_shape].u_obj; + vectorio_ishape_t ishape; + // Wire up shape functions + if (MP_OBJ_IS_TYPE(shape, &vectorio_polygon_type)) { + ishape.shape = shape; + ishape.get_area = &common_hal_vectorio_polygon_get_area; + ishape.get_pixel = &common_hal_vectorio_polygon_get_pixel; + } else if (MP_OBJ_IS_TYPE(shape, &vectorio_rectangle_type)) { + ishape.shape = shape; + ishape.get_area = &common_hal_vectorio_rectangle_get_area; + ishape.get_pixel = &common_hal_vectorio_rectangle_get_pixel; + } else if (MP_OBJ_IS_TYPE(shape, &vectorio_circle_type)) { + ishape.shape = shape; + ishape.get_area = &common_hal_vectorio_circle_get_area; + ishape.get_pixel = &common_hal_vectorio_circle_get_pixel; + } else { + mp_raise_TypeError_varg(translate("unsupported %q type"), MP_QSTR_shape); + } + + vectorio_vector_shape_t *self = m_new_obj(vectorio_vector_shape_t); + self->base.type = &vectorio_vector_shape_type; + common_hal_vectorio_vector_shape_construct(self, + ishape, pixel_shader, x, y, args[ARG_transpose_xy].u_bool + ); + + // Wire up event callbacks + vectorio_event_t on_dirty = { + .obj = self, + .event = &common_hal_vectorio_vector_shape_set_dirty + }; + + if (MP_OBJ_IS_TYPE(shape, &vectorio_polygon_type)) { + common_hal_vectorio_polygon_set_on_dirty(self->ishape.shape, on_dirty); + } else if (MP_OBJ_IS_TYPE(shape, &vectorio_rectangle_type)) { + common_hal_vectorio_circle_set_on_dirty(self->ishape.shape, on_dirty); + } else if (MP_OBJ_IS_TYPE(shape, &vectorio_circle_type)) { + } else { + mp_raise_TypeError_varg(translate("unsupported %q type"), MP_QSTR_shape); + } + + return MP_OBJ_FROM_PTR(self); +} + + +//| .. attribute:: x +//| +//| X position of the center point of the shape in the parent. +//| +STATIC mp_obj_t vectorio_vector_shape_obj_get_x(mp_obj_t self_in) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + return MP_OBJ_NEW_SMALL_INT(common_hal_vectorio_vector_shape_get_x(self)); +} +MP_DEFINE_CONST_FUN_OBJ_1(vectorio_vector_shape_get_x_obj, vectorio_vector_shape_obj_get_x); + +STATIC mp_obj_t vectorio_vector_shape_obj_set_x(mp_obj_t self_in, mp_obj_t x_obj) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + + mp_int_t x = mp_obj_get_int(x_obj); + common_hal_vectorio_vector_shape_set_x(self, x); + return mp_const_none; +} +MP_DEFINE_CONST_FUN_OBJ_2(vectorio_vector_shape_set_x_obj, vectorio_vector_shape_obj_set_x); + +const mp_obj_property_t vectorio_vector_shape_x_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&vectorio_vector_shape_get_x_obj, + (mp_obj_t)&vectorio_vector_shape_set_x_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + + +//| .. attribute:: y +//| +//| Y position of the center point of the shape in the parent. +//| +STATIC mp_obj_t vectorio_vector_shape_obj_get_y(mp_obj_t self_in) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + return MP_OBJ_NEW_SMALL_INT(common_hal_vectorio_vector_shape_get_y(self)); +} +MP_DEFINE_CONST_FUN_OBJ_1(vectorio_vector_shape_get_y_obj, vectorio_vector_shape_obj_get_y); + +STATIC mp_obj_t vectorio_vector_shape_obj_set_y(mp_obj_t self_in, mp_obj_t y_obj) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + + mp_int_t y = mp_obj_get_int(y_obj); + common_hal_vectorio_vector_shape_set_y(self, y); + return mp_const_none; +} +MP_DEFINE_CONST_FUN_OBJ_2(vectorio_vector_shape_set_y_obj, vectorio_vector_shape_obj_set_y); + +const mp_obj_property_t vectorio_vector_shape_y_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&vectorio_vector_shape_get_y_obj, + (mp_obj_t)&vectorio_vector_shape_set_y_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + + +//| .. attribute:: transpose_xy +//| +//| true if the object is to be flipped. +//| +STATIC mp_obj_t vectorio_vector_shape_obj_get_transpose_xy(mp_obj_t self_in) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + return mp_obj_new_bool(common_hal_vectorio_vector_shape_get_transpose_xy(self)); +} +MP_DEFINE_CONST_FUN_OBJ_1(vectorio_vector_shape_get_transpose_xy_obj, vectorio_vector_shape_obj_get_transpose_xy); + +const mp_obj_property_t vectorio_vector_shape_transpose_xy_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&vectorio_vector_shape_get_transpose_xy_obj, + (mp_obj_t)&mp_const_none_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + +//| .. attribute:: pixel_shader +//| +//| The pixel shader of the shape. +//| +STATIC mp_obj_t vectorio_vector_shape_obj_get_pixel_shader(mp_obj_t self_in) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + return common_hal_vectorio_vector_shape_get_pixel_shader(self); +} +MP_DEFINE_CONST_FUN_OBJ_1(vectorio_vector_shape_get_pixel_shader_obj, vectorio_vector_shape_obj_get_pixel_shader); + +STATIC mp_obj_t vectorio_vector_shape_obj_set_pixel_shader(mp_obj_t self_in, mp_obj_t pixel_shader) { + vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); + if (!MP_OBJ_IS_TYPE(pixel_shader, &displayio_palette_type) && !MP_OBJ_IS_TYPE(pixel_shader, &displayio_colorconverter_type)) { + mp_raise_TypeError(translate("pixel_shader must be displayio.Palette or displayio.ColorConverter")); + } + + common_hal_vectorio_vector_shape_set_pixel_shader(self, pixel_shader); + + return mp_const_none; +} +MP_DEFINE_CONST_FUN_OBJ_2(vectorio_vector_shape_set_pixel_shader_obj, vectorio_vector_shape_obj_set_pixel_shader); + +const mp_obj_property_t vectorio_vector_shape_pixel_shader_obj = { + .base.type = &mp_type_property, + .proxy = {(mp_obj_t)&vectorio_vector_shape_get_pixel_shader_obj, + (mp_obj_t)&vectorio_vector_shape_set_pixel_shader_obj, + (mp_obj_t)&mp_const_none_obj}, +}; + + +STATIC const mp_rom_map_elem_t vectorio_vector_shape_locals_dict_table[] = { + // Properties + { MP_ROM_QSTR(MP_QSTR_x), MP_ROM_PTR(&vectorio_vector_shape_x_obj) }, + { MP_ROM_QSTR(MP_QSTR_y), MP_ROM_PTR(&vectorio_vector_shape_y_obj) }, + { MP_ROM_QSTR(MP_QSTR_pixel_shader), MP_ROM_PTR(&vectorio_vector_shape_pixel_shader_obj) }, +}; +STATIC MP_DEFINE_CONST_DICT(vectorio_vector_shape_locals_dict, vectorio_vector_shape_locals_dict_table); + +const mp_obj_type_t vectorio_vector_shape_type = { + { &mp_type_type }, + .name = MP_QSTR_VectorShape, + .make_new = vectorio_vector_shape_make_new, + .locals_dict = (mp_obj_dict_t*)&vectorio_vector_shape_locals_dict, +}; diff --git a/shared-bindings/vectorio/VectorShape.h b/shared-bindings/vectorio/VectorShape.h new file mode 100644 index 000000000..ad745b30f --- /dev/null +++ b/shared-bindings/vectorio/VectorShape.h @@ -0,0 +1,25 @@ +#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_SHAPE_H +#define MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_SHAPE_H + +#include "shared-module/vectorio/VectorShape.h" + +extern const mp_obj_type_t vectorio_vector_shape_type; + +void common_hal_vectorio_vector_shape_construct(vectorio_vector_shape_t *self, + vectorio_ishape_t ishape, + mp_obj_t pixel_shader, uint16_t x, uint16_t y, bool transpose_xy); + +void common_hal_vectorio_vector_shape_set_dirty(void *self); + +mp_int_t common_hal_vectorio_vector_shape_get_x(vectorio_vector_shape_t *self); +void common_hal_vectorio_vector_shape_set_x(vectorio_vector_shape_t *self, mp_int_t x); + +mp_int_t common_hal_vectorio_vector_shape_get_y(vectorio_vector_shape_t *self); +void common_hal_vectorio_vector_shape_set_y(vectorio_vector_shape_t *self, mp_int_t y); + +bool common_hal_vectorio_vector_shape_get_transpose_xy(vectorio_vector_shape_t *self); + +mp_obj_t common_hal_vectorio_vector_shape_get_pixel_shader(vectorio_vector_shape_t *self); +void common_hal_vectorio_vector_shape_set_pixel_shader(vectorio_vector_shape_t *self, mp_obj_t pixel_shader); + +#endif // MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_SHAPE_H diff --git a/shared-bindings/vectorio/__init__.c b/shared-bindings/vectorio/__init__.c new file mode 100644 index 000000000..b9e3828bd --- /dev/null +++ b/shared-bindings/vectorio/__init__.c @@ -0,0 +1,46 @@ +#include + +#include "py/obj.h" +#include "py/runtime.h" + +#include "shared-bindings/vectorio/Circle.h" +#include "shared-bindings/vectorio/Polygon.h" +#include "shared-bindings/vectorio/Rectangle.h" +#include "shared-bindings/vectorio/VectorShape.h" + +//| :mod:`vectorio` --- Lightweight 2d shapes for displays +//| ========================================================================= +//| +//| .. module:: vectorio +//| :synopsis: Adds vector graphics to displayio +//| :platform: SAMD21, SAMD51, nRF52 +//| +//| The `vectorio` module contains classes to construct shapes +//| by describing their points rather than providing them in bitmaps. +//| +//| Libraries +//| +//| .. toctree:: +//| :maxdepth: 3 +//| +//| Circle +//| Polygon +//| Rectangle +//| VectorShape +//| + + +STATIC const mp_rom_map_elem_t vectorio_module_globals_table[] = { + { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_vectorio) }, + { MP_ROM_QSTR(MP_QSTR_Circle), MP_ROM_PTR(&vectorio_circle_type) }, + { MP_ROM_QSTR(MP_QSTR_Polygon), MP_ROM_PTR(&vectorio_polygon_type) }, + { MP_ROM_QSTR(MP_QSTR_Rectangle), MP_ROM_PTR(&vectorio_rectangle_type) }, + { MP_ROM_QSTR(MP_QSTR_VectorShape), MP_ROM_PTR(&vectorio_vector_shape_type) }, +}; + +STATIC MP_DEFINE_CONST_DICT(vectorio_module_globals, vectorio_module_globals_table); + +const mp_obj_module_t vectorio_module = { + .base = { &mp_type_module }, + .globals = (mp_obj_dict_t*)&vectorio_module_globals, +}; diff --git a/shared-module/displayio/Group.c b/shared-module/displayio/Group.c index d69e9f585..9d50dabec 100644 --- a/shared-module/displayio/Group.c +++ b/shared-module/displayio/Group.c @@ -29,6 +29,11 @@ #include "py/runtime.h" #include "shared-bindings/displayio/TileGrid.h" +#if CIRCUITPY_VECTORIO +#include "shared-bindings/vectorio/VectorShape.h" +#endif + + void common_hal_displayio_group_construct(displayio_group_t* self, uint32_t max_size, uint32_t scale, mp_int_t x, mp_int_t y) { displayio_group_child_t* children = m_new(displayio_group_child_t, max_size); displayio_group_construct(self, children, max_size, scale, x, y); @@ -200,7 +205,14 @@ void common_hal_displayio_group_set_y(displayio_group_t* self, mp_int_t y) { } static mp_obj_t _add_layer(displayio_group_t* self, mp_obj_t layer) { - mp_obj_t native_layer = mp_instance_cast_to_native_base(layer, &displayio_group_type); + mp_obj_t native_layer; +#if CIRCUITPY_VECTORIO + native_layer = mp_instance_cast_to_native_base(layer, &vectorio_vector_shape_type); + if (native_layer != MP_OBJ_NULL) { + return native_layer; + } +#endif + native_layer = mp_instance_cast_to_native_base(layer, &displayio_group_type); if (native_layer == MP_OBJ_NULL) { native_layer = mp_instance_cast_to_native_base(layer, &displayio_tilegrid_type); if (native_layer == MP_OBJ_NULL) { @@ -317,6 +329,15 @@ bool displayio_group_fill_area(displayio_group_t *self, const _displayio_colorsp bool full_coverage = false; for (int32_t i = self->size - 1; i >= 0 ; i--) { mp_obj_t layer = self->children[i].native; +#if CIRCUITPY_VECTORIO + if (MP_OBJ_IS_TYPE(layer, &vectorio_vector_shape_type)) { + if (vectorio_vector_shape_fill_area(layer, colorspace, area, mask, buffer)) { + full_coverage = true; + break; + } + } + else +#endif if (MP_OBJ_IS_TYPE(layer, &displayio_tilegrid_type)) { if (displayio_tilegrid_fill_area(layer, colorspace, area, mask, buffer)) { full_coverage = true; @@ -336,6 +357,12 @@ void displayio_group_finish_refresh(displayio_group_t *self) { self->item_removed = false; for (int32_t i = self->size - 1; i >= 0 ; i--) { mp_obj_t layer = self->children[i].native; +#if CIRCUITPY_VECTORIO + if (MP_OBJ_IS_TYPE(layer, &vectorio_vector_shape_type)) { + vectorio_vector_shape_finish_refresh(layer); + } + else +#endif if (MP_OBJ_IS_TYPE(layer, &displayio_tilegrid_type)) { displayio_tilegrid_finish_refresh(layer); } else if (MP_OBJ_IS_TYPE(layer, &displayio_group_type)) { @@ -352,6 +379,12 @@ displayio_area_t* displayio_group_get_refresh_areas(displayio_group_t *self, dis for (int32_t i = self->size - 1; i >= 0 ; i--) { mp_obj_t layer = self->children[i].native; +#if CIRCUITPY_VECTORIO + if (MP_OBJ_IS_TYPE(layer, &vectorio_vector_shape_type)) { + tail = vectorio_vector_shape_get_refresh_areas(layer, tail); + } + else +#endif if (MP_OBJ_IS_TYPE(layer, &displayio_tilegrid_type)) { tail = displayio_tilegrid_get_refresh_areas(layer, tail); } else if (MP_OBJ_IS_TYPE(layer, &displayio_group_type)) { diff --git a/shared-module/displayio/display_core.c b/shared-module/displayio/display_core.c index d01100f7f..43f2d1937 100644 --- a/shared-module/displayio/display_core.c +++ b/shared-module/displayio/display_core.c @@ -40,6 +40,9 @@ #include #include +#define DISPLAYIO_CORE_DEBUG(...) (void)0 +// #define DISPLAYIO_CORE_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + void displayio_display_core_construct(displayio_display_core_t* self, mp_obj_t bus, uint16_t width, uint16_t height, uint16_t ram_width, uint16_t ram_height, int16_t colstart, int16_t rowstart, uint16_t rotation, uint16_t color_depth, bool grayscale, bool pixels_in_byte_share_row, uint8_t bytes_per_cell, bool reverse_pixels_in_byte, bool reverse_bytes_in_word) { @@ -298,6 +301,7 @@ void displayio_display_core_start_refresh(displayio_display_core_t* self) { void displayio_display_core_finish_refresh(displayio_display_core_t* self) { if (self->current_group != NULL) { + DISPLAYIO_CORE_DEBUG("displayiocore group_finish_refresh\n"); displayio_group_finish_refresh(self->current_group); } self->full_refresh = false; diff --git a/shared-module/vectorio/Circle.c b/shared-module/vectorio/Circle.c new file mode 100644 index 000000000..6bcd6318f --- /dev/null +++ b/shared-module/vectorio/Circle.c @@ -0,0 +1,55 @@ + +#include "shared-bindings/vectorio/Circle.h" +#include "shared-module/vectorio/__init__.h" +#include "shared-module/displayio/area.h" + +#include "py/runtime.h" +#include "stdlib.h" + + +void common_hal_vectorio_circle_construct(vectorio_circle_t *self, uint16_t radius) { + self->radius = radius; + self->on_dirty.obj = NULL; +} + +void common_hal_vectorio_circle_set_on_dirty(vectorio_circle_t *self, vectorio_event_t on_dirty) { + if (self->on_dirty.obj != NULL) { + mp_raise_TypeError(translate("circle can only be registered in one parent")); + } + self->on_dirty = on_dirty; +} + + +uint32_t common_hal_vectorio_circle_get_pixel(void *obj, int16_t x, int16_t y) { + vectorio_circle_t *self = obj; + int16_t radius = abs(self->radius); + x = abs(x); + y = abs(y); + if (x+y <= radius) return 1; + if (x > radius) return 0; + if (y > radius) return 0; + return (int32_t)x*x + (int32_t)y*y <= (int32_t)radius*radius; +} + + +void common_hal_vectorio_circle_get_area(void *circle, displayio_area_t *out_area) { + vectorio_circle_t *self = circle; + out_area->x1 = -1 * self->radius; + out_area->y1 = -1 * self->radius; + out_area->x2 = self->radius + 1; + out_area->y2 = self->radius + 1; +} + +int16_t common_hal_vectorio_circle_get_radius(void *obj) { + vectorio_circle_t *self = obj; + return self->radius; +} + +void common_hal_vectorio_circle_set_radius(void *obj, int16_t radius) { + vectorio_circle_t *self = obj; + self->radius = abs(radius); + if (self->on_dirty.obj != NULL) { + self->on_dirty.event(self->on_dirty.obj); + } +} + diff --git a/shared-module/vectorio/Circle.h b/shared-module/vectorio/Circle.h new file mode 100644 index 000000000..4b43d767e --- /dev/null +++ b/shared-module/vectorio/Circle.h @@ -0,0 +1,17 @@ +#ifndef MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_CIRCLE_H +#define MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_CIRCLE_H + +#include + +#include "py/obj.h" + +#include "shared-module/vectorio/__init__.h" + +typedef struct { + mp_obj_base_t base; + uint16_t radius; + vectorio_event_t on_dirty; +} vectorio_circle_t; + +#endif // MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_CIRCLE_H + diff --git a/shared-module/vectorio/Polygon.c b/shared-module/vectorio/Polygon.c new file mode 100644 index 000000000..6722912c2 --- /dev/null +++ b/shared-module/vectorio/Polygon.c @@ -0,0 +1,110 @@ + +#include "shared-module/vectorio/__init__.h" +#include "shared-bindings/vectorio/Polygon.h" +#include "shared-module/displayio/area.h" + +#include "py/runtime.h" +#include "stdlib.h" +#include + + +#define VECTORIO_POLYGON_DEBUG(...) (void)0 +// #define VECTORIO_POLYGON_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + + +void common_hal_vectorio_polygon_construct(vectorio_polygon_t *self, mp_obj_t points_list) { + VECTORIO_POLYGON_DEBUG("%p polygon_construct\n", self); + self->points_list = points_list; + self->on_dirty.obj = NULL; +} + + +mp_obj_t common_hal_vectorio_polygon_get_points(vectorio_polygon_t *self) { + return self->points_list; +} +void common_hal_vectorio_polygon_set_points(vectorio_polygon_t *self, mp_obj_t points_list) { + self->points_list = points_list; + if (self->on_dirty.obj != NULL) { + self->on_dirty.event(self->on_dirty.obj); + } +} + +void common_hal_vectorio_polygon_set_on_dirty(vectorio_polygon_t *self, vectorio_event_t notification) { + if ( self->on_dirty.obj != NULL ) { + mp_raise_TypeError(translate("polygon can only be registered in one parent")); + } + self->on_dirty = notification; +} + + +void common_hal_vectorio_polygon_get_area(void *polygon, displayio_area_t *area) { + VECTORIO_POLYGON_DEBUG("%p polygon get_area", polygon); + vectorio_polygon_t *self = polygon; + size_t len; + mp_obj_t *points; + mp_obj_list_get(self->points_list, &len, &points); + VECTORIO_POLYGON_DEBUG(" len: %2d, points: %d\n", len, len/2); + + area->x1 = SHRT_MAX; + area->y1 = SHRT_MAX; + area->x2 = SHRT_MIN; + area->y2 = SHRT_MIN; + for (size_t i=0; i < len; ++i) { + mp_int_t x = mp_obj_get_int(points[i]); + ++i; + mp_int_t y = mp_obj_get_int(points[i]); + if (x <= area->x1) area->x1 = x-1; + if (y <= area->y1) area->y1 = y-1; + if (x >= area->x2) area->x2 = x+1; + if (y >= area->y2) area->y2 = y+1; + } +} + + +// <0 if the point is to the left of the line vector +// 0 if the point is on the line +// >0 if the point is to the right of the line vector +__attribute__((always_inline)) static inline int line_side( mp_int_t x1, mp_int_t y1, mp_int_t x2, mp_int_t y2, int16_t px, int16_t py ) { + return (px - x1) * (y2 - y1) + - (py - y1) * (x2 - x1); +} + + +uint32_t common_hal_vectorio_polygon_get_pixel(void *obj, int16_t x, int16_t y) { + VECTORIO_POLYGON_DEBUG("%p polygon get_pixel %d, %d\n", obj, x, y); + vectorio_polygon_t *self = obj; + size_t len; + mp_obj_t *points; + mp_obj_list_get(self->points_list, &len, &points); + + if (len == 0) { + return 0; + } + + int winding_number = 0; + mp_int_t x1 = mp_obj_get_int(points[0]); + mp_int_t y1 = mp_obj_get_int(points[1]); + for (size_t i=2; i <= len + 1; ++i) { + VECTORIO_POLYGON_DEBUG(" {(%3d, %3d),", x1, y1); + mp_int_t x2 = mp_obj_get_int(points[i % len]); + ++i; + mp_int_t y2 = mp_obj_get_int(points[i % len]); + VECTORIO_POLYGON_DEBUG(" (%3d, %3d)}\n", x2, y2); + if ( y1 <= y ) { + if ( y2 > y && line_side(x1, y1, x2, y2, x, y) > 0 ) { + // Wind up, point is to the right of the edge vector + ++winding_number; + VECTORIO_POLYGON_DEBUG(" wind:%2d winding_number:%2d\n", 1, winding_number); + } + } else if ( y2 <= y && line_side(x1, y1, x2, y2, x, y) < 0 ) { + // Wind down, point is to the left of the edge vector + --winding_number; + VECTORIO_POLYGON_DEBUG(" wind:%2d winding_number:%2d\n", -1, winding_number); + } + + x1 = x2; + y1 = y2; + } + return winding_number == 0 ? 0 : 1; +} + diff --git a/shared-module/vectorio/Polygon.h b/shared-module/vectorio/Polygon.h new file mode 100644 index 000000000..1aef854a7 --- /dev/null +++ b/shared-module/vectorio/Polygon.h @@ -0,0 +1,16 @@ +#ifndef MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_POLYGON_H +#define MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_POLYGON_H + +#include + +#include "py/obj.h" +#include "shared-module/vectorio/__init__.h" + +typedef struct { + mp_obj_base_t base; + // A micropython List[ x, y, ... ] + mp_obj_t points_list; + vectorio_event_t on_dirty; +} vectorio_polygon_t; + +#endif // MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_POLYGON_H diff --git a/shared-module/vectorio/Rectangle.c b/shared-module/vectorio/Rectangle.c new file mode 100644 index 000000000..dfad58a4d --- /dev/null +++ b/shared-module/vectorio/Rectangle.c @@ -0,0 +1,35 @@ +#include "shared-bindings/vectorio/Rectangle.h" +#include "shared-module/displayio/area.h" + +#include "py/runtime.h" + + +void common_hal_vectorio_rectangle_construct(vectorio_rectangle_t *self, uint32_t width, uint32_t height) { + self->width = width; + self->height = height; +} + + +uint32_t common_hal_vectorio_rectangle_get_pixel(void *obj, int16_t x, int16_t y) { + vectorio_rectangle_t *self = obj; + if (x < 0 || x >= self->width || y >= self->height || y < 0) { + return 0; + } + return 1; +} + + +void common_hal_vectorio_rectangle_get_area(void *rectangle, displayio_area_t *out_area) { + vectorio_rectangle_t *self = rectangle; + out_area->x1 = 0; + out_area->y1 = 0; + out_area->x2 = self->width; + out_area->y2 = self->height; +} + + +uint32_t common_hal_vectorio_rectangle_get_height(void *rectangle) { + vectorio_rectangle_t *self = rectangle; + return self->height; +} + diff --git a/shared-module/vectorio/Rectangle.h b/shared-module/vectorio/Rectangle.h new file mode 100644 index 000000000..c1f2a7a64 --- /dev/null +++ b/shared-module/vectorio/Rectangle.h @@ -0,0 +1,15 @@ +#ifndef MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_RECTANGLE_H +#define MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_RECTANGLE_H + +#include + +#include "py/obj.h" + +typedef struct { + mp_obj_base_t base; + uint16_t width; + uint16_t height; +} vectorio_rectangle_t; + +#endif // MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_RECTANGLE_H + diff --git a/shared-module/vectorio/VectorShape.c b/shared-module/vectorio/VectorShape.c new file mode 100644 index 000000000..985b77858 --- /dev/null +++ b/shared-module/vectorio/VectorShape.c @@ -0,0 +1,282 @@ + +#include "stdlib.h" + +#include "shared-module/vectorio/__init__.h" +#include "shared-bindings/vectorio/VectorShape.h" + +#include "py/runtime.h" +#include "shared-bindings/displayio/ColorConverter.h" +#include "shared-bindings/displayio/Palette.h" + +#include "shared-bindings/vectorio/Circle.h" +#include "shared-bindings/vectorio/Polygon.h" +#include "shared-bindings/vectorio/Rectangle.h" + +// Lifecycle actions. +#define VECTORIO_SHAPE_DEBUG(...) (void)0 +// #define VECTORIO_SHAPE_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + + +// Really verbose. +#define VECTORIO_SHAPE_PIXEL_DEBUG(...) (void)0 +// #define VECTORIO_SHAPE_PIXEL_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + + +inline __attribute__((always_inline)) +static int32_t max(int32_t a, int32_t b) { + return a > b ? a : b; +} + + +inline __attribute__((always_inline)) +static void _transpose_area(displayio_area_t *out_area) { + int16_t swap = out_area->x1; + out_area->x1 = out_area->y1; + out_area->y1 = swap; + swap = out_area->x2; + out_area->x2 = out_area->y2; + out_area->y2 = swap; +} + + +inline __attribute__((always_inline)) +static void _get_shape_area(vectorio_vector_shape_t *self, displayio_area_t *out_area) { + VECTORIO_SHAPE_DEBUG("%p get_area\n", self); + self->ishape.get_area(self->ishape.shape, out_area); +} + + +inline __attribute__((always_inline)) +static void _get_screen_area(vectorio_vector_shape_t *self, displayio_area_t *out_area) { + VECTORIO_SHAPE_DEBUG("%p get_screen_area\n", self); + self->ishape.get_area(self->ishape.shape, out_area); + if (self->transpose_xy) { + _transpose_area(out_area); + displayio_area_shift(out_area, self->y, self->x); + } else { + displayio_area_shift(out_area, self->x, self->y); + } +} + + +// This must be invoked each time a shape changes its position or its shape in any way. +void common_hal_vectorio_vector_shape_set_dirty(void *vector_shape) { + vectorio_vector_shape_t *self = vector_shape; + // In screen space. Need to offset the shape space. + displayio_area_t current_area; + _get_screen_area(self, ¤t_area); + VECTORIO_SHAPE_DEBUG("%p shape_dirty current:{(%3d,%3d), (%3d,%3d)} dirty:{(%3d,%3d), (%3d,%3d)}", + self, + current_area.x1, current_area.y1, current_area.x2, current_area.y2, + self->ephemeral_dirty_area.x1, self->ephemeral_dirty_area.y1, self->ephemeral_dirty_area.x2, self->ephemeral_dirty_area.y2); + self->dirty = true; + // Dirty area tracks the shape's footprint between draws. It's reset on refresh finish, + displayio_area_expand(&self->ephemeral_dirty_area, ¤t_area); + VECTORIO_SHAPE_DEBUG(" -> expanded:{(%3d,%3d), (%3d,%3d)}\n", self->ephemeral_dirty_area.x1, self->ephemeral_dirty_area.y1, self->ephemeral_dirty_area.x2, self->ephemeral_dirty_area.y2); +} + + +void common_hal_vectorio_vector_shape_construct(vectorio_vector_shape_t *self, + vectorio_ishape_t ishape, + mp_obj_t pixel_shader, uint16_t x, uint16_t y, bool transpose_xy) { + VECTORIO_SHAPE_DEBUG("%p vector_shape_construct x:%3d, y:%3d\n", self, x, y); + self->x = x; + self->y = y; + self->pixel_shader = pixel_shader; + self->ishape = ishape; + self->transpose_xy = transpose_xy; + self->dirty = true; + _get_screen_area(self, &self->ephemeral_dirty_area); + self->ephemeral_dirty_area.next = NULL; +} + + +mp_int_t common_hal_vectorio_vector_shape_get_x(vectorio_vector_shape_t *self) { + VECTORIO_SHAPE_DEBUG("%p get_x\n", self); + return self->x; +} + + +void common_hal_vectorio_vector_shape_set_x(vectorio_vector_shape_t *self, mp_int_t x) { + VECTORIO_SHAPE_DEBUG("%p set_x %d\n", self, x); + if (self->x == x) { + return; + } + self->x = x; + common_hal_vectorio_vector_shape_set_dirty(self); +} + + +mp_int_t common_hal_vectorio_vector_shape_get_y(vectorio_vector_shape_t *self) { + VECTORIO_SHAPE_DEBUG("%p get_y\n", self); + return self->y; +} + + +void common_hal_vectorio_vector_shape_set_y(vectorio_vector_shape_t *self, mp_int_t y) { + VECTORIO_SHAPE_DEBUG("%p set_y %d\n", self, y); + if (self->y == y) { + return; + } + self->y = y; + common_hal_vectorio_vector_shape_set_dirty(self); +} + + +bool common_hal_vectorio_vector_shape_get_transpose_xy(vectorio_vector_shape_t *self) { + VECTORIO_SHAPE_DEBUG("%p get_transpose_xy\n", self); + return self->transpose_xy; +} + + +mp_obj_t common_hal_vectorio_vector_shape_get_pixel_shader(vectorio_vector_shape_t *self) { + VECTORIO_SHAPE_DEBUG("%p get_pixel_shader\n", self); + return self->pixel_shader; +} + +void common_hal_vectorio_vector_shape_set_pixel_shader(vectorio_vector_shape_t *self, mp_obj_t pixel_shader) { + VECTORIO_SHAPE_DEBUG("%p set_pixel_shader\n", self); + self->pixel_shader = pixel_shader; + common_hal_vectorio_vector_shape_set_dirty(self); +} + + +bool vectorio_vector_shape_fill_area(vectorio_vector_shape_t *self, const _displayio_colorspace_t* colorspace, const displayio_area_t* area, uint32_t* mask, uint32_t *buffer) { + // Shape areas are relative to 0,0. This will allow rotation about a known axis. + // The consequence is that the area reported by the shape itself is _relative_ to 0,0. + // To make it relative to the VectorShape position, we must shift it. + // Pixels are drawn on the screen_area (shifted) coordinate space, while pixels are _determined_ from + // the shape_area (unshifted) space. + displayio_area_t overlap; + displayio_area_t shape_area; + _get_shape_area(self, &shape_area); + VECTORIO_SHAPE_DEBUG("%p fill_area dirty:%d fill: {(%3d,%3d), (%3d,%3d)} dirty: {(%3d,%3d), (%3d,%3d)}", + self, self->dirty, + area->x1, area->y1, area->x2, area->y2, + self->ephemeral_dirty_area.x1, self->ephemeral_dirty_area.y1, self->ephemeral_dirty_area.x2, self->ephemeral_dirty_area.y2 + ); + if (!displayio_area_compute_overlap(area, &self->ephemeral_dirty_area, &overlap)) { + VECTORIO_SHAPE_DEBUG(" no overlap\n"); + return false; + } + VECTORIO_SHAPE_DEBUG(", overlap: {(%3d,%3d), (%3d,%3d)}", overlap.x1, overlap.y1, overlap.x2, overlap.y2); + + bool full_coverage = displayio_area_equal(area, &overlap); + + uint8_t pixels_per_byte = 8 / colorspace->depth; + + uint32_t linestride_px = displayio_area_width(area); + uint32_t line_dirty_offset_px = (overlap.y1 - area->y1) * linestride_px; + uint32_t column_dirty_offset_px = overlap.x1 - area->x1; + VECTORIO_SHAPE_DEBUG(", linestride:%3d line_offset:%3d col_offset:%3d depth:%2d ppb:%2d\n", linestride_px, line_dirty_offset_px, column_dirty_offset_px, colorspace->depth, pixels_per_byte); + + displayio_input_pixel_t input_pixel; + displayio_output_pixel_t output_pixel; + + uint32_t mask_start_px = line_dirty_offset_px; + for (input_pixel.y = overlap.y1; input_pixel.y < overlap.y2; ++input_pixel.y) { + mask_start_px += column_dirty_offset_px; + for (input_pixel.x = overlap.x1; input_pixel.x < overlap.x2; ++input_pixel.x) { + // Check the mask first to see if the pixel has already been set. + uint32_t pixel_index = mask_start_px + (input_pixel.x - overlap.x1); + uint32_t *mask_doubleword = &(mask[pixel_index / 32]); + uint8_t mask_bit = pixel_index % 32; + VECTORIO_SHAPE_PIXEL_DEBUG("%p pixel_index: %5u mask_bit: %2u", self, pixel_index, mask_bit); + if ((*mask_doubleword & (1u << mask_bit)) != 0) { + VECTORIO_SHAPE_PIXEL_DEBUG(" masked\n"); + continue; + } + output_pixel.pixel = 0; + + // Get the target pixel based on the shape's coordinate space + int16_t pixel_to_get_x; + int16_t pixel_to_get_y; + if (self->transpose_xy) { + pixel_to_get_x = input_pixel.y - self->x; + pixel_to_get_y = input_pixel.x - self->y; + } else { + pixel_to_get_x = input_pixel.x - self->x; + pixel_to_get_y = input_pixel.y - self->y; + } + VECTORIO_SHAPE_PIXEL_DEBUG(" get_pixel %p (%3d, %3d) -> ( %3d, %3d )", self->ishape.shape, input_pixel.x, input_pixel.y, pixel_to_get_x, pixel_to_get_y); + input_pixel.pixel = self->ishape.get_pixel(self->ishape.shape, pixel_to_get_x, pixel_to_get_y); + VECTORIO_SHAPE_PIXEL_DEBUG(" -> %d", input_pixel.pixel); + + output_pixel.opaque = true; + if (self->pixel_shader == mp_const_none) { + output_pixel.pixel = input_pixel.pixel; + } else if (MP_OBJ_IS_TYPE(self->pixel_shader, &displayio_palette_type)) { + output_pixel.opaque = displayio_palette_get_color(self->pixel_shader, colorspace, input_pixel.pixel, &output_pixel.pixel); + } else if (MP_OBJ_IS_TYPE(self->pixel_shader, &displayio_colorconverter_type)) { + displayio_colorconverter_convert(self->pixel_shader, colorspace, &input_pixel, &output_pixel); + } + if (!output_pixel.opaque) { + VECTORIO_SHAPE_PIXEL_DEBUG(" (encountered transparent pixel; input area is not fully covered)\n"); + full_coverage = false; + } else { + *mask_doubleword |= 1u << mask_bit; + if (colorspace->depth == 16) { + VECTORIO_SHAPE_PIXEL_DEBUG(" buffer = %04x 16\n", output_pixel.pixel); + *(((uint16_t*) buffer) + pixel_index) = output_pixel.pixel; + } else if (colorspace->depth == 8) { + VECTORIO_SHAPE_PIXEL_DEBUG(" buffer = %02x 8\n", output_pixel.pixel); + *(((uint8_t*) buffer) + pixel_index) = output_pixel.pixel; + } else if (colorspace->depth < 8) { + // Reorder the offsets to pack multiple rows into a byte (meaning they share a column). + if (!colorspace->pixels_in_byte_share_row) { + uint16_t width = linestride_px; + uint16_t row = pixel_index / width; + uint16_t col = pixel_index % width; + pixel_index = col * pixels_per_byte + (row / pixels_per_byte) * pixels_per_byte * width + row % pixels_per_byte; + } + uint8_t shift = (pixel_index % pixels_per_byte) * colorspace->depth; + if (colorspace->reverse_pixels_in_byte) { + // Reverse the shift by subtracting it from the leftmost shift. + shift = (pixels_per_byte - 1) * colorspace->depth - shift; + } + VECTORIO_SHAPE_PIXEL_DEBUG(" buffer = %2d %d\n", output_pixel.pixel, colorspace->depth); + ((uint8_t*)buffer)[pixel_index / pixels_per_byte] |= output_pixel.pixel << shift; + } + } + } + mask_start_px += linestride_px - column_dirty_offset_px; + } + return full_coverage; +} + + +void vectorio_vector_shape_finish_refresh(vectorio_vector_shape_t *self) { + if ( !self->dirty ) { + return; + } + VECTORIO_SHAPE_DEBUG("%p finish_refresh was:{(%3d,%3d), (%3d,%3d)}\n", self, self->ephemeral_dirty_area.x1, self->ephemeral_dirty_area.y1, self->ephemeral_dirty_area.x2, self->ephemeral_dirty_area.y2); + self->dirty = false; + // Reset dirty area tracking to current footprint + _get_screen_area(self, &self->ephemeral_dirty_area); + self->ephemeral_dirty_area.next = NULL; + VECTORIO_SHAPE_DEBUG("%p finish_refresh now:{(%3d,%3d), (%3d,%3d)}\n", self, self->ephemeral_dirty_area.x1, self->ephemeral_dirty_area.y1, self->ephemeral_dirty_area.x2, self->ephemeral_dirty_area.y2); + + if (MP_OBJ_IS_TYPE(self->pixel_shader, &displayio_palette_type)) { + displayio_palette_finish_refresh(self->pixel_shader); + } else if (MP_OBJ_IS_TYPE(self->pixel_shader, &displayio_colorconverter_type)) { + displayio_colorconverter_finish_refresh(self->pixel_shader); + } +} + + +// Assembles a singly linked list of dirty areas from all components on the display. +displayio_area_t* vectorio_vector_shape_get_refresh_areas(vectorio_vector_shape_t *self, displayio_area_t* tail) { + if (self->dirty + || (MP_OBJ_IS_TYPE(self->pixel_shader, &displayio_palette_type) && displayio_palette_needs_refresh(self->pixel_shader)) + || (MP_OBJ_IS_TYPE(self->pixel_shader, &displayio_colorconverter_type) && displayio_colorconverter_needs_refresh(self->pixel_shader)) + ) { + VECTORIO_SHAPE_DEBUG("%p get_refresh_area dirty:%d {(%3d,%3d), (%3d,%3d)}", self, self->dirty, self->ephemeral_dirty_area.x1, self->ephemeral_dirty_area.y1, self->ephemeral_dirty_area.x2, self->ephemeral_dirty_area.y2); + common_hal_vectorio_vector_shape_set_dirty(self); + // vector.add_to_head + self->ephemeral_dirty_area.next = tail; + VECTORIO_SHAPE_DEBUG(" this_area: %p next: %p after: %p\n", &self->ephemeral_dirty_area, tail, tail == NULL ? NULL : tail->next); + return &self->ephemeral_dirty_area; + } + return tail; +} + diff --git a/shared-module/vectorio/VectorShape.h b/shared-module/vectorio/VectorShape.h new file mode 100644 index 000000000..ac60e5b98 --- /dev/null +++ b/shared-module/vectorio/VectorShape.h @@ -0,0 +1,51 @@ + +#ifndef MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_SHAPE_H +#define MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_SHAPE_H + +#include +#include + +#include "py/obj.h" +#include "shared-module/displayio/area.h" +#include "shared-module/displayio/Palette.h" + +typedef void get_area_function(mp_obj_t shape, displayio_area_t *out_area); +typedef uint32_t get_pixel_function(mp_obj_t shape, int16_t x, int16_t y); + +// This struct binds a shape's common Shape support functions (its vector shape interface) +// to its instance pointer. We only check at construction time what the type of the +// associated shape is and link the correct functions up. +// Later when using the shape for drawing logic these functions may be invoked +// unconditionally. This simplifies the addition of new types and restricts the +// respective responsibilities of VectorShape and actual shape implementations. +typedef struct { + mp_obj_t shape; + get_area_function *get_area; + get_pixel_function *get_pixel; +} vectorio_ishape_t; + +typedef struct { + mp_obj_base_t base; + vectorio_ishape_t ishape; + mp_obj_t pixel_shader; + int16_t x; + int16_t y; + bool transpose_xy; + bool dirty; // True if we need to draw + // Tracks current shape footprint and expands outward as the shape dirties and changes. + // This is suboptimal if you move your shape far. Could add more state to only redraw + // exactly what we left behind. + displayio_area_t ephemeral_dirty_area; +} vectorio_vector_shape_t; + +displayio_area_t* vectorio_vector_shape_get_refresh_areas(vectorio_vector_shape_t *self, displayio_area_t* tail); + +// Area is always in absolute screen coordinates. +bool vectorio_vector_shape_fill_area(vectorio_vector_shape_t *self, const _displayio_colorspace_t *colorspace, const displayio_area_t *area, uint32_t *mask, uint32_t *buffer); + +// Fills in out_area with the maximum bounds of all related pixels in the last rendered frame. Returns +// false if the vector shape wasn't rendered in the last frame. +bool vectorio_vector_shape_get_previous_area(vectorio_vector_shape_t *self, displayio_area_t *out_area); +void vectorio_vector_shape_finish_refresh(vectorio_vector_shape_t *self); + +#endif // MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_SHAPE_H diff --git a/shared-module/vectorio/__init__.c b/shared-module/vectorio/__init__.c new file mode 100644 index 000000000..473c509c3 --- /dev/null +++ b/shared-module/vectorio/__init__.c @@ -0,0 +1,3 @@ + +// Don't need anything in here yet + diff --git a/shared-module/vectorio/__init__.h b/shared-module/vectorio/__init__.h new file mode 100644 index 000000000..6ae381f06 --- /dev/null +++ b/shared-module/vectorio/__init__.h @@ -0,0 +1,15 @@ +#ifndef MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_INIT_H +#define MICROPY_INCLUDED_SHARED_MODULE_VECTORIO_INIT_H + +#include "py/obj.h" + +typedef void event_function(mp_obj_t obj); + +typedef struct { + mp_obj_t obj; + event_function *event; +} vectorio_event_t; + + +#endif + -- cgit v1.2.3 From 4086600b61f14e043f02c1b8771e7780b82f313c Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Fri, 8 May 2020 23:03:15 -0700 Subject: vectorio: switch per-shape transform to Display Rather than maintain a transform per-shape, we'll just use whatever settings are on the Display. Currently only transpose is done. --- shared-bindings/vectorio/VectorShape.c | 22 ++-------------------- shared-bindings/vectorio/VectorShape.h | 8 +++++--- shared-module/displayio/Group.c | 6 ++++++ shared-module/vectorio/VectorShape.c | 34 ++++++++++++++++++++++++---------- shared-module/vectorio/VectorShape.h | 2 +- 5 files changed, 38 insertions(+), 34 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/vectorio/VectorShape.c b/shared-bindings/vectorio/VectorShape.c index 8f99577b4..02a42536d 100644 --- a/shared-bindings/vectorio/VectorShape.c +++ b/shared-bindings/vectorio/VectorShape.c @@ -32,13 +32,12 @@ //| :param int y: Initial y position of the center axis of the shape within the parent. //| STATIC mp_obj_t vectorio_vector_shape_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { - enum { ARG_shape, ARG_pixel_shader, ARG_x, ARG_y, ARG_transpose_xy }; + enum { ARG_shape, ARG_pixel_shader, ARG_x, ARG_y }; static const mp_arg_t allowed_args[] = { { MP_QSTR_shape, MP_ARG_OBJ | MP_ARG_KW_ONLY | MP_ARG_REQUIRED }, { MP_QSTR_pixel_shader, MP_ARG_OBJ | MP_ARG_KW_ONLY | MP_ARG_REQUIRED }, { MP_QSTR_x, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} }, { MP_QSTR_y, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} }, - { MP_QSTR_transpose_xy, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} }, }; mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); @@ -74,7 +73,7 @@ STATIC mp_obj_t vectorio_vector_shape_make_new(const mp_obj_type_t *type, size_t vectorio_vector_shape_t *self = m_new_obj(vectorio_vector_shape_t); self->base.type = &vectorio_vector_shape_type; common_hal_vectorio_vector_shape_construct(self, - ishape, pixel_shader, x, y, args[ARG_transpose_xy].u_bool + ishape, pixel_shader, x, y ); // Wire up event callbacks @@ -150,23 +149,6 @@ const mp_obj_property_t vectorio_vector_shape_y_obj = { }; -//| .. attribute:: transpose_xy -//| -//| true if the object is to be flipped. -//| -STATIC mp_obj_t vectorio_vector_shape_obj_get_transpose_xy(mp_obj_t self_in) { - vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); - return mp_obj_new_bool(common_hal_vectorio_vector_shape_get_transpose_xy(self)); -} -MP_DEFINE_CONST_FUN_OBJ_1(vectorio_vector_shape_get_transpose_xy_obj, vectorio_vector_shape_obj_get_transpose_xy); - -const mp_obj_property_t vectorio_vector_shape_transpose_xy_obj = { - .base.type = &mp_type_property, - .proxy = {(mp_obj_t)&vectorio_vector_shape_get_transpose_xy_obj, - (mp_obj_t)&mp_const_none_obj, - (mp_obj_t)&mp_const_none_obj}, -}; - //| .. attribute:: pixel_shader //| //| The pixel shader of the shape. diff --git a/shared-bindings/vectorio/VectorShape.h b/shared-bindings/vectorio/VectorShape.h index ad745b30f..d098504e9 100644 --- a/shared-bindings/vectorio/VectorShape.h +++ b/shared-bindings/vectorio/VectorShape.h @@ -2,12 +2,13 @@ #define MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_SHAPE_H #include "shared-module/vectorio/VectorShape.h" +#include "shared-module/displayio/area.h" extern const mp_obj_type_t vectorio_vector_shape_type; void common_hal_vectorio_vector_shape_construct(vectorio_vector_shape_t *self, vectorio_ishape_t ishape, - mp_obj_t pixel_shader, uint16_t x, uint16_t y, bool transpose_xy); + mp_obj_t pixel_shader, uint16_t x, uint16_t y); void common_hal_vectorio_vector_shape_set_dirty(void *self); @@ -17,9 +18,10 @@ void common_hal_vectorio_vector_shape_set_x(vectorio_vector_shape_t *self, mp_in mp_int_t common_hal_vectorio_vector_shape_get_y(vectorio_vector_shape_t *self); void common_hal_vectorio_vector_shape_set_y(vectorio_vector_shape_t *self, mp_int_t y); -bool common_hal_vectorio_vector_shape_get_transpose_xy(vectorio_vector_shape_t *self); - mp_obj_t common_hal_vectorio_vector_shape_get_pixel_shader(vectorio_vector_shape_t *self); void common_hal_vectorio_vector_shape_set_pixel_shader(vectorio_vector_shape_t *self, mp_obj_t pixel_shader); + +void vectorio_vector_shape_update_transform(vectorio_vector_shape_t *self, displayio_buffer_transform_t *group_transform); + #endif // MICROPY_INCLUDED_SHARED_BINDINGS_VECTORIO_SHAPE_H diff --git a/shared-module/displayio/Group.c b/shared-module/displayio/Group.c index 9d50dabec..0c31de532 100644 --- a/shared-module/displayio/Group.c +++ b/shared-module/displayio/Group.c @@ -122,6 +122,12 @@ static void _update_child_transforms(displayio_group_t* self) { } for (size_t i = 0; i < self->size; i++) { mp_obj_t layer = self->children[i].native; +#if CIRCUITPY_VECTORIO + if (MP_OBJ_IS_TYPE(layer, &vectorio_vector_shape_type)) { + vectorio_vector_shape_update_transform(layer, &self->absolute_transform); + } + else +#endif if (MP_OBJ_IS_TYPE(layer, &displayio_tilegrid_type)) { displayio_tilegrid_update_transform(layer, &self->absolute_transform); } else if (MP_OBJ_IS_TYPE(layer, &displayio_group_type)) { diff --git a/shared-module/vectorio/VectorShape.c b/shared-module/vectorio/VectorShape.c index 985b77858..6030c1e3d 100644 --- a/shared-module/vectorio/VectorShape.c +++ b/shared-module/vectorio/VectorShape.c @@ -50,7 +50,7 @@ inline __attribute__((always_inline)) static void _get_screen_area(vectorio_vector_shape_t *self, displayio_area_t *out_area) { VECTORIO_SHAPE_DEBUG("%p get_screen_area\n", self); self->ishape.get_area(self->ishape.shape, out_area); - if (self->transpose_xy) { + if (self->absolute_transform->transpose_xy) { _transpose_area(out_area); displayio_area_shift(out_area, self->y, self->x); } else { @@ -76,18 +76,32 @@ void common_hal_vectorio_vector_shape_set_dirty(void *vector_shape) { } +static displayio_buffer_transform_t null_transform = { + .x = 0, + .y = 0, + .dx = 0, + .dy = 0, + .scale = 1, + .width = 0, + .height = 0, + .mirror_x = false, + .mirror_y = false, + .transpose_xy = false +}; + + void common_hal_vectorio_vector_shape_construct(vectorio_vector_shape_t *self, vectorio_ishape_t ishape, - mp_obj_t pixel_shader, uint16_t x, uint16_t y, bool transpose_xy) { + mp_obj_t pixel_shader, uint16_t x, uint16_t y) { VECTORIO_SHAPE_DEBUG("%p vector_shape_construct x:%3d, y:%3d\n", self, x, y); self->x = x; self->y = y; self->pixel_shader = pixel_shader; self->ishape = ishape; - self->transpose_xy = transpose_xy; self->dirty = true; _get_screen_area(self, &self->ephemeral_dirty_area); self->ephemeral_dirty_area.next = NULL; + self->absolute_transform = &null_transform; } @@ -123,12 +137,6 @@ void common_hal_vectorio_vector_shape_set_y(vectorio_vector_shape_t *self, mp_in } -bool common_hal_vectorio_vector_shape_get_transpose_xy(vectorio_vector_shape_t *self) { - VECTORIO_SHAPE_DEBUG("%p get_transpose_xy\n", self); - return self->transpose_xy; -} - - mp_obj_t common_hal_vectorio_vector_shape_get_pixel_shader(vectorio_vector_shape_t *self) { VECTORIO_SHAPE_DEBUG("%p get_pixel_shader\n", self); return self->pixel_shader; @@ -191,7 +199,7 @@ bool vectorio_vector_shape_fill_area(vectorio_vector_shape_t *self, const _displ // Get the target pixel based on the shape's coordinate space int16_t pixel_to_get_x; int16_t pixel_to_get_y; - if (self->transpose_xy) { + if (self->absolute_transform->transpose_xy) { pixel_to_get_x = input_pixel.y - self->x; pixel_to_get_y = input_pixel.x - self->y; } else { @@ -280,3 +288,9 @@ displayio_area_t* vectorio_vector_shape_get_refresh_areas(vectorio_vector_shape_ return tail; } +void vectorio_vector_shape_update_transform(vectorio_vector_shape_t *self, displayio_buffer_transform_t *group_transform) { + self->absolute_transform = group_transform; + common_hal_vectorio_vector_shape_set_dirty(self); +} + + diff --git a/shared-module/vectorio/VectorShape.h b/shared-module/vectorio/VectorShape.h index ac60e5b98..8fc698dbc 100644 --- a/shared-module/vectorio/VectorShape.h +++ b/shared-module/vectorio/VectorShape.h @@ -30,7 +30,7 @@ typedef struct { mp_obj_t pixel_shader; int16_t x; int16_t y; - bool transpose_xy; + displayio_buffer_transform_t *absolute_transform; bool dirty; // True if we need to draw // Tracks current shape footprint and expands outward as the shape dirties and changes. // This is suboptimal if you move your shape far. Could add more state to only redraw -- cgit v1.2.3 From 2f7c0ec8e4497c95bb7f5f5ee630c3748acdf9a9 Mon Sep 17 00:00:00 2001 From: Roy Hooper Date: Sun, 10 May 2020 16:22:01 -0400 Subject: Minor fixes to _pixelbuf.PixelBuf docs --- shared-bindings/_pixelbuf/PixelBuf.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 61b4c9ae0..78f94b66b 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -44,7 +44,7 @@ extern const int32_t colorwheel(float pos); static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t* parsed); -//| .. currentmodule:: pixelbuf +//| .. currentmodule:: _pixelbuf //| //| :class:`PixelBuf` -- A fast RGB[W] pixel buffer for LED and similar devices //| =========================================================================== @@ -64,7 +64,7 @@ static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t //| output buffer (``buf``). //| //| :param ~int size: Number of pixelsx -//| :param ~str byteorder: Byte order string (such as "BGR" or "PBGR") +//| :param ~str byteorder: Byte order string (such as "BGR" or "BGRP") //| :param ~float brightness: Brightness (0 to 1.0, default 1.0) //| :param ~bool auto_write: Whether to automatically write pixels (Default False) //| :param bytes header: Sequence of bytes to always send before pixel values. -- cgit v1.2.3 From 70f2ef3f8ef3707744741549bf7f094fd60f8435 Mon Sep 17 00:00:00 2001 From: Roy Hooper Date: Sun, 10 May 2020 19:50:10 -0400 Subject: Fix docs some more --- shared-bindings/_pixelbuf/PixelBuf.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 78f94b66b..3414b5d62 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -58,7 +58,7 @@ static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t //| When brightness is less than 1.0, a second buffer will be used to store the color values //| before they are adjusted for brightness. //| -//| When ``P`` (pwm duration) is present as the 4th character of the byteorder +//| When ``P`` (pwm duration) is present as the first character of the byteorder //| string, the 4th value in the tuple/list for a pixel is the individual pixel //| brightness (0.0-1.0) and will enable a Dotstar compatible 1st byte in the //| output buffer (``buf``). @@ -265,7 +265,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_show(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(pixelbuf_pixelbuf_show_obj, pixelbuf_pixelbuf_show); -//| .. function:: fill(color) +//| .. method:: fill(color) //| //| Fills the given pixelbuf with the given color. //| -- cgit v1.2.3 From 09fedb3fd5d0dd5852d7aa54ac9826c9a0b287b0 Mon Sep 17 00:00:00 2001 From: Roy Hooper Date: Sun, 10 May 2020 21:35:37 -0400 Subject: fix another doc error (pixelsx - thanks @theacodes) --- shared-bindings/_pixelbuf/PixelBuf.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 3414b5d62..626dde680 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -63,7 +63,7 @@ static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t //| brightness (0.0-1.0) and will enable a Dotstar compatible 1st byte in the //| output buffer (``buf``). //| -//| :param ~int size: Number of pixelsx +//| :param ~int size: Number of pixels //| :param ~str byteorder: Byte order string (such as "BGR" or "BGRP") //| :param ~float brightness: Brightness (0 to 1.0, default 1.0) //| :param ~bool auto_write: Whether to automatically write pixels (Default False) -- cgit v1.2.3 From eb3d5fa453bd04cc116e704c36a97250c93b7b4b Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Sun, 10 May 2020 20:45:42 -0700 Subject: ujson: do not eat trailing whitespace Ujson should only worry about whitespace before JSON. This becomes apparent when you are using MP stream protocol to read directly from input buffers. When you attempt to read(1) on a UART (and possibly other protocols) you have to wait for either the byte or the timeout. Fixes: - Waiting for a timeout after you have completed reading a correct and complete JSON off the input. - Raising an OSError after reading a correct and complete JSON off the input. - Eating more data than semantically owned off the input buffer. - Blocking to start parsing JSON until the entire JSON body has been loaded into a potentially large, contiguous Python object. Code you would write before: ``` line = board_busio_uart_port.read_line() json_dict = json.loads(line) ``` or reaching for fixed buffers and swapping them around in Python. Code that did not work before that does now: ``` json_dict = json.load(board_busio_uart_port) ``` - This removes the need for intermediate copies of data when reading JSON from micropython stream protocol inputs. - It also increases total application speed by parsing JSON concurrently with receiving on boards that read from UART via DMA. - It simplifies code that users write while improving their apps. --- extmod/modujson.c | 26 ++++++++++++++++++-------- ports/atmel-samd/common-hal/busio/UART.c | 3 +++ shared-bindings/busio/UART.c | 4 ++++ 3 files changed, 25 insertions(+), 8 deletions(-) (limited to 'shared-bindings') diff --git a/extmod/modujson.c b/extmod/modujson.c index 6b24bf578..daefe18ba 100644 --- a/extmod/modujson.c +++ b/extmod/modujson.c @@ -53,6 +53,10 @@ STATIC mp_obj_t mod_ujson_dumps(mp_obj_t obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mod_ujson_dumps_obj, mod_ujson_dumps); +#define JSON_DEBUG(...) (void)0 +// #define JSON_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + + // The function below implements a simple non-recursive JSON parser. // // The JSON specification is at http://www.ietf.org/rfc/rfc4627.txt @@ -80,6 +84,7 @@ typedef struct _ujson_stream_t { STATIC byte ujson_stream_next(ujson_stream_t *s) { mp_uint_t ret = s->read(s->stream_obj, &s->cur, 1, &s->errcode); + JSON_DEBUG(" usjon_stream_next err:%2d cur: %c \n", s->errcode, s->cur); if (s->errcode != 0) { mp_raise_OSError(s->errcode); } @@ -92,6 +97,7 @@ STATIC byte ujson_stream_next(ujson_stream_t *s) { STATIC mp_obj_t mod_ujson_load(mp_obj_t stream_obj) { const mp_stream_p_t *stream_p = mp_get_stream_raise(stream_obj, MP_STREAM_OP_READ); ujson_stream_t s = {stream_obj, stream_p->read, 0, 0}; + JSON_DEBUG("got JSON stream\n"); vstr_t vstr; vstr_init(&vstr, 8); mp_obj_list_t stack; // we use a list as a simple stack for nested JSON @@ -101,6 +107,15 @@ STATIC mp_obj_t mod_ujson_load(mp_obj_t stream_obj) { mp_obj_type_t *stack_top_type = NULL; mp_obj_t stack_key = MP_OBJ_NULL; S_NEXT(s); + // Eat _leading_ whitespace. + // If we eat trailing whitespace we will block for timeout on streams like UART that + // wait for requested data. Furthermore, it is an OSError to read(1) and incur + // a timeout on those APIs. + // For these reasons, we must only eat _leading_ whitespace. + while (unichar_isspace(S_CUR(s))) { + JSON_DEBUG("Eating leading whitespace"); + S_NEXT(s); + } for (;;) { cont: if (S_END(s)) { @@ -262,14 +277,9 @@ STATIC mp_obj_t mod_ujson_load(mp_obj_t stream_obj) { } } success: - // eat trailing whitespace - while (unichar_isspace(S_CUR(s))) { - S_NEXT(s); - } - if (!S_END(s)) { - // unexpected chars - goto fail; - } + // It is legal for a stream to have contents before and after JSON. + // If this parser has consumed a full successful JSON and its parse + // stack is empty, the parse has succeeded. if (stack_top == MP_OBJ_NULL || stack.len != 0) { // not exactly 1 object goto fail; diff --git a/ports/atmel-samd/common-hal/busio/UART.c b/ports/atmel-samd/common-hal/busio/UART.c index 1f6b75f97..d6c13eb7e 100644 --- a/ports/atmel-samd/common-hal/busio/UART.c +++ b/ports/atmel-samd/common-hal/busio/UART.c @@ -45,6 +45,9 @@ #include "samd/sercom.h" +#define UART_DEBUG(...) (void)0 +// #define UART_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + // Do-nothing callback needed so that usart_async code will enable rx interrupts. // See comment below re usart_async_register_callback() static void usart_async_rxc_callback(const struct usart_async_descriptor *const descr) { diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index f231924d5..883b4630f 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -39,6 +39,9 @@ #include "py/stream.h" #include "supervisor/shared/translate.h" +#define STREAM_DEBUG(...) (void)0 +// #define STREAM_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) + //| .. currentmodule:: busio //| @@ -219,6 +222,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(busio_uart___exit___obj, 4, 4, busio_ // These three methods are used by the shared stream methods. STATIC mp_uint_t busio_uart_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) { + STREAM_DEBUG("busio_uart_read stream %d\n", size); busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); byte *buf = buf_in; -- cgit v1.2.3 From 838b6c56858fa3888c558e5640031b8764c313d7 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 11 May 2020 10:48:11 -0400 Subject: Did ps2io, pulseio, random --- shared-bindings/ps2io/Ps2.c | 135 ++++++++++++++++--------------- shared-bindings/ps2io/__init__.c | 4 +- shared-bindings/pulseio/PWMOut.c | 114 +++++++++++++------------- shared-bindings/pulseio/PulseIn.c | 161 ++++++++++++++++++------------------- shared-bindings/pulseio/PulseOut.c | 83 +++++++++---------- shared-bindings/pulseio/__init__.c | 4 +- shared-bindings/random/__init__.c | 55 +++++++------ 7 files changed, 278 insertions(+), 278 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/ps2io/Ps2.c b/shared-bindings/ps2io/Ps2.c index 89ed0a76c..d327d4180 100644 --- a/shared-bindings/ps2io/Ps2.c +++ b/shared-bindings/ps2io/Ps2.c @@ -36,38 +36,39 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: ps2io +//| class Ps2: +//| """.. currentmodule:: ps2io //| -//| :class:`Ps2` -- Communicate with a PS/2 keyboard or mouse -//| ========================================================= +//| :class:`Ps2` -- Communicate with a PS/2 keyboard or mouse +//| ========================================================= //| -//| Ps2 implements the PS/2 keyboard/mouse serial protocol, used in -//| legacy devices. It is similar to UART but there are only two -//| lines (Data and Clock). PS/2 devices are 5V, so bidirectional -//| level converters must be used to connect the I/O lines to pins -//| of 3.3V boards. +//| Ps2 implements the PS/2 keyboard/mouse serial protocol, used in +//| legacy devices. It is similar to UART but there are only two +//| lines (Data and Clock). PS/2 devices are 5V, so bidirectional +//| level converters must be used to connect the I/O lines to pins +//| of 3.3V boards.""" //| -//| .. class:: Ps2(data_pin, clock_pin) +//| def __init__(self, data_pin: microcontroller.Pin, clock_pin: microcontroller.Pin): +//| """Create a Ps2 object associated with the given pins. //| -//| Create a Ps2 object associated with the given pins. +//| :param ~microcontroller.Pin data_pin: Pin tied to data wire. +//| :param ~microcontroller.Pin clock_pin: Pin tied to clock wire. +//| This pin must support interrupts. //| -//| :param ~microcontroller.Pin data_pin: Pin tied to data wire. -//| :param ~microcontroller.Pin clock_pin: Pin tied to clock wire. -//| This pin must support interrupts. +//| Read one byte from PS/2 keyboard and turn on Scroll Lock LED:: //| -//| Read one byte from PS/2 keyboard and turn on Scroll Lock LED:: +//| import ps2io +//| import board //| -//| import ps2io -//| import board +//| kbd = ps2io.Ps2(board.D10, board.D11) //| -//| kbd = ps2io.Ps2(board.D10, board.D11) +//| while len(kbd) == 0: +//| pass //| -//| while len(kbd) == 0: -//| pass -//| -//| print(kbd.popleft()) -//| print(kbd.sendcmd(0xed)) -//| print(kbd.sendcmd(0x01)) +//| print(kbd.popleft()) +//| print(kbd.sendcmd(0xed)) +//| print(kbd.sendcmd(0x01))""" +//| ... //| STATIC mp_obj_t ps2io_ps2_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_datapin, ARG_clkpin }; @@ -89,9 +90,9 @@ STATIC mp_obj_t ps2io_ps2_make_new(const mp_obj_type_t *type, size_t n_args, con return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the Ps2 and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the Ps2 and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t ps2io_ps2_deinit(mp_obj_t self_in) { ps2io_ps2_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -106,16 +107,16 @@ STATIC void check_for_deinit(ps2io_ps2_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t ps2io_ps2_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -124,10 +125,10 @@ STATIC mp_obj_t ps2io_ps2_obj___exit__(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(ps2io_ps2___exit___obj, 4, 4, ps2io_ps2_obj___exit__); -//| .. method:: popleft() -//| -//| Removes and returns the oldest received byte. When buffer -//| is empty, raises an IndexError exception. +//| def popleft(self, ) -> Any: +//| """Removes and returns the oldest received byte. When buffer +//| is empty, raises an IndexError exception.""" +//| ... //| STATIC mp_obj_t ps2io_ps2_obj_popleft(mp_obj_t self_in) { ps2io_ps2_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -141,18 +142,18 @@ STATIC mp_obj_t ps2io_ps2_obj_popleft(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(ps2io_ps2_popleft_obj, ps2io_ps2_obj_popleft); -//| .. method:: sendcmd(byte) -//| -//| Sends a command byte to PS/2. Returns the response byte, typically -//| the general ack value (0xFA). Some commands return additional data -//| which is available through :py:func:`popleft()`. +//| def sendcmd(self, byte: int) -> Any: +//| """Sends a command byte to PS/2. Returns the response byte, typically +//| the general ack value (0xFA). Some commands return additional data +//| which is available through :py:func:`popleft()`. //| -//| Raises a RuntimeError in case of failure. The root cause can be found -//| by calling :py:func:`clear_errors()`. It is advisable to call -//| :py:func:`clear_errors()` before :py:func:`sendcmd()` to flush any -//| previous errors. +//| Raises a RuntimeError in case of failure. The root cause can be found +//| by calling :py:func:`clear_errors()`. It is advisable to call +//| :py:func:`clear_errors()` before :py:func:`sendcmd()` to flush any +//| previous errors. //| -//| :param int byte: byte value of the command +//| :param int byte: byte value of the command""" +//| ... //| STATIC mp_obj_t ps2io_ps2_obj_sendcmd(mp_obj_t self_in, mp_obj_t ob) { ps2io_ps2_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -166,35 +167,35 @@ STATIC mp_obj_t ps2io_ps2_obj_sendcmd(mp_obj_t self_in, mp_obj_t ob) { } MP_DEFINE_CONST_FUN_OBJ_2(ps2io_ps2_sendcmd_obj, ps2io_ps2_obj_sendcmd); -//| .. method:: clear_errors() +//| def clear_errors(self, ) -> Any: +//| """Returns and clears a bitmap with latest recorded communication errors. //| -//| Returns and clears a bitmap with latest recorded communication errors. +//| Reception errors (arise asynchronously, as data is received): //| -//| Reception errors (arise asynchronously, as data is received): +//| 0x01: start bit not 0 //| -//| 0x01: start bit not 0 +//| 0x02: timeout //| -//| 0x02: timeout +//| 0x04: parity bit error //| -//| 0x04: parity bit error +//| 0x08: stop bit not 1 //| -//| 0x08: stop bit not 1 +//| 0x10: buffer overflow, newest data discarded //| -//| 0x10: buffer overflow, newest data discarded +//| Transmission errors (can only arise in the course of sendcmd()): //| -//| Transmission errors (can only arise in the course of sendcmd()): +//| 0x100: clock pin didn't go to LO in time //| -//| 0x100: clock pin didn't go to LO in time +//| 0x200: clock pin didn't go to HI in time //| -//| 0x200: clock pin didn't go to HI in time +//| 0x400: data pin didn't ACK //| -//| 0x400: data pin didn't ACK +//| 0x800: clock pin didn't ACK //| -//| 0x800: clock pin didn't ACK +//| 0x1000: device didn't respond to RTS //| -//| 0x1000: device didn't respond to RTS -//| -//| 0x2000: device didn't send a response byte in time +//| 0x2000: device didn't send a response byte in time""" +//| ... //| STATIC mp_obj_t ps2io_ps2_obj_clear_errors(mp_obj_t self_in) { ps2io_ps2_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -204,10 +205,10 @@ STATIC mp_obj_t ps2io_ps2_obj_clear_errors(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(ps2io_ps2_clear_errors_obj, ps2io_ps2_obj_clear_errors); -//| .. method:: __len__() -//| -//| Returns the number of received bytes in buffer, available -//| to :py:func:`popleft()`. +//| def __len__(self, ) -> Any: +//| """Returns the number of received bytes in buffer, available +//| to :py:func:`popleft()`.""" +//| ... //| STATIC mp_obj_t ps2_unary_op(mp_unary_op_t op, mp_obj_t self_in) { ps2io_ps2_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/ps2io/__init__.c b/shared-bindings/ps2io/__init__.c index ec7c43e51..081127bac 100644 --- a/shared-bindings/ps2io/__init__.c +++ b/shared-bindings/ps2io/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/ps2io/Ps2.h" -//| :mod:`ps2io` --- Support for PS/2 protocol +//| """:mod:`ps2io` --- Support for PS/2 protocol //| ===================================================== //| //| .. module:: ps2io @@ -57,7 +57,7 @@ //| 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. +//| :ref:`lifetime-and-contextmanagers` for more info.""" //| STATIC const mp_rom_map_elem_t ps2io_module_globals_table[] = { diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c index 2491a5c3f..3a25d6938 100644 --- a/shared-bindings/pulseio/PWMOut.c +++ b/shared-bindings/pulseio/PWMOut.c @@ -35,55 +35,56 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: pulseio +//| class PWMOut: +//| """.. currentmodule:: pulseio //| -//| :class:`PWMOut` -- Output a Pulse Width Modulated signal -//| ======================================================== +//| :class:`PWMOut` -- Output a Pulse Width Modulated signal +//| ======================================================== //| -//| PWMOut can be used to output a PWM signal on a given pin. +//| PWMOut can be used to output a PWM signal on a given pin.""" //| -//| .. class:: PWMOut(pin, *, duty_cycle=0, frequency=500, variable_frequency=False) +//| def __init__(self, pin: microcontroller.Pin, *, duty_cycle: int = 0, frequency: int = 500, variable_frequency: bool = False): +//| """Create a PWM object associated with the given pin. This allows you to +//| write PWM signals out on the given pin. Frequency is fixed after init +//| unless ``variable_frequency`` is True. //| -//| Create a PWM object associated with the given pin. This allows you to -//| write PWM signals out on the given pin. Frequency is fixed after init -//| unless ``variable_frequency`` is True. +//| .. note:: When ``variable_frequency`` is True, further PWM outputs may be +//| limited because it may take more internal resources to be flexible. So, +//| when outputting both fixed and flexible frequency signals construct the +//| fixed outputs first. //| -//| .. note:: When ``variable_frequency`` is True, further PWM outputs may be -//| limited because it may take more internal resources to be flexible. So, -//| when outputting both fixed and flexible frequency signals construct the -//| fixed outputs first. +//| :param ~microcontroller.Pin pin: The pin to output to +//| :param int duty_cycle: The fraction of each pulse which is high. 16-bit +//| :param int frequency: The target frequency in Hertz (32-bit) +//| :param bool variable_frequency: True if the frequency will change over time //| -//| :param ~microcontroller.Pin pin: The pin to output to -//| :param int duty_cycle: The fraction of each pulse which is high. 16-bit -//| :param int frequency: The target frequency in Hertz (32-bit) -//| :param bool variable_frequency: True if the frequency will change over time +//| Simple LED fade:: //| -//| Simple LED fade:: +//| import pulseio +//| import board //| -//| import pulseio -//| import board +//| pwm = pulseio.PWMOut(board.D13) # output on D13 +//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz //| -//| pwm = pulseio.PWMOut(board.D13) # output on D13 -//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz +//| PWM at specific frequency (servos and motors):: //| -//| PWM at specific frequency (servos and motors):: +//| import pulseio +//| import board //| -//| import pulseio -//| import board +//| pwm = pulseio.PWMOut(board.D13, frequency=50) +//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz //| -//| pwm = pulseio.PWMOut(board.D13, frequency=50) -//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz +//| Variable frequency (usually tones):: //| -//| Variable frequency (usually tones):: +//| import pulseio +//| import board +//| import time //| -//| import pulseio -//| import board -//| import time -//| -//| pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True) -//| time.sleep(0.2) -//| pwm.frequency = 880 -//| time.sleep(0.1) +//| pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True) +//| time.sleep(0.2) +//| pwm.frequency = 880 +//| time.sleep(0.1)""" +//| ... //| STATIC mp_obj_t pulseio_pwmout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { enum { ARG_pin, ARG_duty_cycle, ARG_frequency, ARG_variable_frequency }; @@ -119,9 +120,9 @@ STATIC mp_obj_t pulseio_pwmout_make_new(const mp_obj_type_t *type, size_t n_args return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the PWMOut and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the PWMOut and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t pulseio_pwmout_deinit(mp_obj_t self_in) { pulseio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -136,16 +137,16 @@ STATIC void check_for_deinit(pulseio_pwmout_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t pulseio_pwmout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -154,16 +155,16 @@ STATIC mp_obj_t pulseio_pwmout_obj___exit__(size_t n_args, const mp_obj_t *args) } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pulseio_pwmout___exit___obj, 4, 4, pulseio_pwmout_obj___exit__); -//| .. attribute:: duty_cycle +//| duty_cycle: Any = ... +//| """16 bit value that dictates how much of one cycle is high (1) versus low +//| (0). 0xffff will always be high, 0 will always be low and 0x7fff will +//| be half high and then half low. //| -//| 16 bit value that dictates how much of one cycle is high (1) versus low -//| (0). 0xffff will always be high, 0 will always be low and 0x7fff will -//| be half high and then half low. +//| Depending on how PWM is implemented on a specific board, the internal +//| representation for duty cycle might have less than 16 bits of resolution. +//| Reading this property will return the value from the internal representation, +//| so it may differ from the value set.""" //| -//| Depending on how PWM is implemented on a specific board, the internal -//| representation for duty cycle might have less than 16 bits of resolution. -//| Reading this property will return the value from the internal representation, -//| so it may differ from the value set. STATIC mp_obj_t pulseio_pwmout_obj_get_duty_cycle(mp_obj_t self_in) { pulseio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -190,16 +191,15 @@ const mp_obj_property_t pulseio_pwmout_duty_cycle_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: frequency -//| -//| 32 bit value that dictates the PWM frequency in Hertz (cycles per +//| frequency: Any = ... +//| """32 bit value that dictates the PWM frequency in Hertz (cycles per //| second). Only writeable when constructed with ``variable_frequency=True``. //| //| Depending on how PWM is implemented on a specific board, the internal value //| for the PWM's duty cycle may need to be recalculated when the frequency //| changes. In these cases, the duty cycle is automatically recalculated //| from the original duty cycle value. This should happen without any need -//| to manually re-set the duty cycle. +//| to manually re-set the duty cycle.""" //| STATIC mp_obj_t pulseio_pwmout_obj_get_frequency(mp_obj_t self_in) { pulseio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c index 6c01a4c17..9024f53e3 100644 --- a/shared-bindings/pulseio/PulseIn.c +++ b/shared-bindings/pulseio/PulseIn.c @@ -35,51 +35,52 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: pulseio +//| class PulseIn: +//| """.. currentmodule:: pulseio //| -//| :class:`PulseIn` -- Read a series of pulse durations -//| ======================================================== +//| :class:`PulseIn` -- Read a series of pulse durations +//| ======================================================== //| -//| PulseIn is used to measure a series of active and idle pulses. This is -//| commonly used in infrared receivers and low cost temperature sensors (DHT). -//| The pulsed signal consists of timed active and idle periods. Unlike PWM, -//| there is no set duration for active and idle pairs. +//| PulseIn is used to measure a series of active and idle pulses. This is +//| commonly used in infrared receivers and low cost temperature sensors (DHT). +//| The pulsed signal consists of timed active and idle periods. Unlike PWM, +//| there is no set duration for active and idle pairs.""" //| -//| .. class:: PulseIn(pin, maxlen=2, *, idle_state=False) +//| def __init__(self, pin: microcontroller.Pin, maxlen: int = 2, *, idle_state: bool = False): +//| """Create a PulseIn object associated with the given pin. The object acts as +//| a read-only sequence of pulse lengths with a given max length. When it is +//| active, new pulse lengths are added to the end of the list. When there is +//| no more room (len() == `maxlen`) the oldest pulse length is removed to +//| make room. //| -//| Create a PulseIn object associated with the given pin. The object acts as -//| a read-only sequence of pulse lengths with a given max length. When it is -//| active, new pulse lengths are added to the end of the list. When there is -//| no more room (len() == `maxlen`) the oldest pulse length is removed to -//| make room. +//| :param ~microcontroller.Pin pin: Pin to read pulses from. +//| :param int maxlen: Maximum number of pulse durations to store at once +//| :param bool idle_state: Idle state of the pin. At start and after `resume` +//| the first recorded pulse will the opposite state from idle. //| -//| :param ~microcontroller.Pin pin: Pin to read pulses from. -//| :param int maxlen: Maximum number of pulse durations to store at once -//| :param bool idle_state: Idle state of the pin. At start and after `resume` -//| the first recorded pulse will the opposite state from idle. +//| Read a short series of pulses:: //| -//| Read a short series of pulses:: +//| import pulseio +//| import board //| -//| import pulseio -//| import board +//| pulses = pulseio.PulseIn(board.D7) //| -//| pulses = pulseio.PulseIn(board.D7) +//| # Wait for an active pulse +//| while len(pulses) == 0: +//| pass +//| # Pause while we do something with the pulses +//| pulses.pause() //| -//| # Wait for an active pulse -//| while len(pulses) == 0: -//| pass -//| # Pause while we do something with the pulses -//| pulses.pause() +//| # Print the pulses. pulses[0] is an active pulse unless the length +//| # reached max length and idle pulses are recorded. +//| print(pulses) //| -//| # Print the pulses. pulses[0] is an active pulse unless the length -//| # reached max length and idle pulses are recorded. -//| print(pulses) +//| # Clear the rest +//| pulses.clear() //| -//| # Clear the rest -//| pulses.clear() -//| -//| # Resume with an 80 microsecond active pulse -//| pulses.resume(80) +//| # Resume with an 80 microsecond active pulse +//| pulses.resume(80)""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin, ARG_maxlen, ARG_idle_state }; @@ -101,9 +102,9 @@ STATIC mp_obj_t pulseio_pulsein_make_new(const mp_obj_type_t *type, size_t n_arg return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the PulseIn and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the PulseIn and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_deinit(mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -118,16 +119,16 @@ STATIC void check_for_deinit(pulseio_pulsein_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -136,9 +137,9 @@ STATIC mp_obj_t pulseio_pulsein_obj___exit__(size_t n_args, const mp_obj_t *args } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pulseio_pulsein___exit___obj, 4, 4, pulseio_pulsein_obj___exit__); -//| .. method:: pause() -//| -//| Pause pulse capture +//| def pause(self, ) -> Any: +//| """Pause pulse capture""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_obj_pause(mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -149,16 +150,16 @@ STATIC mp_obj_t pulseio_pulsein_obj_pause(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulsein_pause_obj, pulseio_pulsein_obj_pause); -//| .. method:: resume(trigger_duration=0) -//| -//| Resumes pulse capture after an optional trigger pulse. +//| def resume(self, trigger_duration: int = 0) -> Any: +//| """Resumes pulse capture after an optional trigger pulse. //| -//| .. warning:: Using trigger pulse with a device that drives both high and -//| low signals risks a short. Make sure your device is open drain (only -//| drives low) when using a trigger pulse. You most likely added a -//| "pull-up" resistor to your circuit to do this. +//| .. warning:: Using trigger pulse with a device that drives both high and +//| low signals risks a short. Make sure your device is open drain (only +//| drives low) when using a trigger pulse. You most likely added a +//| "pull-up" resistor to your circuit to do this. //| -//| :param int trigger_duration: trigger pulse duration in microseconds +//| :param int trigger_duration: trigger pulse duration in microseconds""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_obj_resume(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_trigger_duration }; @@ -176,9 +177,9 @@ STATIC mp_obj_t pulseio_pulsein_obj_resume(size_t n_args, const mp_obj_t *pos_ar } MP_DEFINE_CONST_FUN_OBJ_KW(pulseio_pulsein_resume_obj, 1, pulseio_pulsein_obj_resume); -//| .. method:: clear() -//| -//| Clears all captured pulses +//| def clear(self, ) -> Any: +//| """Clears all captured pulses""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_obj_clear(mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -189,9 +190,9 @@ STATIC mp_obj_t pulseio_pulsein_obj_clear(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulsein_clear_obj, pulseio_pulsein_obj_clear); -//| .. method:: popleft() -//| -//| Removes and returns the oldest read pulse. +//| def popleft(self, ) -> Any: +//| """Removes and returns the oldest read pulse.""" +//| ... //| STATIC mp_obj_t pulseio_pulsein_obj_popleft(mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -201,10 +202,9 @@ STATIC mp_obj_t pulseio_pulsein_obj_popleft(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulsein_popleft_obj, pulseio_pulsein_obj_popleft); -//| .. attribute:: maxlen -//| -//| The maximum length of the PulseIn. When len() is equal to maxlen, -//| it is unclear which pulses are active and which are idle. +//| maxlen: Any = ... +//| """The maximum length of the PulseIn. When len() is equal to maxlen, +//| it is unclear which pulses are active and which are idle.""" //| STATIC mp_obj_t pulseio_pulsein_obj_get_maxlen(mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -221,10 +221,9 @@ const mp_obj_property_t pulseio_pulsein_maxlen_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: paused -//| -//| True when pulse capture is paused as a result of :py:func:`pause` or an error during capture -//| such as a signal that is too fast. +//| paused: Any = ... +//| """True when pulse capture is paused as a result of :py:func:`pause` or an error during capture +//| such as a signal that is too fast.""" //| STATIC mp_obj_t pulseio_pulsein_obj_get_paused(mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -241,14 +240,14 @@ const mp_obj_property_t pulseio_pulsein_paused_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __len__() -//| -//| Returns the current pulse length +//| def __len__(self, ) -> Any: +//| """Returns the current pulse length //| -//| This allows you to:: +//| This allows you to:: //| -//| pulses = pulseio.PulseIn(pin) -//| print(len(pulses)) +//| pulses = pulseio.PulseIn(pin) +//| print(len(pulses))""" +//| ... //| STATIC mp_obj_t pulsein_unary_op(mp_unary_op_t op, mp_obj_t self_in) { pulseio_pulsein_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -261,14 +260,14 @@ STATIC mp_obj_t pulsein_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| .. method:: __getitem__(index) -//| -//| Returns the value at the given index or values in slice. +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the value at the given index or values in slice. //| -//| This allows you to:: +//| This allows you to:: //| -//| pulses = pulseio.PulseIn(pin) -//| print(pulses[0]) +//| pulses = pulseio.PulseIn(pin) +//| print(pulses[0])""" +//| ... //| STATIC mp_obj_t pulsein_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value) { if (value == mp_const_none) { diff --git a/shared-bindings/pulseio/PulseOut.c b/shared-bindings/pulseio/PulseOut.c index 172459e5d..9c650731b 100644 --- a/shared-bindings/pulseio/PulseOut.c +++ b/shared-bindings/pulseio/PulseOut.c @@ -36,37 +36,38 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: pulseio +//| class PulseOut: +//| """.. currentmodule:: pulseio //| -//| :class:`PulseOut` -- Output a pulse train -//| ======================================================== +//| :class:`PulseOut` -- Output a pulse train +//| ======================================================== //| -//| PulseOut is used to pulse PWM "carrier" output on and off. This is commonly -//| used in infrared remotes. The pulsed signal consists of timed on and off -//| periods. Unlike PWM, there is no set duration for on and off pairs. +//| PulseOut is used to pulse PWM "carrier" output on and off. This is commonly +//| used in infrared remotes. The pulsed signal consists of timed on and off +//| periods. Unlike PWM, there is no set duration for on and off pairs.""" //| -//| .. class:: PulseOut(carrier) +//| def __init__(self, carrier: pulseio.PWMOut): +//| """Create a PulseOut object associated with the given PWMout object. //| -//| Create a PulseOut object associated with the given PWMout object. +//| :param ~pulseio.PWMOut carrier: PWMOut that is set to output on the desired pin. //| -//| :param ~pulseio.PWMOut carrier: PWMOut that is set to output on the desired pin. +//| Send a short series of pulses:: //| -//| Send a short series of pulses:: +//| import array +//| import pulseio +//| import board //| -//| import array -//| import pulseio -//| import board +//| # 50% duty cycle at 38kHz. +//| pwm = pulseio.PWMOut(board.D13, frequency=38000, duty_cycle=32768) +//| pulse = pulseio.PulseOut(pwm) +//| # on off on off on +//| pulses = array.array('H', [65000, 1000, 65000, 65000, 1000]) +//| pulse.send(pulses) //| -//| # 50% duty cycle at 38kHz. -//| pwm = pulseio.PWMOut(board.D13, frequency=38000, duty_cycle=32768) -//| pulse = pulseio.PulseOut(pwm) -//| # on off on off on -//| pulses = array.array('H', [65000, 1000, 65000, 65000, 1000]) -//| pulse.send(pulses) -//| -//| # Modify the array of pulses. -//| pulses[0] = 200 -//| pulse.send(pulses) +//| # Modify the array of pulses. +//| pulses[0] = 200 +//| pulse.send(pulses)""" +//| ... //| STATIC mp_obj_t pulseio_pulseout_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -85,9 +86,9 @@ STATIC mp_obj_t pulseio_pulseout_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitialises the PulseOut and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the PulseOut and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t pulseio_pulseout_deinit(mp_obj_t self_in) { pulseio_pulseout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -96,16 +97,16 @@ STATIC mp_obj_t pulseio_pulseout_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulseout_deinit_obj, pulseio_pulseout_deinit); -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t pulseio_pulseout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -114,16 +115,16 @@ STATIC mp_obj_t pulseio_pulseout_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pulseio_pulseout___exit___obj, 4, 4, pulseio_pulseout_obj___exit__); -//| .. method:: send(pulses) -//| -//| Pulse alternating on and off durations in microseconds starting with on. -//| ``pulses`` must be an `array.array` with data type 'H' for unsigned -//| halfword (two bytes). +//| def send(self, pulses: array.array) -> Any: +//| """Pulse alternating on and off durations in microseconds starting with on. +//| ``pulses`` must be an `array.array` with data type 'H' for unsigned +//| halfword (two bytes). //| -//| This method waits until the whole array of pulses has been sent and -//| ensures the signal is off afterwards. +//| This method waits until the whole array of pulses has been sent and +//| ensures the signal is off afterwards. //| -//| :param array.array pulses: pulse durations in microseconds +//| :param array.array pulses: pulse durations in microseconds""" +//| ... //| STATIC mp_obj_t pulseio_pulseout_obj_send(mp_obj_t self_in, mp_obj_t pulses) { pulseio_pulseout_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/pulseio/__init__.c b/shared-bindings/pulseio/__init__.c index a3cec3dca..70cb61fc3 100644 --- a/shared-bindings/pulseio/__init__.c +++ b/shared-bindings/pulseio/__init__.c @@ -35,7 +35,7 @@ #include "shared-bindings/pulseio/PulseOut.h" #include "shared-bindings/pulseio/PWMOut.h" -//| :mod:`pulseio` --- Support for pulse based protocols +//| """:mod:`pulseio` --- Support for pulse based protocols //| ===================================================== //| //| .. module:: pulseio @@ -73,7 +73,7 @@ //| :py:data:`~pulseio.PWMOut.duty_cycle`, and then sleep 0.1 seconds. //| CircuitPython will automatically turn off the PWM when it resets all //| hardware after program completion. Use ``deinit()`` or a ``with`` statement -//| to do it yourself. +//| to do it yourself.""" //| STATIC const mp_rom_map_elem_t pulseio_module_globals_table[] = { diff --git a/shared-bindings/random/__init__.c b/shared-bindings/random/__init__.c index de4c90910..d8b266be0 100644 --- a/shared-bindings/random/__init__.c +++ b/shared-bindings/random/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/random/__init__.h" #include "supervisor/shared/translate.h" -//| :mod:`random` --- pseudo-random numbers and choices +//| """:mod:`random` --- pseudo-random numbers and choices //| ======================================================== //| //| .. module:: random @@ -49,13 +49,13 @@ //| Once seeded, it will be deterministic, which is why its bad for cryptography. //| //| .. warning:: Numbers from this module are not cryptographically strong! Use -//| bytes from `os.urandom` directly for true randomness. +//| bytes from `os.urandom` directly for true randomness.""" //| -//| .. function:: seed(seed) -//| -//| Sets the starting seed of the random number generation. Further calls to -//| `random` will return deterministic results afterwards. +//| def seed(seed: Any) -> Any: +//| """Sets the starting seed of the random number generation. Further calls to +//| `random` will return deterministic results afterwards.""" +//| ... //| STATIC mp_obj_t random_seed(mp_obj_t seed_in) { mp_uint_t seed = mp_obj_get_int_truncated(seed_in); @@ -64,9 +64,9 @@ STATIC mp_obj_t random_seed(mp_obj_t seed_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(random_seed_obj, random_seed); -//| .. function:: getrandbits(k) -//| -//| Returns an integer with *k* random bits. +//| def getrandbits(k: Any) -> Any: +//| """Returns an integer with *k* random bits.""" +//| ... //| STATIC mp_obj_t random_getrandbits(mp_obj_t num_in) { int n = mp_obj_get_int(num_in); @@ -77,10 +77,9 @@ STATIC mp_obj_t random_getrandbits(mp_obj_t num_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(random_getrandbits_obj, random_getrandbits); -//| .. function:: randrange(stop) -//| randrange(start, stop, step=1) -//| -//| Returns a randomly selected integer from ``range(start, stop, step)``. +//| def randrange(stop: Any) -> Any: +//| """Returns a randomly selected integer from ``range(start, stop, step)``.""" +//| ... //| STATIC mp_obj_t random_randrange(size_t n_args, const mp_obj_t *args) { mp_int_t start = 0; @@ -120,10 +119,10 @@ STATIC mp_obj_t random_randrange(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(random_randrange_obj, 1, 3, random_randrange); -//| .. function:: randint(a, b) -//| -//| Returns a randomly selected integer between a and b inclusive. Equivalent -//| to ``randrange(a, b + 1, 1)`` +//| def randint(a: Any, b: Any) -> Any: +//| """Returns a randomly selected integer between a and b inclusive. Equivalent +//| to ``randrange(a, b + 1, 1)``""" +//| ... //| STATIC mp_obj_t random_randint(mp_obj_t a_in, mp_obj_t b_in) { mp_int_t a = mp_obj_get_int(a_in); @@ -135,10 +134,10 @@ STATIC mp_obj_t random_randint(mp_obj_t a_in, mp_obj_t b_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(random_randint_obj, random_randint); -//| .. function:: choice(seq) -//| -//| Returns a randomly selected element from the given sequence. Raises -//| IndexError when the sequence is empty. +//| def choice(seq: Any) -> Any: +//| """Returns a randomly selected element from the given sequence. Raises +//| IndexError when the sequence is empty.""" +//| ... //| STATIC mp_obj_t random_choice(mp_obj_t seq) { mp_int_t len = mp_obj_get_int(mp_obj_len(seq)); @@ -149,19 +148,19 @@ STATIC mp_obj_t random_choice(mp_obj_t seq) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(random_choice_obj, random_choice); -//| .. function:: random() -//| -//| Returns a random float between 0 and 1.0. +//| def random() -> Any: +//| """Returns a random float between 0 and 1.0.""" +//| ... //| STATIC mp_obj_t random_random(void) { return mp_obj_new_float(shared_modules_random_random()); } STATIC MP_DEFINE_CONST_FUN_OBJ_0(random_random_obj, random_random); -//| .. function:: uniform(a, b) -//| -//| Returns a random float between a and b. It may or may not be inclusive -//| depending on float rounding. +//| def uniform(a: Any, b: Any) -> Any: +//| """Returns a random float between a and b. It may or may not be inclusive +//| depending on float rounding.""" +//| ... //| STATIC mp_obj_t random_uniform(mp_obj_t a_in, mp_obj_t b_in) { mp_float_t a = mp_obj_get_float(a_in); -- cgit v1.2.3 From c7a9d49cba38499ec6701fdfef0c14e1dd5503a8 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 11 May 2020 13:00:19 -0400 Subject: Did rgbmatrix, rotaryio, and RTC --- shared-bindings/rgbmatrix/RGBMatrix.c | 103 +++++++++++++------------- shared-bindings/rgbmatrix/__init__.c | 5 +- shared-bindings/rotaryio/IncrementalEncoder.c | 72 +++++++++--------- shared-bindings/rotaryio/__init__.c | 4 +- shared-bindings/rtc/RTC.c | 49 ++++++------ shared-bindings/rtc/__init__.c | 30 ++++---- 6 files changed, 132 insertions(+), 131 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index d758774d9..e2393eb61 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -38,10 +38,11 @@ #include "shared-module/framebufferio/__init__.h" #include "shared-module/framebufferio/FramebufferDisplay.h" -//| .. currentmodule:: rgbmatrix +//| class RGBMatrix: +//| """.. currentmodule:: rgbmatrix //| -//| :class:`RGBMatrix` -- Driver for HUB75-style RGB LED matrices -//| ================================================================ +//| :class:`RGBMatrix` -- Driver for HUB75-style RGB LED matrices +//| ================================================================ //| extern Protomatter_core *_PM_protoPtr; @@ -133,45 +134,45 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ } } -//| :class:`~rgbmatrix.RGBMatrix` displays an in-memory framebuffer to an LED matrix. -//| -//| .. class:: RGBMatrix(*, width, bit_depth, rgb_pins, addr_pins, clock_pin, latch_pin, output_enable_pin, doublebuffer=True, framebuffer=None, height=0) + +//| :class:`~rgbmatrix.RGBMatrix` displays an in-memory framebuffer to an LED matrix.""" //| -//| Create a RGBMatrix object with the given attributes. The height of -//| the display is determined by the number of rgb and address pins: -//| len(rgb_pins) // 3 * 2 ** len(address_pins). With 6 RGB pins and 4 -//| address lines, the display will be 32 pixels tall. If the optional height -//| parameter is specified and is not 0, it is checked against the calculated -//| height. +//| def __init__(self, *, width: Any, bit_depth: Any, rgb_pins: Any, addr_pins: Any, clock_pin: Any, latch_pin: Any, output_enable_pin: Any, doublebuffer: Any = True, framebuffer: Any = None, height: Any = 0): +//| """Create a RGBMatrix object with the given attributes. The height of +//| the display is determined by the number of rgb and address pins: +//| len(rgb_pins) // 3 * 2 ** len(address_pins). With 6 RGB pins and 4 +//| address lines, the display will be 32 pixels tall. If the optional height +//| parameter is specified and is not 0, it is checked against the calculated +//| height. //| -//| Up to 30 RGB pins and 8 address pins are supported. +//| Up to 30 RGB pins and 8 address pins are supported. //| -//| The RGB pins must be within a single "port" and performance and memory -//| usage are best when they are all within "close by" bits of the port. -//| The clock pin must also be on the same port as the RGB pins. See the -//| documentation of the underlying protomatter C library for more -//| information. Generally, Adafruit's interface boards are designed so -//| that these requirements are met when matched with the intended -//| microcontroller board. For instance, the Feather M4 Express works -//| together with the RGB Matrix Feather. +//| The RGB pins must be within a single "port" and performance and memory +//| usage are best when they are all within "close by" bits of the port. +//| The clock pin must also be on the same port as the RGB pins. See the +//| documentation of the underlying protomatter C library for more +//| information. Generally, Adafruit's interface boards are designed so +//| that these requirements are met when matched with the intended +//| microcontroller board. For instance, the Feather M4 Express works +//| together with the RGB Matrix Feather. //| -//| The framebuffer is in "RGB565" format. +//| The framebuffer is in "RGB565" format. //| -//| "RGB565" means that it is organized as a series of 16-bit numbers -//| where the highest 5 bits are interpreted as red, the next 6 as -//| green, and the final 5 as blue. The object can be any buffer, but -//| `array.array` and `ulab.array` objects are most often useful. -//| To update the content, modify the framebuffer and call refresh. +//| "RGB565" means that it is organized as a series of 16-bit numbers +//| where the highest 5 bits are interpreted as red, the next 6 as +//| green, and the final 5 as blue. The object can be any buffer, but +//| `array.array` and `ulab.array` objects are most often useful. +//| To update the content, modify the framebuffer and call refresh. //| -//| If a framebuffer is not passed in, one is allocated and initialized -//| to all black. In any case, the framebuffer can be retrieved -//| by passing the RGBMatrix object to memoryview(). +//| If a framebuffer is not passed in, one is allocated and initialized +//| to all black. In any case, the framebuffer can be retrieved +//| by passing the RGBMatrix object to memoryview(). //| -//| If doublebuffer is False, some memory is saved, but the display may -//| flicker during updates. +//| If doublebuffer is False, some memory is saved, but the display may +//| flicker during updates. //| -//| A RGBMatrix is often used in conjunction with a -//| `framebufferio.FramebufferDisplay`. +//| A RGBMatrix is often used in conjunction with a +//| `framebufferio.FramebufferDisplay`.""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -245,11 +246,11 @@ STATIC mp_obj_t rgbmatrix_rgbmatrix_make_new(const mp_obj_type_t *type, size_t n return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit -//| -//| Free the resources (pins, timers, etc.) associated with this -//| rgbmatrix instance. After deinitialization, no further operations -//| may be performed. +//| def deinit(self, ) -> Any: +//| """Free the resources (pins, timers, etc.) associated with this +//| rgbmatrix instance. After deinitialization, no further operations +//| may be performed.""" +//| ... //| STATIC mp_obj_t rgbmatrix_rgbmatrix_deinit(mp_obj_t self_in) { rgbmatrix_rgbmatrix_obj_t *self = (rgbmatrix_rgbmatrix_obj_t*)self_in; @@ -265,10 +266,9 @@ static void check_for_deinit(rgbmatrix_rgbmatrix_obj_t *self) { } } -//| .. attribute:: brightness -//| -//| In the current implementation, 0.0 turns the display off entirely -//| and any other value up to 1.0 turns the display on fully. +//| brightness: Any = ... +//| """In the current implementation, 0.0 turns the display off entirely +//| and any other value up to 1.0 turns the display on fully.""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_brightness(mp_obj_t self_in) { rgbmatrix_rgbmatrix_obj_t *self = (rgbmatrix_rgbmatrix_obj_t*)self_in; @@ -297,10 +297,9 @@ const mp_obj_property_t rgbmatrix_rgbmatrix_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: refresh() -//| -//| Transmits the color data in the buffer to the pixels so that -//| they are shown. +//| def refresh(self, ) -> Any: ... +//| """Transmits the color data in the buffer to the pixels so that +//| they are shown.""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_refresh(mp_obj_t self_in) { rgbmatrix_rgbmatrix_obj_t *self = (rgbmatrix_rgbmatrix_obj_t*)self_in; @@ -310,9 +309,8 @@ STATIC mp_obj_t rgbmatrix_rgbmatrix_refresh(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(rgbmatrix_rgbmatrix_refresh_obj, rgbmatrix_rgbmatrix_refresh); -//| .. attribute:: width -//| -//| The width of the display, in pixels +//| width: Any = ... +//| """The width of the display, in pixels""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_width(mp_obj_t self_in) { rgbmatrix_rgbmatrix_obj_t *self = (rgbmatrix_rgbmatrix_obj_t*)self_in; @@ -327,9 +325,8 @@ const mp_obj_property_t rgbmatrix_rgbmatrix_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| The height of the display, in pixels +//| height: Any = ... +//| """The height of the display, in pixels""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_height(mp_obj_t self_in) { rgbmatrix_rgbmatrix_obj_t *self = (rgbmatrix_rgbmatrix_obj_t*)self_in; diff --git a/shared-bindings/rgbmatrix/__init__.c b/shared-bindings/rgbmatrix/__init__.c index 662d2c4f6..f61002a78 100644 --- a/shared-bindings/rgbmatrix/__init__.c +++ b/shared-bindings/rgbmatrix/__init__.c @@ -31,7 +31,7 @@ #include "shared-bindings/rgbmatrix/RGBMatrix.h" -//| :mod:`rgbmatrix` --- Low-level routines for bitbanged LED matrices +//| """:mod:`rgbmatrix` --- Low-level routines for bitbanged LED matrices //| ===================================================================== //| //| .. module:: rgbmatrix @@ -40,7 +40,8 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| RGBMatrix +//| RGBMatrix""" +//| STATIC const mp_rom_map_elem_t rgbmatrix_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_rgbmatrix) }, diff --git a/shared-bindings/rotaryio/IncrementalEncoder.c b/shared-bindings/rotaryio/IncrementalEncoder.c index 058241d24..a10fb6fd5 100644 --- a/shared-bindings/rotaryio/IncrementalEncoder.c +++ b/shared-bindings/rotaryio/IncrementalEncoder.c @@ -34,35 +34,36 @@ #include "shared-bindings/rotaryio/IncrementalEncoder.h" #include "shared-bindings/util.h" -//| .. currentmodule:: rotaryio +//| class IncrementalEncoder: +//| """.. currentmodule:: rotaryio //| -//| :class:`IncrementalEncoder` -- Track the relative position of an incremental encoder -//| ==================================================================================== +//| :class:`IncrementalEncoder` -- Track the relative position of an incremental encoder +//| ==================================================================================== //| -//| IncrementalEncoder determines the relative rotational position based on two series of pulses. +//| IncrementalEncoder determines the relative rotational position based on two series of pulses.""" //| -//| .. class:: IncrementalEncoder(pin_a, pin_b) +//| def __init__(self, pin_a: microcontroller.Pin, pin_b: microcontroller.Pin): +//| """Create an IncrementalEncoder object associated with the given pins. It tracks the positional +//| state of an incremental rotary encoder (also known as a quadrature encoder.) Position is +//| relative to the position when the object is contructed. //| -//| Create an IncrementalEncoder object associated with the given pins. It tracks the positional -//| state of an incremental rotary encoder (also known as a quadrature encoder.) Position is -//| relative to the position when the object is contructed. +//| :param ~microcontroller.Pin pin_a: First pin to read pulses from. +//| :param ~microcontroller.Pin pin_b: Second pin to read pulses from. //| -//| :param ~microcontroller.Pin pin_a: First pin to read pulses from. -//| :param ~microcontroller.Pin pin_b: Second pin to read pulses from. +//| For example:: //| -//| For example:: +//| import rotaryio +//| import time +//| from board import * //| -//| import rotaryio -//| import time -//| from board import * -//| -//| enc = rotaryio.IncrementalEncoder(D1, D2) -//| last_position = None -//| while True: -//| position = enc.position -//| if last_position == None or position != last_position: -//| print(position) -//| last_position = position +//| enc = rotaryio.IncrementalEncoder(D1, D2) +//| last_position = None +//| while True: +//| position = enc.position +//| if last_position == None or position != last_position: +//| print(position) +//| last_position = position""" +//| ... //| STATIC mp_obj_t rotaryio_incrementalencoder_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin_a, ARG_pin_b }; @@ -84,9 +85,9 @@ STATIC mp_obj_t rotaryio_incrementalencoder_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitializes the IncrementalEncoder and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitializes the IncrementalEncoder and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t rotaryio_incrementalencoder_deinit(mp_obj_t self_in) { rotaryio_incrementalencoder_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -101,16 +102,16 @@ STATIC void check_for_deinit(rotaryio_incrementalencoder_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t rotaryio_incrementalencoder_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -120,10 +121,9 @@ STATIC mp_obj_t rotaryio_incrementalencoder_obj___exit__(size_t n_args, const mp STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(rotaryio_incrementalencoder___exit___obj, 4, 4, rotaryio_incrementalencoder_obj___exit__); -//| .. attribute:: position -//| -//| The current position in terms of pulses. The number of pulses per rotation is defined by the -//| specific hardware. +//| position: Any = ... +//| """The current position in terms of pulses. The number of pulses per rotation is defined by the +//| specific hardware.""" //| STATIC mp_obj_t rotaryio_incrementalencoder_obj_get_position(mp_obj_t self_in) { rotaryio_incrementalencoder_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/rotaryio/__init__.c b/shared-bindings/rotaryio/__init__.c index a0166771a..0cc8eb556 100644 --- a/shared-bindings/rotaryio/__init__.c +++ b/shared-bindings/rotaryio/__init__.c @@ -33,7 +33,7 @@ #include "shared-bindings/rotaryio/__init__.h" #include "shared-bindings/rotaryio/IncrementalEncoder.h" -//| :mod:`rotaryio` --- Support for reading rotation sensors +//| """:mod:`rotaryio` --- Support for reading rotation sensors //| ======================================================== //| //| .. module:: rotaryio @@ -59,7 +59,7 @@ //| 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. +//| :ref:`lifetime-and-contextmanagers` for more info.""" //| STATIC const mp_rom_map_elem_t rotaryio_module_globals_table[] = { diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c index 3ff09a4ec..8a3e89d73 100644 --- a/shared-bindings/rtc/RTC.c +++ b/shared-bindings/rtc/RTC.c @@ -38,14 +38,19 @@ const rtc_rtc_obj_t rtc_rtc_obj = {{&rtc_rtc_type}}; -//| .. currentmodule:: rtc -//| -//| :class:`RTC` --- Real Time Clock -//| -------------------------------- + + + + +//| class RTC: +//| """.. currentmodule:: rtc //| -//| .. class:: RTC() +//| :class:`RTC` --- Real Time Clock +//| --------------------------------""" //| -//| This class represents the onboard Real Time Clock. It is a singleton and will always return the same instance. +//| def __init__(self, ): +//| """This class represents the onboard Real Time Clock. It is a singleton and will always return the same instance.""" +//| ... //| STATIC mp_obj_t rtc_rtc_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { // No arguments @@ -55,25 +60,24 @@ STATIC mp_obj_t rtc_rtc_make_new(const mp_obj_type_t *type, size_t n_args, const return (mp_obj_t)&rtc_rtc_obj; } -//| .. attribute:: datetime -//| -//| The current date and time of the RTC as a `time.struct_time`. +//| datetime: Any = ... +//| """The current date and time of the RTC as a `time.struct_time`. //| -//| This must be set to the current date and time whenever the board loses power:: +//| This must be set to the current date and time whenever the board loses power:: //| -//| import rtc -//| import time +//| import rtc +//| import time //| -//| r = rtc.RTC() -//| r.datetime = rtctime.struct_time((2019, 5, 29, 15, 14, 15, 0, -1, -1)) +//| r = rtc.RTC() +//| r.datetime = rtctime.struct_time((2019, 5, 29, 15, 14, 15, 0, -1, -1)) //| //| -//| Once set, the RTC will automatically update this value as time passes. You can read this -//| property to get a snapshot of the current time:: +//| Once set, the RTC will automatically update this value as time passes. You can read this +//| property to get a snapshot of the current time:: //| -//| current_time = r.datetime -//| print(current_time) -//| # struct_time(tm_year=2019, tm_month=5, ...) +//| current_time = r.datetime +//| print(current_time) +//| # struct_time(tm_year=2019, tm_month=5, ...)""" //| STATIC mp_obj_t rtc_rtc_obj_get_datetime(mp_obj_t self_in) { timeutils_struct_time_t tm; @@ -97,12 +101,11 @@ const mp_obj_property_t rtc_rtc_datetime_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: calibration -//| -//| The RTC calibration value as an `int`. +//| calibration: Any = ... +//| """The RTC calibration value as an `int`. //| //| A positive value speeds up the clock and a negative value slows it down. -//| Range and value is hardware specific, but one step is often approximately 1 ppm. +//| Range and value is hardware specific, but one step is often approximately 1 ppm.""" //| STATIC mp_obj_t rtc_rtc_obj_get_calibration(mp_obj_t self_in) { int calibration = common_hal_rtc_get_calibration(); diff --git a/shared-bindings/rtc/__init__.c b/shared-bindings/rtc/__init__.c index 22eda9b66..66669ca5f 100644 --- a/shared-bindings/rtc/__init__.c +++ b/shared-bindings/rtc/__init__.c @@ -31,7 +31,7 @@ #include "shared-bindings/rtc/RTC.h" #include "shared-bindings/time/__init__.h" -//| :mod:`rtc` --- Real Time Clock +//| """:mod:`rtc` --- Real Time Clock //| ======================================================== //| //| .. module:: rtc @@ -47,7 +47,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| RTC +//| RTC""" //| void rtc_reset(void) { @@ -62,22 +62,22 @@ mp_obj_t rtc_get_time_source_time(void) { return struct_time_from_tm(&tm); } -//| .. function:: set_time_source(rtc) +//| def set_time_source(rtc: Any) -> Any: +//| """Sets the RTC time source used by :func:`time.localtime`. +//| The default is :class:`rtc.RTC`, but it's useful to use this to override the +//| time source for testing purposes. For example:: //| -//| Sets the RTC time source used by :func:`time.localtime`. -//| The default is :class:`rtc.RTC`, but it's useful to use this to override the -//| time source for testing purposes. For example:: +//| import rtc +//| import time //| -//| import rtc -//| import time +//| class RTC(object): +//| @property +//| def datetime(self): +//| return time.struct_time((2018, 3, 17, 21, 1, 47, 0, 0, 0)) //| -//| class RTC(object): -//| @property -//| def datetime(self): -//| return time.struct_time((2018, 3, 17, 21, 1, 47, 0, 0, 0)) -//| -//| r = RTC() -//| rtc.set_time_source(r) +//| r = RTC() +//| rtc.set_time_source(r)""" +//| ... //| STATIC mp_obj_t rtc_set_time_source(mp_obj_t time_source) { MP_STATE_VM(rtc_time_source) = time_source; -- cgit v1.2.3 From 603df58f971743bc36b9e391cd5fb04812262533 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 11 May 2020 13:40:02 -0400 Subject: Did stage, socket, storage --- shared-bindings/_stage/Layer.c | 45 +++++------ shared-bindings/_stage/Text.c | 37 ++++----- shared-bindings/_stage/__init__.c | 12 +-- shared-bindings/socket/__init__.c | 156 +++++++++++++++++++------------------ shared-bindings/storage/__init__.c | 138 ++++++++++++++++---------------- 5 files changed, 196 insertions(+), 192 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/_stage/Layer.c b/shared-bindings/_stage/Layer.c index 12028b131..437114cd3 100644 --- a/shared-bindings/_stage/Layer.c +++ b/shared-bindings/_stage/Layer.c @@ -30,25 +30,26 @@ #include "Layer.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: _stage +//| class Layer: +//| """.. currentmodule:: _stage //| -//| :class:`Layer` -- Keep information about a single layer of graphics -//| =================================================================== +//| :class:`Layer` -- Keep information about a single layer of graphics +//| ===================================================================""" //| -//| .. class:: Layer(width, height, graphic, palette, [grid]) +//| def __init__(self, width: int, height: int, graphic: bytearray, palette: bytearray, grid: bytearray): +//| """Keep internal information about a layer of graphics (either a +//| ``Grid`` or a ``Sprite``) in a format suitable for fast rendering +//| with the ``render()`` function. //| -//| Keep internal information about a layer of graphics (either a -//| ``Grid`` or a ``Sprite``) in a format suitable for fast rendering -//| with the ``render()`` function. +//| :param int width: The width of the grid in tiles, or 1 for sprites. +//| :param int height: The height of the grid in tiles, or 1 for sprites. +//| :param bytearray graphic: The graphic data of the tiles. +//| :param bytearray palette: The color palette to be used. +//| :param bytearray grid: The contents of the grid map. //| -//| :param int width: The width of the grid in tiles, or 1 for sprites. -//| :param int height: The height of the grid in tiles, or 1 for sprites. -//| :param bytearray graphic: The graphic data of the tiles. -//| :param bytearray palette: The color palette to be used. -//| :param bytearray grid: The contents of the grid map. -//| -//| This class is intended for internal use in the ``stage`` library and -//| it shouldn't be used on its own. +//| This class is intended for internal use in the ``stage`` library and +//| it shouldn't be used on its own.""" +//| ... //| STATIC mp_obj_t layer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -90,9 +91,9 @@ STATIC mp_obj_t layer_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| .. method:: move(x, y) -//| -//| Set the offset of the layer to the specified values. +//| def move(self, x: Any, y: Any) -> Any: +//| """Set the offset of the layer to the specified values.""" +//| ... //| STATIC mp_obj_t layer_move(mp_obj_t self_in, mp_obj_t x_in, mp_obj_t y_in) { layer_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -102,10 +103,10 @@ STATIC mp_obj_t layer_move(mp_obj_t self_in, mp_obj_t x_in, mp_obj_t y_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(layer_move_obj, layer_move); -//| .. method:: frame(frame, rotation) -//| -//| Set the animation frame of the sprite, and optionally rotation its -//| graphic. +//| def frame(self, frame: Any, rotation: Any) -> Any: +//| """Set the animation frame of the sprite, and optionally rotation its +//| graphic.""" +//| ... //| STATIC mp_obj_t layer_frame(mp_obj_t self_in, mp_obj_t frame_in, mp_obj_t rotation_in) { diff --git a/shared-bindings/_stage/Text.c b/shared-bindings/_stage/Text.c index 49c1d00ca..8797f74db 100644 --- a/shared-bindings/_stage/Text.c +++ b/shared-bindings/_stage/Text.c @@ -30,25 +30,26 @@ #include "Text.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: _stage +//| class Text: +//| """.. currentmodule:: _stage //| -//| :class:`Text` -- Keep information about a single text of text -//| ============================================================== +//| :class:`Text` -- Keep information about a single text of text +//| ==============================================================""" //| -//| .. class:: Text(width, height, font, palette, chars) +//| def __init__(self, width: int, height: int, font: bytearray, palette: bytearray, chars: bytearray): +//| """Keep internal information about a text of text +//| in a format suitable for fast rendering +//| with the ``render()`` function. //| -//| Keep internal information about a text of text -//| in a format suitable for fast rendering -//| with the ``render()`` function. +//| :param int width: The width of the grid in tiles, or 1 for sprites. +//| :param int height: The height of the grid in tiles, or 1 for sprites. +//| :param bytearray font: The font data of the characters. +//| :param bytearray palette: The color palette to be used. +//| :param bytearray chars: The contents of the character grid. //| -//| :param int width: The width of the grid in tiles, or 1 for sprites. -//| :param int height: The height of the grid in tiles, or 1 for sprites. -//| :param bytearray font: The font data of the characters. -//| :param bytearray palette: The color palette to be used. -//| :param bytearray chars: The contents of the character grid. -//| -//| This class is intended for internal use in the ``stage`` library and -//| it shouldn't be used on its own. +//| This class is intended for internal use in the ``stage`` library and +//| it shouldn't be used on its own.""" +//| ... //| STATIC mp_obj_t text_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -84,9 +85,9 @@ STATIC mp_obj_t text_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| .. method:: move(x, y) -//| -//| Set the offset of the text to the specified values. +//| def move(self, x: Any, y: Any) -> Any: +//| """Set the offset of the text to the specified values.""" +//| ... //| STATIC mp_obj_t text_move(mp_obj_t self_in, mp_obj_t x_in, mp_obj_t y_in) { text_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c index 4bac280bf..6b5c4fd8b 100644 --- a/shared-bindings/_stage/__init__.c +++ b/shared-bindings/_stage/__init__.c @@ -34,7 +34,7 @@ #include "Layer.h" #include "Text.h" -//| :mod:`_stage` --- C-level helpers for animation of sprites on a stage +//| """:mod:`_stage` --- C-level helpers for animation of sprites on a stage //| ===================================================================== //| //| .. module:: _stage @@ -49,11 +49,10 @@ //| :maxdepth: 3 //| //| Layer -//| Text +//| Text""" //| -//| .. function:: render(x0, y0, x1, y1, layers, buffer, display[, scale[, background]]) -//| -//| Render and send to the display a fragment of the screen. +//| def render(x0: int, y0: int, x1: int, y1: int, layers: list, buffer: bytearray, display: displayio.Display, scale: int, background: int) -> Any: +//| """Render and send to the display a fragment of the screen. //| //| :param int x0: Left edge of the fragment. //| :param int y0: Top edge of the fragment. @@ -70,7 +69,8 @@ //| valid. //| //| This function is intended for internal use in the ``stage`` library -//| and all the necessary checks are performed there. +//| and all the necessary checks are performed there.""" +//| STATIC mp_obj_t stage_render(size_t n_args, const mp_obj_t *args) { uint16_t x0 = mp_obj_get_int(args[0]); uint16_t y0 = mp_obj_get_int(args[1]); diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 2d6c16e90..4c0811bdb 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -37,27 +37,28 @@ #include "shared-module/network/__init__.h" -//| :mod:`socket` --- TCP, UDP and RAW socket support +//| """:mod:`socket` --- TCP, UDP and RAW socket support //| ================================================= //| //| .. module:: socket //| :synopsis: TCP, UDP and RAW sockets //| :platform: SAMD21, SAMD51 //| -//| Create TCP, UDP and RAW sockets for communicating over the Internet. +//| Create TCP, UDP and RAW sockets for communicating over the Internet.""" //| STATIC const mp_obj_type_t socket_type; -//| .. currentmodule:: socket +//| class socket: +//| """.. currentmodule:: socket""" //| -//| .. class:: socket(family, type, proto) +//| def __init__(self, family: int, type: int, proto: int): +//| """Create a new socket //| -//| Create a new socket -//| -//| :param ~int family: AF_INET or AF_INET6 -//| :param ~int type: SOCK_STREAM, SOCK_DGRAM or SOCK_RAW -//| :param ~int proto: IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW (ignored) +//| :param ~int family: AF_INET or AF_INET6 +//| :param ~int type: SOCK_STREAM, SOCK_DGRAM or SOCK_RAW +//| :param ~int proto: IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW (ignored)""" +//| ... //| STATIC mp_obj_t socket_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -98,11 +99,11 @@ STATIC void socket_select_nic(mod_network_socket_obj_t *self, const byte *ip) { } } -//| .. method:: bind(address) -//| -//| Bind a socket to an address +//| def bind(self, address: tuple) -> Any: +//| """Bind a socket to an address //| -//| :param ~tuple address: tuple of (remote_address, remote_port) +//| :param ~tuple address: tuple of (remote_address, remote_port)""" +//| ... //| STATIC mp_obj_t socket_bind(mp_obj_t self_in, mp_obj_t addr_in) { @@ -125,11 +126,11 @@ STATIC mp_obj_t socket_bind(mp_obj_t self_in, mp_obj_t addr_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_bind_obj, socket_bind); -//| .. method:: listen(backlog) -//| -//| Set socket to listen for incoming connections +//| def listen(self, backlog: int) -> Any: +//| """Set socket to listen for incoming connections //| -//| :param ~int backlog: length of backlog queue for waiting connetions +//| :param ~int backlog: length of backlog queue for waiting connetions""" +//| ... //| STATIC mp_obj_t socket_listen(mp_obj_t self_in, mp_obj_t backlog) { @@ -150,11 +151,10 @@ STATIC mp_obj_t socket_listen(mp_obj_t self_in, mp_obj_t backlog) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_listen_obj, socket_listen); -//| .. method:: accept() -//| -//| Accept a connection on a listening socket of type SOCK_STREAM, -//| creating a new socket of type SOCK_STREAM. -//| Returns a tuple of (new_socket, remote_address) +//| def accept(self, ) -> Any: +//| """Accept a connection on a listening socket of type SOCK_STREAM, +//| creating a new socket of type SOCK_STREAM. +//| Returns a tuple of (new_socket, remote_address)""" //| STATIC mp_obj_t socket_accept(mp_obj_t self_in) { @@ -188,11 +188,11 @@ STATIC mp_obj_t socket_accept(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(socket_accept_obj, socket_accept); -//| .. method:: connect(address) -//| -//| Connect a socket to a remote address +//| def connect(self, address: tuple) -> Any: +//| """Connect a socket to a remote address //| -//| :param ~tuple address: tuple of (remote_address, remote_port) +//| :param ~tuple address: tuple of (remote_address, remote_port)""" +//| ... //| STATIC mp_obj_t socket_connect(mp_obj_t self_in, mp_obj_t addr_in) { @@ -215,12 +215,12 @@ STATIC mp_obj_t socket_connect(mp_obj_t self_in, mp_obj_t addr_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_connect_obj, socket_connect); -//| .. method:: send(bytes) -//| -//| Send some bytes to the connected remote address. -//| Suits sockets of type SOCK_STREAM +//| def send(self, bytes: bytes) -> Any: +//| """Send some bytes to the connected remote address. +//| Suits sockets of type SOCK_STREAM //| -//| :param ~bytes bytes: some bytes to send +//| :param ~bytes bytes: some bytes to send""" +//| ... //| STATIC mp_obj_t socket_send(mp_obj_t self_in, mp_obj_t buf_in) { @@ -252,19 +252,20 @@ STATIC mp_int_t _socket_recv_into(mod_network_socket_obj_t *sock, byte *buf, mp_ } -//| .. method:: recv_into(buffer[, bufsize]) +//| def recv_into(self, buffer: bytearray, bufsize: int) -> Any: +//| """Reads some bytes from the connected remote address, writing +//| into the provided buffer. If bufsize <= len(buffer) is given, +//| a maximum of bufsize bytes will be read into the buffer. If no +//| valid value is given for bufsize, the default is the length of +//| the given buffer. //| -//| Reads some bytes from the connected remote address, writing -//| into the provided buffer. If bufsize <= len(buffer) is given, -//| a maximum of bufsize bytes will be read into the buffer. If no -//| valid value is given for bufsize, the default is the length of -//| the given buffer. +//| Suits sockets of type SOCK_STREAM +//| Returns an int of number of bytes read. //| -//| Suits sockets of type SOCK_STREAM -//| Returns an int of number of bytes read. +//| :param bytearray buffer: buffer to receive into +//| :param int bufsize: optionally, a maximum number of bytes to read.""" +//| ... //| -//| :param bytearray buffer: buffer to receive into -//| :param int bufsize: optionally, a maximum number of bytes to read. STATIC mp_obj_t socket_recv_into(size_t n_args, const mp_obj_t *args) { mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(args[0]); @@ -287,13 +288,14 @@ STATIC mp_obj_t socket_recv_into(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_recv_into_obj, 2, 3, socket_recv_into); -//| .. method:: recv(bufsize) +//| def recv(self, bufsize: int) -> Any: +//| """Reads some bytes from the connected remote address. +//| Suits sockets of type SOCK_STREAM +//| Returns a bytes() of length <= bufsize //| -//| Reads some bytes from the connected remote address. -//| Suits sockets of type SOCK_STREAM -//| Returns a bytes() of length <= bufsize +//| :param ~int bufsize: maximum number of bytes to receive""" +//| ... //| -//| :param ~int bufsize: maximum number of bytes to receive STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) { mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -313,13 +315,13 @@ STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_recv_obj, socket_recv); -//| .. method:: sendto(bytes, address) +//| def sendto(self, bytes: bytes, address: tuple) -> Any: +//| """Send some bytes to a specific address. +//| Suits sockets of type SOCK_DGRAM //| -//| Send some bytes to a specific address. -//| Suits sockets of type SOCK_DGRAM -//| -//| :param ~bytes bytes: some bytes to send -//| :param ~tuple address: tuple of (remote_address, remote_port) +//| :param ~bytes bytes: some bytes to send +//| :param ~tuple address: tuple of (remote_address, remote_port)""" +//| ... //| STATIC mp_obj_t socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_in) { @@ -347,16 +349,16 @@ STATIC mp_obj_t socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_ } STATIC MP_DEFINE_CONST_FUN_OBJ_3(socket_sendto_obj, socket_sendto); -//| .. method:: recvfrom(bufsize) -//| -//| Reads some bytes from the connected remote address. -//| Suits sockets of type SOCK_STREAM +//| def recvfrom(self, bufsize: int) -> Any: +//| """Reads some bytes from the connected remote address. +//| Suits sockets of type SOCK_STREAM //| -//| Returns a tuple containing -//| * a bytes() of length <= bufsize -//| * a remote_address, which is a tuple of ip address and port number +//| Returns a tuple containing +//| * a bytes() of length <= bufsize +//| * a remote_address, which is a tuple of ip address and port number //| -//| :param ~int bufsize: maximum number of bytes to receive +//| :param ~int bufsize: maximum number of bytes to receive""" +//| ... //| STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) { @@ -386,9 +388,9 @@ STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_recvfrom_obj, socket_recvfrom); -//| .. method:: setsockopt(level, optname, value) -//| -//| Sets socket options +//| def setsockopt(self, level: Any, optname: Any, value: Any) -> Any: +//| """Sets socket options""" +//| ... //| STATIC mp_obj_t socket_setsockopt(size_t n_args, const mp_obj_t *args) { @@ -420,11 +422,11 @@ STATIC mp_obj_t socket_setsockopt(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_setsockopt_obj, 4, 4, socket_setsockopt); -//| .. method:: settimeout(value) +//| def settimeout(self, value: int) -> Any: +//| """Set the timeout value for this socket. //| -//| Set the timeout value for this socket. -//| -//| :param ~int value: timeout in seconds. 0 means non-blocking. None means block indefinitely. +//| :param ~int value: timeout in seconds. 0 means non-blocking. None means block indefinitely.""" +//| ... //| STATIC mp_obj_t socket_settimeout(mp_obj_t self_in, mp_obj_t timeout_in) { @@ -451,11 +453,11 @@ STATIC mp_obj_t socket_settimeout(mp_obj_t self_in, mp_obj_t timeout_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_settimeout_obj, socket_settimeout); -//| .. method:: setblocking(flag) -//| -//| Set the blocking behaviour of this socket. +//| def setblocking(self, flag: bool) -> Any: +//| """Set the blocking behaviour of this socket. //| -//| :param ~bool flag: False means non-blocking, True means block indefinitely. +//| :param ~bool flag: False means non-blocking, True means block indefinitely.""" +//| ... //| // method socket.setblocking(flag) @@ -513,13 +515,13 @@ STATIC const mp_obj_type_t socket_type = { .locals_dict = (mp_obj_dict_t*)&socket_locals_dict, }; -//| .. function:: getaddrinfo(host, port) -//| -//| Gets the address information for a hostname and port +//| def getaddrinfo(host: Any, port: Any) -> Any: +//| """Gets the address information for a hostname and port //| -//| Returns the appropriate family, socket type, socket protocol and -//| address information to call socket.socket() and socket.connect() with, -//| as a tuple. +//| Returns the appropriate family, socket type, socket protocol and +//| address information to call socket.socket() and socket.connect() with, +//| as a tuple.""" +//| ... //| STATIC mp_obj_t socket_getaddrinfo(mp_obj_t host_in, mp_obj_t port_in) { diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c index ba439b951..feb1a9bd7 100644 --- a/shared-bindings/storage/__init__.c +++ b/shared-bindings/storage/__init__.c @@ -35,7 +35,7 @@ #include "shared-bindings/storage/__init__.h" #include "supervisor/shared/translate.h" -//| :mod:`storage` --- storage management +//| """:mod:`storage` --- storage management //| ======================================================== //| //| .. module:: storage @@ -45,16 +45,16 @@ //| The `storage` provides storage management functionality such as mounting and //| unmounting which is typically handled by the operating system hosting Python. //| CircuitPython does not have an OS, so this module provides this functionality -//| directly. +//| directly.""" //| -//| .. function:: mount(filesystem, mount_path, *, readonly=False) +//| def mount(filesystem: Any, mount_path: Any, *, readonly: bool = False) -> Any: +//| """Mounts the given filesystem object at the given path. //| -//| Mounts the given filesystem object at the given path. +//| This is the CircuitPython analog to the UNIX ``mount`` command. //| -//| This is the CircuitPython analog to the UNIX ``mount`` command. -//| -//| :param bool readonly: True when the filesystem should be readonly to CircuitPython. +//| :param bool readonly: True when the filesystem should be readonly to CircuitPython.""" +//| ... //| mp_obj_t storage_mount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_readonly }; @@ -85,12 +85,12 @@ mp_obj_t storage_mount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_arg } MP_DEFINE_CONST_FUN_OBJ_KW(storage_mount_obj, 2, storage_mount); -//| .. function:: umount(mount) -//| -//| Unmounts the given filesystem object or if *mount* is a path, then unmount -//| the filesystem mounted at that location. +//| def umount(mount: Any) -> Any: +//| """Unmounts the given filesystem object or if *mount* is a path, then unmount +//| the filesystem mounted at that location. //| -//| This is the CircuitPython analog to the UNIX ``umount`` command. +//| This is the CircuitPython analog to the UNIX ``umount`` command.""" +//| ... //| mp_obj_t storage_umount(mp_obj_t mnt_in) { if (MP_OBJ_IS_STR(mnt_in)) { @@ -103,15 +103,15 @@ mp_obj_t storage_umount(mp_obj_t mnt_in) { } MP_DEFINE_CONST_FUN_OBJ_1(storage_umount_obj, storage_umount); -//| .. function:: remount(mount_path, readonly=False, *, disable_concurrent_write_protection=False) +//| def remount(mount_path: Any, readonly: bool = False, *, disable_concurrent_write_protection: bool = False) -> Any: +//| """Remounts the given path with new parameters. //| -//| Remounts the given path with new parameters. -//| -//| :param bool readonly: True when the filesystem should be readonly to CircuitPython. -//| :param bool disable_concurrent_write_protection: When True, the check that makes sure the -//| underlying filesystem data is written by one computer is disabled. Disabling the protection -//| allows CircuitPython and a host to write to the same filesystem with the risk that the -//| filesystem will be corrupted. +//| :param bool readonly: True when the filesystem should be readonly to CircuitPython. +//| :param bool disable_concurrent_write_protection: When True, the check that makes sure the +//| underlying filesystem data is written by one computer is disabled. Disabling the protection +//| allows CircuitPython and a host to write to the same filesystem with the risk that the +//| filesystem will be corrupted.""" +//| ... //| mp_obj_t storage_remount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_readonly, ARG_disable_concurrent_write_protection }; @@ -133,28 +133,29 @@ mp_obj_t storage_remount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_a } MP_DEFINE_CONST_FUN_OBJ_KW(storage_remount_obj, 1, storage_remount); -//| .. function:: getmount(mount_path) -//| -//| Retrieves the mount object associated with the mount path +//| def getmount(mount_path: Any) -> Any: +//| """Retrieves the mount object associated with the mount path""" +//| ... //| mp_obj_t storage_getmount(const mp_obj_t mnt_in) { return common_hal_storage_getmount(mp_obj_str_get_str(mnt_in)); } MP_DEFINE_CONST_FUN_OBJ_1(storage_getmount_obj, storage_getmount); -//| .. function:: erase_filesystem() +//| def erase_filesystem() -> Any: +//| """Erase and re-create the ``CIRCUITPY`` filesystem. //| -//| Erase and re-create the ``CIRCUITPY`` filesystem. +//| On boards that present USB-visible ``CIRCUITPY`` drive (e.g., SAMD21 and SAMD51), +//| then call `microcontroller.reset()` to restart CircuitPython and have the +//| host computer remount CIRCUITPY. //| -//| On boards that present USB-visible ``CIRCUITPY`` drive (e.g., SAMD21 and SAMD51), -//| then call `microcontroller.reset()` to restart CircuitPython and have the -//| host computer remount CIRCUITPY. +//| This function can be called from the REPL when ``CIRCUITPY`` +//| has become corrupted. //| -//| This function can be called from the REPL when ``CIRCUITPY`` -//| has become corrupted. +//| .. warning:: All the data on ``CIRCUITPY`` will be lost, and +//| CircuitPython will restart on certain boards.""" +//| ... //| -//| .. warning:: All the data on ``CIRCUITPY`` will be lost, and -//| CircuitPython will restart on certain boards. mp_obj_t storage_erase_filesystem(void) { common_hal_storage_erase_filesystem(); @@ -171,54 +172,53 @@ STATIC const mp_rom_map_elem_t storage_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR_getmount), MP_ROM_PTR(&storage_getmount_obj) }, { MP_ROM_QSTR(MP_QSTR_erase_filesystem), MP_ROM_PTR(&storage_erase_filesystem_obj) }, - //| .. class:: VfsFat(block_device) - //| - //| Create a new VfsFat filesystem around the given block device. - //| - //| :param block_device: Block device the the filesystem lives on - //| - //| .. attribute:: label - //| - //| The filesystem label, up to 11 case-insensitive bytes. Note that - //| this property can only be set when the device is writable by the - //| microcontroller. - //| - //| .. method:: mkfs() - //| - //| Format the block device, deleting any data that may have been there - //| - //| .. method:: open(path, mode) - //| - //| Like builtin ``open()`` - //| - //| .. method:: ilistdir([path]) - //| - //| Return an iterator whose values describe files and folders within - //| ``path`` - //| - //| .. method:: mkdir(path) + //| class VfsFat: + //| def __init__(self, block_device: Any): ... + //| """Create a new VfsFat filesystem around the given block device. //| - //| Like `os.mkdir` + //| :param block_device: Block device the the filesystem lives on""" //| - //| .. method:: rmdir(path) + //| label: Any = ... + //| """The filesystem label, up to 11 case-insensitive bytes. Note that + //| this property can only be set when the device is writable by the + //| microcontroller.""" //| - //| Like `os.rmdir` + //| def mkfs(self, ) -> Any: + //| """Format the block device, deleting any data that may have been there""" + //| ... //| - //| .. method:: stat(path) + //| def open(self, path: Any, mode: Any) -> Any: + //| """Like builtin ``open()``""" + //| ... //| - //| Like `os.stat` + //| def ilistdir(self, path: Any) -> Any: + //| """Return an iterator whose values describe files and folders within + //| ``path``""" + //| ... //| - //| .. method:: statvfs(path) + //| def mkdir(self, path: Any) -> Any: + //| """Like `os.mkdir`""" + //| ... //| - //| Like `os.statvfs` + //| def rmdir(self, path: Any) -> Any: + //| """Like `os.rmdir`""" + //| ... //| - //| .. method:: mount(readonly, mkfs) + //| def stat(self, path: Any) -> Any: + //| """Like `os.stat`""" + //| ... //| - //| Don't call this directly, call `storage.mount`. + //| def statvfs(self, path: Any) -> Any: + //| """Like `os.statvfs`""" + //| ... //| - //| .. method:: umount() + //| def mount(self, readonly: Any, mkfs: Any) -> Any: + //| """Don't call this directly, call `storage.mount`.""" + //| ... //| - //| Don't call this directly, call `storage.umount`. + //| def umount(self, ) -> Any: + //| """Don't call this directly, call `storage.umount`.""" + //| ... //| { MP_ROM_QSTR(MP_QSTR_VfsFat), MP_ROM_PTR(&mp_fat_vfs_type) }, }; -- cgit v1.2.3 From 040beb0577f4360f34953db16c285a9af1bea6b8 Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Mon, 11 May 2020 21:15:40 -0700 Subject: Clean up circle documentation --- shared-bindings/vectorio/Circle.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'shared-bindings') diff --git a/shared-bindings/vectorio/Circle.c b/shared-bindings/vectorio/Circle.c index 8f409bd65..260e80d0f 100644 --- a/shared-bindings/vectorio/Circle.c +++ b/shared-bindings/vectorio/Circle.c @@ -17,6 +17,8 @@ //| //| .. class:: Circle(radius) //| +//| Circle is positioned on screen by its center point. +//| //| :param int radius: The radius of the circle in pixels //| static mp_obj_t vectorio_circle_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -42,7 +44,7 @@ static mp_obj_t vectorio_circle_make_new(const mp_obj_type_t *type, size_t n_arg //| .. attribute:: radius //| -//| Update the radius of the circle +//| The radius of the circle in pixels. //| STATIC mp_obj_t vectorio_circle_obj_get_radius(mp_obj_t self_in) { vectorio_circle_t *self = MP_OBJ_TO_PTR(self_in); -- cgit v1.2.3 From 78444a1018f5a9dbac6e2fac1b7385970accedbc Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Mon, 11 May 2020 21:21:05 -0700 Subject: fix VectorShape on_dirty callback registration being set for the wrong type --- shared-bindings/vectorio/VectorShape.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'shared-bindings') diff --git a/shared-bindings/vectorio/VectorShape.c b/shared-bindings/vectorio/VectorShape.c index 02a42536d..4b39ec996 100644 --- a/shared-bindings/vectorio/VectorShape.c +++ b/shared-bindings/vectorio/VectorShape.c @@ -85,8 +85,8 @@ STATIC mp_obj_t vectorio_vector_shape_make_new(const mp_obj_type_t *type, size_t if (MP_OBJ_IS_TYPE(shape, &vectorio_polygon_type)) { common_hal_vectorio_polygon_set_on_dirty(self->ishape.shape, on_dirty); } else if (MP_OBJ_IS_TYPE(shape, &vectorio_rectangle_type)) { - common_hal_vectorio_circle_set_on_dirty(self->ishape.shape, on_dirty); } else if (MP_OBJ_IS_TYPE(shape, &vectorio_circle_type)) { + common_hal_vectorio_circle_set_on_dirty(self->ishape.shape, on_dirty); } else { mp_raise_TypeError_varg(translate("unsupported %q type"), MP_QSTR_shape); } -- cgit v1.2.3 From 22bf99ccc438e499378af099a446d1c6d9b542ac Mon Sep 17 00:00:00 2001 From: Daniel Pollard Date: Tue, 12 May 2020 14:52:48 +1000 Subject: Fixed underline in documentation --- shared-bindings/countio/Counter.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c index 1777acc8a..d9d97f0ea 100644 --- a/shared-bindings/countio/Counter.c +++ b/shared-bindings/countio/Counter.c @@ -12,13 +12,13 @@ //| .. currentmodule:: countio //| //| :class:`Counter` -- Track the count of falling edge transistions (pulses) on a given pin -//| ==================================================================================== +//| ======================================================================================== //| //| Counter will keep track of the number of falling edge transistions (pulses) on a given pin //| //| .. class:: Counter(pin_a) //| -//| Create an Counter object associated with the given pin. It tracks the number of +//| Create a Counter object associated with the given pin. It tracks the number of //| falling pulses relative when the object is constructed. //| //| :param ~microcontroller.Pin pin_a: Pin to read pulses from. -- cgit v1.2.3 From 991045b9ce958db9d7102d621f4e7860301e4c21 Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 12 May 2020 11:28:33 -0400 Subject: Did struct, supervisor, terminalio --- shared-bindings/struct/__init__.c | 48 +++++++++++++++++------------------ shared-bindings/supervisor/Runtime.c | 41 +++++++++++++++--------------- shared-bindings/supervisor/__init__.c | 47 +++++++++++++++++----------------- shared-bindings/terminalio/Terminal.c | 26 +++++++++---------- shared-bindings/terminalio/__init__.c | 4 +-- 5 files changed, 82 insertions(+), 84 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/struct/__init__.c b/shared-bindings/struct/__init__.c index ea14b3763..3772f93a7 100644 --- a/shared-bindings/struct/__init__.c +++ b/shared-bindings/struct/__init__.c @@ -38,7 +38,7 @@ #include "shared-module/struct/__init__.h" #include "supervisor/shared/translate.h" -//| :mod:`struct` --- manipulation of c-style data +//| """:mod:`struct` --- manipulation of c-style data //| ======================================================== //| //| .. module:: struct @@ -52,13 +52,13 @@ //| Supported size/byte order prefixes: *@*, *<*, *>*, *!*. //| //| Supported format codes: *b*, *B*, *x*, *h*, *H*, *i*, *I*, *l*, *L*, *q*, *Q*, -//| *s*, *P*, *f*, *d* (the latter 2 depending on the floating-point support). +//| *s*, *P*, *f*, *d* (the latter 2 depending on the floating-point support).""" //| -//| .. function:: calcsize(fmt) -//| -//| Return the number of bytes needed to store the given fmt. +//| def calcsize(fmt: Any) -> Any: +//| """Return the number of bytes needed to store the given fmt.""" +//| ... //| STATIC mp_obj_t struct_calcsize(mp_obj_t fmt_in) { @@ -67,10 +67,10 @@ STATIC mp_obj_t struct_calcsize(mp_obj_t fmt_in) { } MP_DEFINE_CONST_FUN_OBJ_1(struct_calcsize_obj, struct_calcsize); -//| .. function:: pack(fmt, *values) -//| -//| Pack the values according to the format string fmt. -//| The return value is a bytes object encoding the values. +//| def pack(fmt: Any, *values: Any) -> Any: +//| """Pack the values according to the format string fmt. +//| The return value is a bytes object encoding the values.""" +//| ... //| STATIC mp_obj_t struct_pack(size_t n_args, const mp_obj_t *args) { @@ -85,10 +85,10 @@ STATIC mp_obj_t struct_pack(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(struct_pack_obj, 1, MP_OBJ_FUN_ARGS_MAX, struct_pack); -//| .. function:: pack_into(fmt, buffer, offset, *values) -//| -//| Pack the values according to the format string fmt into a buffer -//| starting at offset. offset may be negative to count from the end of buffer. +//| def pack_into(fmt: Any, buffer: Any, offset: Any, *values: Any) -> Any: +//| """Pack the values according to the format string fmt into a buffer +//| starting at offset. offset may be negative to count from the end of buffer.""" +//| ... //| STATIC mp_obj_t struct_pack_into(size_t n_args, const mp_obj_t *args) { @@ -111,11 +111,11 @@ STATIC mp_obj_t struct_pack_into(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(struct_pack_into_obj, 3, MP_OBJ_FUN_ARGS_MAX, struct_pack_into); -//| .. function:: unpack(fmt, data) -//| -//| Unpack from the data according to the format string fmt. The return value -//| is a tuple of the unpacked values. The buffer size must match the size -//| required by the format. +//| def unpack(fmt: Any, data: Any) -> Any: +//| """Unpack from the data according to the format string fmt. The return value +//| is a tuple of the unpacked values. The buffer size must match the size +//| required by the format.""" +//| ... //| STATIC mp_obj_t struct_unpack(size_t n_args, const mp_obj_t *args) { @@ -129,12 +129,12 @@ STATIC mp_obj_t struct_unpack(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(struct_unpack_obj, 2, 3, struct_unpack); -//| .. function:: unpack_from(fmt, data, offset=0) -//| -//| Unpack from the data starting at offset according to the format string fmt. -//| offset may be negative to count from the end of buffer. The return value is -//| a tuple of the unpacked values. The buffer size must be at least as big -//| as the size required by the form. +//| def unpack_from(fmt: Any, data: Any, offset: Any = 0) -> Any: +//| """Unpack from the data starting at offset according to the format string fmt. +//| offset may be negative to count from the end of buffer. The return value is +//| a tuple of the unpacked values. The buffer size must be at least as big +//| as the size required by the form.""" +//| ... //| STATIC mp_obj_t struct_unpack_from(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { diff --git a/shared-bindings/supervisor/Runtime.c b/shared-bindings/supervisor/Runtime.c index 746dfe5ee..05921899c 100755 --- a/shared-bindings/supervisor/Runtime.c +++ b/shared-bindings/supervisor/Runtime.c @@ -29,35 +29,35 @@ #include "shared-bindings/supervisor/Runtime.h" //TODO: add USB, REPL to description once they're operational -//| .. currentmodule:: supervisor +//| class Runtime: +//| """.. currentmodule:: supervisor //| -//| :class:`Runtime` --- Supervisor Runtime information -//| ---------------------------------------------------- +//| :class:`Runtime` --- Supervisor Runtime information +//| ---------------------------------------------------- //| -//| Get current status of runtime objects. +//| Get current status of runtime objects. //| -//| Usage:: +//| Usage:: //| -//| import supervisor -//| if supervisor.runtime.serial_connected: -//| print("Hello World!") +//| import supervisor +//| if supervisor.runtime.serial_connected: +//| print("Hello World!")""" //| -//| .. class:: Runtime() -//| -//| You cannot create an instance of `supervisor.Runtime`. -//| Use `supervisor.runtime` to access the sole instance available. +//| def __init__(self, ): +//| """You cannot create an instance of `supervisor.Runtime`. +//| Use `supervisor.runtime` to access the sole instance available.""" +//| ... //| -//| .. attribute:: runtime.serial_connected -//| -//| Returns the USB serial communication status (read-only). +//| runtime.serial_connected: Any = ... +//| """Returns the USB serial communication status (read-only). //| //| .. note:: //| //| SAMD: Will return ``True`` if the USB serial connection //| has been established at any point. Will not reset if -//| USB is disconnected but power remains (e.g. battery connected) +//| USB is disconnected but power remains (e.g. battery connected)""" //| STATIC mp_obj_t supervisor_get_serial_connected(mp_obj_t self){ @@ -78,11 +78,10 @@ const mp_obj_property_t supervisor_serial_connected_obj = { }; -//| .. attribute:: runtime.serial_bytes_available -//| -//| Returns the whether any bytes are available to read -//| on the USB serial input. Allows for polling to see whether -//| to call the built-in input() or wait. (read-only) +//| runtime.serial_bytes_available: Any = ... +//| """Returns the whether any bytes are available to read +//| on the USB serial input. Allows for polling to see whether +//| to call the built-in input() or wait. (read-only)""" //| STATIC mp_obj_t supervisor_get_serial_bytes_available(mp_obj_t self){ if (!common_hal_get_serial_bytes_available()) { diff --git a/shared-bindings/supervisor/__init__.c b/shared-bindings/supervisor/__init__.c index 2705c8e58..7fe6668f4 100644 --- a/shared-bindings/supervisor/__init__.c +++ b/shared-bindings/supervisor/__init__.c @@ -36,7 +36,7 @@ #include "shared-bindings/supervisor/__init__.h" #include "shared-bindings/supervisor/Runtime.h" -//| :mod:`supervisor` --- Supervisor settings +//| """:mod:`supervisor` --- Supervisor settings //| ================================================= //| //| .. module:: supervisor @@ -50,19 +50,18 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| Runtime +//| Runtime""" //| -//| .. attribute:: runtime -//| -//| Runtime information, such as `runtime.serial_connected` -//| (USB serial connection status). -//| This object is the sole instance of `supervisor.Runtime`. +//| runtime: Any = ... +//| """Runtime information, such as `runtime.serial_connected` +//| (USB serial connection status). +//| This object is the sole instance of `supervisor.Runtime`.""" //| -//| .. method:: enable_autoreload() -//| -//| Enable autoreload based on USB file write activity. +//| def enable_autoreload(self, ) -> Any: +//| """Enable autoreload based on USB file write activity.""" +//| ... //| STATIC mp_obj_t supervisor_enable_autoreload(void) { autoreload_enable(); @@ -70,10 +69,10 @@ STATIC mp_obj_t supervisor_enable_autoreload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_enable_autoreload_obj, supervisor_enable_autoreload); -//| .. method:: disable_autoreload() -//| -//| Disable autoreload based on USB file write activity until -//| `enable_autoreload` is called. +//| def disable_autoreload(self, ) -> Any: +//| """Disable autoreload based on USB file write activity until +//| `enable_autoreload` is called.""" +//| ... //| STATIC mp_obj_t supervisor_disable_autoreload(void) { autoreload_disable(); @@ -81,10 +80,10 @@ STATIC mp_obj_t supervisor_disable_autoreload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_disable_autoreload_obj, supervisor_disable_autoreload); -//| .. method:: set_rgb_status_brightness() -//| -//| Set brightness of status neopixel from 0-255 -//| `set_rgb_status_brightness` is called. +//| def set_rgb_status_brightness(self, ) -> Any: +//| """Set brightness of status neopixel from 0-255 +//| `set_rgb_status_brightness` is called.""" +//| ... //| STATIC mp_obj_t supervisor_set_rgb_status_brightness(mp_obj_t lvl){ // This must be int. If cast to uint8_t first, will never raise a ValueError. @@ -97,9 +96,9 @@ STATIC mp_obj_t supervisor_set_rgb_status_brightness(mp_obj_t lvl){ } MP_DEFINE_CONST_FUN_OBJ_1(supervisor_set_rgb_status_brightness_obj, supervisor_set_rgb_status_brightness); -//| .. method:: reload() -//| -//| Reload the main Python code and run it (equivalent to hitting Ctrl-D at the REPL). +//| def reload(self, ) -> Any: +//| """Reload the main Python code and run it (equivalent to hitting Ctrl-D at the REPL).""" +//| ... //| STATIC mp_obj_t supervisor_reload(void) { reload_requested = true; @@ -108,9 +107,9 @@ STATIC mp_obj_t supervisor_reload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_reload_obj, supervisor_reload); -//| .. method:: set_next_stack_limit(size) -//| -//| Set the size of the stack for the next vm run. If its too large, the default will be used. +//| def set_next_stack_limit(self, size: Any) -> Any: +//| """Set the size of the stack for the next vm run. If its too large, the default will be used.""" +//| ... //| STATIC mp_obj_t supervisor_set_next_stack_limit(mp_obj_t size_obj) { mp_int_t size = mp_obj_get_int(size_obj); diff --git a/shared-bindings/terminalio/Terminal.c b/shared-bindings/terminalio/Terminal.c index 9c01fba20..1288b7018 100644 --- a/shared-bindings/terminalio/Terminal.c +++ b/shared-bindings/terminalio/Terminal.c @@ -37,16 +37,16 @@ #include "shared-bindings/fontio/BuiltinFont.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: terminalio -//| -//| :class:`Terminal` -- display a character stream with a TileGrid -//| ================================================================ +//| class Terminal: +//| """.. currentmodule:: terminalio //| -//| .. class:: Terminal(tilegrid, font) +//| :class:`Terminal` -- display a character stream with a TileGrid +//| ================================================================""" //| -//| Terminal manages tile indices and cursor position based on VT100 commands. The font should be -//| a `fontio.BuiltinFont` and the TileGrid's bitmap should match the font's bitmap. +//| def __init__(self, tilegrid: Any, font: Any): +//| """Terminal manages tile indices and cursor position based on VT100 commands. The font should be +//| a `fontio.BuiltinFont` and the TileGrid's bitmap should match the font's bitmap.""" +//| ... //| STATIC mp_obj_t terminalio_terminal_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -75,12 +75,12 @@ STATIC mp_obj_t terminalio_terminal_make_new(const mp_obj_type_t *type, size_t n // These are standard stream methods. Code is in py/stream.c. // -//| .. method:: write(buf) -//| -//| Write the buffer of bytes to the bus. +//| def write(self, buf: Any) -> Any: +//| """Write the buffer of bytes to the bus. //| -//| :return: the number of bytes written -//| :rtype: int or None +//| :return: the number of bytes written +//| :rtype: int or None""" +//| ... //| STATIC mp_uint_t terminalio_terminal_write(mp_obj_t self_in, const void *buf_in, mp_uint_t size, int *errcode) { terminalio_terminal_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/terminalio/__init__.c b/shared-bindings/terminalio/__init__.c index a9fe20f30..591be839a 100644 --- a/shared-bindings/terminalio/__init__.c +++ b/shared-bindings/terminalio/__init__.c @@ -35,7 +35,7 @@ #include "py/runtime.h" -//| :mod:`terminalio` --- Displays text in a TileGrid +//| """:mod:`terminalio` --- Displays text in a TileGrid //| ================================================= //| //| .. module:: terminalio @@ -49,7 +49,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| Terminal +//| Terminal""" //| //| STATIC const mp_rom_map_elem_t terminalio_module_globals_table[] = { -- cgit v1.2.3 From e4589543fbe8df12f5c30101e94ddc0fa95cd29e Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 12 May 2020 11:43:24 -0400 Subject: Did time, touchio, uheap --- shared-bindings/time/__init__.c | 103 +++++++++++++++++++------------------ shared-bindings/touchio/TouchIn.c | 68 ++++++++++++------------ shared-bindings/touchio/__init__.c | 4 +- shared-bindings/uheap/__init__.c | 12 ++--- 4 files changed, 93 insertions(+), 94 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c index 8d7f2f3fd..36eaa27f6 100644 --- a/shared-bindings/time/__init__.c +++ b/shared-bindings/time/__init__.c @@ -36,7 +36,7 @@ #include "shared-bindings/time/__init__.h" #include "supervisor/shared/translate.h" -//| :mod:`time` --- time and timing related functions +//| """:mod:`time` --- time and timing related functions //| ======================================================== //| //| .. module:: time @@ -45,15 +45,15 @@ //| //| The `time` module is a strict subset of the CPython `cpython:time` module. So, code //| written in MicroPython will work in CPython but not necessarily the other -//| way around. +//| way around.""" //| -//| .. function:: monotonic() +//| def monotonic() -> Any: +//| """Returns an always increasing value of time with an unknown reference +//| point. Only use it to compare against other values from `monotonic`. //| -//| Returns an always increasing value of time with an unknown reference -//| point. Only use it to compare against other values from `monotonic`. -//| -//| :return: the current monotonic time -//| :rtype: float +//| :return: the current monotonic time +//| :rtype: float""" +//| ... //| STATIC mp_obj_t time_monotonic(void) { uint64_t time64 = common_hal_time_monotonic(); @@ -62,11 +62,11 @@ STATIC mp_obj_t time_monotonic(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_monotonic_obj, time_monotonic); -//| .. function:: sleep(seconds) -//| -//| Sleep for a given number of seconds. +//| def sleep(seconds: float) -> Any: +//| """Sleep for a given number of seconds. //| -//| :param float seconds: the time to sleep in fractional seconds +//| :param float seconds: the time to sleep in fractional seconds""" +//| ... //| STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) { #if MICROPY_PY_BUILTINS_FLOAT @@ -97,21 +97,22 @@ mp_obj_t struct_time_make_new(const mp_obj_type_t *type, size_t n_args, const mp return namedtuple_make_new(type, 9, tuple->items, NULL); } -//| .. class:: struct_time(time_tuple) +//| class struct_time: +//| def __init__(self, time_tuple: Any): +//| """Structure used to capture a date and time. Note that it takes a tuple! //| -//| Structure used to capture a date and time. Note that it takes a tuple! +//| :param tuple time_tuple: Tuple of time info: ``(tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)`` //| -//| :param tuple time_tuple: Tuple of time info: ``(tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)`` -//| -//| * ``tm_year``: the year, 2017 for example -//| * ``tm_month``: the month, range [1, 12] -//| * ``tm_mday``: the day of the month, range [1, 31] -//| * ``tm_hour``: the hour, range [0, 23] -//| * ``tm_minute``: the minute, range [0, 59] -//| * ``tm_sec``: the second, range [0, 61] -//| * ``tm_wday``: the day of the week, range [0, 6], Monday is 0 -//| * ``tm_yday``: the day of the year, range [1, 366], -1 indicates not known -//| * ``tm_isdst``: 1 when in daylight savings, 0 when not, -1 if unknown. +//| * ``tm_year``: the year, 2017 for example +//| * ``tm_month``: the month, range [1, 12] +//| * ``tm_mday``: the day of the month, range [1, 31] +//| * ``tm_hour``: the hour, range [0, 23] +//| * ``tm_minute``: the minute, range [0, 59] +//| * ``tm_sec``: the second, range [0, 61] +//| * ``tm_wday``: the day of the week, range [0, 6], Monday is 0 +//| * ``tm_yday``: the day of the year, range [1, 366], -1 indicates not known +//| * ``tm_isdst``: 1 when in daylight savings, 0 when not, -1 if unknown.""" +//| ... //| const mp_obj_namedtuple_type_t struct_time_type_obj = { .base = { @@ -194,12 +195,12 @@ mp_obj_t MP_WEAK rtc_get_time_source_time(void) { mp_raise_RuntimeError(translate("RTC is not supported on this board")); } -//| .. function:: time() -//| -//| Return the current time in seconds since since Jan 1, 1970. +//| def time() -> Any: +//| """Return the current time in seconds since since Jan 1, 1970. //| -//| :return: the current time -//| :rtype: int +//| :return: the current time +//| :rtype: int""" +//| ... //| STATIC mp_obj_t time_time(void) { timeutils_struct_time_t tm; @@ -210,12 +211,12 @@ STATIC mp_obj_t time_time(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_time_obj, time_time); -//| .. function:: monotonic_ns() +//| def monotonic_ns() -> Any: +//| """Return the time of the specified clock clk_id in nanoseconds. //| -//| Return the time of the specified clock clk_id in nanoseconds. -//| -//| :return: the current time -//| :rtype: int +//| :return: the current time +//| :rtype: int""" +//| ... //| STATIC mp_obj_t time_monotonic_ns(void) { uint64_t time64 = common_hal_time_monotonic_ns(); @@ -223,15 +224,15 @@ STATIC mp_obj_t time_monotonic_ns(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_monotonic_ns_obj, time_monotonic_ns); -//| .. function:: localtime([secs]) -//| -//| Convert a time expressed in seconds since Jan 1, 1970 to a struct_time in -//| local time. If secs is not provided or None, the current time as returned -//| by time() is used. -//| The earliest date for which it can generate a time is Jan 1, 2000. +//| def localtime(secs: Any) -> Any: +//| """Convert a time expressed in seconds since Jan 1, 1970 to a struct_time in +//| local time. If secs is not provided or None, the current time as returned +//| by time() is used. +//| The earliest date for which it can generate a time is Jan 1, 2000. //| -//| :return: the current time -//| :rtype: time.struct_time +//| :return: the current time +//| :rtype: time.struct_time""" +//| ... //| STATIC mp_obj_t time_localtime(size_t n_args, const mp_obj_t *args) { if (n_args == 0 || args[0] == mp_const_none) { @@ -256,15 +257,15 @@ STATIC mp_obj_t time_localtime(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(time_localtime_obj, 0, 1, time_localtime); -//| .. function:: mktime(t) -//| -//| This is the inverse function of localtime(). Its argument is the -//| struct_time or full 9-tuple (since the dst flag is needed; use -1 as the -//| dst flag if it is unknown) which expresses the time in local time, not UTC. -//| The earliest date for which it can generate a time is Jan 1, 2000. +//| def mktime(t: Any) -> Any: +//| """This is the inverse function of localtime(). Its argument is the +//| struct_time or full 9-tuple (since the dst flag is needed; use -1 as the +//| dst flag if it is unknown) which expresses the time in local time, not UTC. +//| The earliest date for which it can generate a time is Jan 1, 2000. //| -//| :return: seconds -//| :rtype: int +//| :return: seconds +//| :rtype: int""" +//| ... //| STATIC mp_obj_t time_mktime(mp_obj_t t) { mp_obj_t *elem; diff --git a/shared-bindings/touchio/TouchIn.c b/shared-bindings/touchio/TouchIn.c index db53ec1bc..6d59a1744 100644 --- a/shared-bindings/touchio/TouchIn.c +++ b/shared-bindings/touchio/TouchIn.c @@ -38,27 +38,28 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: touchio +//| class TouchIn: +//| """.. currentmodule:: touchio //| -//| :class:`TouchIn` -- Read the state of a capacitive touch sensor -//| =================================================================== +//| :class:`TouchIn` -- Read the state of a capacitive touch sensor +//| =================================================================== //| -//| Usage:: +//| Usage:: //| -//| import touchio -//| from board import * +//| import touchio +//| from board import * //| -//| touch = touchio.TouchIn(A1) -//| while True: -//| if touch.value: -//| print("touched!") +//| touch = touchio.TouchIn(A1) +//| while True: +//| if touch.value: +//| print("touched!")""" //| -//| .. class:: TouchIn(pin) +//| def __init__(self, pin: microcontroller.Pin): +//| """Use the TouchIn on the given pin. //| -//| Use the TouchIn on the given pin. -//| -//| :param ~microcontroller.Pin pin: the pin to read from +//| :param ~microcontroller.Pin pin: the pin to read from""" +//| ... //| STATIC mp_obj_t touchio_touchin_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -75,9 +76,9 @@ STATIC mp_obj_t touchio_touchin_make_new(const mp_obj_type_t *type, return (mp_obj_t) self; } -//| .. method:: deinit() -//| -//| Deinitialises the TouchIn and releases any hardware resources for reuse. +//| def deinit(self, ) -> Any: +//| """Deinitialises the TouchIn and releases any hardware resources for reuse.""" +//| ... //| STATIC mp_obj_t touchio_touchin_deinit(mp_obj_t self_in) { touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -92,16 +93,16 @@ STATIC void check_for_deinit(touchio_touchin_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t touchio_touchin_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -110,11 +111,10 @@ STATIC mp_obj_t touchio_touchin_obj___exit__(size_t n_args, const mp_obj_t *args } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(touchio_touchin___exit___obj, 4, 4, touchio_touchin_obj___exit__); -//| .. attribute:: value +//| value: Any = ... +//| """Whether the touch pad is being touched or not. (read-only) //| -//| Whether the touch pad is being touched or not. (read-only) -//| -//| True when `raw_value` > `threshold`. +//| True when `raw_value` > `threshold`.""" //| STATIC mp_obj_t touchio_touchin_obj_get_value(mp_obj_t self_in) { touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -131,9 +131,8 @@ const mp_obj_property_t touchio_touchin_value_obj = { }; -//| .. attribute:: raw_value -//| -//| The raw touch measurement as an `int`. (read-only) +//| raw_value: Any = ... +//| """The raw touch measurement as an `int`. (read-only)""" //| STATIC mp_obj_t touchio_touchin_obj_get_raw_value(mp_obj_t self_in) { touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -151,14 +150,13 @@ const mp_obj_property_t touchio_touchin_raw_value_obj = { }; -//| .. attribute:: threshold -//| -//| Minimum `raw_value` needed to detect a touch (and for `value` to be `True`). +//| threshold: Any = ... +//| """Minimum `raw_value` needed to detect a touch (and for `value` to be `True`). //| //| When the **TouchIn** object is created, an initial `raw_value` is read from the pin, //| and then `threshold` is set to be 100 + that value. //| -//| You can adjust `threshold` to make the pin more or less sensitive. +//| You can adjust `threshold` to make the pin more or less sensitive.""" //| STATIC mp_obj_t touchio_touchin_obj_get_threshold(mp_obj_t self_in) { touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/touchio/__init__.c b/shared-bindings/touchio/__init__.c index 6adbe09cf..96367f082 100644 --- a/shared-bindings/touchio/__init__.c +++ b/shared-bindings/touchio/__init__.c @@ -35,7 +35,7 @@ #include "py/runtime.h" -//| :mod:`touchio` --- Touch related IO +//| """:mod:`touchio` --- Touch related IO //| ================================================= //| //| .. module:: touchio @@ -66,7 +66,7 @@ //| print(touch_pin.value) //| //| This example will initialize the the device, and print the -//| :py:data:`~touchio.TouchIn.value`. +//| :py:data:`~touchio.TouchIn.value`.""" //| STATIC const mp_rom_map_elem_t touchio_module_globals_table[] = { diff --git a/shared-bindings/uheap/__init__.c b/shared-bindings/uheap/__init__.c index 0d699cd28..f1be30424 100644 --- a/shared-bindings/uheap/__init__.c +++ b/shared-bindings/uheap/__init__.c @@ -31,17 +31,17 @@ #include "shared-bindings/uheap/__init__.h" -//| :mod:`uheap` --- Heap size analysis +//| """:mod:`uheap` --- Heap size analysis //| ================================================================ //| //| .. module:: uheap -//| :synopsis: Heap size analysis +//| :synopsis: Heap size analysis""" //| -//| .. function:: info(object) -//| -//| Prints memory debugging info for the given object and returns the -//| estimated size. +//| def info(object: Any) -> Any: +//| """Prints memory debugging info for the given object and returns the +//| estimated size.""" +//| ... //| STATIC mp_obj_t uheap_info(mp_obj_t obj) { uint32_t size = shared_module_uheap_info(obj); -- cgit v1.2.3 From 6490137812eb9f0c0b08ad81bc77ea21f5f31d04 Mon Sep 17 00:00:00 2001 From: dherrada Date: Tue, 12 May 2020 12:08:46 -0400 Subject: Did usb_hid, usb_midi, ustack, wiznet --- shared-bindings/usb_hid/Device.c | 39 +++++++++++++------------- shared-bindings/usb_hid/__init__.c | 14 +++++----- shared-bindings/usb_midi/PortIn.c | 46 +++++++++++++++---------------- shared-bindings/usb_midi/PortOut.c | 27 +++++++++--------- shared-bindings/usb_midi/__init__.c | 4 +-- shared-bindings/ustack/__init__.c | 31 +++++++++++---------- shared-bindings/wiznet/__init__.c | 4 +-- shared-bindings/wiznet/wiznet5k.c | 55 ++++++++++++++++++------------------- 8 files changed, 110 insertions(+), 110 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/usb_hid/Device.c b/shared-bindings/usb_hid/Device.c index b1097fb24..bcea5b2c5 100644 --- a/shared-bindings/usb_hid/Device.c +++ b/shared-bindings/usb_hid/Device.c @@ -27,27 +27,28 @@ #include "py/objproperty.h" #include "shared-bindings/usb_hid/Device.h" -//| .. currentmodule:: usb_hid +//| class Device: +//| """.. currentmodule:: usb_hid //| -//| :class:`Device` -- HID Device -//| ============================================ +//| :class:`Device` -- HID Device +//| ============================================ //| -//| Usage:: +//| Usage:: //| -//| import usb_hid +//| import usb_hid //| -//| mouse = usb_hid.devices[0] +//| mouse = usb_hid.devices[0] //| -//| mouse.send_report() +//| mouse.send_report()""" //| -//| .. class:: Device() +//| def __init__(self, ): +//| """Not currently dynamically supported.""" +//| ... //| -//| Not currently dynamically supported. -//| -//| .. method:: send_report(buf) -//| -//| Send a HID report. +//| def send_report(self, buf: Any) -> Any: +//| """Send a HID report.""" +//| ... //| STATIC mp_obj_t usb_hid_device_send_report(mp_obj_t self_in, mp_obj_t buffer) { usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -60,9 +61,8 @@ STATIC mp_obj_t usb_hid_device_send_report(mp_obj_t self_in, mp_obj_t buffer) { } MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_report); -//| .. attribute:: usage_page -//| -//| The usage page of the device as an `int`. Can be thought of a category. (read-only) +//| usage_page: Any = ... +//| """The usage page of the device as an `int`. Can be thought of a category. (read-only)""" //| STATIC mp_obj_t usb_hid_device_obj_get_usage_page(mp_obj_t self_in) { usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -77,12 +77,11 @@ const mp_obj_property_t usb_hid_device_usage_page_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: usage -//| -//| The functionality of the device as an int. (read-only) +//| usage: Any = ... +//| """The functionality of the device as an int. (read-only) //| //| For example, Keyboard is 0x06 within the generic desktop usage page 0x01. -//| Mouse is 0x02 within the same usage page. +//| Mouse is 0x02 within the same usage page.""" //| STATIC mp_obj_t usb_hid_device_obj_get_usage(mp_obj_t self_in) { usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/usb_hid/__init__.c b/shared-bindings/usb_hid/__init__.c index 3ad5b06e0..3d0978d62 100644 --- a/shared-bindings/usb_hid/__init__.c +++ b/shared-bindings/usb_hid/__init__.c @@ -31,27 +31,27 @@ #include "shared-bindings/usb_hid/__init__.h" #include "shared-bindings/usb_hid/Device.h" -//| :mod:`usb_hid` --- USB Human Interface Device +//| """:mod:`usb_hid` --- USB Human Interface Device //| =========================================================== //| //| .. module:: usb_hid //| :synopsis: USB Human Interface Device //| :platform: SAMD21 //| -//| The `usb_hid` module allows you to output data as a HID device. +//| The `usb_hid` module allows you to output data as a HID device.""" //| -//| .. attribute:: usb_hid.devices -//| -//| Tuple of all active HID device interfaces. +//| usb_hid.devices: Any = ... +//| """Tuple of all active HID device interfaces.""" //| -//| Libraries +//| """Libraries //| //| .. toctree:: //| :maxdepth: 3 //| -//| Device +//| Device""" +//| STATIC const mp_rom_map_elem_t usb_hid_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_usb_hid) }, { MP_ROM_QSTR(MP_QSTR_devices), MP_ROM_PTR(&common_hal_usb_hid_devices) }, diff --git a/shared-bindings/usb_midi/PortIn.c b/shared-bindings/usb_midi/PortIn.c index e2df56e95..55a5865ca 100644 --- a/shared-bindings/usb_midi/PortIn.c +++ b/shared-bindings/usb_midi/PortIn.c @@ -35,39 +35,39 @@ #include "py/stream.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: usb_midi -//| -//| :class:`PortIn` -- receives midi commands over USB -//| =================================================== +//| class PortIn: +//| """.. currentmodule:: usb_midi //| -//| .. class:: PortIn() +//| :class:`PortIn` -- receives midi commands over USB +//| ===================================================""" //| -//| You cannot create an instance of `usb_midi.PortIn`. +//| def __init__(self, ): +//| """You cannot create an instance of `usb_midi.PortIn`. //| -//| PortIn objects are constructed for every corresponding entry in the USB -//| descriptor and added to the ``usb_midi.ports`` tuple. +//| PortIn objects are constructed for every corresponding entry in the USB +//| descriptor and added to the ``usb_midi.ports`` tuple.""" +//| ... //| // These are standard stream methods. Code is in py/stream.c. // -//| .. method:: read(nbytes=None) -//| -//| Read characters. If ``nbytes`` is specified then read at most that many -//| bytes. Otherwise, read everything that arrives until the connection -//| times out. Providing the number of bytes expected is highly recommended -//| because it will be faster. -//| -//| :return: Data read -//| :rtype: bytes or None +//| def read(self, nbytes: Any = None) -> Any: +//| """Read characters. If ``nbytes`` is specified then read at most that many +//| bytes. Otherwise, read everything that arrives until the connection +//| times out. Providing the number of bytes expected is highly recommended +//| because it will be faster. //| -//| .. method:: readinto(buf, nbytes=None) +//| :return: Data read +//| :rtype: bytes or None""" +//| ... //| -//| Read bytes into the ``buf``. If ``nbytes`` is specified then read at most -//| that many bytes. Otherwise, read at most ``len(buf)`` bytes. +//| def readinto(self, buf: Any, nbytes: Any = None) -> Any: +//| """Read bytes into the ``buf``. If ``nbytes`` is specified then read at most +//| that many bytes. Otherwise, read at most ``len(buf)`` bytes. //| -//| :return: number of bytes read and stored into ``buf`` -//| :rtype: bytes or None +//| :return: number of bytes read and stored into ``buf`` +//| :rtype: bytes or None""" +//| ... //| // These three methods are used by the shared stream methods. diff --git a/shared-bindings/usb_midi/PortOut.c b/shared-bindings/usb_midi/PortOut.c index e3eddfaf5..d83eb53b6 100644 --- a/shared-bindings/usb_midi/PortOut.c +++ b/shared-bindings/usb_midi/PortOut.c @@ -35,28 +35,27 @@ #include "py/stream.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: usb_midi -//| -//| :class:`PortOut` -- sends midi messages to a computer over USB -//| ============================================================== +//| class PortOut: +//| """.. currentmodule:: usb_midi //| -//| .. class:: PortOut() +//| :class:`PortOut` -- sends midi messages to a computer over USB +//| ==============================================================""" //| -//| You cannot create an instance of `usb_midi.PortOut`. +//| def __init__(self, ): +//| """You cannot create an instance of `usb_midi.PortOut`. //| -//| PortOut objects are constructed for every corresponding entry in the USB -//| descriptor and added to the ``usb_midi.ports`` tuple. +//| PortOut objects are constructed for every corresponding entry in the USB +//| descriptor and added to the ``usb_midi.ports`` tuple.""" //| // These are standard stream methods. Code is in py/stream.c. // -//| .. method:: write(buf) -//| -//| Write the buffer of bytes to the bus. +//| def write(self, buf: Any) -> Any: +//| """Write the buffer of bytes to the bus. //| -//| :return: the number of bytes written -//| :rtype: int or None +//| :return: the number of bytes written +//| :rtype: int or None""" +//| ... //| STATIC mp_uint_t usb_midi_portout_write(mp_obj_t self_in, const void *buf_in, mp_uint_t size, int *errcode) { diff --git a/shared-bindings/usb_midi/__init__.c b/shared-bindings/usb_midi/__init__.c index f57d3631b..2631d8a88 100644 --- a/shared-bindings/usb_midi/__init__.c +++ b/shared-bindings/usb_midi/__init__.c @@ -35,7 +35,7 @@ #include "py/runtime.h" -//| :mod:`usb_midi` --- MIDI over USB +//| """:mod:`usb_midi` --- MIDI over USB //| ================================================= //| //| .. module:: usb_midi @@ -49,7 +49,7 @@ //| :maxdepth: 3 //| //| PortIn -//| PortOut +//| PortOut""" //| //| mp_map_elem_t usb_midi_module_globals_table[] = { diff --git a/shared-bindings/ustack/__init__.c b/shared-bindings/ustack/__init__.c index 08b772e41..073840aba 100644 --- a/shared-bindings/ustack/__init__.c +++ b/shared-bindings/ustack/__init__.c @@ -31,17 +31,20 @@ #include "shared-bindings/ustack/__init__.h" -//| :mod:`ustack` --- Stack information and analysis + + + +//| """:mod:`ustack` --- Stack information and analysis //| ======================================================== //| //| .. module:: ustack -//| :synopsis: stack information functions +//| :synopsis: stack information functions""" //| #if MICROPY_MAX_STACK_USAGE -//| .. function:: max_stack_usage() -//| -//| Return the maximum excursion of the stack so far. +//| def max_stack_usage() -> Any: +//| """Return the maximum excursion of the stack so far.""" +//| ... //| STATIC mp_obj_t max_stack_usage(void) { return MP_OBJ_NEW_SMALL_INT(shared_module_ustack_max_stack_usage()); @@ -50,21 +53,21 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_0(max_stack_usage_obj, max_stack_usage); #endif // MICROPY_MAX_STACK_USAGE -//| .. function:: stack_size() -//| -//| Return the size of the entire stack. -//| Same as in micropython.mem_info(), but returns a value instead -//| of just printing it. +//| def stack_size() -> Any: +//| """Return the size of the entire stack. +//| Same as in micropython.mem_info(), but returns a value instead +//| of just printing it.""" +//| ... //| STATIC mp_obj_t stack_size(void) { return MP_OBJ_NEW_SMALL_INT(shared_module_ustack_stack_size()); } STATIC MP_DEFINE_CONST_FUN_OBJ_0(stack_size_obj, stack_size); -//| .. function:: stack_usage() -//| -//| Return how much stack is currently in use. -//| Same as micropython.stack_use(); duplicated here for convenience. +//| def stack_usage() -> Any: +//| """Return how much stack is currently in use. +//| Same as micropython.stack_use(); duplicated here for convenience.""" +//| ... //| STATIC mp_obj_t stack_usage(void) { return MP_OBJ_NEW_SMALL_INT(shared_module_ustack_stack_usage()); diff --git a/shared-bindings/wiznet/__init__.c b/shared-bindings/wiznet/__init__.c index e230deecc..5c8e8d3fd 100644 --- a/shared-bindings/wiznet/__init__.c +++ b/shared-bindings/wiznet/__init__.c @@ -35,7 +35,7 @@ #include "shared-module/network/__init__.h" -//| :mod:`wiznet` --- Support for WizNet hardware +//| """:mod:`wiznet` --- Support for WizNet hardware //| ============================================= //| //| .. module:: wiznet @@ -49,7 +49,7 @@ //| .. toctree:: //| :maxdepth: 3 //| -//| wiznet5k +//| wiznet5k""" //| extern const mod_network_nic_type_t mod_network_nic_type_wiznet5k; diff --git a/shared-bindings/wiznet/wiznet5k.c b/shared-bindings/wiznet/wiznet5k.c index 786978bfe..2e2ee3949 100644 --- a/shared-bindings/wiznet/wiznet5k.c +++ b/shared-bindings/wiznet/wiznet5k.c @@ -46,25 +46,26 @@ #include "shared-module/network/__init__.h" #include "shared-module/wiznet/wiznet5k.h" -//| .. currentmodule:: wiznet +//| class WIZNET5K: +//| """.. currentmodule:: wiznet //| -//| :class:`WIZNET5K` -- wrapper for Wiznet 5500 Ethernet interface -//| =============================================================== +//| :class:`WIZNET5K` -- wrapper for Wiznet 5500 Ethernet interface +//| ===============================================================""" //| -//| .. class:: WIZNET5K(spi, cs, rst, dhcp=True) +//| def __init__(self, spi: busio.SPI, cs: microcontroller.Pin, rst: microcontroller.Pin, dhcp: bool = True): +//| """Create a new WIZNET5500 interface using the specified pins //| -//| Create a new WIZNET5500 interface using the specified pins +//| :param ~busio.SPI spi: spi bus to use +//| :param ~microcontroller.Pin cs: pin to use for Chip Select +//| :param ~microcontroller.Pin rst: pin to use for Reset (optional) +//| :param bool dhcp: boolean flag, whether to start DHCP automatically (optional, keyword only, default True) //| -//| :param ~busio.SPI spi: spi bus to use -//| :param ~microcontroller.Pin cs: pin to use for Chip Select -//| :param ~microcontroller.Pin rst: pin to use for Reset (optional) -//| :param bool dhcp: boolean flag, whether to start DHCP automatically (optional, keyword only, default True) -//| -//| * The reset pin is optional: if supplied it is used to reset the -//| wiznet board before initialization. -//| * The SPI bus will be initialized appropriately by this library. -//| * At present, the WIZNET5K object is a singleton, so only one WizNet -//| interface is supported at a time. +//| * The reset pin is optional: if supplied it is used to reset the +//| wiznet board before initialization. +//| * The SPI bus will be initialized appropriately by this library. +//| * At present, the WIZNET5K object is a singleton, so only one WizNet +//| interface is supported at a time.""" +//| ... //| STATIC mp_obj_t wiznet5k_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -86,9 +87,8 @@ STATIC mp_obj_t wiznet5k_make_new(const mp_obj_type_t *type, size_t n_args, cons return ret; } -//| .. attribute:: connected -//| -//| (boolean, readonly) is this device physically connected? +//| connected: Any = ... +//| """(boolean, readonly) is this device physically connected?""" //| STATIC mp_obj_t wiznet5k_connected_get_value(mp_obj_t self_in) { @@ -104,11 +104,10 @@ const mp_obj_property_t wiznet5k_connected_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: dhcp +//| dhcp: Any = ... +//| """(boolean, readwrite) is DHCP active on this device? //| -//| (boolean, readwrite) is DHCP active on this device? -//| -//| * set to True to activate DHCP, False to turn it off +//| * set to True to activate DHCP, False to turn it off""" //| STATIC mp_obj_t wiznet5k_dhcp_get_value(mp_obj_t self_in) { @@ -138,13 +137,13 @@ const mp_obj_property_t wiznet5k_dhcp_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: ifconfig(params=None) -//| -//| Called without parameters, returns a tuple of -//| (ip_address, subnet_mask, gateway_address, dns_server) +//| def ifconfig(self, params: Any = None) -> Any: +//| """Called without parameters, returns a tuple of +//| (ip_address, subnet_mask, gateway_address, dns_server) //| -//| Or can be called with the same tuple to set those parameters. -//| Setting ifconfig parameters turns DHCP off, if it was on. +//| Or can be called with the same tuple to set those parameters. +//| Setting ifconfig parameters turns DHCP off, if it was on.""" +//| ... //| STATIC mp_obj_t wiznet5k_ifconfig(size_t n_args, const mp_obj_t *args) { -- cgit v1.2.3 From 4e8de3c554024d3ac89e9ee77b958a6932a64bec Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Tue, 12 May 2020 17:15:28 -0700 Subject: Swap sphinx to autoapi and the inline stubs --- .github/workflows/build.yml | 2 +- .gitignore | 2 + Makefile | 6 +- conf.py | 14 +- docs/c2rst.py | 31 -- ports/atmel-samd/README.rst | 2 +- ports/atmel-samd/bindings/samd/Clock.c | 36 +- ports/atmel-samd/bindings/samd/__init__.c | 19 +- setup.py | 8 +- shared-bindings/_bleio/Adapter.c | 5 +- shared-bindings/_bleio/Address.c | 9 +- shared-bindings/_bleio/Attribute.c | 6 +- shared-bindings/_bleio/Characteristic.c | 9 +- shared-bindings/_bleio/CharacteristicBuffer.c | 7 +- shared-bindings/_bleio/Connection.c | 14 +- shared-bindings/_bleio/Descriptor.c | 6 +- shared-bindings/_bleio/PacketBuffer.c | 26 +- shared-bindings/_bleio/ScanEntry.c | 9 +- shared-bindings/_bleio/ScanResults.c | 7 +- shared-bindings/_bleio/Service.c | 7 +- shared-bindings/_bleio/UUID.c | 9 +- shared-bindings/_bleio/__init__.c | 26 +- shared-bindings/_eve/__init__.c | 22 +- shared-bindings/_pew/PewPew.c | 7 +- shared-bindings/_pew/__init__.c | 12 +- shared-bindings/_pixelbuf/PixelBuf.c | 7 +- shared-bindings/_pixelbuf/__init__.c | 27 +- shared-bindings/_stage/Layer.c | 5 +- shared-bindings/_stage/Text.c | 7 +- shared-bindings/_stage/__init__.c | 16 +- shared-bindings/aesio/__init__.c | 17 +- shared-bindings/aesio/aes.c | 64 ++- shared-bindings/analogio/AnalogIn.c | 5 +- shared-bindings/analogio/AnalogOut.c | 7 +- shared-bindings/analogio/__init__.c | 15 +- shared-bindings/audiobusio/I2SOut.c | 7 +- shared-bindings/audiobusio/PDMIn.c | 7 +- shared-bindings/audiobusio/__init__.c | 15 +- shared-bindings/audiocore/RawSample.c | 13 +- shared-bindings/audiocore/WaveFile.c | 5 +- shared-bindings/audiocore/__init__.c | 17 +- shared-bindings/audioio/AudioOut.c | 7 +- shared-bindings/audioio/__init__.c | 14 +- shared-bindings/audiomixer/Mixer.c | 7 +- shared-bindings/audiomixer/MixerVoice.c | 5 +- shared-bindings/audiomixer/__init__.c | 16 +- shared-bindings/audiomp3/MP3Decoder.c | 7 +- shared-bindings/audiomp3/__init__.c | 15 +- shared-bindings/audiopwmio/PWMAudioOut.c | 7 +- shared-bindings/audiopwmio/__init__.c | 14 +- shared-bindings/bitbangio/I2C.c | 5 +- shared-bindings/bitbangio/OneWire.c | 5 +- shared-bindings/bitbangio/SPI.c | 5 +- shared-bindings/bitbangio/__init__.c | 16 +- shared-bindings/board/__init__.c | 6 +- shared-bindings/busio/I2C.c | 5 +- shared-bindings/busio/OneWire.c | 5 +- shared-bindings/busio/SPI.c | 7 +- shared-bindings/busio/UART.c | 5 +- shared-bindings/busio/__init__.c | 17 +- shared-bindings/digitalio/DigitalInOut.c | 5 +- shared-bindings/digitalio/Direction.c | 5 +- shared-bindings/digitalio/DriveMode.c | 5 +- shared-bindings/digitalio/Pull.c | 5 +- shared-bindings/digitalio/__init__.c | 17 +- shared-bindings/displayio/Bitmap.c | 7 +- shared-bindings/displayio/ColorConverter.c | 7 +- shared-bindings/displayio/Display.c | 5 +- shared-bindings/displayio/EPaperDisplay.c | 5 +- shared-bindings/displayio/FourWire.c | 7 +- shared-bindings/displayio/Group.c | 7 +- shared-bindings/displayio/I2CDisplay.c | 7 +- shared-bindings/displayio/OnDiskBitmap.c | 7 +- shared-bindings/displayio/Palette.c | 7 +- shared-bindings/displayio/ParallelBus.c | 7 +- shared-bindings/displayio/Shape.c | 7 +- shared-bindings/displayio/TileGrid.c | 5 +- shared-bindings/displayio/__init__.c | 27 +- shared-bindings/fontio/BuiltinFont.c | 7 +- shared-bindings/fontio/Glyph.c | 31 +- shared-bindings/fontio/__init__.c | 17 +- shared-bindings/framebufferio/FramebufferDisplay.c | 5 +- shared-bindings/framebufferio/__init__.c | 16 +- shared-bindings/frequencyio/FrequencyIn.c | 5 +- shared-bindings/frequencyio/__init__.c | 17 +- shared-bindings/gamepad/GamePad.c | 7 +- shared-bindings/gamepad/__init__.c | 12 +- shared-bindings/gamepadshift/GamePadShift.c | 5 +- shared-bindings/gamepadshift/__init__.c | 12 +- shared-bindings/help.c | 34 -- shared-bindings/help.rst | 31 ++ shared-bindings/i2cslave/I2CSlave.c | 36 +- shared-bindings/i2cslave/__init__.c | 14 +- shared-bindings/index.rst | 10 +- shared-bindings/math/__init__.c | 7 +- shared-bindings/microcontroller/Pin.c | 7 +- shared-bindings/microcontroller/Processor.c | 11 +- shared-bindings/microcontroller/RunMode.c | 5 +- shared-bindings/microcontroller/__init__.c | 20 +- shared-bindings/multiterminal/__init__.c | 7 +- shared-bindings/neopixel_write/__init__.c | 13 +- shared-bindings/network/__init__.c | 7 +- shared-bindings/nvm/ByteArray.c | 8 +- shared-bindings/nvm/__init__.c | 17 +- shared-bindings/os/__init__.c | 7 +- shared-bindings/ps2io/Ps2.c | 5 +- shared-bindings/ps2io/__init__.c | 14 +- shared-bindings/pulseio/PWMOut.c | 7 +- shared-bindings/pulseio/PulseIn.c | 12 +- shared-bindings/pulseio/PulseOut.c | 13 +- shared-bindings/pulseio/__init__.c | 16 +- shared-bindings/random/__init__.c | 7 +- shared-bindings/rgbmatrix/RGBMatrix.c | 14 +- shared-bindings/rgbmatrix/__init__.c | 11 +- shared-bindings/rotaryio/IncrementalEncoder.c | 7 +- shared-bindings/rotaryio/__init__.c | 18 +- shared-bindings/rtc/RTC.c | 13 +- shared-bindings/rtc/__init__.c | 16 +- shared-bindings/socket/__init__.c | 8 +- shared-bindings/storage/__init__.c | 7 +- shared-bindings/struct/__init__.c | 9 +- shared-bindings/supervisor/Runtime.c | 11 +- shared-bindings/supervisor/__init__.c | 30 +- shared-bindings/terminalio/Terminal.c | 5 +- shared-bindings/terminalio/__init__.c | 16 +- shared-bindings/time/__init__.c | 7 +- shared-bindings/touchio/TouchIn.c | 5 +- shared-bindings/touchio/__init__.c | 14 +- shared-bindings/uheap/__init__.c | 6 +- shared-bindings/ulab/__init__.pyi | 523 +++++++++++++++++++++ shared-bindings/ulab/__init__.rst | 523 --------------------- shared-bindings/usb_hid/Device.c | 5 +- shared-bindings/usb_hid/__init__.c | 15 +- shared-bindings/usb_midi/PortIn.c | 7 +- shared-bindings/usb_midi/PortOut.c | 5 +- shared-bindings/usb_midi/__init__.c | 17 +- shared-bindings/ustack/__init__.c | 10 +- shared-bindings/wiznet/__init__.c | 16 +- shared-bindings/wiznet/wiznet5k.c | 5 +- tools/extract_pyi.py | 12 +- 140 files changed, 860 insertions(+), 1762 deletions(-) delete mode 100644 docs/c2rst.py delete mode 100644 shared-bindings/help.c create mode 100644 shared-bindings/help.rst create mode 100644 shared-bindings/ulab/__init__.pyi delete mode 100644 shared-bindings/ulab/__init__.rst (limited to 'shared-bindings') diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3dda76db4..057395eee 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -34,7 +34,7 @@ jobs: run: | sudo apt-get install -y eatmydata sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64 - pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter polib pyyaml + pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinx-autoapi sphinxcontrib-svg2pdfconverter polib pyyaml - name: Versions run: | gcc --version diff --git a/.gitignore b/.gitignore index 435ed73a7..403fcc299 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ ############ dist/ *.egg-info +.eggs # Logs and Databases ###################### @@ -51,6 +52,7 @@ _build # Generated rst files ###################### genrst/ +autoapi/ # ctags and similar ################### diff --git a/Makefile b/Makefile index aa8fc26d1..1971076a3 100644 --- a/Makefile +++ b/Makefile @@ -69,7 +69,7 @@ clean: rm -rf $(BUILDDIR)/* rm -rf $(STUBDIR) $(DISTDIR) *.egg-info -html: +html: stubs $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @@ -213,8 +213,10 @@ check-translate: locale/circuitpython.pot $(wildcard locale/*.po) $(PYTHON) tools/check_translations.py $^ stubs: + mkdir -p circuitpython-stubs python tools/extract_pyi.py shared-bindings/ $(STUBDIR) - #python setup.py sdist + python tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR) + python setup.py sdist update-frozen-libraries: @echo "Updating all frozen libraries to latest tagged version." diff --git a/conf.py b/conf.py index 2e503737c..aea84dd21 100644 --- a/conf.py +++ b/conf.py @@ -55,7 +55,6 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'rstjinja', - 'c2rst', 'recommonmark', ] @@ -66,9 +65,17 @@ templates_path = ['templates'] source_suffix = { '.rst': 'restructuredtext', '.md': 'markdown', - '.c': '' } +extensions.append('autoapi.extension') + +autoapi_type = 'python' +# Uncomment this if debugging autoapi +# autoapi_keep_files = True +autoapi_dirs = ['circuitpython-stubs'] +autoapi_add_toctree_entry = False +autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary'] +autoapi_template_dir = 'docs/autoapi/templates' # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -78,7 +85,7 @@ source_suffix = { # General information about the project. project = 'Adafruit CircuitPython' -copyright = '2014-2018, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)' +copyright = '2014-2020, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)' # These are overwritten on ReadTheDocs. # The version info for the project you're documenting, acts as replacement for @@ -105,6 +112,7 @@ exclude_patterns = ["**/build*", ".git", ".venv", ".direnv", + "docs/autoapi", "docs/README.md", "drivers", "examples", diff --git a/docs/c2rst.py b/docs/c2rst.py deleted file mode 100644 index 76489dca3..000000000 --- a/docs/c2rst.py +++ /dev/null @@ -1,31 +0,0 @@ -def c2rst(app, docname, source): - """ Pre-parse '.c' & '.h' files that contain rST source. - """ - # Make sure we're outputting HTML - if app.builder.format != 'html': - return - - fname = app.env.doc2path(docname) - if (not fname.endswith(".c") and - not fname.endswith(".h")): - #print("skipping:", fname) - return - - src = source[0] - - stripped = [] - for line in src.split("\n"): - line = line.strip() - if line == "//|": - stripped.append("") - elif line.startswith("//| "): - stripped.append(line[len("//| "):]) - stripped = "\r\n".join(stripped) - - rendered = app.builder.templates.render_string( - stripped, app.config.html_context - ) - source[0] = rendered - -def setup(app): - app.connect("source-read", c2rst) diff --git a/ports/atmel-samd/README.rst b/ports/atmel-samd/README.rst index 721177275..a6881902e 100644 --- a/ports/atmel-samd/README.rst +++ b/ports/atmel-samd/README.rst @@ -21,4 +21,4 @@ Port Specific modules --------------------- .. toctree:: - bindings/samd/__init__ + ../../autoapi/samd/index diff --git a/ports/atmel-samd/bindings/samd/Clock.c b/ports/atmel-samd/bindings/samd/Clock.c index b88bb82e2..24e425e8c 100644 --- a/ports/atmel-samd/bindings/samd/Clock.c +++ b/ports/atmel-samd/bindings/samd/Clock.c @@ -30,18 +30,12 @@ #include "py/objproperty.h" #include "py/runtime.h" -//| .. currentmodule:: samd +//| import typing +//| class Clock: +//| """Identifies a clock on the microcontroller. //| -//| :class:`Clock` --- Clock reference -//| ------------------------------------------ -//| -//| Identifies a clock on the microcontroller. -//| -//| .. class:: Clock -//| -//| Identifies a clock on the microcontroller. They are fixed by the -//| hardware so they cannot be constructed on demand. Instead, use -//| `samd.clock` to reference the desired clock. +//| They are fixed by the hardware so they cannot be constructed on demand. Instead, use +//| ``samd.clock`` to reference the desired clock.""" //| STATIC void samd_clock_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) { @@ -50,9 +44,8 @@ STATIC void samd_clock_print(const mp_print_t *print, mp_obj_t self_in, mp_print mp_printf(print, "%q.%q.%q", MP_QSTR_samd, MP_QSTR_clock, self->name); } -//| .. attribute:: enabled -//| -//| Is the clock enabled? (read-only) +//| enabled: bool = ... +//| """Is the clock enabled? (read-only)""" //| STATIC mp_obj_t samd_clock_get_enabled(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -69,9 +62,8 @@ const mp_obj_property_t samd_clock_enabled_obj = { }, }; -//| .. attribute:: parent -//| -//| Clock parent. (read-only) +//| parent: typing.Union(Clock | None) = ... +//| """Clock parent. (read-only)""" //| STATIC mp_obj_t samd_clock_get_parent(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -98,9 +90,8 @@ const mp_obj_property_t samd_clock_parent_obj = { }, }; -//| .. attribute:: frequency -//| -//| Clock frequency. (read-only) +//| frequency: int = ... +//| """Clock frequency in Herz. (read-only)""" //| STATIC mp_obj_t samd_clock_get_frequency(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -117,9 +108,8 @@ const mp_obj_property_t samd_clock_frequency_obj = { }, }; -//| .. attribute:: calibration -//| -//| Clock calibration. Not all clocks can be calibrated. +//| calibration: int = ... +//| """Clock calibration. Not all clocks can be calibrated.""" //| STATIC mp_obj_t samd_clock_get_calibration(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/ports/atmel-samd/bindings/samd/__init__.c b/ports/atmel-samd/bindings/samd/__init__.c index 55a10001d..6e9b68ccc 100644 --- a/ports/atmel-samd/bindings/samd/__init__.c +++ b/ports/atmel-samd/bindings/samd/__init__.c @@ -30,29 +30,16 @@ #include "bindings/samd/Clock.h" -//| :mod:`samd` --- SAMD implementation settings -//| ================================================= -//| -//| .. module:: samd -//| :synopsis: SAMD implementation settings -//| :platform: SAMD21 -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Clock -//| +//| """SAMD implementation settings""" -//| :mod:`samd.clock` --- samd clock names +//| """:mod:`samd.clock` --- samd clock names //| -------------------------------------------------------- //| //| .. module:: samd.clock //| :synopsis: samd clock names //| :platform: SAMD21 //| -//| References to clocks as named by the microcontroller +//| References to clocks as named by the microcontroller""" //| const mp_obj_module_t samd_clock_module = { .base = { &mp_type_module }, diff --git a/setup.py b/setup.py index 1e0d81da3..37afb6f1b 100644 --- a/setup.py +++ b/setup.py @@ -5,18 +5,16 @@ from pathlib import Path stub_root = Path("circuitpython-stubs") stubs = [p.relative_to(stub_root).as_posix() for p in stub_root.glob("*.pyi")] -now = datetime.utcnow() -version = now.strftime("%Y.%m.%d") - setup( name="circuitpython-stubs", description="PEP 561 type stubs for CircuitPython", url="https://github.com/adafruit/circuitpython", maintainer="CircuitPythonistas", author_email="circuitpython@adafruit.com", - version=version, + use_scm_version=True, license="MIT", package_data={"circuitpython-stubs": stubs}, packages=["circuitpython-stubs"], - setup_requires=["setuptools>=38.6.0"], + setup_requires=["setuptools>=38.6.0", + "setuptools_scm"], ) diff --git a/shared-bindings/_bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c index 6fb5c323d..4816294f7 100644 --- a/shared-bindings/_bleio/Adapter.c +++ b/shared-bindings/_bleio/Adapter.c @@ -48,10 +48,7 @@ #define WINDOW_DEFAULT (0.1f) //| class Adapter: -//| """.. currentmodule:: _bleio -//| -//| :class:`Adapter` --- BLE adapter -//| ---------------------------------------------------- +//| """BLE adapter //| //| The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices. //| This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP). diff --git a/shared-bindings/_bleio/Address.c b/shared-bindings/_bleio/Address.c index 2071bd3b2..ccbab1b9d 100644 --- a/shared-bindings/_bleio/Address.c +++ b/shared-bindings/_bleio/Address.c @@ -35,12 +35,7 @@ #include "shared-module/_bleio/Address.h" //| class Address: -//| """.. currentmodule:: _bleio -//| -//| :class:`Address` -- BLE address -//| ========================================================= -//| -//| Encapsulates the address of a BLE device.""" +//| """Encapsulates the address of a BLE device.""" //| //| def __init__(self, address: buf, address_type: Any): @@ -97,7 +92,7 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args, //| >>> _bleio.adapter.address //|
//| >>> _bleio.adapter.address.address_bytes -//| b'5\xa8\xed\xf5\x1d\xc8'""" +//| b'5\\xa8\\xed\\xf5\\x1d\\xc8'""" //| STATIC mp_obj_t bleio_address_get_address_bytes(mp_obj_t self_in) { bleio_address_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Attribute.c b/shared-bindings/_bleio/Attribute.c index 72fd13d1c..6c47c87ba 100644 --- a/shared-bindings/_bleio/Attribute.c +++ b/shared-bindings/_bleio/Attribute.c @@ -30,12 +30,8 @@ #include "shared-bindings/_bleio/UUID.h" //| class Attribute: -//| """.. currentmodule:: _bleio +//| """Definitions associated with all BLE attributes: characteristics, descriptors, etc. //| -//| :class:`Attribute` -- BLE Attribute -//| ========================================================= -//| -//| Definitions associated with all BLE attributes: characteristics, descriptors, etc. //| :py:class:`~_bleio.Attribute` is, notionally, a superclass of //| :py:class:`~Characteristic` and :py:class:`~Descriptor`, //| but is not defined as a Python superclass of those classes.""" diff --git a/shared-bindings/_bleio/Characteristic.c b/shared-bindings/_bleio/Characteristic.c index f8f18d0bd..785b677d6 100644 --- a/shared-bindings/_bleio/Characteristic.c +++ b/shared-bindings/_bleio/Characteristic.c @@ -34,13 +34,8 @@ #include "shared-bindings/_bleio/UUID.h" //| class Characteristic: -//| """.. currentmodule:: _bleio -//| -//| :class:`Characteristic` -- BLE service characteristic -//| ========================================================= -//| -//| Stores information about a BLE service characteristic and allows reading -//| and writing of the characteristic's value.""" +//| """Stores information about a BLE service characteristic and allows reading +//| and writing of the characteristic's value.""" //| //| def __init__(self, ): //| """There is no regular constructor for a Characteristic. A new local Characteristic can be created diff --git a/shared-bindings/_bleio/CharacteristicBuffer.c b/shared-bindings/_bleio/CharacteristicBuffer.c index f38f650d9..6cbd587c6 100644 --- a/shared-bindings/_bleio/CharacteristicBuffer.c +++ b/shared-bindings/_bleio/CharacteristicBuffer.c @@ -42,12 +42,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self } //| class CharacteristicBuffer: -//| """.. currentmodule:: _bleio -//| -//| :class:`CharacteristicBuffer` -- BLE Service incoming values buffer. -//| ===================================================================== -//| -//| Accumulates a Characteristic's incoming values in a FIFO buffer.""" +//| """Accumulates a Characteristic's incoming values in a FIFO buffer.""" //| //| def __init__(self, characteristic: Characteristic, *, timeout: int = 1, buffer_size: int = 64): //| diff --git a/shared-bindings/_bleio/Connection.c b/shared-bindings/_bleio/Connection.c index 93600e76d..0a96d8a11 100644 --- a/shared-bindings/_bleio/Connection.c +++ b/shared-bindings/_bleio/Connection.c @@ -43,12 +43,7 @@ #include "shared-bindings/_bleio/Service.h" //| class Connection: -//| """.. currentmodule:: _bleio -//| -//| :class:`Connection` -- A BLE connection -//| ========================================================= -//| -//| A BLE connection to another device. Used to discover and interact with services on the other +//| """A BLE connection to another device. Used to discover and interact with services on the other //| device. //| //| Usage:: @@ -211,15 +206,14 @@ STATIC mp_obj_t bleio_connection_get_connection_interval(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_connection_get_connection_interval_obj, bleio_connection_get_connection_interval); -//| .. attribute:: max_packet_length -//| -//| The maximum number of data bytes that can be sent in a single transmission, +//| attribute: Any = ... +//| """The maximum number of data bytes that can be sent in a single transmission, //| not including overhead bytes. //| //| This is the maximum number of bytes that can be sent in a notification, //| which must be sent in a single packet. //| But for a regular characteristic read or write, may be sent in multiple packets, -//| so this limit does not apply. +//| so this limit does not apply.""" //| STATIC mp_obj_t bleio_connection_get_max_packet_length(mp_obj_t self_in) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Descriptor.c b/shared-bindings/_bleio/Descriptor.c index 00b3bacf5..9d7020849 100644 --- a/shared-bindings/_bleio/Descriptor.c +++ b/shared-bindings/_bleio/Descriptor.c @@ -34,12 +34,8 @@ #include "shared-bindings/_bleio/UUID.h" //| class Descriptor: -//| """.. currentmodule:: _bleio +//| """Stores information about a BLE descriptor. //| -//| :class:`Descriptor` -- BLE descriptor -//| ========================================================= -//| -//| Stores information about a BLE descriptor. //| Descriptors are attached to BLE characteristics and provide contextual //| information about the characteristic.""" //| diff --git a/shared-bindings/_bleio/PacketBuffer.c b/shared-bindings/_bleio/PacketBuffer.c index 80beadb15..907bfabd2 100644 --- a/shared-bindings/_bleio/PacketBuffer.c +++ b/shared-bindings/_bleio/PacketBuffer.c @@ -36,12 +36,7 @@ #include "shared-bindings/util.h" //| class PacketBuffer: -//| """.. currentmodule:: _bleio -//| -//| :class:`PacketBuffer` -- Packet-oriented characteristic usage. -//| ===================================================================== -//| -//| Accumulates a Characteristic's incoming packets in a FIFO buffer and facilitates packet aware +//| """Accumulates a Characteristic's incoming packets in a FIFO buffer and facilitates packet aware //| outgoing writes. A packet's size is either the characteristic length or the maximum transmission //| unit (MTU) minus overhead, whichever is smaller. The MTU can change so check `incoming_packet_length` //| and `outgoing_packet_length` before creating a buffer to store data. @@ -60,7 +55,7 @@ //| It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic //| in a remote Service that a Central has connected to. //| :param int buffer_size: Size of ring buffer (in packets of the Characteristic's maximum -//| length) that stores incoming packets coming from the peer. +//| length) that stores incoming packets coming from the peer.""" //| ... //| STATIC mp_obj_t bleio_packet_buffer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -126,11 +121,11 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(bleio_packet_buffer_readinto_obj, bleio_packet_ //| """Writes all bytes from data into the same outgoing packet. The bytes from header are included //| before data when the pending packet is currently empty. //| -//| This does not block until the data is sent. It only blocks until the data is pending.""" -//| ... +//| This does not block until the data is sent. It only blocks until the data is pending. //| -//| :return: number of bytes written. May include header bytes when packet is empty. -//| :rtype: int +//| :return: number of bytes written. May include header bytes when packet is empty. +//| :rtype: int""" +//| ... //| // TODO: Add a kwarg `merge=False` to dictate whether subsequent writes are merged into a pending // one. @@ -174,7 +169,7 @@ STATIC mp_obj_t bleio_packet_buffer_write(mp_uint_t n_args, const mp_obj_t *pos_ } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_packet_buffer_write_obj, 1, bleio_packet_buffer_write); -//| def deinit(self, ) -> Any: +//| def deinit(self) -> Any: //| """Disable permanently.""" //| ... STATIC mp_obj_t bleio_packet_buffer_deinit(mp_obj_t self_in) { @@ -184,7 +179,7 @@ STATIC mp_obj_t bleio_packet_buffer_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_packet_buffer_deinit_obj, bleio_packet_buffer_deinit); -//| packet_size: Any = ... +//| packet_size: int = ... //| """`packet_size` is the same as `incoming_packet_length`. //| The name `packet_size` is deprecated and //| will be removed in CircuitPython 6.0.0.""" @@ -210,9 +205,8 @@ const mp_obj_property_t bleio_packet_buffer_incoming_packet_length_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: outgoing_packet_length -//| -//| Maximum length in bytes of a packet we are writing. +//| outgoing_packet_length: int = ... +//| """Maximum length in bytes of a packet we are writing.""" //| STATIC mp_obj_t bleio_packet_buffer_get_outgoing_packet_length(mp_obj_t self_in) { bleio_packet_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/ScanEntry.c b/shared-bindings/_bleio/ScanEntry.c index a92b247be..905bea81d 100644 --- a/shared-bindings/_bleio/ScanEntry.c +++ b/shared-bindings/_bleio/ScanEntry.c @@ -36,12 +36,7 @@ #include "shared-module/_bleio/ScanEntry.h" //| class ScanEntry: -//| """.. currentmodule:: _bleio -//| -//| :class:`ScanEntry` -- BLE scan data -//| ========================================================= -//| -//| Encapsulates information about a device that was received during scanning. It can be +//| """Encapsulates information about a device that was received during scanning. It can be //| advertisement or scan response data. This object may only be created by a `_bleio.ScanResults`: //| it has no user-visible constructor.""" //| @@ -68,7 +63,7 @@ STATIC mp_obj_t bleio_scanentry_matches(mp_uint_t n_args, const mp_obj_t *pos_ar mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - + mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[ARG_prefixes].u_obj, &bufinfo, MP_BUFFER_READ); return mp_obj_new_bool(common_hal_bleio_scanentry_matches(self, bufinfo.buf, bufinfo.len, args[ARG_all].u_bool)); diff --git a/shared-bindings/_bleio/ScanResults.c b/shared-bindings/_bleio/ScanResults.c index 4b274fc68..6077dcbda 100644 --- a/shared-bindings/_bleio/ScanResults.c +++ b/shared-bindings/_bleio/ScanResults.c @@ -33,12 +33,7 @@ #include "shared-bindings/_bleio/ScanResults.h" //| class ScanResults: -//| """.. currentmodule:: _bleio -//| -//| :class:`ScanResults` -- An Iterator over BLE scanning results -//| =============================================================== -//| -//| Iterates over advertising data received while scanning. This object is always created +//| """Iterates over advertising data received while scanning. This object is always created //| by a `_bleio.Adapter`: it has no user-visible constructor.""" //| STATIC mp_obj_t scanresults_iternext(mp_obj_t self_in) { diff --git a/shared-bindings/_bleio/Service.c b/shared-bindings/_bleio/Service.c index 3526ce189..5ca7504f2 100644 --- a/shared-bindings/_bleio/Service.c +++ b/shared-bindings/_bleio/Service.c @@ -33,12 +33,7 @@ #include "shared-bindings/_bleio/UUID.h" //| class Service: -//| """.. currentmodule:: _bleio -//| -//| :class:`Service` -- BLE GATT Service -//| ========================================================= -//| -//| Stores information about a BLE service and its characteristics.""" +//| """Stores information about a BLE service and its characteristics.""" //| //| def __init__(self, uuid: UUID, *, secondary: bool = False): //| """Create a new Service identified by the specified UUID. It can be accessed by all diff --git a/shared-bindings/_bleio/UUID.c b/shared-bindings/_bleio/UUID.c index d4b0f84ca..78161b956 100644 --- a/shared-bindings/_bleio/UUID.c +++ b/shared-bindings/_bleio/UUID.c @@ -34,12 +34,7 @@ #include "shared-bindings/_bleio/UUID.h" //| class UUID: -//| """.. currentmodule:: _bleio -//| -//| :class:`UUID` -- BLE UUID -//| ========================================================= -//| -//| A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more.""" +//| """A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more.""" //| //| def __init__(self, value: Any): //| """Create a new UUID or UUID object encapsulating the uuid value. @@ -207,7 +202,7 @@ STATIC mp_obj_t bleio_uuid_pack_into(mp_uint_t n_args, const mp_obj_t *pos_args, mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - + mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[ARG_buffer].u_obj, &bufinfo, MP_BUFFER_WRITE); diff --git a/shared-bindings/_bleio/__init__.c b/shared-bindings/_bleio/__init__.c index da7bfdd81..90b185f79 100644 --- a/shared-bindings/_bleio/__init__.c +++ b/shared-bindings/_bleio/__init__.c @@ -41,13 +41,7 @@ #include "shared-bindings/_bleio/Service.h" #include "shared-bindings/_bleio/UUID.h" -//| """:mod:`_bleio` --- Bluetooth Low Energy (BLE) communication -//| ================================================================ -//| -//| .. module:: _bleio -//| :synopsis: Bluetooth Low Energy functionality -//| :platform: nRF -//| +//| """ //| The `_bleio` module provides necessary low-level functionality for communicating //| using Bluetooth Low Energy (BLE). The '_' prefix indicates this module is meant //| for internal use by libraries but not by the end user. Its API may change incompatibly @@ -58,24 +52,6 @@ //| provides higher-level convenience functionality, including predefined beacons, clients, //| servers. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Address -//| Adapter -//| Attribute -//| Characteristic -//| CharacteristicBuffer -//| Connection -//| Descriptor -//| PacketBuffer -//| ScanEntry -//| ScanResults -//| Service -//| UUID -//| //| .. attribute:: adapter //| //| BLE Adapter used to manage device discovery and connections. diff --git a/shared-bindings/_eve/__init__.c b/shared-bindings/_eve/__init__.c index 0e78cea16..4fa48f2c7 100644 --- a/shared-bindings/_eve/__init__.c +++ b/shared-bindings/_eve/__init__.c @@ -34,28 +34,10 @@ #include "shared-module/_eve/__init__.h" #include "shared-bindings/_eve/__init__.h" - - - - - - - - - - - - - -//| """:mod:`_eve` --- low-level BridgeTek EVE bindings -//| ================================================ -//| -//| .. module:: _eve -//| :synopsis: low-level BridgeTek EVE bindings -//| :platform: SAMD21/SAMD51 +//| """Low-level BridgeTek EVE bindings //| //| The `_eve` module provides a class _EVE which -//| contains methods for constructing EVE command +//| contains methods for constructing EVE command //| buffers and appending basic graphics commands.""" //| diff --git a/shared-bindings/_pew/PewPew.c b/shared-bindings/_pew/PewPew.c index 37188d2b7..82bf04a61 100644 --- a/shared-bindings/_pew/PewPew.c +++ b/shared-bindings/_pew/PewPew.c @@ -35,12 +35,7 @@ #include "supervisor/shared/translate.h" //| class PewPew: -//| """.. currentmodule:: _pew -//| -//| :class:`PewPew` -- LED matrix and button driver -//| =============================================== -//| -//| This is an internal module to be used by the ``pew.py`` library from +//| """This is an internal module to be used by the ``pew.py`` library from //| https://github.com/pewpew-game/pew-pewpew-standalone-10.x to handle the //| LED matrix display and buttons on the ``pewpew10`` board. //| diff --git a/shared-bindings/_pew/__init__.c b/shared-bindings/_pew/__init__.c index b6aab6726..6e0070d8e 100644 --- a/shared-bindings/_pew/__init__.c +++ b/shared-bindings/_pew/__init__.c @@ -41,17 +41,7 @@ STATIC mp_obj_t get_pressed(void) { STATIC MP_DEFINE_CONST_FUN_OBJ_0(get_pressed_obj, get_pressed); -//| """:mod:`_pew` --- LED matrix driver -//| ================================== -//| -//| .. module:: _pew -//| :synopsis: LED matrix driver -//| :platform: SAMD21 -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PewPew""" +//| """LED matrix driver""" //| STATIC const mp_rom_map_elem_t pew_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR__pew) }, diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 2d1f4fff2..71a91d707 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -45,12 +45,7 @@ extern const int32_t colorwheel(float pos); static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t* parsed); //| class PixelBuf: -//| """.. currentmodule:: _pixelbuf -//| -//| :class:`PixelBuf` -- A fast RGB[W] pixel buffer for LED and similar devices -//| =========================================================================== -//| -//| :class:`~_pixelbuf.PixelBuf` implements an RGB[W] bytearray abstraction.""" +//| """A fast RGB[W] pixel buffer for LED and similar devices.""" //| //| def __init__(self, size: int, *, byteorder: str = "BGR", brightness: float = 0, auto_write: bool = False, header: bytes = b"", trailer: bytes = b""): //| """Create a PixelBuf object of the specified size, byteorder, and bits per pixel. diff --git a/shared-bindings/_pixelbuf/__init__.c b/shared-bindings/_pixelbuf/__init__.c index 30656f1c7..bfd479fde 100644 --- a/shared-bindings/_pixelbuf/__init__.c +++ b/shared-bindings/_pixelbuf/__init__.c @@ -33,35 +33,22 @@ #include "shared-bindings/_pixelbuf/PixelBuf.h" -//| """:mod:`_pixelbuf` --- Fast RGB(W) pixel buffer and helpers -//| =========================================================== - -//| .. module:: _pixelbuf -//| :synopsis: A fast RGB(W) pixel buffer library for like NeoPixel and DotStar. +//| """A fast RGB(W) pixel buffer library for like NeoPixel and DotStar. //| //| The `_pixelbuf` module provides the :py:class:`PixelBuf` class to accelerate //| RGB(W) strip/matrix manipulation, such as DotStar and Neopixel. //| -//| Byteorders are configured with strings, such as "RGB" or "RGBD". -//| TODO: Pull in docs from pypixelbuf. +//| Byteorders are configured with strings, such as "RGB" or "RGBD".""" +// TODO: Pull in docs from pypixelbuf. -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PixelBuf""" - -//| def colorwheel(n: Any) -> Any: ... -//| - -//| def wheel(n: Any) -> Any: +//| def colorwheel(n: int) -> Any: //| """C implementation of the common wheel() function found in many examples. //| Returns the colorwheel RGB value as an integer value for n (usable in :py:class:`PixelBuf`, neopixel, and dotstar).""" //| ... //| -//| .. function:: wheel(n) -//| Use of wheel() is deprecated. Please use colorwheel(). +//| def wheel(n: Any) -> Any: +//| """Use of wheel() is deprecated. Please use colorwheel().""" +//| STATIC mp_obj_t pixelbuf_colorwheel(mp_obj_t n) { return MP_OBJ_NEW_SMALL_INT(colorwheel(MP_OBJ_IS_SMALL_INT(n) ? MP_OBJ_SMALL_INT_VALUE(n) : mp_obj_float_get(n))); diff --git a/shared-bindings/_stage/Layer.c b/shared-bindings/_stage/Layer.c index 437114cd3..0f8260e53 100644 --- a/shared-bindings/_stage/Layer.c +++ b/shared-bindings/_stage/Layer.c @@ -31,10 +31,7 @@ #include "supervisor/shared/translate.h" //| class Layer: -//| """.. currentmodule:: _stage -//| -//| :class:`Layer` -- Keep information about a single layer of graphics -//| ===================================================================""" +//| """Keep information about a single layer of graphics""" //| //| def __init__(self, width: int, height: int, graphic: bytearray, palette: bytearray, grid: bytearray): //| """Keep internal information about a layer of graphics (either a diff --git a/shared-bindings/_stage/Text.c b/shared-bindings/_stage/Text.c index 8797f74db..b0ff1525c 100644 --- a/shared-bindings/_stage/Text.c +++ b/shared-bindings/_stage/Text.c @@ -31,13 +31,10 @@ #include "supervisor/shared/translate.h" //| class Text: -//| """.. currentmodule:: _stage -//| -//| :class:`Text` -- Keep information about a single text of text -//| ==============================================================""" +//| """Keep information about a single grid of text""" //| //| def __init__(self, width: int, height: int, font: bytearray, palette: bytearray, chars: bytearray): -//| """Keep internal information about a text of text +//| """Keep internal information about a grid of text //| in a format suitable for fast rendering //| with the ``render()`` function. //| diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c index 6b5c4fd8b..6a5638185 100644 --- a/shared-bindings/_stage/__init__.c +++ b/shared-bindings/_stage/__init__.c @@ -34,22 +34,10 @@ #include "Layer.h" #include "Text.h" -//| """:mod:`_stage` --- C-level helpers for animation of sprites on a stage -//| ===================================================================== -//| -//| .. module:: _stage -//| :synopsis: C-level helpers for animation of sprites on a stage -//| :platform: SAMD21 +//| """C-level helpers for animation of sprites on a stage //| //| The `_stage` module contains native code to speed-up the ```stage`` Library -//| `_. -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Layer -//| Text""" +//| `_.""" //| //| def render(x0: int, y0: int, x1: int, y1: int, layers: list, buffer: bytearray, display: displayio.Display, scale: int, background: int) -> Any: //| """Render and send to the display a fragment of the screen. diff --git a/shared-bindings/aesio/__init__.c b/shared-bindings/aesio/__init__.c index 43dc73e8b..fa2a2c426 100644 --- a/shared-bindings/aesio/__init__.c +++ b/shared-bindings/aesio/__init__.c @@ -31,23 +31,10 @@ #include "__init__.h" -//| :mod:`aesio` --- AES encryption routines -//| ======================================== -//| -//| .. module:: aesio -//| :synopsis: Embedded implementation of AES +//| """AES encryption routines //| //| The `AES` module contains classes used to implement encryption -//| and decryption. It aims to be low overhead in terms of memory. -//| -//| - -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| aes +//| and decryption. It aims to be low overhead in terms of memory.""" STATIC const mp_obj_tuple_t mp_aes_key_size_obj = { diff --git a/shared-bindings/aesio/aes.c b/shared-bindings/aesio/aes.c index 4ddcfa898..7a559b0bb 100644 --- a/shared-bindings/aesio/aes.c +++ b/shared-bindings/aesio/aes.c @@ -9,35 +9,31 @@ // Defined at the end of this file -//| .. currentmodule:: aesio +//| class AES: +//| """Encrypt and decrypt AES streams""" //| -//| :class:`aesio` -- Encrypt and decrypt AES streams -//| ===================================================== +//| def __init__(self, key, mode=0, iv=None, segment_size=8) -> Any: +//| """Create a new AES state with the given key. //| -//| An object that represents an AES stream, including the current state. +//| :param bytearray key: A 16-, 24-, or 32-byte key +//| :param int mode: AES mode to use. One of: AES.MODE_ECB, AES.MODE_CBC, or +//| AES.MODE_CTR +//| :param bytearray iv: Initialization vector to use for CBC or CTR mode //| -//| .. class:: AES(key, mode=0, iv=None, segment_size=8) +//| Additional arguments are supported for legacy reasons. //| -//| Create a new AES state with the given key. +//| Encrypting a string:: //| -//| :param bytearray key: A 16-, 24-, or 32-byte key -//| :param int mode: AES mode to use. One of: AES.MODE_ECB, AES.MODE_CBC, or -//| AES.MODE_CTR -//| :param bytearray iv: Initialization vector to use for CBC or CTR mode +//| import aesio +//| from binascii import hexlify //| -//| Additional arguments are supported for legacy reasons. -//| -//| Encrypting a string:: -//| -//| import aesio -//| from binascii import hexlify -//| -//| key = b'Sixteen byte key' -//| inp = b'Circuit Python!!' # Note: 16-bytes long -//| outp = bytearray(len(inp)) -//| cipher = aesio.AES(key, aesio.mode.MODE_ECB) -//| cipher.encrypt_into(inp, outp) -//| hexlify(outp) +//| key = b'Sixteen byte key' +//| inp = b'Circuit Python!!' # Note: 16-bytes long +//| outp = bytearray(len(inp)) +//| cipher = aesio.AES(key, aesio.mode.MODE_ECB) +//| cipher.encrypt_into(inp, outp) +//| hexlify(outp)""" +//| ... //| STATIC mp_obj_t aesio_aes_make_new(const mp_obj_type_t *type, size_t n_args, @@ -154,12 +150,13 @@ STATIC void validate_length(aesio_aes_obj_t *self, size_t src_length, } } -//| .. method:: encrypt_into(src, dest) +//| def encrypt_into(src, dest) -> None: +//| """Encrypt the buffer from ``src`` into ``dest``. //| -//| Encrypt the buffer from ``src`` into ``dest``. -//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the -//| buffers must be a multiple of 16 bytes, and must be equal length. For -//| CTX mode, there are no restrictions. +//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the +//| buffers must be a multiple of 16 bytes, and must be equal length. For +//| CTX mode, there are no restrictions.""" +//| ... //| STATIC mp_obj_t aesio_aes_encrypt_into(mp_obj_t aesio_obj, mp_obj_t src, mp_obj_t dest) { @@ -184,12 +181,13 @@ STATIC mp_obj_t aesio_aes_encrypt_into(mp_obj_t aesio_obj, mp_obj_t src, STATIC MP_DEFINE_CONST_FUN_OBJ_3(aesio_aes_encrypt_into_obj, aesio_aes_encrypt_into); -//| .. method:: decrypt_into(src, dest) +//| def decrypt_into(src, dest) -> None: //| -//| Decrypt the buffer from ``src`` into ``dest``. -//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the -//| buffers must be a multiple of 16 bytes, and must be equal length. For -//| CTX mode, there are no restrictions. +//| """Decrypt the buffer from ``src`` into ``dest``. +//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the +//| buffers must be a multiple of 16 bytes, and must be equal length. For +//| CTX mode, there are no restrictions.""" +//| ... //| STATIC mp_obj_t aesio_aes_decrypt_into(mp_obj_t aesio_obj, mp_obj_t src, mp_obj_t dest) { diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index 2fb5051eb..bafa287ff 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -37,10 +37,7 @@ #include "shared-bindings/util.h" //| class AnalogIn: -//| """.. currentmodule:: analogio -//| -//| :class:`AnalogIn` -- read analog voltage -//| ============================================ +//| """Read analog voltage levels //| //| Usage:: //| diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 9064bb5dc..a8edcc0ae 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class AnalogOut: -//| """.. currentmodule:: analogio -//| -//| :class:`AnalogOut` -- output analog voltage -//| ============================================ -//| -//| The AnalogOut is used to output analog values (a specific voltage). +//| """Output analog values (a specific voltage). //| //| Example usage:: //| diff --git a/shared-bindings/analogio/__init__.c b/shared-bindings/analogio/__init__.c index 79627f16a..1f059f340 100644 --- a/shared-bindings/analogio/__init__.c +++ b/shared-bindings/analogio/__init__.c @@ -34,25 +34,12 @@ #include "shared-bindings/analogio/AnalogIn.h" #include "shared-bindings/analogio/AnalogOut.h" -//| """:mod:`analogio` --- Analog hardware support -//| ================================================= -//| -//| .. module:: analogio -//| :synopsis: Analog hardware support -//| :platform: SAMD21, ESP8266 +//| """Analog hardware support //| //| The `analogio` module contains classes to provide access to analog IO //| typically implemented with digital-to-analog (DAC) and analog-to-digital //| (ADC) converters. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| AnalogIn -//| AnalogOut -//| //| 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 diff --git a/shared-bindings/audiobusio/I2SOut.c b/shared-bindings/audiobusio/I2SOut.c index 724a65a34..d965aac89 100644 --- a/shared-bindings/audiobusio/I2SOut.c +++ b/shared-bindings/audiobusio/I2SOut.c @@ -36,12 +36,7 @@ #include "supervisor/shared/translate.h" //| class I2SOut: -//| """.. currentmodule:: audiobusio -//| -//| :class:`I2SOut` -- Output an I2S audio signal -//| ======================================================== -//| -//| I2S is used to output an audio signal on an I2S bus.""" +//| """Output an I2S audio signal""" //| //| def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): //| """Create a I2SOut object associated with the given pins. diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 6cc834724..5b950297b 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class PDMIn: -//| """.. currentmodule:: audiobusio -//| -//| :class:`PDMIn` -- Record an input PDM audio stream -//| ======================================================== -//| -//| PDMIn can be used to record an input audio signal on a given set of pins.""" +//| """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): //| """Create a PDMIn object associated with the given pins. This allows you to diff --git a/shared-bindings/audiobusio/__init__.c b/shared-bindings/audiobusio/__init__.c index c5c387361..89ccbb88b 100644 --- a/shared-bindings/audiobusio/__init__.c +++ b/shared-bindings/audiobusio/__init__.c @@ -34,26 +34,13 @@ #include "shared-bindings/audiobusio/I2SOut.h" #include "shared-bindings/audiobusio/PDMIn.h" -//| """:mod:`audiobusio` --- Support for audio input and output over digital bus -//| ========================================================================= -//| -//| .. module:: audiobusio -//| :synopsis: Support for audio input and output over digital bus -//| :platform: SAMD21 +//| """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. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2SOut -//| PDMIn -//| //| All libraries 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.""" diff --git a/shared-bindings/audiocore/RawSample.c b/shared-bindings/audiocore/RawSample.c index 6091fbfc0..c0f9325e6 100644 --- a/shared-bindings/audiocore/RawSample.c +++ b/shared-bindings/audiocore/RawSample.c @@ -35,19 +35,8 @@ #include "shared-bindings/audiocore/RawSample.h" #include "supervisor/shared/translate.h" - - - - - - //| class RawSample: -//| """.. currentmodule:: audiocore -//| -//| :class:`RawSample` -- A raw audio sample buffer -//| ======================================================== -//| -//| An in-memory sound sample""" +//| """A raw audio sample buffer in memory""" //| //| def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): //| """Create a RawSample based on the given buffer of signed values. If channel_count is more than diff --git a/shared-bindings/audiocore/WaveFile.c b/shared-bindings/audiocore/WaveFile.c index 65b42fb6c..a067f6cda 100644 --- a/shared-bindings/audiocore/WaveFile.c +++ b/shared-bindings/audiocore/WaveFile.c @@ -34,10 +34,7 @@ #include "supervisor/shared/translate.h" //| class WaveFile: -//| """.. currentmodule:: audiocore -//| -//| :class:`WaveFile` -- Load a wave file for audio playback -//| ======================================================== +//| """Load a wave file for audio playback //| //| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must //| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating diff --git a/shared-bindings/audiocore/__init__.c b/shared-bindings/audiocore/__init__.c index 38f91d8ee..b400b9454 100644 --- a/shared-bindings/audiocore/__init__.c +++ b/shared-bindings/audiocore/__init__.c @@ -35,22 +35,7 @@ #include "shared-bindings/audiocore/WaveFile.h" //#include "shared-bindings/audiomixer/Mixer.h" -//| """:mod:`audiocore` --- Support for audio samples and mixer -//| ======================================================== -//| -//| .. module:: audiocore -//| :synopsis: Support for audio samples and mixer -//| :platform: SAMD21 -//| -//| The `audiocore` module contains core classes for audio IO -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| RawSample -//| WaveFile""" +//| """Support for audio samples""" //| STATIC const mp_rom_map_elem_t audiocore_module_globals_table[] = { diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c index 84e5e4422..574868202 100644 --- a/shared-bindings/audioio/AudioOut.c +++ b/shared-bindings/audioio/AudioOut.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class AudioOut: -//| """.. currentmodule:: audioio -//| -//| :class:`AudioOut` -- Output an analog audio signal -//| ======================================================== -//| -//| AudioOut can be used to output an analog audio signal on a given pin.""" +//| """Output an analog audio signal""" //| //| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): //| """Create a AudioOut object associated with the given pin(s). This allows you to diff --git a/shared-bindings/audioio/__init__.c b/shared-bindings/audioio/__init__.c index bc2e26cfc..7ec927834 100644 --- a/shared-bindings/audioio/__init__.c +++ b/shared-bindings/audioio/__init__.c @@ -42,22 +42,10 @@ #include "shared-bindings/audiomixer/Mixer.h" #endif -//| """:mod:`audioio` --- Support for audio input and output -//| ====================================================== -//| -//| .. module:: audioio -//| :synopsis: Support for audio input and output -//| :platform: SAMD21 +//| """Support for audio output //| //| The `audioio` module contains classes to provide access to audio IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| AudioOut -//| //| 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 diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c index 966581d45..31e62cdae 100644 --- a/shared-bindings/audiomixer/Mixer.c +++ b/shared-bindings/audiomixer/Mixer.c @@ -39,12 +39,7 @@ #include "supervisor/shared/translate.h" //| class Mixer: -//| """.. currentmodule:: audiomixer -//| -//| :class:`Mixer` -- Mixes one or more audio samples together -//| =========================================================== -//| -//| Mixer mixes multiple samples into one sample.""" +//| """Mixes one or more audio samples together into one sample.""" //| //| def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): //| """Create a Mixer object that can mix multiple channels with the same sample rate. diff --git a/shared-bindings/audiomixer/MixerVoice.c b/shared-bindings/audiomixer/MixerVoice.c index 257d9507b..ec5768d2f 100644 --- a/shared-bindings/audiomixer/MixerVoice.c +++ b/shared-bindings/audiomixer/MixerVoice.c @@ -38,10 +38,7 @@ #include "supervisor/shared/translate.h" //| class MixerVoice: -//| """.. currentmodule:: audiomixer -//| -//| :class:`MixerVoice` -- Voice objects used with Mixer -//| ===================================================== +//| """Voice objects used with Mixer //| //| Used to access and control samples with `audiomixer.Mixer`.""" //| diff --git a/shared-bindings/audiomixer/__init__.c b/shared-bindings/audiomixer/__init__.c index c90a4a0e6..1146bb798 100644 --- a/shared-bindings/audiomixer/__init__.c +++ b/shared-bindings/audiomixer/__init__.c @@ -32,21 +32,7 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/audiomixer/Mixer.h" -//| """:mod:`audiomixer` --- Support for audio mixer -//| ======================================================== -//| -//| .. module:: audiomixer -//| :synopsis: Support for audio mixer -//| -//| The `audiomixer` module contains core classes for mixing audio sources -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Mixer -//| MixerVoice""" +//| """Support for audio mixing""" //| STATIC const mp_rom_map_elem_t audiomixer_module_globals_table[] = { diff --git a/shared-bindings/audiomp3/MP3Decoder.c b/shared-bindings/audiomp3/MP3Decoder.c index d9c85bbf6..e6d48e32c 100644 --- a/shared-bindings/audiomp3/MP3Decoder.c +++ b/shared-bindings/audiomp3/MP3Decoder.c @@ -35,12 +35,7 @@ #include "supervisor/shared/translate.h" //| class MP3: -//| """.. currentmodule:: audiomp3 -//| -//| :class:`MP3Decoder` -- Load a mp3 file for audio playback -//| ========================================================= -//| -//| An object that decodes MP3 files for playback on an audio device.""" +//| """Load a mp3 file for audio playback""" //| //| def __init__(self, file: typing.BinaryIO, buffer: bytearray): //| diff --git a/shared-bindings/audiomp3/__init__.c b/shared-bindings/audiomp3/__init__.c index 50b29da52..62e5f56cb 100644 --- a/shared-bindings/audiomp3/__init__.c +++ b/shared-bindings/audiomp3/__init__.c @@ -31,20 +31,7 @@ #include "shared-bindings/audiomp3/MP3Decoder.h" -//| """:mod:`audiomp3` --- Support for MP3-compressed audio files -//| ========================================================== -//| -//| .. module:: audiomp3 -//| :synopsis: Support for mp3 files -//| -//| The `audiomp3` module contains an mp3 decoder -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| MP3Decoder""" +//| """Support for MP3-compressed audio files""" //| STATIC const mp_rom_map_elem_t audiomp3_module_globals_table[] = { diff --git a/shared-bindings/audiopwmio/PWMAudioOut.c b/shared-bindings/audiopwmio/PWMAudioOut.c index 17f82e3f6..d6b102317 100644 --- a/shared-bindings/audiopwmio/PWMAudioOut.c +++ b/shared-bindings/audiopwmio/PWMAudioOut.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class PWMAudioOut: -//| """.. currentmodule:: audiopwmio -//| -//| :class:`PWMAudioOut` -- Output an analog audio signal -//| ======================================================== -//| -//| AudioOut can be used to output an analog audio signal on a given pin.""" +//| """Output an analog audio signal by varying the PWM duty cycle.""" //| //| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): //| """Create a PWMAudioOut object associated with the given pin(s). This allows you to diff --git a/shared-bindings/audiopwmio/__init__.c b/shared-bindings/audiopwmio/__init__.c index 74d22b45e..5caea1420 100644 --- a/shared-bindings/audiopwmio/__init__.c +++ b/shared-bindings/audiopwmio/__init__.c @@ -33,22 +33,10 @@ #include "shared-bindings/audiopwmio/__init__.h" #include "shared-bindings/audiopwmio/PWMAudioOut.h" -//| """:mod:`audiopwmio` --- Support for audio input and output -//| ======================================================== -//| -//| .. module:: audiopwmio -//| :synopsis: Support for audio output via digital PWM -//| :platform: NRF52 +//| """Audio output via digital PWM //| //| The `audiopwmio` module contains classes to provide access to audio IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PWMAudioOut -//| //| 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 diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index a682e050e..2043fc903 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -38,10 +38,7 @@ #include "supervisor/shared/translate.h" //| class I2C: -//| """.. currentmodule:: bitbangio -//| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------""" +//| """Two wire serial protocol""" //| //| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int): //| """I2C is a two-wire protocol for communicating between devices. At the diff --git a/shared-bindings/bitbangio/OneWire.c b/shared-bindings/bitbangio/OneWire.c index 1c9405bd8..a236f4c2a 100644 --- a/shared-bindings/bitbangio/OneWire.c +++ b/shared-bindings/bitbangio/OneWire.c @@ -35,10 +35,7 @@ #include "shared-bindings/util.h" //| class OneWire: -//| """.. currentmodule:: bitbangio -//| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| =============================================================== +//| """Lowest-level of the Maxim OneWire protocol //| //| :class:`~bitbangio.OneWire` implements the timing-sensitive foundation of //| the Maxim (formerly Dallas Semi) OneWire protocol. diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index 38e0926e8..08bbf1257 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -40,10 +40,7 @@ #include "supervisor/shared/translate.h" //| class SPI: -//| """.. currentmodule:: bitbangio -//| -//| :class:`SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//| """A 3-4 wire serial protocol //| //| SPI is a serial protocol that has exclusive pins for data in and out of the //| master. It is typically faster than :py:class:`~bitbangio.I2C` because a diff --git a/shared-bindings/bitbangio/__init__.c b/shared-bindings/bitbangio/__init__.c index e9600a7e6..e04bdf701 100644 --- a/shared-bindings/bitbangio/__init__.c +++ b/shared-bindings/bitbangio/__init__.c @@ -40,12 +40,7 @@ #include "py/runtime.h" -//| """:mod:`bitbangio` --- Digital protocols implemented by the CPU -//| ============================================================= -//| -//| .. module:: bitbangio -//| :synopsis: Digital protocols implemented by the CPU -//| :platform: SAMD21, ESP8266 +//| """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 @@ -55,15 +50,6 @@ //| hardware to implement the protocols. Native implementations will be faster //| than bitbanged versions and have more capabilities. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2C -//| OneWire -//| SPI -//| //| 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 diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c index 77675e093..010a9fb92 100644 --- a/shared-bindings/board/__init__.c +++ b/shared-bindings/board/__init__.c @@ -29,11 +29,7 @@ #include "shared-bindings/board/__init__.h" -//| """:mod:`board` --- Board specific pin names -//| ======================================================== -//| -//| .. module:: board -//| :synopsis: Board specific pin names +//| """Board specific pin names //| //| Common container for board base pin names. These will vary from board to //| board so don't expect portability when using this module. diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 8ae3658ee..7e8af765f 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -37,10 +37,7 @@ #include "supervisor/shared/translate.h" //| class I2C: -//| """.. currentmodule:: busio -//| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------""" +//| """Two wire serial protocol""" //| //| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): //| diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index 556e567ef..723cc031a 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -35,10 +35,7 @@ #include "shared-bindings/util.h" //| class OneWire: -//| """.. currentmodule:: busio -//| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| =================================================================""" +//| """Lowest-level of the Maxim OneWire protocol""" //| //| def __init__(self, pin: microcontroller.Pin): //| """(formerly Dallas Semi) OneWire protocol. diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 5b1881702..2ba9a4c22 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -42,10 +42,7 @@ //| class SPI: -//| """.. currentmodule:: busio -//| -//| `SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//| """A 3-4 wire serial protocol //| //| SPI is a serial protocol that has exclusive pins for data in and out of the //| master. It is typically faster than :py:class:`~busio.I2C` because a @@ -147,7 +144,7 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { //| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: //| """Configures the SPI bus. The SPI object must be locked. //| -//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower +//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower //| due to the granularity of available clock settings. //| Check the `frequency` attribute for the actual clock rate. //| :param int polarity: the base state of the clock line (0 or 1) diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 5984194a9..d4642225c 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -43,10 +43,7 @@ // #define STREAM_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) //| class UART: -//| """.. currentmodule:: busio -//| -//| :class:`UART` -- a bidirectional serial protocol -//| =================================================""" +//| """A bidirectional serial protocol""" //| def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): //| """A common bidirectional serial protocol that uses an an agreed upon speed //| rather than a shared clock line. diff --git a/shared-bindings/busio/__init__.c b/shared-bindings/busio/__init__.c index 212b3218c..04632c2f4 100644 --- a/shared-bindings/busio/__init__.c +++ b/shared-bindings/busio/__init__.c @@ -38,12 +38,7 @@ #include "py/runtime.h" -//| """:mod:`busio` --- Hardware accelerated behavior -//| ================================================= -//| -//| .. module:: busio -//| :synopsis: Hardware accelerated behavior -//| :platform: SAMD21 +//| """Hardware accelerated external bus access //| //| The `busio` module contains classes to support a variety of serial //| protocols. @@ -54,16 +49,6 @@ //| then a RuntimeError will be raised. Use the `bitbangio` module to explicitly //| bitbang a serial protocol on any general purpose pins. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2C -//| OneWire -//| SPI -//| UART -//| //| 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 diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 5fffb3f65..54ced099d 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -44,10 +44,7 @@ #include "supervisor/shared/translate.h" //| class DigitalInOut: -//| """.. currentmodule:: digitalio -//| -//| :class:`DigitalInOut` -- digital input and output -//| ========================================================= +//| """Digital input and output //| //| A DigitalInOut is used to digitally control I/O pins. For analog control of //| a pin, see the :py:class:`analogio.AnalogIn` and diff --git a/shared-bindings/digitalio/Direction.c b/shared-bindings/digitalio/Direction.c index 0586e95de..dbd0e93e4 100644 --- a/shared-bindings/digitalio/Direction.c +++ b/shared-bindings/digitalio/Direction.c @@ -39,10 +39,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" //| class Direction: -//| """.. currentmodule:: digitalio -//| -//| :class:`Direction` -- defines the direction of a digital pin -//| =============================================================""" +//| """Defines the direction of a digital pin""" //| //| def __init__(self, ): //| """Enum-like class to define which direction the digital values are diff --git a/shared-bindings/digitalio/DriveMode.c b/shared-bindings/digitalio/DriveMode.c index 23745b046..31b682d38 100644 --- a/shared-bindings/digitalio/DriveMode.c +++ b/shared-bindings/digitalio/DriveMode.c @@ -27,10 +27,7 @@ #include "shared-bindings/digitalio/DriveMode.h" //| class DriveMode: -//| """.. currentmodule:: digitalio -//| -//| :class:`DriveMode` -- defines the drive mode of a digital pin -//| =============================================================""" +//| """Defines the drive mode of a digital pin""" //| //| def __init__(self, ): //| """Enum-like class to define the drive mode used when outputting diff --git a/shared-bindings/digitalio/Pull.c b/shared-bindings/digitalio/Pull.c index 1e64d0788..9aeec1f33 100644 --- a/shared-bindings/digitalio/Pull.c +++ b/shared-bindings/digitalio/Pull.c @@ -27,10 +27,7 @@ #include "shared-bindings/digitalio/Pull.h" //| class Pull: -//| """.. currentmodule:: digitalio -//| -//| :class:`Pull` -- defines the pull of a digital input pin -//| =============================================================""" +//| """Defines the pull of a digital input pin""" //| //| def __init__(self, ): //| """Enum-like class to define the pull value, if any, used while reading diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c index 5a11436a2..f8f45b158 100644 --- a/shared-bindings/digitalio/__init__.c +++ b/shared-bindings/digitalio/__init__.c @@ -38,25 +38,10 @@ #include "py/runtime.h" -//| """:mod:`digitalio` --- Basic digital pin support -//| ================================================= -//| -//| .. module:: digitalio -//| :synopsis: Basic digital pin support -//| :platform: SAMD21, ESP8266 +//| """Basic digital pin support //| //| The `digitalio` module contains classes to provide access to basic digital IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| DigitalInOut -//| Direction -//| DriveMode -//| Pull -//| //| 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 diff --git a/shared-bindings/displayio/Bitmap.c b/shared-bindings/displayio/Bitmap.c index d15c3b107..a52840f2e 100644 --- a/shared-bindings/displayio/Bitmap.c +++ b/shared-bindings/displayio/Bitmap.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class Bitmap: -//| """.. currentmodule:: displayio -//| -//| :class:`Bitmap` -- Stores values in a 2D array -//| ========================================================================== -//| -//| Stores values of a certain size in a 2D array""" +//| """Stores values of a certain size in a 2D array""" //| //| def __init__(self, width: int, height: int, value_count: int): //| """Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to diff --git a/shared-bindings/displayio/ColorConverter.c b/shared-bindings/displayio/ColorConverter.c index 1d6e5a0cc..505e9f766 100644 --- a/shared-bindings/displayio/ColorConverter.c +++ b/shared-bindings/displayio/ColorConverter.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class ColorConverter: -//| """.. currentmodule:: displayio -//| -//| :class:`ColorConverter` -- Converts one color format to another -//| ========================================================================================= -//| -//| Converts one color format to another.""" +//| """Converts one color format to another.""" //| //| def __init__(self, *, dither: bool = False): //| """Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c index 12abec1c8..62ef0f5d0 100644 --- a/shared-bindings/displayio/Display.c +++ b/shared-bindings/displayio/Display.c @@ -40,10 +40,7 @@ #include "supervisor/shared/translate.h" //| class Display: -//| """.. currentmodule:: displayio -//| -//| :class:`Display` -- Manage updating a display over a display bus -//| ========================================================================== +//| """Manage updating a display over a display bus //| //| This initializes a display and connects it into CircuitPython. Unlike other //| objects in CircuitPython, Display objects live until `displayio.release_displays()` diff --git a/shared-bindings/displayio/EPaperDisplay.c b/shared-bindings/displayio/EPaperDisplay.c index 8b03ddc06..8b77e4df3 100644 --- a/shared-bindings/displayio/EPaperDisplay.c +++ b/shared-bindings/displayio/EPaperDisplay.c @@ -40,10 +40,7 @@ #include "supervisor/shared/translate.h" //| class EPaperDisplay: -//| """.. currentmodule:: displayio -//| -//| :class:`EPaperDisplay` -- Manage updating an epaper display over a display bus -//| ============================================================================== +//| """Manage updating an epaper display over a display bus //| //| This initializes an epaper display and connects it into CircuitPython. Unlike other //| objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()` diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c index 649045039..5ee4ec5a9 100644 --- a/shared-bindings/displayio/FourWire.c +++ b/shared-bindings/displayio/FourWire.c @@ -39,12 +39,7 @@ #include "supervisor/shared/translate.h" //| class FourWire: -//| """.. currentmodule:: displayio -//| -//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol -//| ========================================================================== -//| -//| Manage updating a display over SPI four wire protocol in the background while Python code runs. +//| """Manage updating a display over SPI four wire protocol in the background while Python code runs. //| It doesn't handle display initialization.""" //| //| def __init__(self, spi_bus: busio.SPI, *, command: microcontroller.Pin, chip_select: microcontroller.Pin, reset: microcontroller.Pin = None, baudrate: int = 24000000, polarity: int = 0, phase: int = 0): diff --git a/shared-bindings/displayio/Group.c b/shared-bindings/displayio/Group.c index 36e137dc9..b6f96883b 100644 --- a/shared-bindings/displayio/Group.c +++ b/shared-bindings/displayio/Group.c @@ -36,12 +36,7 @@ #include "supervisor/shared/translate.h" //| class Group: -//| """.. currentmodule:: displayio -//| -//| :class:`Group` -- Group together sprites and subgroups -//| ========================================================================== -//| -//| Manage a group of sprites and groups and how they are inter-related.""" +//| """Manage a group of sprites and groups and how they are inter-related.""" //| //| def __init__(self, *, max_size: int = 4, scale: int = 1, x: int = 0, y: int = 0): //| """Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 diff --git a/shared-bindings/displayio/I2CDisplay.c b/shared-bindings/displayio/I2CDisplay.c index e2402dc49..0cfac6672 100644 --- a/shared-bindings/displayio/I2CDisplay.c +++ b/shared-bindings/displayio/I2CDisplay.c @@ -39,12 +39,7 @@ #include "supervisor/shared/translate.h" //| class I2CDisplay: -//| """.. currentmodule:: displayio -//| -//| :class:`I2CDisplay` -- Manage updating a display over I2C -//| ========================================================================== -//| -//| Manage updating a display over I2C in the background while Python code runs. +//| """Manage updating a display over I2C in the background while Python code runs. //| It doesn't handle display initialization.""" //| //| def __init__(self, i2c_bus: busio.I2C, *, device_address: int, reset: microcontroller.Pin = None): diff --git a/shared-bindings/displayio/OnDiskBitmap.c b/shared-bindings/displayio/OnDiskBitmap.c index 95c890c3b..170873653 100644 --- a/shared-bindings/displayio/OnDiskBitmap.c +++ b/shared-bindings/displayio/OnDiskBitmap.c @@ -34,12 +34,7 @@ #include "shared-bindings/displayio/OnDiskBitmap.h" //| class OnDiskBitmap: -//| """.. currentmodule:: displayio -//| -//| :class:`OnDiskBitmap` -- Loads pixels straight from disk -//| ========================================================================== -//| -//| Loads values straight from disk. This minimizes memory use but can lead to +//| """Loads values straight from disk. This minimizes memory use but can lead to //| much slower pixel load times. These load times may result in frame tearing where only part of //| the image is visible. //| diff --git a/shared-bindings/displayio/Palette.c b/shared-bindings/displayio/Palette.c index 5df11d2b1..871b2b06a 100644 --- a/shared-bindings/displayio/Palette.c +++ b/shared-bindings/displayio/Palette.c @@ -43,12 +43,7 @@ //| class Palette: -//| """.. currentmodule:: displayio -//| -//| :class:`Palette` -- Stores a mapping from bitmap pixel palette_indexes to display colors -//| ========================================================================================= -//| -//| Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to +//| """Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to //| save memory.""" //| //| def __init__(self, color_count: int): diff --git a/shared-bindings/displayio/ParallelBus.c b/shared-bindings/displayio/ParallelBus.c index cedcf1de5..eb75ecc03 100644 --- a/shared-bindings/displayio/ParallelBus.c +++ b/shared-bindings/displayio/ParallelBus.c @@ -38,12 +38,7 @@ #include "supervisor/shared/translate.h" //| class ParallelBus: -//| """.. currentmodule:: displayio -//| -//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus -//| ============================================================================== -//| -//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This +//| """Manage updating a display over 8-bit parallel bus in the background while Python code runs. This //| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle //| display initialization.""" //| diff --git a/shared-bindings/displayio/Shape.c b/shared-bindings/displayio/Shape.c index 0f22bb2a3..fce89c771 100644 --- a/shared-bindings/displayio/Shape.c +++ b/shared-bindings/displayio/Shape.c @@ -35,12 +35,7 @@ #include "supervisor/shared/translate.h" //| class Shape: -//| """.. currentmodule:: displayio -//| -//| :class:`Shape` -- Represents a shape by defining its bounds on each row -//| ========================================================================== -//| -//| Represents any shape made by defining boundaries that may be mirrored.""" +//| """Represents a shape made by defining boundaries that may be mirrored.""" //| //| def __init__(self, width: int, height: int, *, mirror_x: bool = False, mirror_y: bool = False): //| """Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index e7410e4b6..01fba46a5 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -41,10 +41,7 @@ #include "supervisor/shared/translate.h" //| class TileGrid: -//| """.. currentmodule:: displayio -//| -//| :class:`TileGrid` -- A grid of tiles sourced out of one bitmap -//| ========================================================================== +//| """A grid of tiles sourced out of one bitmap //| //| Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids //| can share bitmaps and pixel shaders. diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index 37c025329..b791336b5 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -43,33 +43,10 @@ #include "shared-bindings/displayio/Shape.h" #include "shared-bindings/displayio/TileGrid.h" -//| """:mod:`displayio` --- Native display driving -//| ========================================================================= -//| -//| .. module:: displayio -//| :synopsis: Native helpers for driving displays -//| :platform: SAMD21, SAMD51, nRF52 +//| """Native helpers for driving displays //| //| The `displayio` module contains classes to manage display output -//| including synchronizing with refresh rates and partial updating. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Bitmap -//| ColorConverter -//| Display -//| EPaperDisplay -//| FourWire -//| Group -//| I2CDisplay -//| OnDiskBitmap -//| Palette -//| ParallelBus -//| Shape -//| TileGrid""" +//| including synchronizing with refresh rates and partial updating.""" //| diff --git a/shared-bindings/fontio/BuiltinFont.c b/shared-bindings/fontio/BuiltinFont.c index f60c9e36c..bf9a65873 100644 --- a/shared-bindings/fontio/BuiltinFont.c +++ b/shared-bindings/fontio/BuiltinFont.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class BuiltinFont: -//| """.. currentmodule:: fontio -//| -//| :class:`BuiltinFont` -- A font built into CircuitPython -//| ========================================================================================= -//| -//| A font built into CircuitPython.""" +//| """A font built into CircuitPython""" //| //| def __init__(self, ): //| """Creation not supported. Available fonts are defined when CircuitPython is built. See the diff --git a/shared-bindings/fontio/Glyph.c b/shared-bindings/fontio/Glyph.c index 6235dbc46..6558e2e7a 100644 --- a/shared-bindings/fontio/Glyph.c +++ b/shared-bindings/fontio/Glyph.c @@ -29,22 +29,27 @@ #include //| class Glyph: -//| """.. currentmodule:: fontio +//| """Storage of glyph info""" //| -//| :class:`Glyph` -- Storage of glyph info -//| ==========================================================================""" -//| -//| def __init__(self, bitmap: displayio.Bitmap, tile_index: int, width: int, height: int, dx: int, dy: int, shift_x: int, shift_y: int): +//| def __init__(self, +//| bitmap: displayio.Bitmap, +//| tile_index: int, +//| width: int, +//| height: int, +//| dx: int, +//| dy: int, +//| shift_x: int, +//| shift_y: int): //| """Named tuple used to capture a single glyph and its attributes. //| -//| :param displayio.Bitmap bitmap: the bitmap including the glyph -//| :param int tile_index: the tile index within the bitmap -//| :param int width: the width of the glyph's bitmap -//| :param int height: the height of the glyph's bitmap -//| :param int dx: x adjustment to the bitmap's position -//| :param int dy: y adjustment to the bitmap's position -//| :param int shift_x: the x difference to the next glyph -//| :param int shift_y: the y difference to the next glyph""" +//| :param bitmap: the bitmap including the glyph +//| :param tile_index: the tile index within the bitmap +//| :param width: the width of the glyph's bitmap +//| :param height: the height of the glyph's bitmap +//| :param dx: x adjustment to the bitmap's position +//| :param dy: y adjustment to the bitmap's position +//| :param shift_x: the x difference to the next glyph +//| :param shift_y: the y difference to the next glyph""" //| ... //| const mp_obj_namedtuple_type_t fontio_glyph_type = { diff --git a/shared-bindings/fontio/__init__.c b/shared-bindings/fontio/__init__.c index 478fc1806..f376f3503 100644 --- a/shared-bindings/fontio/__init__.c +++ b/shared-bindings/fontio/__init__.c @@ -33,22 +33,7 @@ #include "shared-bindings/fontio/BuiltinFont.h" #include "shared-bindings/fontio/Glyph.h" -//| """:mod:`fontio` --- Core font related data structures -//| ========================================================================= -//| -//| .. module:: fontio -//| :synopsis: Core font related data structures -//| :platform: SAMD21, SAMD51, nRF52 -//| -//| The `fontio` module contains classes to store font related information. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| BuiltinFont -//| Glyph""" +//| """Core font related data structures""" //| STATIC const mp_rom_map_elem_t fontio_module_globals_table[] = { diff --git a/shared-bindings/framebufferio/FramebufferDisplay.c b/shared-bindings/framebufferio/FramebufferDisplay.c index 5e63b988e..51ef09059 100644 --- a/shared-bindings/framebufferio/FramebufferDisplay.c +++ b/shared-bindings/framebufferio/FramebufferDisplay.c @@ -41,10 +41,7 @@ #include "supervisor/shared/translate.h" //| class FramebufferDisplay: -//| """.. currentmodule:: framebufferio -//| -//| :class:`FramebufferDisplay` -- Manage updating a display with framebuffer in RAM -//| ================================================================================ +//| """Manage updating a display with framebuffer in RAM //| //| This initializes a display and connects it into CircuitPython. Unlike other //| objects in CircuitPython, Display objects live until `displayio.release_displays()` diff --git a/shared-bindings/framebufferio/__init__.c b/shared-bindings/framebufferio/__init__.c index 50725c515..492423464 100644 --- a/shared-bindings/framebufferio/__init__.c +++ b/shared-bindings/framebufferio/__init__.c @@ -28,25 +28,13 @@ #include "shared-bindings/framebufferio/__init__.h" #include "shared-bindings/framebufferio/FramebufferDisplay.h" -//| """:mod:`framebufferio` --- Native framebuffer display driving -//| ========================================================================= -//| -//| .. module:: framebufferio -//| :synopsis: Native helpers for driving displays -//| :platform: SAMD51, nRF52 +//| """Native framebuffer display driving //| //| The `framebufferio` module contains classes to manage display output //| including synchronizing with refresh rates and partial updating. //| It is used in conjunction with classes from `displayio` to actually //| place items on the display; and classes like `RGBMatrix` to actually -//| drive the display. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| FramebufferDisplay""" +//| drive the display.""" //| #if CIRCUITPY_FRAMEBUFFERIO diff --git a/shared-bindings/frequencyio/FrequencyIn.c b/shared-bindings/frequencyio/FrequencyIn.c index 270fa87c3..2d628088b 100644 --- a/shared-bindings/frequencyio/FrequencyIn.c +++ b/shared-bindings/frequencyio/FrequencyIn.c @@ -36,10 +36,7 @@ #include "supervisor/shared/translate.h" //| class FrequencyIn: -//| """.. currentmodule:: frequencyio -//| -//| :class:`FrequencyIn` -- Read a frequency signal -//| ======================================================== +//| """Read a frequency signal //| //| FrequencyIn is used to measure the frequency, in hertz, of a digital signal //| on an incoming pin. Accuracy has shown to be within 10%, if not better. It diff --git a/shared-bindings/frequencyio/__init__.c b/shared-bindings/frequencyio/__init__.c index 219d5f645..031004d4b 100644 --- a/shared-bindings/frequencyio/__init__.c +++ b/shared-bindings/frequencyio/__init__.c @@ -33,23 +33,8 @@ #include "shared-bindings/frequencyio/__init__.h" #include "shared-bindings/frequencyio/FrequencyIn.h" -//| """:mod:`frequencyio` --- Support for frequency based protocols -//| ============================================================= +//| """Support for frequency based protocols //| -//| .. module:: frequencyio -//| :synopsis: Support for frequency based protocols -//| :platform: SAMD51 -//| -//| The `frequencyio` module contains classes to provide access to basic frequency IO. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| FrequencyIn -//| - //| .. warning:: This module is not available in SAMD21 builds. See the //| :ref:`module-support-matrix` for more info. //| diff --git a/shared-bindings/gamepad/GamePad.c b/shared-bindings/gamepad/GamePad.c index 946a24dbf..a750892fe 100644 --- a/shared-bindings/gamepad/GamePad.c +++ b/shared-bindings/gamepad/GamePad.c @@ -35,10 +35,7 @@ #include "supervisor/shared/translate.h" //| class GamePad: -//| """.. currentmodule:: gamepad -//| -//| :class:`GamePad` -- Scan buttons for presses -//| ============================================ +//| """Scan buttons for presses //| //| Usage:: //| @@ -90,7 +87,7 @@ //| on delays. //| //| They button presses are accumulated, until the ``get_pressed`` method -//| is called, at which point the button state is cleared, and the new +//| is called, at which point the button state is cleared, and the new //| button presses start to be recorded.""" //| ... //| diff --git a/shared-bindings/gamepad/__init__.c b/shared-bindings/gamepad/__init__.c index 0c32fd6c1..557777f50 100644 --- a/shared-bindings/gamepad/__init__.c +++ b/shared-bindings/gamepad/__init__.c @@ -29,17 +29,7 @@ #include "shared-bindings/gamepad/GamePad.h" #include "shared-bindings/util.h" -//| """:mod:`gamepad` --- Button handling -//| ================================== -//| -//| .. module:: gamepad -//| :synopsis: Button handling -//| :platform: SAMD21 -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| GamePad""" +//| """Button handling in the background""" //| STATIC const mp_rom_map_elem_t gamepad_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_gamepad) }, diff --git a/shared-bindings/gamepadshift/GamePadShift.c b/shared-bindings/gamepadshift/GamePadShift.c index 37be3d957..48b579457 100644 --- a/shared-bindings/gamepadshift/GamePadShift.c +++ b/shared-bindings/gamepadshift/GamePadShift.c @@ -33,10 +33,7 @@ #include "supervisor/shared/translate.h" //| class GamePadShift: -//| """.. currentmodule:: gamepadshift -//| -//| :class:`GamePadShift` -- Scan buttons for presses through a shift register -//| ===========================================================================""" +//| """Scan buttons for presses through a shift register""" //| //| def __init__(self, clock: Any, data: Any, latch: Any): //| """Initializes button scanning routines. diff --git a/shared-bindings/gamepadshift/__init__.c b/shared-bindings/gamepadshift/__init__.c index 3763b0487..f17135893 100644 --- a/shared-bindings/gamepadshift/__init__.c +++ b/shared-bindings/gamepadshift/__init__.c @@ -30,17 +30,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "shared-bindings/util.h" -//| """:mod:`gamepadshift` --- Tracks button presses read through a shift register -//| =========================================================================== -//| -//| .. module:: gamepadshift -//| :synopsis: Tracks button presses read through a shift register -//| :platform: SAMD21, SAMD51 -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| GamePadShift""" +//| """Tracks button presses read through a shift register""" //| STATIC const mp_rom_map_elem_t gamepadshift_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_gamepadshift) }, diff --git a/shared-bindings/help.c b/shared-bindings/help.c deleted file mode 100644 index 4e7c3a78b..000000000 --- a/shared-bindings/help.c +++ /dev/null @@ -1,34 +0,0 @@ -/* - * This file is part of the MicroPython project, http://micropython.org/ - * - * The MIT License (MIT) - * - * Copyright (c) 2016 Scott Shawcroft for Adafruit Industries - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - * THE SOFTWARE. - */ - -//| :func:`help` - Built-in method to provide helpful information -//| ============================================================== -//| -//| .. function:: help(object=None) -//| -//| Prints a help method about the given object. When ``object`` is none, -//| prints general port information. -//| diff --git a/shared-bindings/help.rst b/shared-bindings/help.rst new file mode 100644 index 000000000..63991bff2 --- /dev/null +++ b/shared-bindings/help.rst @@ -0,0 +1,31 @@ +# This file is part of the MicroPython project, http://micropython.org/ +# +# The MIT License (MIT) +# +# Copyright (c) 2016 Scott Shawcroft for Adafruit Industries +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +:func:`help` - Built-in method to provide helpful information +============================================================== + +.. function:: help(object=None) + + Prints a help method about the given object. When ``object`` is none, + prints general port information. diff --git a/shared-bindings/i2cslave/I2CSlave.c b/shared-bindings/i2cslave/I2CSlave.c index 5bab2af74..80875ce75 100644 --- a/shared-bindings/i2cslave/I2CSlave.c +++ b/shared-bindings/i2cslave/I2CSlave.c @@ -50,10 +50,7 @@ STATIC mp_obj_t mp_obj_new_i2cslave_i2c_slave_request(i2cslave_i2c_slave_obj_t * } //| class I2CSlave: -//| """.. currentmodule:: i2cslave -//| -//| :class:`I2CSlave` --- Two wire serial protocol slave -//| ----------------------------------------------------""" +//| """Two wire serial protocol slave""" //| //| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, addresses: tuple, smbus: bool = False): //| """I2C is a two-wire protocol for communicating between devices. @@ -229,17 +226,15 @@ const mp_obj_type_t i2cslave_i2c_slave_type = { }; //| class I2CSlaveRequest: -//| """:class:`I2CSlaveRequest` --- I2C Slave Request -//| ----------------------------------------------""" //| //| def __init__(self, slave: i2cslave.I2CSlave, address: int, is_read: bool, is_restart: bool): //| """I2C transfer request from a master. //| This cannot be instantiated directly, but is returned by :py:meth:`I2CSlave.request`. //| -//| :param ~i2cslave.I2CSlave slave: The I2C Slave receiving this request -//| :param int address: I2C address -//| :param bool is_read: I2C Master read request -//| :param bool is_restart: Repeated Start Condition""" +//| :param slave: The I2C Slave receiving this request +//| :param address: I2C address +//| :param is_read: I2C Master read request +//| :param is_restart: Repeated Start Condition""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 4, 4, false); @@ -264,7 +259,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_obj___exit__(size_t n_args, const mp_ } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(i2cslave_i2c_slave_request___exit___obj, 4, 4, i2cslave_i2c_slave_request_obj___exit__); -//| address: Any = ... +//| address: int = ... //| """The I2C address of the request.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) { @@ -274,7 +269,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_address_obj, i2cslave_i2c_slave_request_get_address); -//| is_read: Any = ... +//| is_read: bool = ... //| """The I2C master is reading from the device.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) { @@ -284,7 +279,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_is_read_obj, i2cslave_i2c_slave_request_get_is_read); -//| is_restart: Any = ... +//| is_restart: bool = ... //| """Is Repeated Start Condition.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_restart(mp_obj_t self_in) { @@ -294,14 +289,13 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_restart(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_is_restart_obj, i2cslave_i2c_slave_request_get_is_restart); -//| def read(self, n: int = -1, ack: bool = True) -> Any: +//| def read(self, n: int = -1, ack: bool = True) -> bytearray: //| """Read data. //| If ack=False, the caller is responsible for calling :py:meth:`I2CSlaveRequest.ack`. //| -//| :param int n: Number of bytes to read (negative means all) -//| :param bool ack: Whether or not to send an ACK after the n'th byte -//| :return: Bytes read -//| :rtype: bytearray""" +//| :param n: Number of bytes to read (negative means all) +//| :param ack: Whether or not to send an ACK after the n'th byte +//| :return: Bytes read""" //| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_read(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -355,10 +349,10 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_read(size_t n_args, const mp_obj_t *p } MP_DEFINE_CONST_FUN_OBJ_KW(i2cslave_i2c_slave_request_read_obj, 1, i2cslave_i2c_slave_request_read); -//| def write(self, buffer: bytearray) -> Any: +//| def write(self, buffer: bytearray) -> int: //| """Write the data contained in buffer. //| -//| :param bytearray buffer: Write out the data in this buffer +//| :param buffer: Write out the data in this buffer //| :return: Number of bytes written""" //| ... //| @@ -393,7 +387,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(i2cslave_i2c_slave_request_write_obj, i2cslave_ //| """Acknowledge or Not Acknowledge last byte received. //| Use together with :py:meth:`I2CSlaveRequest.read` ack=False. //| -//| :param bool ack: Whether to send an ACK or NACK""" +//| :param ack: Whether to send an ACK or NACK""" //| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_ack(uint n_args, const mp_obj_t *args) { diff --git a/shared-bindings/i2cslave/__init__.c b/shared-bindings/i2cslave/__init__.c index ffeb216fa..41b42fef8 100644 --- a/shared-bindings/i2cslave/__init__.c +++ b/shared-bindings/i2cslave/__init__.c @@ -35,22 +35,10 @@ #include "py/runtime.h" -//| """:mod:`i2cslave` --- Two wire serial protocol slave -//| ================================================== -//| -//| .. module:: i2cslave -//| :synopsis: Two wire serial protocol slave -//| :platform: SAMD21, SAMD51 +//| """Two wire serial protocol slave //| //| The `i2cslave` module contains classes to support a I2C slave. //| -//| Classes -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2CSlave -//| //| Example emulating 2 devices:: //| //| import board diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst index cbffdb614..d94177394 100644 --- a/shared-bindings/index.rst +++ b/shared-bindings/index.rst @@ -7,13 +7,17 @@ present or if flash space is limited. For example, a microcontroller without analog features will not have `analogio`. See the `support_matrix` page for a list of modules supported on each board. +.. toctree:: + :hidden: + + support_matrix + Modules --------- .. toctree:: :glob: - :maxdepth: 3 + :maxdepth: 2 - support_matrix - */__init__ + ../autoapi/*/index help diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c index 755bf7589..56155306f 100644 --- a/shared-bindings/math/__init__.c +++ b/shared-bindings/math/__init__.c @@ -38,12 +38,7 @@ #define MP_PI MICROPY_FLOAT_CONST(3.14159265358979323846) -//| """:mod:`math` --- mathematical functions -//| ======================================================== -//| -//| .. module:: math -//| :synopsis: mathematical functions -//| :platform: SAMD21/SAMD51 +//| """mathematical functions //| //| The `math` module provides some basic mathematical functions for //| working with floating-point numbers.""" diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c index cad0d67b1..765e602e5 100644 --- a/shared-bindings/microcontroller/Pin.c +++ b/shared-bindings/microcontroller/Pin.c @@ -34,12 +34,7 @@ #include "supervisor/shared/translate.h" //| class Pin: -//| """.. currentmodule:: microcontroller -//| -//| :class:`Pin` --- Pin reference -//| ------------------------------------------ -//| -//| Identifies an IO pin on the microcontroller.""" +//| """Identifies an IO pin on the microcontroller.""" //| //| def __init__(self, ): //| """Identifies an IO pin on the microcontroller. They are fixed by the diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c index dedb5a27c..c4b249124 100644 --- a/shared-bindings/microcontroller/Processor.c +++ b/shared-bindings/microcontroller/Processor.c @@ -35,12 +35,7 @@ #include "py/runtime.h" //| class Processor: -//| """.. currentmodule:: microcontroller -//| -//| :class:`Processor` --- Microcontroller CPU information and control -//| ------------------------------------------------------------------ -//| -//| Get information about the microcontroller CPU and control it. +//| """Microcontroller CPU information and control //| //| Usage:: //| @@ -55,8 +50,8 @@ //| ... //| -//| frequency: Any = ... -//| """The CPU operating frequency as an `int`, in Hertz. (read-only)""" +//| frequency: int = ... +//| """The CPU operating frequency in Hertz. (read-only)""" //| STATIC mp_obj_t mcu_processor_get_frequency(mp_obj_t self) { return mp_obj_new_int_from_uint(common_hal_mcu_processor_get_frequency()); diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c index df3ff4186..6db315d8d 100644 --- a/shared-bindings/microcontroller/RunMode.c +++ b/shared-bindings/microcontroller/RunMode.c @@ -27,10 +27,7 @@ #include "shared-bindings/microcontroller/RunMode.h" //| class RunMode: -//| """.. currentmodule:: microcontroller -//| -//| :class:`RunMode` -- run state of the microcontroller -//| =============================================================""" +//| """run state of the microcontroller""" //| //| def __init__(self, ): //| """Enum-like class to define the run mode of the microcontroller and diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c index 75b763980..21e1c90a9 100644 --- a/shared-bindings/microcontroller/__init__.c +++ b/shared-bindings/microcontroller/__init__.c @@ -42,27 +42,13 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| """:mod:`microcontroller` --- Pin references and cpu functionality -//| ================================================================ -//| -//| .. module:: microcontroller -//| :synopsis: Pin references and core functionality -//| :platform: SAMD21, ESP8266 +//| """Pin references and cpu functionality //| //| The `microcontroller` module defines the pins from the perspective of the -//| microcontroller. See `board` for board-specific pin mappings. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Pin -//| Processor -//| RunMode""" +//| microcontroller. See `board` for board-specific pin mappings.""" //| -//| cpu: Any = ... +//| cpu: Processor = ... //| """CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency`` //| (clock frequency). //| This object is the sole instance of `microcontroller.Processor`.""" diff --git a/shared-bindings/multiterminal/__init__.c b/shared-bindings/multiterminal/__init__.c index 3a4065019..baf2fb674 100644 --- a/shared-bindings/multiterminal/__init__.c +++ b/shared-bindings/multiterminal/__init__.c @@ -30,12 +30,7 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| """:mod:`multiterminal` --- Manage additional terminal sources -//| =========================================================== -//| -//| .. module:: multiterminal -//| :synopsis: Manage additional terminal sources -//| :platform: ESP8266 +//| """Manage additional terminal sources //| //| The `multiterminal` module allows you to configure an additional serial //| terminal source. Incoming characters are accepted from both the internal diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c index f18c7fdfd..5e5bc31eb 100644 --- a/shared-bindings/neopixel_write/__init__.c +++ b/shared-bindings/neopixel_write/__init__.c @@ -31,12 +31,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "supervisor/shared/translate.h" -//| """:mod:`neopixel_write` --- Low-level neopixel implementation -//| =========================================================== -//| -//| .. module:: neopixel_write -//| :synopsis: Low-level neopixel implementation -//| :platform: SAMD21 +//| """Low-level neopixel implementation //| //| The `neopixel_write` module contains a helper method to write out bytes in //| the 800khz neopixel protocol. @@ -55,11 +50,11 @@ //| pixel_off = bytearray([0, 0, 0]) //| neopixel_write.neopixel_write(pin, pixel_off)""" //| -//| def neopixel_write(digitalinout: digitalio.DigitalInOut, buf: bytearray) -> Any: +//| def neopixel_write(digitalinout: digitalio.DigitalInOut, buf: bytearray) -> None: //| """Write buf out on the given DigitalInOut. //| -//| :param ~digitalio.DigitalInOut digitalinout: the DigitalInOut to output with -//| :param bytearray buf: The bytes to clock out. No assumption is made about color order""" +//| :param digitalinout: the DigitalInOut to output with +//| :param buf: The bytes to clock out. No assumption is made about color order""" //| ... STATIC mp_obj_t neopixel_write_neopixel_write_(mp_obj_t digitalinout_obj, mp_obj_t buf) { if (!MP_OBJ_IS_TYPE(digitalinout_obj, &digitalio_digitalinout_type)) { diff --git a/shared-bindings/network/__init__.c b/shared-bindings/network/__init__.c index 4f03781cf..6af86688e 100644 --- a/shared-bindings/network/__init__.c +++ b/shared-bindings/network/__init__.c @@ -38,12 +38,7 @@ #if CIRCUITPY_NETWORK -//| """:mod:`network` --- Network Interface Management -//| =============================================== -//| -//| .. module:: network -//| :synopsis: Network Interface Management -//| :platform: SAMD +//| """Network Interface Management //| //| This module provides a registry of configured NICs. //| It is used by the 'socket' module to look up a suitable diff --git a/shared-bindings/nvm/ByteArray.c b/shared-bindings/nvm/ByteArray.c index a28c2c4f9..326f719a8 100644 --- a/shared-bindings/nvm/ByteArray.c +++ b/shared-bindings/nvm/ByteArray.c @@ -31,14 +31,8 @@ #include "shared-bindings/nvm/ByteArray.h" #include "supervisor/shared/translate.h" - - - //| class ByteArray: -//| """.. currentmodule:: nvm -//| -//| :class:`ByteArray` -- Presents a stretch of non-volatile memory as a bytearray. -//| ================================================================================ +//| """Presents a stretch of non-volatile memory as a bytearray. //| //| Non-volatile memory is available as a byte array that persists over reloads //| and power cycles. Each assignment causes an erase and write cycle so its recommended to assign diff --git a/shared-bindings/nvm/__init__.c b/shared-bindings/nvm/__init__.c index 3bd9a309b..51c5bb278 100644 --- a/shared-bindings/nvm/__init__.c +++ b/shared-bindings/nvm/__init__.c @@ -31,23 +31,10 @@ #include "shared-bindings/nvm/__init__.h" #include "shared-bindings/nvm/ByteArray.h" -//| """:mod:`nvm` --- Non-volatile memory -//| =========================================================== -//| -//| .. module:: nvm -//| :synopsis: Non-volatile memory -//| :platform: SAMD21 +//| """Non-volatile memory //| //| The `nvm` module allows you to store whatever raw bytes you wish in a -//| reserved section non-volatile memory. -//| - -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| ByteArray""" +//| reserved section non-volatile memory.""" //| STATIC const mp_rom_map_elem_t nvm_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_nvm) }, diff --git a/shared-bindings/os/__init__.c b/shared-bindings/os/__init__.c index 2a6b13c9b..4e991d089 100644 --- a/shared-bindings/os/__init__.c +++ b/shared-bindings/os/__init__.c @@ -37,12 +37,7 @@ #include "py/runtime.h" #include "shared-bindings/os/__init__.h" -//| """:mod:`os` --- functions that an OS normally provides -//| ======================================================== -//| -//| .. module:: os -//| :synopsis: functions that an OS normally provides -//| :platform: SAMD21 +//| """functions that an OS normally provides //| //| The `os` module is a strict subset of the CPython `cpython:os` module. So, //| code written in CircuitPython will work in CPython but not necessarily the diff --git a/shared-bindings/ps2io/Ps2.c b/shared-bindings/ps2io/Ps2.c index d327d4180..a87b14ddd 100644 --- a/shared-bindings/ps2io/Ps2.c +++ b/shared-bindings/ps2io/Ps2.c @@ -37,10 +37,7 @@ #include "supervisor/shared/translate.h" //| class Ps2: -//| """.. currentmodule:: ps2io -//| -//| :class:`Ps2` -- Communicate with a PS/2 keyboard or mouse -//| ========================================================= +//| """Communicate with a PS/2 keyboard or mouse //| //| Ps2 implements the PS/2 keyboard/mouse serial protocol, used in //| legacy devices. It is similar to UART but there are only two diff --git a/shared-bindings/ps2io/__init__.c b/shared-bindings/ps2io/__init__.c index 081127bac..38a70b1a2 100644 --- a/shared-bindings/ps2io/__init__.c +++ b/shared-bindings/ps2io/__init__.c @@ -33,22 +33,10 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/ps2io/Ps2.h" -//| """:mod:`ps2io` --- Support for PS/2 protocol -//| ===================================================== -//| -//| .. module:: ps2io -//| :synopsis: Support for PS/2 based devices -//| :platform: SAMD21 +//| """Support for PS/2 protocol //| //| The `ps2io` module contains classes to provide PS/2 communication. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Ps2 -//| //| .. warning:: This module is not available in some SAMD21 builds. See the //| :ref:`module-support-matrix` for more info. diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c index 3a25d6938..7970c02f3 100644 --- a/shared-bindings/pulseio/PWMOut.c +++ b/shared-bindings/pulseio/PWMOut.c @@ -36,12 +36,7 @@ #include "supervisor/shared/translate.h" //| class PWMOut: -//| """.. currentmodule:: pulseio -//| -//| :class:`PWMOut` -- Output a Pulse Width Modulated signal -//| ======================================================== -//| -//| PWMOut can be used to output a PWM signal on a given pin.""" +//| """Output a Pulse Width Modulated signal on a given pin.""" //| //| def __init__(self, pin: microcontroller.Pin, *, duty_cycle: int = 0, frequency: int = 500, variable_frequency: bool = False): //| """Create a PWM object associated with the given pin. This allows you to diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c index 9024f53e3..5c52b2582 100644 --- a/shared-bindings/pulseio/PulseIn.c +++ b/shared-bindings/pulseio/PulseIn.c @@ -36,15 +36,9 @@ #include "supervisor/shared/translate.h" //| class PulseIn: -//| """.. currentmodule:: pulseio -//| -//| :class:`PulseIn` -- Read a series of pulse durations -//| ======================================================== -//| -//| PulseIn is used to measure a series of active and idle pulses. This is -//| commonly used in infrared receivers and low cost temperature sensors (DHT). -//| The pulsed signal consists of timed active and idle periods. Unlike PWM, -//| there is no set duration for active and idle pairs.""" +//| """Measure a series of active and idle pulses. This is commonly used in infrared receivers +//| and low cost temperature sensors (DHT). The pulsed signal consists of timed active and +//| idle periods. Unlike PWM, there is no set duration for active and idle pairs.""" //| //| def __init__(self, pin: microcontroller.Pin, maxlen: int = 2, *, idle_state: bool = False): //| """Create a PulseIn object associated with the given pin. The object acts as diff --git a/shared-bindings/pulseio/PulseOut.c b/shared-bindings/pulseio/PulseOut.c index 9c650731b..16b0a6f0c 100644 --- a/shared-bindings/pulseio/PulseOut.c +++ b/shared-bindings/pulseio/PulseOut.c @@ -37,14 +37,9 @@ #include "supervisor/shared/translate.h" //| class PulseOut: -//| """.. currentmodule:: pulseio -//| -//| :class:`PulseOut` -- Output a pulse train -//| ======================================================== -//| -//| PulseOut is used to pulse PWM "carrier" output on and off. This is commonly -//| used in infrared remotes. The pulsed signal consists of timed on and off -//| periods. Unlike PWM, there is no set duration for on and off pairs.""" +//| """Pulse PWM "carrier" output on and off. This is commonly used in infrared remotes. The +//| pulsed signal consists of timed on and off periods. Unlike PWM, there is no set duration +//| for on and off pairs.""" //| //| def __init__(self, carrier: pulseio.PWMOut): //| """Create a PulseOut object associated with the given PWMout object. @@ -115,7 +110,7 @@ STATIC mp_obj_t pulseio_pulseout_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pulseio_pulseout___exit___obj, 4, 4, pulseio_pulseout_obj___exit__); -//| def send(self, pulses: array.array) -> Any: +//| def send(self, pulses: array.array) -> Any: //| """Pulse alternating on and off durations in microseconds starting with on. //| ``pulses`` must be an `array.array` with data type 'H' for unsigned //| halfword (two bytes). diff --git a/shared-bindings/pulseio/__init__.c b/shared-bindings/pulseio/__init__.c index 70cb61fc3..87946e5f0 100644 --- a/shared-bindings/pulseio/__init__.c +++ b/shared-bindings/pulseio/__init__.c @@ -35,24 +35,10 @@ #include "shared-bindings/pulseio/PulseOut.h" #include "shared-bindings/pulseio/PWMOut.h" -//| """:mod:`pulseio` --- Support for pulse based protocols -//| ===================================================== -//| -//| .. module:: pulseio -//| :synopsis: Support for pulse based protocols -//| :platform: SAMD21, ESP8266 +//| """Support for pulse based protocols //| //| The `pulseio` module contains classes to provide access to basic pulse IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PulseIn -//| PulseOut -//| PWMOut -//| //| 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 diff --git a/shared-bindings/random/__init__.c b/shared-bindings/random/__init__.c index d8b266be0..c0124df41 100644 --- a/shared-bindings/random/__init__.c +++ b/shared-bindings/random/__init__.c @@ -33,12 +33,7 @@ #include "shared-bindings/random/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`random` --- pseudo-random numbers and choices -//| ======================================================== -//| -//| .. module:: random -//| :synopsis: pseudo-random numbers and choices -//| :platform: SAMD21, ESP8266 +//| """pseudo-random numbers and choices //| //| The `random` module is a strict subset of the CPython `cpython:random` //| module. So, code written in CircuitPython will work in CPython but not diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index e2393eb61..cbf570958 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -39,10 +39,7 @@ #include "shared-module/framebufferio/FramebufferDisplay.h" //| class RGBMatrix: -//| """.. currentmodule:: rgbmatrix -//| -//| :class:`RGBMatrix` -- Driver for HUB75-style RGB LED matrices -//| ================================================================ +//| """Displays an in-memory framebuffer to a HUB75-style RGB LED matrix.""" //| extern Protomatter_core *_PM_protoPtr; @@ -134,9 +131,6 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ } } - -//| :class:`~rgbmatrix.RGBMatrix` displays an in-memory framebuffer to an LED matrix.""" -//| //| def __init__(self, *, width: Any, bit_depth: Any, rgb_pins: Any, addr_pins: Any, clock_pin: Any, latch_pin: Any, output_enable_pin: Any, doublebuffer: Any = True, framebuffer: Any = None, height: Any = 0): //| """Create a RGBMatrix object with the given attributes. The height of //| the display is determined by the number of rgb and address pins: @@ -297,7 +291,7 @@ const mp_obj_property_t rgbmatrix_rgbmatrix_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def refresh(self, ) -> Any: ... +//| def refresh(self) -> Any: ... //| """Transmits the color data in the buffer to the pixels so that //| they are shown.""" //| @@ -309,7 +303,7 @@ STATIC mp_obj_t rgbmatrix_rgbmatrix_refresh(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(rgbmatrix_rgbmatrix_refresh_obj, rgbmatrix_rgbmatrix_refresh); -//| width: Any = ... +//| width: int = ... //| """The width of the display, in pixels""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_width(mp_obj_t self_in) { @@ -325,7 +319,7 @@ const mp_obj_property_t rgbmatrix_rgbmatrix_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| height: Any = ... +//| height: int = ... //| """The height of the display, in pixels""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_height(mp_obj_t self_in) { diff --git a/shared-bindings/rgbmatrix/__init__.c b/shared-bindings/rgbmatrix/__init__.c index f61002a78..7f0576652 100644 --- a/shared-bindings/rgbmatrix/__init__.c +++ b/shared-bindings/rgbmatrix/__init__.c @@ -31,16 +31,7 @@ #include "shared-bindings/rgbmatrix/RGBMatrix.h" -//| """:mod:`rgbmatrix` --- Low-level routines for bitbanged LED matrices -//| ===================================================================== -//| -//| .. module:: rgbmatrix -//| :synopsis: Low-level routines for bitbanged LED matrices -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| RGBMatrix""" +//| """Low-level routines for bitbanged LED matrices""" //| STATIC const mp_rom_map_elem_t rgbmatrix_module_globals_table[] = { diff --git a/shared-bindings/rotaryio/IncrementalEncoder.c b/shared-bindings/rotaryio/IncrementalEncoder.c index a10fb6fd5..8b2723866 100644 --- a/shared-bindings/rotaryio/IncrementalEncoder.c +++ b/shared-bindings/rotaryio/IncrementalEncoder.c @@ -35,12 +35,7 @@ #include "shared-bindings/util.h" //| class IncrementalEncoder: -//| """.. currentmodule:: rotaryio -//| -//| :class:`IncrementalEncoder` -- Track the relative position of an incremental encoder -//| ==================================================================================== -//| -//| IncrementalEncoder determines the relative rotational position based on two series of pulses.""" +//| """IncrementalEncoder determines the relative rotational position based on two series of pulses.""" //| //| def __init__(self, pin_a: microcontroller.Pin, pin_b: microcontroller.Pin): //| """Create an IncrementalEncoder object associated with the given pins. It tracks the positional diff --git a/shared-bindings/rotaryio/__init__.c b/shared-bindings/rotaryio/__init__.c index 0cc8eb556..0fa457ca7 100644 --- a/shared-bindings/rotaryio/__init__.c +++ b/shared-bindings/rotaryio/__init__.c @@ -33,27 +33,13 @@ #include "shared-bindings/rotaryio/__init__.h" #include "shared-bindings/rotaryio/IncrementalEncoder.h" -//| """:mod:`rotaryio` --- Support for reading rotation sensors -//| ======================================================== -//| -//| .. module:: rotaryio -//| :synopsis: Support for reading rotation sensors -//| :platform: SAMD +//| """Support for reading rotation sensors //| //| The `rotaryio` module contains classes to read different rotation encoding schemes. See //| `Wikipedia's Rotary Encoder page `_ for more //| background. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| IncrementalEncoder -//| -//| .. warning:: This module is not available in some SAMD21 (aka M0) builds. See the -//| :ref:`module-support-matrix` for more info. +//| .. warning:: This module is not available in some SAMD21 (aka M0) builds. See the :ref:`module-support-matrix` for more info. //| //| All classes change hardware state and should be deinitialized when they diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c index 663f5be6c..58fe308f5 100644 --- a/shared-bindings/rtc/RTC.c +++ b/shared-bindings/rtc/RTC.c @@ -38,15 +38,8 @@ const rtc_rtc_obj_t rtc_rtc_obj = {{&rtc_rtc_type}}; - - - - //| class RTC: -//| """.. currentmodule:: rtc -//| -//| :class:`RTC` --- Real Time Clock -//| --------------------------------""" +//| """Real Time Clock""" //| //| def __init__(self, ): //| """This class represents the onboard Real Time Clock. It is a singleton and will always return the same instance.""" @@ -60,7 +53,7 @@ STATIC mp_obj_t rtc_rtc_make_new(const mp_obj_type_t *type, size_t n_args, const return (mp_obj_t)&rtc_rtc_obj; } -//| datetime: Any = ... +//| datetime: time.struct_time = ... //| """The current date and time of the RTC as a `time.struct_time`. //| //| This must be set to the current date and time whenever the board loses power:: @@ -101,7 +94,7 @@ const mp_obj_property_t rtc_rtc_datetime_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| calibration: Any = ... +//| calibration: int = ... //| """The RTC calibration value as an `int`. //| //| A positive value speeds up the clock and a negative value slows it down. diff --git a/shared-bindings/rtc/__init__.c b/shared-bindings/rtc/__init__.c index 66669ca5f..b204d511c 100644 --- a/shared-bindings/rtc/__init__.c +++ b/shared-bindings/rtc/__init__.c @@ -31,23 +31,11 @@ #include "shared-bindings/rtc/RTC.h" #include "shared-bindings/time/__init__.h" -//| """:mod:`rtc` --- Real Time Clock -//| ======================================================== -//| -//| .. module:: rtc -//| :synopsis: Real Time Clock -//| :platform: SAMD21, SAMD51, nRF52 +//| """Real Time Clock //| //| The `rtc` module provides support for a Real Time Clock. You can access and manage the //| RTC using :class:`rtc.RTC`. It also backs the :func:`time.time` and :func:`time.localtime` -//| functions using the onboard RTC if present. -//| -//| Classes -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| RTC""" +//| functions using the onboard RTC if present.""" //| void rtc_reset(void) { diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 4c0811bdb..19c4850cd 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -37,12 +37,7 @@ #include "shared-module/network/__init__.h" -//| """:mod:`socket` --- TCP, UDP and RAW socket support -//| ================================================= -//| -//| .. module:: socket -//| :synopsis: TCP, UDP and RAW sockets -//| :platform: SAMD21, SAMD51 +//| """TCP, UDP and RAW socket support //| //| Create TCP, UDP and RAW sockets for communicating over the Internet.""" //| @@ -50,7 +45,6 @@ STATIC const mp_obj_type_t socket_type; //| class socket: -//| """.. currentmodule:: socket""" //| //| def __init__(self, family: int, type: int, proto: int): //| """Create a new socket diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c index feb1a9bd7..8ac08d8c9 100644 --- a/shared-bindings/storage/__init__.c +++ b/shared-bindings/storage/__init__.c @@ -35,12 +35,7 @@ #include "shared-bindings/storage/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`storage` --- storage management -//| ======================================================== -//| -//| .. module:: storage -//| :synopsis: storage management -//| :platform: SAMD21, SAMD51 +//| """Storage management //| //| The `storage` provides storage management functionality such as mounting and //| unmounting which is typically handled by the operating system hosting Python. diff --git a/shared-bindings/struct/__init__.c b/shared-bindings/struct/__init__.c index 3772f93a7..256b385c8 100644 --- a/shared-bindings/struct/__init__.c +++ b/shared-bindings/struct/__init__.c @@ -38,12 +38,7 @@ #include "shared-module/struct/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`struct` --- manipulation of c-style data -//| ======================================================== -//| -//| .. module:: struct -//| :synopsis: byte data control -//| :platform: SAMD21 +//| """Manipulation of c-style data //| //| This module implements a subset of the corresponding CPython module, //| as described below. For more information, refer to the original CPython @@ -56,7 +51,7 @@ //| -//| def calcsize(fmt: Any) -> Any: +//| def calcsize(fmt: str) -> int: //| """Return the number of bytes needed to store the given fmt.""" //| ... //| diff --git a/shared-bindings/supervisor/Runtime.c b/shared-bindings/supervisor/Runtime.c index 05921899c..a420d5b80 100755 --- a/shared-bindings/supervisor/Runtime.c +++ b/shared-bindings/supervisor/Runtime.c @@ -30,12 +30,7 @@ //TODO: add USB, REPL to description once they're operational //| class Runtime: -//| """.. currentmodule:: supervisor -//| -//| :class:`Runtime` --- Supervisor Runtime information -//| ---------------------------------------------------- -//| -//| Get current status of runtime objects. +//| """Current status of runtime objects. //| //| Usage:: //| @@ -50,7 +45,7 @@ //| ... //| -//| runtime.serial_connected: Any = ... +//| serial_connected: bool = ... //| """Returns the USB serial communication status (read-only). //| //| .. note:: @@ -78,7 +73,7 @@ const mp_obj_property_t supervisor_serial_connected_obj = { }; -//| runtime.serial_bytes_available: Any = ... +//| serial_bytes_available: int = ... //| """Returns the whether any bytes are available to read //| on the USB serial input. Allows for polling to see whether //| to call the built-in input() or wait. (read-only)""" diff --git a/shared-bindings/supervisor/__init__.c b/shared-bindings/supervisor/__init__.c index 7fe6668f4..1830308b7 100644 --- a/shared-bindings/supervisor/__init__.c +++ b/shared-bindings/supervisor/__init__.c @@ -36,30 +36,16 @@ #include "shared-bindings/supervisor/__init__.h" #include "shared-bindings/supervisor/Runtime.h" -//| """:mod:`supervisor` --- Supervisor settings -//| ================================================= -//| -//| .. module:: supervisor -//| :synopsis: Supervisor settings -//| :platform: SAMD21/51 (All), nRF (Runtime only) -//| -//| The `supervisor` module. (TODO: expand description) -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Runtime""" +//| """Supervisor settings""" //| -//| runtime: Any = ... -//| """Runtime information, such as `runtime.serial_connected` +//| runtime: Runtime = ... +//| """Runtime information, such as ``runtime.serial_connected`` //| (USB serial connection status). //| This object is the sole instance of `supervisor.Runtime`.""" //| -//| def enable_autoreload(self, ) -> Any: +//| def enable_autoreload(self) -> None: //| """Enable autoreload based on USB file write activity.""" //| ... //| @@ -69,7 +55,7 @@ STATIC mp_obj_t supervisor_enable_autoreload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_enable_autoreload_obj, supervisor_enable_autoreload); -//| def disable_autoreload(self, ) -> Any: +//| def disable_autoreload(self) -> None: //| """Disable autoreload based on USB file write activity until //| `enable_autoreload` is called.""" //| ... @@ -80,7 +66,7 @@ STATIC mp_obj_t supervisor_disable_autoreload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_disable_autoreload_obj, supervisor_disable_autoreload); -//| def set_rgb_status_brightness(self, ) -> Any: +//| def set_rgb_status_brightness(self, brightness: int) -> None: //| """Set brightness of status neopixel from 0-255 //| `set_rgb_status_brightness` is called.""" //| ... @@ -96,7 +82,7 @@ STATIC mp_obj_t supervisor_set_rgb_status_brightness(mp_obj_t lvl){ } MP_DEFINE_CONST_FUN_OBJ_1(supervisor_set_rgb_status_brightness_obj, supervisor_set_rgb_status_brightness); -//| def reload(self, ) -> Any: +//| def reload(self) -> None: //| """Reload the main Python code and run it (equivalent to hitting Ctrl-D at the REPL).""" //| ... //| @@ -107,7 +93,7 @@ STATIC mp_obj_t supervisor_reload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_reload_obj, supervisor_reload); -//| def set_next_stack_limit(self, size: Any) -> Any: +//| def set_next_stack_limit(self, size: int) -> None: //| """Set the size of the stack for the next vm run. If its too large, the default will be used.""" //| ... //| diff --git a/shared-bindings/terminalio/Terminal.c b/shared-bindings/terminalio/Terminal.c index 1288b7018..5c045fdee 100644 --- a/shared-bindings/terminalio/Terminal.c +++ b/shared-bindings/terminalio/Terminal.c @@ -38,10 +38,7 @@ #include "supervisor/shared/translate.h" //| class Terminal: -//| """.. currentmodule:: terminalio -//| -//| :class:`Terminal` -- display a character stream with a TileGrid -//| ================================================================""" +//| """Display a character stream with a TileGrid""" //| //| def __init__(self, tilegrid: Any, font: Any): //| """Terminal manages tile indices and cursor position based on VT100 commands. The font should be diff --git a/shared-bindings/terminalio/__init__.c b/shared-bindings/terminalio/__init__.c index 591be839a..589211139 100644 --- a/shared-bindings/terminalio/__init__.c +++ b/shared-bindings/terminalio/__init__.c @@ -35,22 +35,10 @@ #include "py/runtime.h" -//| """:mod:`terminalio` --- Displays text in a TileGrid -//| ================================================= -//| -//| .. module:: terminalio -//| :synopsis: Displays text in a TileGrid +//| """Displays text in a TileGrid //| //| The `terminalio` module contains classes to display a character stream on a display. The built -//| in font is available as ``terminalio.FONT``. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Terminal""" -//| +//| in font is available as ``terminalio.FONT``.""" //| STATIC const mp_rom_map_elem_t terminalio_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_terminalio) }, diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c index 36eaa27f6..20277d6b0 100644 --- a/shared-bindings/time/__init__.c +++ b/shared-bindings/time/__init__.c @@ -36,12 +36,7 @@ #include "shared-bindings/time/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`time` --- time and timing related functions -//| ======================================================== -//| -//| .. module:: time -//| :synopsis: time and timing related functions -//| :platform: SAMD21 +//| """time and timing related functions //| //| The `time` module is a strict subset of the CPython `cpython:time` module. So, code //| written in MicroPython will work in CPython but not necessarily the other diff --git a/shared-bindings/touchio/TouchIn.c b/shared-bindings/touchio/TouchIn.c index 6d59a1744..4c1d534ea 100644 --- a/shared-bindings/touchio/TouchIn.c +++ b/shared-bindings/touchio/TouchIn.c @@ -39,10 +39,7 @@ #include "supervisor/shared/translate.h" //| class TouchIn: -//| """.. currentmodule:: touchio -//| -//| :class:`TouchIn` -- Read the state of a capacitive touch sensor -//| =================================================================== +//| """Read the state of a capacitive touch sensor //| //| Usage:: //| diff --git a/shared-bindings/touchio/__init__.c b/shared-bindings/touchio/__init__.c index 96367f082..92e067cf6 100644 --- a/shared-bindings/touchio/__init__.c +++ b/shared-bindings/touchio/__init__.c @@ -35,23 +35,11 @@ #include "py/runtime.h" -//| """:mod:`touchio` --- Touch related IO -//| ================================================= -//| -//| .. module:: touchio -//| :synopsis: Hardware accelerated behavior -//| :platform: SAMD21 +//| """Touch related IO //| //| The `touchio` module contains classes to provide access to touch IO typically //| accelerated by hardware on the onboard microcontroller. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| TouchIn -//| //| 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 diff --git a/shared-bindings/uheap/__init__.c b/shared-bindings/uheap/__init__.c index f1be30424..f089f2922 100644 --- a/shared-bindings/uheap/__init__.c +++ b/shared-bindings/uheap/__init__.c @@ -31,11 +31,7 @@ #include "shared-bindings/uheap/__init__.h" -//| """:mod:`uheap` --- Heap size analysis -//| ================================================================ -//| -//| .. module:: uheap -//| :synopsis: Heap size analysis""" +//| """Heap size analysis""" //| //| def info(object: Any) -> Any: diff --git a/shared-bindings/ulab/__init__.pyi b/shared-bindings/ulab/__init__.pyi new file mode 100644 index 000000000..d2ff7eb80 --- /dev/null +++ b/shared-bindings/ulab/__init__.pyi @@ -0,0 +1,523 @@ + +:mod:`ulab` --- Manipulate numeric data similar to numpy +======================================================== + +.. module:: ulab + :synopsis: Manipulate numeric data similar to numpy + +`ulab` is a numpy-like module for micropython, meant to simplify and +speed up common mathematical operations on arrays. The primary goal was to +implement a small subset of numpy that might be useful in the context of a +microcontroller. This means low-level data processing of linear (array) and +two-dimensional (matrix) data. + +`ulab` is adapted from micropython-ulab, and the original project's +documentation can be found at +https://micropython-ulab.readthedocs.io/en/latest/ + +`ulab` is modeled after numpy, and aims to be a compatible subset where +possible. Numpy's documentation can be found at +https://docs.scipy.org/doc/numpy/index.html + +.. contents:: + +.. attribute:: __version__ + +The closest corresponding version of micropython-ulab + +ulab.array -- 1- and 2- dimensional array +----------------------------------------- + +.. class:: ulab.array(values, \*, dtype=float) + + :param sequence values: Sequence giving the initial content of the array. + :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` + + The `values` sequence can either be another ~ulab.array, sequence of numbers + (in which case a 1-dimensional array is created), or a sequence where each + subsequence has the same length (in which case a 2-dimensional array is + created). + + Passing a ~ulab.array and a different dtype can be used to convert an array + from one dtype to another. + + In many cases, it is more convenient to create an array from a function + like `zeros` or `linspace`. + + `ulab.array` implements the buffer protocol, so it can be used in many + places an `array.array` can be used. + + .. attribute:: shape + + The size of the array, a tuple of length 1 or 2 + + .. attribute:: size + + The number of elements in the array + + .. attribute:: itemsize + + The number of elements in the array + + .. method:: flatten(\*, order='C') + + :param order: Whether to flatten by rows ('C') or columns ('F') + + Returns a new `ulab.array` object which is always 1 dimensional. + If order is 'C' (the default", then the data is ordered in rows; + If it is 'F', then the data is ordered in columns. "C" and "F" refer + to the typical storage organization of the C and Fortran languages. + + .. method:: sort(\*, axis=1) + + :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) + + .. method:: transpose() + + Swap the rows and columns of a 2-dimensional array + + .. method:: __add__() + + Adds corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match. + + .. method:: __sub__() + + Subtracts corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match. + + .. method:: __mul__() + + Multiplies corresponding elements of the two arrays, or multiplies + all elements of the array by a number. If both arguments are arrays, + their sizes must match. + + .. method:: __div__() + + Multiplies corresponding elements of the two arrays, or divides + all elements of the array by a number. If both arguments are arrays, + their sizes must match. + + .. method:: __pow__() + + Computes the power (x**y) of corresponding elements of the the two arrays, + or one number and one array. If both arguments are arrays, their sizes + must match. + + .. method:: __getitem__() + + Retrieve an element of the array. + + .. method:: __setitem__() + + Set an element of the array. + +Array type codes +---------------- +.. attribute:: int8 + + Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` + +.. attribute:: int16 + + Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` + +.. attribute:: float + + Type code for floating point values, like the 'f' typecode of `array.array` + +.. attribute:: uint8 + + Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` + +.. attribute:: uint16 + + Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` + + +Basic Array defining functions +------------------------------ + +.. method:: ones(shape, \*, dtype=float) + + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + + .. param: dtype + Type of values in the array + + Return a new array of the given shape with all elements set to 1. + +.. method:: zeros + + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + + .. param: dtype + Type of values in the array + + Return a new array of the given shape with all elements set to 0. + + +.. method:: eye(size, \*, dtype=float) + + Return a new square array of size, with the diagonal elements set to 1 + and the other elements set to 0. + +.. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) + + .. param: start + + First value in the array + + .. param: stop + + Final value in the array + + .. param int: num + + Count of values in the array + + .. param: dtype + + Type of values in the array + + .. param bool: endpoint + + Whether the ``stop`` value is included. Note that even when + endpoint=True, the exact ``stop`` value may not be included due to the + inaccuracy of floating point arithmetic. + + Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. + + +:mod:`ulab.compare` --- Comparison functions +============================================ + +.. module::ulab.compare + +.. method:: clip(x1, x2, x3) + + Constrain the values from ``x1`` to be between ``x2`` and ``x3``. + ``x2`` is assumed to be less than or equal to ``x3``. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are all scalars, a 1-element + array is returned. + + Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))`` + +.. method:: maximum(x1, x2) + + Compute the element by element maximum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned + +.. method:: minimum(x1, x2) + + Compute the element by element minimum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned + + +:mod:`ulab.vector` --- Element-by-element functions +=================================================== + +.. module:: ulab.vector + +These functions can operate on numbers, 1-D arrays, or 2-D arrays by +applying the function to every element in the array. This is typically +much more efficient than expressing the same operation as a Python loop. + +.. method:: acos + + Computes the inverse cosine function + +.. method:: acosh + + Computes the inverse hyperbolic cosine function + +.. method:: asin + + Computes the inverse sine function + +.. method:: asinh + + Computes the inverse hyperbolic sine function + +.. method:: around(a, \*, decimals) + + Returns a new float array in which each element is rounded to + ``decimals`` places. + +.. method:: atan + + Computes the inverse tangent function; the return values are in the + range [-pi/2,pi/2]. + +.. method:: atan2(y,x) + + Computes the inverse tangent function of y/x; the return values are in + the range [-pi, pi]. + +.. method:: atanh + + Computes the inverse hyperbolic tangent function + +.. method:: ceil + + Rounds numbers up to the next whole number + +.. method:: cos + + Computes the cosine function + +.. method:: erf + + Computes the error function, which has applications in statistics + +.. method:: erfc + + Computes the complementary error function, which has applications in statistics + +.. method:: exp + + Computes the exponent function. + +.. method:: expm1 + + Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. + +.. method:: floor + + Rounds numbers up to the next whole number + +.. method:: gamma + + Computes the gamma function + +.. method:: lgamma + + Computes the natural log of the gamma function + +.. method:: log + + Computes the natural log + +.. method:: log10 + + Computes the log base 10 + +.. method:: log2 + + Computes the log base 2 + +.. method:: sin + + Computes the sine + +.. method:: sinh + + Computes the hyperbolic sine + +.. method:: sqrt + + Computes the square root + +.. method:: tan + + Computes the tangent + +.. method:: tanh + + Computes the hyperbolic tangent + +:mod:`ulab.linalg` - Linear algebra functions +============================================= + +.. module:: ulab.linalg + +.. method:: cholesky(A) + + :param ~ulab.array A: a positive definite, symmetric square matrix + :return ~ulab.array L: a square root matrix in the lower triangular form + :raises ValueError: If the input does not fulfill the necessary conditions + + The returned matrix satisfies the equation m=LL* + +.. method:: det + + :param: m, a square matrix + :return float: The determinant of the matrix + + Computes the eigenvalues and eigenvectors of a square matrix + +.. method:: dot(m1, m2) + + :param ~ulab.array m1: a matrix + :param ~ulab.array m2: a matrix + + Computes the matrix product of two matrices + + **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors + +.. method:: eig(m) + + :param m: a square matrix + :return tuple (eigenvectors, eigenvalues): + + Computes the eigenvalues and eigenvectors of a square matrix + +.. method:: inv(m) + + :param ~ulab.array m: a square matrix + :return: The inverse of the matrix, if it exists + :raises ValueError: if the matrix is not invertible + + Computes the inverse of a square matrix + +.. method:: size(array) + + Return the total number of elements in the array, as an integer. + +.. method:: trace(m) + + :param m: a square matrix + + Compute the trace of the matrix, the sum of its diagonal elements. + +:mod:`ulab.filter` --- Filtering functions +========================================== + +.. module:: ulab.filter + +.. method:: convolve(r, c=None) + + :param ulab.array a: + :param ulab.array v: + + Returns the discrete, linear convolution of two one-dimensional sequences. + The result is always an array of float. Only the ``full`` mode is supported, + and the ``mode`` named parameter of numpy is not accepted. Note that all other + modes can be had by slicing a ``full`` result. + + Convolution filters can implement high pass, low pass, band pass, etc., + filtering operations. Convolution filters are typically constructed ahead + of time. This can be done using desktop python with scipy, or on web pages + such as https://fiiir.com/ + + Convolution is most time-efficient when both inputs are of float type. + +:mod:`ulab.fft` --- Frequency-domain functions +============================================== + +.. module:: ulab.fft + +.. method:: fft(r, c=None) + + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the FFT + + Perform a Fast Fourier Transform from the time domain into the frequency domain + + See also ~ulab.extras.spectrum, which computes the magnitude of the fft, + rather than separately returning its real and imaginary parts. + +.. method:: ifft(r, c=None) + + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the inverse FFT + + Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain + +:mod:`ulab.numerical` --- Numerical and Statistical functions +============================================================= + +.. module:: ulab.numerical + +Most of these functions take an "axis" argument, which indicates whether to +operate over the flattened array (None), rows (0), or columns (1). + +.. method:: argmax(array, \*, axis=None) + + Return the index of the maximum element of the 1D array + +.. method:: argmin(array, \*, axis=None) + + Return the index of the minimum element of the 1D array + +.. method:: argsort(array, \*, axis=None) + + Returns an array which gives indices into the input array from least to greatest. + +.. method:: diff(array, \*, axis=1) + + Return the numerical derivative of successive elements of the array, as + an array. axis=None is not supported. + +.. method:: flip(array, \*, axis=None) + + Returns a new array that reverses the order of the elements along the + given axis, or along all axes if axis is None. + +.. method:: max(array, \*, axis=None) + + Return the maximum element of the 1D array + +.. method:: mean(array, \*, axis=None) + + Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. + +.. method:: min(array, \*, axis=None) + + Return the minimum element of the 1D array + +.. method:: roll(array, distance, \*, axis=None) + + Shift the content of a vector by the positions given as the second + argument. If the ``axis`` keyword is supplied, the shift is applied to + the given axis. The array is modified in place. + +.. method:: std(array, \*, axis=None) + + Return the standard deviation of the array, as a number if axis is None, otherwise as an array. + +.. method:: sum(array, \*, axis=None) + + Return the sum of the array, as a number if axis is None, otherwise as an array. + +.. method:: sort(array, \*, axis=0) + + Sort the array along the given axis, or along all axes if axis is None. + The array is modified in place. + +:mod:`ulab.poly` --- Polynomial functions +========================================= + +.. module:: ulab.poly + +.. method:: polyfit([x, ] y, degree) + + Return a polynomial of given degree that approximates the function + f(x)=y. If x is not supplied, it is the range(len(y)). + +.. method:: polyval(p, x) + + Evaluate the polynomial p at the points x. x must be an array. + +:mod:`ulab.extras` --- Additional functions not in numpy +======================================================== + +.. method:: spectrum(r): + + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + + Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. + + This function is similar to scipy's ``scipy.signal.spectrogram``. diff --git a/shared-bindings/ulab/__init__.rst b/shared-bindings/ulab/__init__.rst deleted file mode 100644 index d2ff7eb80..000000000 --- a/shared-bindings/ulab/__init__.rst +++ /dev/null @@ -1,523 +0,0 @@ - -:mod:`ulab` --- Manipulate numeric data similar to numpy -======================================================== - -.. module:: ulab - :synopsis: Manipulate numeric data similar to numpy - -`ulab` is a numpy-like module for micropython, meant to simplify and -speed up common mathematical operations on arrays. The primary goal was to -implement a small subset of numpy that might be useful in the context of a -microcontroller. This means low-level data processing of linear (array) and -two-dimensional (matrix) data. - -`ulab` is adapted from micropython-ulab, and the original project's -documentation can be found at -https://micropython-ulab.readthedocs.io/en/latest/ - -`ulab` is modeled after numpy, and aims to be a compatible subset where -possible. Numpy's documentation can be found at -https://docs.scipy.org/doc/numpy/index.html - -.. contents:: - -.. attribute:: __version__ - -The closest corresponding version of micropython-ulab - -ulab.array -- 1- and 2- dimensional array ------------------------------------------ - -.. class:: ulab.array(values, \*, dtype=float) - - :param sequence values: Sequence giving the initial content of the array. - :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` - - The `values` sequence can either be another ~ulab.array, sequence of numbers - (in which case a 1-dimensional array is created), or a sequence where each - subsequence has the same length (in which case a 2-dimensional array is - created). - - Passing a ~ulab.array and a different dtype can be used to convert an array - from one dtype to another. - - In many cases, it is more convenient to create an array from a function - like `zeros` or `linspace`. - - `ulab.array` implements the buffer protocol, so it can be used in many - places an `array.array` can be used. - - .. attribute:: shape - - The size of the array, a tuple of length 1 or 2 - - .. attribute:: size - - The number of elements in the array - - .. attribute:: itemsize - - The number of elements in the array - - .. method:: flatten(\*, order='C') - - :param order: Whether to flatten by rows ('C') or columns ('F') - - Returns a new `ulab.array` object which is always 1 dimensional. - If order is 'C' (the default", then the data is ordered in rows; - If it is 'F', then the data is ordered in columns. "C" and "F" refer - to the typical storage organization of the C and Fortran languages. - - .. method:: sort(\*, axis=1) - - :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) - - .. method:: transpose() - - Swap the rows and columns of a 2-dimensional array - - .. method:: __add__() - - Adds corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. - - .. method:: __sub__() - - Subtracts corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. - - .. method:: __mul__() - - Multiplies corresponding elements of the two arrays, or multiplies - all elements of the array by a number. If both arguments are arrays, - their sizes must match. - - .. method:: __div__() - - Multiplies corresponding elements of the two arrays, or divides - all elements of the array by a number. If both arguments are arrays, - their sizes must match. - - .. method:: __pow__() - - Computes the power (x**y) of corresponding elements of the the two arrays, - or one number and one array. If both arguments are arrays, their sizes - must match. - - .. method:: __getitem__() - - Retrieve an element of the array. - - .. method:: __setitem__() - - Set an element of the array. - -Array type codes ----------------- -.. attribute:: int8 - - Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` - -.. attribute:: int16 - - Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` - -.. attribute:: float - - Type code for floating point values, like the 'f' typecode of `array.array` - -.. attribute:: uint8 - - Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` - -.. attribute:: uint16 - - Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` - - -Basic Array defining functions ------------------------------- - -.. method:: ones(shape, \*, dtype=float) - - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) - - .. param: dtype - Type of values in the array - - Return a new array of the given shape with all elements set to 1. - -.. method:: zeros - - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) - - .. param: dtype - Type of values in the array - - Return a new array of the given shape with all elements set to 0. - - -.. method:: eye(size, \*, dtype=float) - - Return a new square array of size, with the diagonal elements set to 1 - and the other elements set to 0. - -.. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) - - .. param: start - - First value in the array - - .. param: stop - - Final value in the array - - .. param int: num - - Count of values in the array - - .. param: dtype - - Type of values in the array - - .. param bool: endpoint - - Whether the ``stop`` value is included. Note that even when - endpoint=True, the exact ``stop`` value may not be included due to the - inaccuracy of floating point arithmetic. - - Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. - - -:mod:`ulab.compare` --- Comparison functions -============================================ - -.. module::ulab.compare - -.. method:: clip(x1, x2, x3) - - Constrain the values from ``x1`` to be between ``x2`` and ``x3``. - ``x2`` is assumed to be less than or equal to ``x3``. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are all scalars, a 1-element - array is returned. - - Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))`` - -.. method:: maximum(x1, x2) - - Compute the element by element maximum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - -.. method:: minimum(x1, x2) - - Compute the element by element minimum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - - -:mod:`ulab.vector` --- Element-by-element functions -=================================================== - -.. module:: ulab.vector - -These functions can operate on numbers, 1-D arrays, or 2-D arrays by -applying the function to every element in the array. This is typically -much more efficient than expressing the same operation as a Python loop. - -.. method:: acos - - Computes the inverse cosine function - -.. method:: acosh - - Computes the inverse hyperbolic cosine function - -.. method:: asin - - Computes the inverse sine function - -.. method:: asinh - - Computes the inverse hyperbolic sine function - -.. method:: around(a, \*, decimals) - - Returns a new float array in which each element is rounded to - ``decimals`` places. - -.. method:: atan - - Computes the inverse tangent function; the return values are in the - range [-pi/2,pi/2]. - -.. method:: atan2(y,x) - - Computes the inverse tangent function of y/x; the return values are in - the range [-pi, pi]. - -.. method:: atanh - - Computes the inverse hyperbolic tangent function - -.. method:: ceil - - Rounds numbers up to the next whole number - -.. method:: cos - - Computes the cosine function - -.. method:: erf - - Computes the error function, which has applications in statistics - -.. method:: erfc - - Computes the complementary error function, which has applications in statistics - -.. method:: exp - - Computes the exponent function. - -.. method:: expm1 - - Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. - -.. method:: floor - - Rounds numbers up to the next whole number - -.. method:: gamma - - Computes the gamma function - -.. method:: lgamma - - Computes the natural log of the gamma function - -.. method:: log - - Computes the natural log - -.. method:: log10 - - Computes the log base 10 - -.. method:: log2 - - Computes the log base 2 - -.. method:: sin - - Computes the sine - -.. method:: sinh - - Computes the hyperbolic sine - -.. method:: sqrt - - Computes the square root - -.. method:: tan - - Computes the tangent - -.. method:: tanh - - Computes the hyperbolic tangent - -:mod:`ulab.linalg` - Linear algebra functions -============================================= - -.. module:: ulab.linalg - -.. method:: cholesky(A) - - :param ~ulab.array A: a positive definite, symmetric square matrix - :return ~ulab.array L: a square root matrix in the lower triangular form - :raises ValueError: If the input does not fulfill the necessary conditions - - The returned matrix satisfies the equation m=LL* - -.. method:: det - - :param: m, a square matrix - :return float: The determinant of the matrix - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: dot(m1, m2) - - :param ~ulab.array m1: a matrix - :param ~ulab.array m2: a matrix - - Computes the matrix product of two matrices - - **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors - -.. method:: eig(m) - - :param m: a square matrix - :return tuple (eigenvectors, eigenvalues): - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: inv(m) - - :param ~ulab.array m: a square matrix - :return: The inverse of the matrix, if it exists - :raises ValueError: if the matrix is not invertible - - Computes the inverse of a square matrix - -.. method:: size(array) - - Return the total number of elements in the array, as an integer. - -.. method:: trace(m) - - :param m: a square matrix - - Compute the trace of the matrix, the sum of its diagonal elements. - -:mod:`ulab.filter` --- Filtering functions -========================================== - -.. module:: ulab.filter - -.. method:: convolve(r, c=None) - - :param ulab.array a: - :param ulab.array v: - - Returns the discrete, linear convolution of two one-dimensional sequences. - The result is always an array of float. Only the ``full`` mode is supported, - and the ``mode`` named parameter of numpy is not accepted. Note that all other - modes can be had by slicing a ``full`` result. - - Convolution filters can implement high pass, low pass, band pass, etc., - filtering operations. Convolution filters are typically constructed ahead - of time. This can be done using desktop python with scipy, or on web pages - such as https://fiiir.com/ - - Convolution is most time-efficient when both inputs are of float type. - -:mod:`ulab.fft` --- Frequency-domain functions -============================================== - -.. module:: ulab.fft - -.. method:: fft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the FFT - - Perform a Fast Fourier Transform from the time domain into the frequency domain - - See also ~ulab.extras.spectrum, which computes the magnitude of the fft, - rather than separately returning its real and imaginary parts. - -.. method:: ifft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the inverse FFT - - Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain - -:mod:`ulab.numerical` --- Numerical and Statistical functions -============================================================= - -.. module:: ulab.numerical - -Most of these functions take an "axis" argument, which indicates whether to -operate over the flattened array (None), rows (0), or columns (1). - -.. method:: argmax(array, \*, axis=None) - - Return the index of the maximum element of the 1D array - -.. method:: argmin(array, \*, axis=None) - - Return the index of the minimum element of the 1D array - -.. method:: argsort(array, \*, axis=None) - - Returns an array which gives indices into the input array from least to greatest. - -.. method:: diff(array, \*, axis=1) - - Return the numerical derivative of successive elements of the array, as - an array. axis=None is not supported. - -.. method:: flip(array, \*, axis=None) - - Returns a new array that reverses the order of the elements along the - given axis, or along all axes if axis is None. - -.. method:: max(array, \*, axis=None) - - Return the maximum element of the 1D array - -.. method:: mean(array, \*, axis=None) - - Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. - -.. method:: min(array, \*, axis=None) - - Return the minimum element of the 1D array - -.. method:: roll(array, distance, \*, axis=None) - - Shift the content of a vector by the positions given as the second - argument. If the ``axis`` keyword is supplied, the shift is applied to - the given axis. The array is modified in place. - -.. method:: std(array, \*, axis=None) - - Return the standard deviation of the array, as a number if axis is None, otherwise as an array. - -.. method:: sum(array, \*, axis=None) - - Return the sum of the array, as a number if axis is None, otherwise as an array. - -.. method:: sort(array, \*, axis=0) - - Sort the array along the given axis, or along all axes if axis is None. - The array is modified in place. - -:mod:`ulab.poly` --- Polynomial functions -========================================= - -.. module:: ulab.poly - -.. method:: polyfit([x, ] y, degree) - - Return a polynomial of given degree that approximates the function - f(x)=y. If x is not supplied, it is the range(len(y)). - -.. method:: polyval(p, x) - - Evaluate the polynomial p at the points x. x must be an array. - -:mod:`ulab.extras` --- Additional functions not in numpy -======================================================== - -.. method:: spectrum(r): - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - - Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. - - This function is similar to scipy's ``scipy.signal.spectrogram``. diff --git a/shared-bindings/usb_hid/Device.c b/shared-bindings/usb_hid/Device.c index bcea5b2c5..8c0c364ff 100644 --- a/shared-bindings/usb_hid/Device.c +++ b/shared-bindings/usb_hid/Device.c @@ -28,10 +28,7 @@ #include "shared-bindings/usb_hid/Device.h" //| class Device: -//| """.. currentmodule:: usb_hid -//| -//| :class:`Device` -- HID Device -//| ============================================ +//| """HID Device //| //| Usage:: //| diff --git a/shared-bindings/usb_hid/__init__.c b/shared-bindings/usb_hid/__init__.c index 3d0978d62..e12ea8da4 100644 --- a/shared-bindings/usb_hid/__init__.c +++ b/shared-bindings/usb_hid/__init__.c @@ -31,12 +31,7 @@ #include "shared-bindings/usb_hid/__init__.h" #include "shared-bindings/usb_hid/Device.h" -//| """:mod:`usb_hid` --- USB Human Interface Device -//| =========================================================== -//| -//| .. module:: usb_hid -//| :synopsis: USB Human Interface Device -//| :platform: SAMD21 +//| """USB Human Interface Device //| //| The `usb_hid` module allows you to output data as a HID device.""" //| @@ -44,14 +39,6 @@ //| usb_hid.devices: Any = ... //| """Tuple of all active HID device interfaces.""" //| - -//| """Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Device""" -//| STATIC const mp_rom_map_elem_t usb_hid_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_usb_hid) }, { MP_ROM_QSTR(MP_QSTR_devices), MP_ROM_PTR(&common_hal_usb_hid_devices) }, diff --git a/shared-bindings/usb_midi/PortIn.c b/shared-bindings/usb_midi/PortIn.c index 55a5865ca..9d9310b47 100644 --- a/shared-bindings/usb_midi/PortIn.c +++ b/shared-bindings/usb_midi/PortIn.c @@ -36,12 +36,9 @@ #include "supervisor/shared/translate.h" //| class PortIn: -//| """.. currentmodule:: usb_midi +//| """Receives midi commands over USB""" //| -//| :class:`PortIn` -- receives midi commands over USB -//| ===================================================""" -//| -//| def __init__(self, ): +//| def __init__(self): //| """You cannot create an instance of `usb_midi.PortIn`. //| //| PortIn objects are constructed for every corresponding entry in the USB diff --git a/shared-bindings/usb_midi/PortOut.c b/shared-bindings/usb_midi/PortOut.c index d83eb53b6..14ed0e767 100644 --- a/shared-bindings/usb_midi/PortOut.c +++ b/shared-bindings/usb_midi/PortOut.c @@ -36,10 +36,7 @@ #include "supervisor/shared/translate.h" //| class PortOut: -//| """.. currentmodule:: usb_midi -//| -//| :class:`PortOut` -- sends midi messages to a computer over USB -//| ==============================================================""" +//| """Sends midi messages to a computer over USB""" //| //| def __init__(self, ): //| """You cannot create an instance of `usb_midi.PortOut`. diff --git a/shared-bindings/usb_midi/__init__.c b/shared-bindings/usb_midi/__init__.c index 2631d8a88..5570b601c 100644 --- a/shared-bindings/usb_midi/__init__.c +++ b/shared-bindings/usb_midi/__init__.c @@ -35,22 +35,7 @@ #include "py/runtime.h" -//| """:mod:`usb_midi` --- MIDI over USB -//| ================================================= -//| -//| .. module:: usb_midi -//| :synopsis: MIDI over USB -//| -//| The `usb_midi` module contains classes to transmit and receive MIDI messages over USB -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PortIn -//| PortOut""" -//| +//| """Classes to transmit and receive MIDI messages over USB""" //| mp_map_elem_t usb_midi_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_usb_midi) }, diff --git a/shared-bindings/ustack/__init__.c b/shared-bindings/ustack/__init__.c index 073840aba..e5fac6941 100644 --- a/shared-bindings/ustack/__init__.c +++ b/shared-bindings/ustack/__init__.c @@ -34,15 +34,11 @@ -//| """:mod:`ustack` --- Stack information and analysis -//| ======================================================== -//| -//| .. module:: ustack -//| :synopsis: stack information functions""" +//| """Stack information and analysis""" //| #if MICROPY_MAX_STACK_USAGE -//| def max_stack_usage() -> Any: +//| def max_stack_usage() -> int: //| """Return the maximum excursion of the stack so far.""" //| ... //| @@ -53,7 +49,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_0(max_stack_usage_obj, max_stack_usage); #endif // MICROPY_MAX_STACK_USAGE -//| def stack_size() -> Any: +//| def stack_size() -> int: //| """Return the size of the entire stack. //| Same as in micropython.mem_info(), but returns a value instead //| of just printing it.""" diff --git a/shared-bindings/wiznet/__init__.c b/shared-bindings/wiznet/__init__.c index 5c8e8d3fd..0b0b7b14b 100644 --- a/shared-bindings/wiznet/__init__.c +++ b/shared-bindings/wiznet/__init__.c @@ -35,21 +35,7 @@ #include "shared-module/network/__init__.h" -//| """:mod:`wiznet` --- Support for WizNet hardware -//| ============================================= -//| -//| .. module:: wiznet -//| :synopsis: Support for WizNet hardware -//| :platform: SAMD -//| -//| Support for WizNet hardware, including the WizNet 5500 Ethernet adaptor. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| wiznet5k""" +//| """Support for WizNet hardware, including the WizNet 5500 Ethernet adaptor.""" //| extern const mod_network_nic_type_t mod_network_nic_type_wiznet5k; diff --git a/shared-bindings/wiznet/wiznet5k.c b/shared-bindings/wiznet/wiznet5k.c index 2e2ee3949..2f49dffea 100644 --- a/shared-bindings/wiznet/wiznet5k.c +++ b/shared-bindings/wiznet/wiznet5k.c @@ -47,10 +47,7 @@ #include "shared-module/wiznet/wiznet5k.h" //| class WIZNET5K: -//| """.. currentmodule:: wiznet -//| -//| :class:`WIZNET5K` -- wrapper for Wiznet 5500 Ethernet interface -//| ===============================================================""" +//| """Wrapper for Wiznet 5500 Ethernet interface""" //| //| def __init__(self, spi: busio.SPI, cs: microcontroller.Pin, rst: microcontroller.Pin, dhcp: bool = True): //| """Create a new WIZNET5500 interface using the specified pins diff --git a/tools/extract_pyi.py b/tools/extract_pyi.py index de783eb27..95370f761 100644 --- a/tools/extract_pyi.py +++ b/tools/extract_pyi.py @@ -22,7 +22,7 @@ for module in modules: pyi_lines = [] classes = os.listdir(module_path) classes = [x for x in sorted(classes) if x.endswith(".c")] - if classes[-1] == "__init__.c": + if classes and classes[-1] == "__init__.c": classes.insert(0, classes.pop()) for class_file in classes: class_path = os.path.join(module_path, class_file) @@ -37,6 +37,13 @@ for module in modules: continue pyi_lines.append(line) + raw_stubs = [x for x in sorted(classes) if x.endswith(".pyi")] + if raw_stubs and raw_stubs[-1] == "__init__.pyi": + raw_stubs.insert(0, raw_stubs.pop()) + for raw_stub in raw_stubs: + raw_stub_path = os.path.join(module_path, raw_stub) + with open(raw_stub_path, "r") as f: + pyi_lines.extend(f.readlines()) stub_filename = os.path.join(stub_directory, module + ".pyi") print(stub_filename) stub_contents = "".join(pyi_lines) @@ -54,3 +61,6 @@ for module in modules: print() print(f"{ok} ok out of {total}") + +if ok != total: + sys.exit(total - ok) -- cgit v1.2.3 From 4e646ee6e4473195df3eba4bd7e006e44bfd1cdc Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Tue, 12 May 2020 18:40:02 -0700 Subject: Move vectorio to stubs --- shared-bindings/vectorio/Circle.c | 18 ++++++------------ shared-bindings/vectorio/Polygon.c | 23 ++++++++--------------- shared-bindings/vectorio/Rectangle.c | 14 +++++--------- shared-bindings/vectorio/VectorShape.c | 33 ++++++++++++++------------------- shared-bindings/vectorio/__init__.c | 21 +-------------------- 5 files changed, 34 insertions(+), 75 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/vectorio/Circle.c b/shared-bindings/vectorio/Circle.c index 260e80d0f..6b5682e14 100644 --- a/shared-bindings/vectorio/Circle.c +++ b/shared-bindings/vectorio/Circle.c @@ -9,17 +9,12 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: vectorio -//| -//| :class:`Circle` -- Represents a circle by its radius -//| ========================================================================== +//| class Circle: //| -//| .. class:: Circle(radius) +//| def __init__(self, radius: int): +//| """Circle is positioned on screen by its center point. //| -//| Circle is positioned on screen by its center point. -//| -//| :param int radius: The radius of the circle in pixels +//| :param radius: The radius of the circle in pixels""" //| static mp_obj_t vectorio_circle_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_radius }; @@ -42,9 +37,8 @@ static mp_obj_t vectorio_circle_make_new(const mp_obj_type_t *type, size_t n_arg } -//| .. attribute:: radius -//| -//| The radius of the circle in pixels. +//| radius : int = ... +//| """The radius of the circle in pixels.""" //| STATIC mp_obj_t vectorio_circle_obj_get_radius(mp_obj_t self_in) { vectorio_circle_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/vectorio/Polygon.c b/shared-bindings/vectorio/Polygon.c index b8bb377ac..5f4d85e21 100644 --- a/shared-bindings/vectorio/Polygon.c +++ b/shared-bindings/vectorio/Polygon.c @@ -49,17 +49,13 @@ static mp_obj_t _to_points_list(mp_obj_t points_tuple_list) { } return points_list; } - - - -//| .. currentmodule:: vectorio -//| -//| :class:`Polygon` -- Represents a closed shape by ordered vertices -//| ========================================================================== +//| from typing import List, Tuple //| -//| .. class:: Polygon( List[ Tuple[ x, y ], ... ] ) +//| class Polygon: +//| def __init__(self, points: List[ Tuple[ x, y ], ... ] ): +//| """Represents a closed shape by ordered vertices //| -//| :param [Point] points_array: Vertices for the polygon +//| :param points: Vertices for the polygon""" //| static mp_obj_t vectorio_polygon_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_points_list }; @@ -83,14 +79,13 @@ static mp_obj_t vectorio_polygon_make_new(const mp_obj_type_t *type, size_t n_ar } -//| .. attribute:: points -//| -//| Set a new look and shape for this polygon +//| points: List[ Tuple[ x, y ], ... ] = ... +//| """Set a new look and shape for this polygon""" //| STATIC mp_obj_t vectorio_polygon_obj_get_points(mp_obj_t self_in) { vectorio_polygon_t *self = MP_OBJ_TO_PTR(self_in); mp_obj_t list = mp_obj_new_list(0, NULL); - + size_t len = 0; mp_obj_t *items; mp_obj_list_get(common_hal_vectorio_polygon_get_points(self), &len, &items); @@ -123,8 +118,6 @@ const mp_obj_property_t vectorio_polygon_points_obj = { (mp_obj_t)&mp_const_none_obj}, }; - - STATIC const mp_rom_map_elem_t vectorio_polygon_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_points), MP_ROM_PTR(&vectorio_polygon_points_obj) }, }; diff --git a/shared-bindings/vectorio/Rectangle.c b/shared-bindings/vectorio/Rectangle.c index ea468f788..f04a25c35 100644 --- a/shared-bindings/vectorio/Rectangle.c +++ b/shared-bindings/vectorio/Rectangle.c @@ -7,16 +7,12 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" - -//| .. currentmodule:: vectorio -//| -//| :class:`Rectangle` -- Represents a rectangle by defining its bounds -//| ========================================================================== -//| -//| .. class:: Rectangle(width, height) +//| class Rectangle: +//| def __init__(self, width: int, height: int): +//| """Represents a rectangle by defining its bounds //| -//| :param int width: The number of pixels wide -//| :param int height: The number of pixels high +//| :param width: The number of pixels wide +//| :param height: The number of pixels high""" //| static mp_obj_t vectorio_rectangle_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_width, ARG_height }; diff --git a/shared-bindings/vectorio/VectorShape.c b/shared-bindings/vectorio/VectorShape.c index 4b39ec996..c512bcd54 100644 --- a/shared-bindings/vectorio/VectorShape.c +++ b/shared-bindings/vectorio/VectorShape.c @@ -19,17 +19,15 @@ #include "supervisor/shared/translate.h" -//| .. currentmodule:: vectorio +//| class VectorShape: +//| def __init__(self, shape: vectorio.Polygon, pixel_shader: displayio.Palette, x: int=0, y: int=0): +//| """Binds a vector shape to a location and pixel color //| -//| :class:`VectorShape` -- Binds a vector shape to a location and pixel color -//| ========================================================================== -//| -//| .. class:: VectorShape( shape, pixel_shader, x=0, y=0) -//| -//| :param vectorio.Polygon shape: The shape to draw. -//| :param displayio.Palette pixel_shader: The pixel shader that produces colors from values -//| :param int x: Initial x position of the center axis of the shape within the parent. -//| :param int y: Initial y position of the center axis of the shape within the parent. +//| :param shape: The shape to draw. +//| :param pixel_shader: The pixel shader that produces colors from values +//| :param x: Initial x position of the center axis of the shape within the parent. +//| :param y: Initial y position of the center axis of the shape within the parent.""" +//| ... //| STATIC mp_obj_t vectorio_vector_shape_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_shape, ARG_pixel_shader, ARG_x, ARG_y }; @@ -95,9 +93,8 @@ STATIC mp_obj_t vectorio_vector_shape_make_new(const mp_obj_type_t *type, size_t } -//| .. attribute:: x -//| -//| X position of the center point of the shape in the parent. +//| x: int = ... +//| """X position of the center point of the shape in the parent.""" //| STATIC mp_obj_t vectorio_vector_shape_obj_get_x(mp_obj_t self_in) { vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); @@ -122,9 +119,8 @@ const mp_obj_property_t vectorio_vector_shape_x_obj = { }; -//| .. attribute:: y -//| -//| Y position of the center point of the shape in the parent. +//| y: int = ... +//| """Y position of the center point of the shape in the parent.""" //| STATIC mp_obj_t vectorio_vector_shape_obj_get_y(mp_obj_t self_in) { vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); @@ -149,9 +145,8 @@ const mp_obj_property_t vectorio_vector_shape_y_obj = { }; -//| .. attribute:: pixel_shader -//| -//| The pixel shader of the shape. +//| pixel_shader: displayio.Palette = ... +//| """The pixel shader of the shape.""" //| STATIC mp_obj_t vectorio_vector_shape_obj_get_pixel_shader(mp_obj_t self_in) { vectorio_vector_shape_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/vectorio/__init__.c b/shared-bindings/vectorio/__init__.c index b9e3828bd..c74783426 100644 --- a/shared-bindings/vectorio/__init__.c +++ b/shared-bindings/vectorio/__init__.c @@ -8,27 +8,8 @@ #include "shared-bindings/vectorio/Rectangle.h" #include "shared-bindings/vectorio/VectorShape.h" -//| :mod:`vectorio` --- Lightweight 2d shapes for displays -//| ========================================================================= +//| """Lightweight 2d shapes for displays""" //| -//| .. module:: vectorio -//| :synopsis: Adds vector graphics to displayio -//| :platform: SAMD21, SAMD51, nRF52 -//| -//| The `vectorio` module contains classes to construct shapes -//| by describing their points rather than providing them in bitmaps. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Circle -//| Polygon -//| Rectangle -//| VectorShape -//| - STATIC const mp_rom_map_elem_t vectorio_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_vectorio) }, -- cgit v1.2.3 From fbf052bb2755b2a3afb85b94ea9625ab29da4ab0 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Wed, 13 May 2020 10:04:19 -0500 Subject: Gamepad & GamepadShift: Enable ticks while object exists Otherwise, button presses might not be noticed. --- shared-bindings/gamepad/GamePad.c | 4 ++++ shared-bindings/gamepadshift/GamePadShift.c | 4 ++++ shared-module/gamepad/GamePad.c | 2 ++ shared-module/gamepad/__init__.c | 4 ++++ shared-module/gamepadshift/GamePadShift.c | 2 ++ 5 files changed, 16 insertions(+) (limited to 'shared-bindings') diff --git a/shared-bindings/gamepad/GamePad.c b/shared-bindings/gamepad/GamePad.c index d3c29019a..88f072f3e 100644 --- a/shared-bindings/gamepad/GamePad.c +++ b/shared-bindings/gamepad/GamePad.c @@ -33,6 +33,7 @@ #include "shared-bindings/gamepad/__init__.h" #include "shared-bindings/digitalio/DigitalInOut.h" #include "supervisor/shared/translate.h" +#include "supervisor/shared/tick.h" //| .. currentmodule:: gamepad @@ -108,6 +109,9 @@ STATIC mp_obj_t gamepad_make_new(const mp_obj_type_t *type, size_t n_args, gamepad_singleton = m_new_obj(gamepad_obj_t); gamepad_singleton->base.type = &gamepad_type; gamepad_singleton = gc_make_long_lived(gamepad_singleton); + if (!MP_STATE_VM(gamepad_singleton)) { + supervisor_enable_tick(); + } MP_STATE_VM(gamepad_singleton) = gamepad_singleton; } common_hal_gamepad_gamepad_init(gamepad_singleton, args, n_args); diff --git a/shared-bindings/gamepadshift/GamePadShift.c b/shared-bindings/gamepadshift/GamePadShift.c index 91203ad20..76f054aae 100644 --- a/shared-bindings/gamepadshift/GamePadShift.c +++ b/shared-bindings/gamepadshift/GamePadShift.c @@ -31,6 +31,7 @@ #include "shared-bindings/gamepadshift/GamePadShift.h" #include "shared-bindings/gamepadshift/__init__.h" #include "supervisor/shared/translate.h" +#include "supervisor/shared/tick.h" //| .. currentmodule:: gamepadshift //| @@ -75,6 +76,9 @@ STATIC mp_obj_t gamepadshift_make_new(const mp_obj_type_t *type, size_t n_args, gamepad_singleton = m_new_obj(gamepadshift_obj_t); gamepad_singleton->base.type = &gamepadshift_type; gamepad_singleton = gc_make_long_lived(gamepad_singleton); + if (!MP_STATE_VM(gamepad_singleton)) { + supervisor_enable_tick(); + } MP_STATE_VM(gamepad_singleton) = gamepad_singleton; } common_hal_gamepadshift_gamepadshift_init(gamepad_singleton, clock_pin, data_pin, latch_pin); diff --git a/shared-module/gamepad/GamePad.c b/shared-module/gamepad/GamePad.c index fdce0caab..7b4108eb2 100644 --- a/shared-module/gamepad/GamePad.c +++ b/shared-module/gamepad/GamePad.c @@ -27,6 +27,7 @@ #include "py/mpstate.h" #include "shared-bindings/digitalio/DigitalInOut.h" #include "shared-bindings/gamepad/GamePad.h" +#include "supervisor/shared/tick.h" void common_hal_gamepad_gamepad_init(gamepad_obj_t *gamepad, const mp_obj_t pins[], size_t n_pins) { @@ -54,4 +55,5 @@ void common_hal_gamepad_gamepad_init(gamepad_obj_t *gamepad, void common_hal_gamepad_gamepad_deinit(gamepad_obj_t *self) { MP_STATE_VM(gamepad_singleton) = NULL; + supervisor_disable_tick(); } diff --git a/shared-module/gamepad/__init__.c b/shared-module/gamepad/__init__.c index 3e17a0fb5..9874b2752 100644 --- a/shared-module/gamepad/__init__.c +++ b/shared-module/gamepad/__init__.c @@ -29,6 +29,7 @@ #include "py/mpstate.h" #include "shared-bindings/gamepad/__init__.h" #include "shared-bindings/gamepad/GamePad.h" +#include "supervisor/shared/tick.h" #include "shared-bindings/digitalio/DigitalInOut.h" @@ -59,5 +60,8 @@ void gamepad_tick(void) { } void gamepad_reset(void) { + if (MP_STATE_VM(gamepad_singleton)) { + supervisor_disable_tick(); + } MP_STATE_VM(gamepad_singleton) = NULL; } diff --git a/shared-module/gamepadshift/GamePadShift.c b/shared-module/gamepadshift/GamePadShift.c index b8fb4d3f4..51da61702 100644 --- a/shared-module/gamepadshift/GamePadShift.c +++ b/shared-module/gamepadshift/GamePadShift.c @@ -27,6 +27,7 @@ #include "py/mpstate.h" #include "shared-bindings/digitalio/DigitalInOut.h" #include "shared-module/gamepadshift/GamePadShift.h" +#include "supervisor/shared/tick.h" void common_hal_gamepadshift_gamepadshift_init(gamepadshift_obj_t *gamepadshift, digitalio_digitalinout_obj_t *clock_pin, @@ -46,4 +47,5 @@ void common_hal_gamepadshift_gamepadshift_init(gamepadshift_obj_t *gamepadshift, void common_hal_gamepadshift_gamepadshift_deinit(gamepadshift_obj_t *gamepadshift) { MP_STATE_VM(gamepad_singleton) = NULL; + supervisor_disable_tick(); } -- cgit v1.2.3 From 23ba58bbf574d029d5b18e57c40d4257b37dfd7a Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Wed, 13 May 2020 10:05:48 -0500 Subject: Gamepad & GamepadShift: Initially allocate as long-lived This makes less heap churn and decreases code size a tiny bit --- shared-bindings/gamepad/GamePad.c | 3 +-- shared-bindings/gamepadshift/GamePadShift.c | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/gamepad/GamePad.c b/shared-bindings/gamepad/GamePad.c index 88f072f3e..d6f91c1c0 100644 --- a/shared-bindings/gamepad/GamePad.c +++ b/shared-bindings/gamepad/GamePad.c @@ -106,9 +106,8 @@ STATIC mp_obj_t gamepad_make_new(const mp_obj_type_t *type, size_t n_args, gamepad_obj_t* gamepad_singleton = MP_STATE_VM(gamepad_singleton); if (!gamepad_singleton || !MP_OBJ_IS_TYPE(MP_OBJ_FROM_PTR(gamepad_singleton), &gamepad_type)) { - gamepad_singleton = m_new_obj(gamepad_obj_t); + gamepad_singleton = m_new_ll_obj(gamepad_obj_t); gamepad_singleton->base.type = &gamepad_type; - gamepad_singleton = gc_make_long_lived(gamepad_singleton); if (!MP_STATE_VM(gamepad_singleton)) { supervisor_enable_tick(); } diff --git a/shared-bindings/gamepadshift/GamePadShift.c b/shared-bindings/gamepadshift/GamePadShift.c index 76f054aae..9586e01ed 100644 --- a/shared-bindings/gamepadshift/GamePadShift.c +++ b/shared-bindings/gamepadshift/GamePadShift.c @@ -73,9 +73,8 @@ STATIC mp_obj_t gamepadshift_make_new(const mp_obj_type_t *type, size_t n_args, if (!gamepad_singleton || !MP_OBJ_IS_TYPE(MP_OBJ_FROM_PTR(gamepad_singleton), &gamepadshift_type)) { - gamepad_singleton = m_new_obj(gamepadshift_obj_t); + gamepad_singleton = m_new_ll_obj(gamepadshift_obj_t); gamepad_singleton->base.type = &gamepadshift_type; - gamepad_singleton = gc_make_long_lived(gamepad_singleton); if (!MP_STATE_VM(gamepad_singleton)) { supervisor_enable_tick(); } -- cgit v1.2.3 From 3ffa5604fc0523aa131be4a353fb883a9c8a37ff Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Wed, 13 May 2020 08:36:16 -0700 Subject: Update countio to python stub docs --- shared-bindings/busio/UART.c | 10 +++--- shared-bindings/countio/Counter.c | 70 +++++++++++++++++--------------------- shared-bindings/countio/__init__.c | 16 ++------- 3 files changed, 38 insertions(+), 58 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index d4642225c..2bd36145d 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -346,13 +346,11 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_o //| class Parity: //| """Enum-like class to define the parity used to verify correct data transfer.""" //| -//| def __init__(self, ): -//| ODD: Any = ... -//| """Total number of ones should be odd.""" +//| ODD: Any = ... +//| """Total number of ones should be odd.""" //| -//| EVEN: Any = ... -//| """Total number of ones should be even.""" -//| ... +//| EVEN: Any = ... +//| """Total number of ones should be even.""" //| const mp_obj_type_t busio_uart_parity_type; diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c index d9d97f0ea..8db795015 100644 --- a/shared-bindings/countio/Counter.c +++ b/shared-bindings/countio/Counter.c @@ -9,45 +9,41 @@ #include "shared-bindings/countio/Counter.h" #include "shared-bindings/util.h" -//| .. currentmodule:: countio +//| class Counter: +//| """Counter will keep track of the number of falling edge transistions (pulses) on a +//| given pin""" //| -//| :class:`Counter` -- Track the count of falling edge transistions (pulses) on a given pin -//| ======================================================================================== +//| def __init__(self, pin_a): +//| """Create a Counter object associated with the given pin. It tracks the number of +//| falling pulses relative when the object is constructed. //| -//| Counter will keep track of the number of falling edge transistions (pulses) on a given pin +//| :param ~microcontroller.Pin pin_a: Pin to read pulses from. //| -//| .. class:: Counter(pin_a) //| -//| Create a Counter object associated with the given pin. It tracks the number of -//| falling pulses relative when the object is constructed. +//| For example:: //| -//| :param ~microcontroller.Pin pin_a: Pin to read pulses from. -//| +//| import countio +//| import time +//| from board import * //| -//| For example:: -//| -//| import countio -//| import time -//| from board import * -//| -//| pin_counter = countio.Counter(board.D1) -//| #reset the count after 100 counts -//| while True: -//| if pin_counter.count == 100: -//| pin_counter.reset() -//| print(pin_counter.count) +//| pin_counter = countio.Counter(board.D1) +//| #reset the count after 100 counts +//| while True: +//| if pin_counter.count == 100: +//| pin_counter.reset() +//| print(pin_counter.count)""" //| STATIC mp_obj_t countio_counter_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pin_a }; static const mp_arg_t allowed_args[] = { { MP_QSTR_pin_a, MP_ARG_REQUIRED | MP_ARG_OBJ } - + }; mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); const mcu_pin_obj_t* pin_a = validate_obj_is_free_pin(args[ARG_pin_a].u_obj); - + countio_counter_obj_t *self = m_new_obj(countio_counter_obj_t); self->base.type = &countio_counter_type; @@ -57,9 +53,8 @@ STATIC mp_obj_t countio_counter_make_new(const mp_obj_type_t *type, size_t n_arg return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Deinitializes the Counter and releases any hardware resources for reuse. +//| def deinit(self): +//| """Deinitializes the Counter and releases any hardware resources for reuse.""" //| STATIC mp_obj_t countio_counter_deinit(mp_obj_t self_in) { countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -74,16 +69,14 @@ STATIC void check_for_deinit(countio_counter_obj_t *self) { } } -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self): +//| """No-op used by Context Managers.""" //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self): +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" //| STATIC mp_obj_t countio_counter_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -93,10 +86,8 @@ STATIC mp_obj_t countio_counter_obj___exit__(size_t n_args, const mp_obj_t *args STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(countio_counter___exit___obj, 4, 4, countio_counter_obj___exit__); -//| .. attribute:: count -//| -//| The current count in terms of pulses. -//| +//| count: int = ... +//| """The current count in terms of pulses.""" //| STATIC mp_obj_t countio_counter_obj_get_count(mp_obj_t self_in) { countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -122,6 +113,9 @@ const mp_obj_property_t countio_counter_count_obj = { (mp_obj_t)&mp_const_none_obj}, }; +//| def reset(self): +//| """Resets the count back to 0.""" +//| STATIC mp_obj_t countio_counter_reset(mp_obj_t self_in){ countio_counter_obj_t *self = MP_OBJ_TO_PTR(self_in); check_for_deinit(self); @@ -129,7 +123,7 @@ STATIC mp_obj_t countio_counter_reset(mp_obj_t self_in){ common_hal_countio_counter_reset(self); return mp_const_none; } - + MP_DEFINE_CONST_FUN_OBJ_1(countio_counter_reset_obj, countio_counter_reset); diff --git a/shared-bindings/countio/__init__.c b/shared-bindings/countio/__init__.c index 8929bf7ed..7046a5e72 100644 --- a/shared-bindings/countio/__init__.c +++ b/shared-bindings/countio/__init__.c @@ -8,22 +8,10 @@ #include "shared-bindings/countio/__init__.h" #include "shared-bindings/countio/Counter.h" -//| :mod:`countio` --- Support for edge counting -//| ======================================================== -//| -//| .. module:: countio -//| :synopsis: Support for edge counting -//| :platform: SAMD +//| """Support for edge counting //| //| The `countio` module contains logic to read and count edge transistions //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Counter -//| //| .. warning:: This module is not available in some SAMD21 (aka M0) builds. See the //| :ref:`module-support-matrix` for more info. @@ -32,7 +20,7 @@ //| 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. +//| :ref:`lifetime-and-contextmanagers` for more info.""" //| STATIC const mp_rom_map_elem_t countio_module_globals_table[] = { -- cgit v1.2.3 From b477c4812d1f0d0ed0fe56abcdcaa356cc3a652e Mon Sep 17 00:00:00 2001 From: dherrada Date: Thu, 14 May 2020 16:58:25 -0400 Subject: Fixed minor indentation issue --- shared-bindings/analogio/AnalogIn.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index bafa287ff..400784b39 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -70,9 +70,9 @@ STATIC mp_obj_t analogio_analogin_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: -//| """Turn off the AnalogIn and release the pin for other use.""" -//| ... +//| def deinit(self, ) -> Any: +//| """Turn off the AnalogIn and release the pin for other use.""" +//| ... //| STATIC mp_obj_t analogio_analogin_deinit(mp_obj_t self_in) { analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in); -- cgit v1.2.3 From afc84c2fd115aa1c7a80bd5d83834c30c4563a6c Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 14 May 2020 15:57:35 -0700 Subject: Fix ulab, math and template. --- .gitignore | 2 +- Makefile | 9 +- conf.py | 6 +- docs/autoapi/templates/python/module.rst | 93 +++++ shared-bindings/math/__init__.c | 324 ++++++++-------- shared-bindings/ulab/__init__.pyi | 564 ++++++---------------------- shared-bindings/ulab/compare/__init__.pyi | 30 ++ shared-bindings/ulab/extras/__init__.pyi | 10 + shared-bindings/ulab/fft/__init__.pyi | 22 ++ shared-bindings/ulab/filter/__init__.pyi | 19 + shared-bindings/ulab/linalg/__init__.pyi | 57 +++ shared-bindings/ulab/numerical/__init__.pyi | 57 +++ shared-bindings/ulab/poly/__init__.pyi | 10 + shared-bindings/ulab/vector/__init__.pyi | 108 ++++++ tools/extract_pyi.py | 77 ++-- 15 files changed, 719 insertions(+), 669 deletions(-) create mode 100644 docs/autoapi/templates/python/module.rst create mode 100644 shared-bindings/ulab/compare/__init__.pyi create mode 100644 shared-bindings/ulab/extras/__init__.pyi create mode 100644 shared-bindings/ulab/fft/__init__.pyi create mode 100644 shared-bindings/ulab/filter/__init__.pyi create mode 100644 shared-bindings/ulab/linalg/__init__.pyi create mode 100644 shared-bindings/ulab/numerical/__init__.pyi create mode 100644 shared-bindings/ulab/poly/__init__.pyi create mode 100644 shared-bindings/ulab/vector/__init__.pyi (limited to 'shared-bindings') diff --git a/.gitignore b/.gitignore index 403fcc299..f5edb89f0 100644 --- a/.gitignore +++ b/.gitignore @@ -52,7 +52,7 @@ _build # Generated rst files ###################### genrst/ -autoapi/ +/autoapi/ # ctags and similar ################### diff --git a/Makefile b/Makefile index 1971076a3..842c18da5 100644 --- a/Makefile +++ b/Makefile @@ -67,6 +67,7 @@ help: clean: rm -rf $(BUILDDIR)/* + rm -rf autoapi rm -rf $(STUBDIR) $(DISTDIR) *.egg-info html: stubs @@ -213,10 +214,10 @@ check-translate: locale/circuitpython.pot $(wildcard locale/*.po) $(PYTHON) tools/check_translations.py $^ stubs: - mkdir -p circuitpython-stubs - python tools/extract_pyi.py shared-bindings/ $(STUBDIR) - python tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR) - python setup.py sdist + @mkdir -p circuitpython-stubs + @$(PYTHON) tools/extract_pyi.py shared-bindings/ $(STUBDIR) + @$(PYTHON) tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR) + @$(PYTHON) setup.py -q sdist update-frozen-libraries: @echo "Updating all frozen libraries to latest tagged version." diff --git a/conf.py b/conf.py index aea84dd21..ee65e39fb 100644 --- a/conf.py +++ b/conf.py @@ -71,11 +71,13 @@ extensions.append('autoapi.extension') autoapi_type = 'python' # Uncomment this if debugging autoapi -# autoapi_keep_files = True -autoapi_dirs = ['circuitpython-stubs'] +autoapi_keep_files = True +autoapi_dirs = [os.path.join('circuitpython-stubs', x) for x in os.listdir('circuitpython-stubs')] +print(autoapi_dirs) autoapi_add_toctree_entry = False autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary'] autoapi_template_dir = 'docs/autoapi/templates' +autoapi_python_use_implicit_namespaces = True # The encoding of source files. #source_encoding = 'utf-8-sig' diff --git a/docs/autoapi/templates/python/module.rst b/docs/autoapi/templates/python/module.rst new file mode 100644 index 000000000..7ede6bdfd --- /dev/null +++ b/docs/autoapi/templates/python/module.rst @@ -0,0 +1,93 @@ +{% if not obj.display %} +:orphan: + +{% endif %} +:mod:`{{ obj.name }}` +======={{ "=" * obj.name|length }} + +.. py:module:: {{ obj.name }} + +{% if obj.docstring %} +.. autoapi-nested-parse:: + + {{ obj.docstring|prepare_docstring|indent(3) }} + +{% endif %} + +{% block subpackages %} +{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} +{% if visible_subpackages %} +.. toctree:: + :titlesonly: + :maxdepth: 3 + +{% for subpackage in visible_subpackages %} + {{ subpackage.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block submodules %} +{% set visible_submodules = obj.submodules|selectattr("display")|list %} +{% if visible_submodules %} + +.. toctree:: + :titlesonly: + :maxdepth: 1 + +{% for submodule in visible_submodules %} + {{ submodule.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block content %} +{% if obj.all is not none %} +{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %} +{% elif obj.type is equalto("package") %} +{% set visible_children = obj.children|selectattr("display")|list %} +{% else %} +{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} +{% endif %} +{% if visible_children %} + +{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} +{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} +{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} +{% block classes %} +{% if visible_classes %} +Classes +~~~~~~~ + +.. autoapisummary:: + +{% for klass in visible_classes %} + {{ klass.id }} +{% endfor %} + + +{% endif %} +{% endblock %} + +{% block functions %} +{% if visible_functions %} +Functions +~~~~~~~~~ + +.. autoapisummary:: + +{% for function in visible_functions %} + {{ function.id }} +{% endfor %} + + +{% endif %} +{% endblock %} +{% endif %} +{% for obj_item in visible_children %} +{{ obj_item.rendered|indent(0) }} +{% endfor %} +{% endif %} +{% endblock %} diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c index 56155306f..8226a08ec 100644 --- a/shared-bindings/math/__init__.c +++ b/shared-bindings/math/__init__.c @@ -78,178 +78,170 @@ STATIC NORETURN void math_error(void) { // 1.442695040888963407354163704 is 1/_M_LN2 #define log2(x) (log(x) * 1.442695040888963407354163704) #endif - //| Constants - //| --------- - //| - //| e: Any = ... - //| """base of the natural logarithm""" - //| - //| pi: Any = ... - //| """the ratio of a circle's circumference to its diameter""" - //| - - //| Functions - //| --------- - //| - //| def acos(x: Any) -> Any: - //| """Return the inverse cosine of ``x``.""" - //| ... - //| - //| def asin(x: Any) -> Any: - //| """Return the inverse sine of ``x``.""" - //| ... - //| - //| def atan(x: Any) -> Any: - //| """Return the inverse tangent of ``x``.""" - //| ... - //| - //| def atan2(y: Any, x: Any) -> Any: - //| """Return the principal value of the inverse tangent of ``y/x``.""" - //| ... - //| - //| def ceil(x: Any) -> Any: - //| """Return an integer, being ``x`` rounded towards positive infinity.""" - //| ... - //| - //| def copysign(x: Any, y: Any) -> Any: - //| """Return ``x`` with the sign of ``y``.""" - //| ... - //| - //| def cos(x: Any) -> Any: - //| """Return the cosine of ``x``.""" - //| ... - //| - //| def degrees(x: Any) -> Any: - //| """Return radians ``x`` converted to degrees.""" - //| ... - //| - //| def exp(x: Any) -> Any: - //| """Return the exponential of ``x``.""" - //| ... - //| - //| def fabs(x: Any) -> Any: - //| """Return the absolute value of ``x``.""" - //| ... - //| - //| def floor(x: Any) -> Any: - //| """Return an integer, being ``x`` rounded towards negative infinity.""" - //| ... - //| - //| def fmod(x: Any, y: Any) -> Any: - //| """Return the remainder of ``x/y``.""" - //| ... - //| - //| def frexp(x: Any) -> Any: - //| """Decomposes a floating-point number into its mantissa and exponent. - //| The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` - //| exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise - //| the relation ``0.5 <= abs(m) < 1`` holds.""" - //| ... - //| - //| def isfinite(x: Any) -> Any: - //| """Return ``True`` if ``x`` is finite.""" - //| ... - //| - //| def isinf(x: Any) -> Any: - //| """Return ``True`` if ``x`` is infinite.""" - //| ... - //| - //| def isnan(x: Any) -> Any: - //| """Return ``True`` if ``x`` is not-a-number""" - //| ... - //| - //| def ldexp(x: Any, exp: Any) -> Any: - //| """Return ``x * (2**exp)``.""" - //| ... - //| - //| def modf(x: Any) -> Any: - //| """Return a tuple of two floats, being the fractional and integral parts of - //| ``x``. Both return values have the same sign as ``x``.""" - //| ... - //| - //| def pow(x: Any, y: Any) -> Any: - //| """Returns ``x`` to the power of ``y``.""" - //| - //| def radians(x: Any) -> Any: - //| """Return degrees ``x`` converted to radians.""" - //| - //| def sin(x: Any) -> Any: - //| """Return the sine of ``x``.""" - //| ... - //| - //| def sqrt(x: Any) -> Any: - //| """Returns the square root of ``x``.""" - //| ... - //| - //| def tan(x: Any) -> Any: ... - //| """Return the tangent of ``x``.""" - //| ... - //| - //| def trunc(x: Any) -> Any: - //| """Return an integer, being ``x`` rounded towards 0.""" - //| ... - //| + +//| e: Any = ... +//| """base of the natural logarithm""" +//| +//| pi: Any = ... +//| """the ratio of a circle's circumference to its diameter""" +//| + +//| def acos(x: Any) -> Any: +//| """Return the inverse cosine of ``x``.""" +//| ... +//| +//| def asin(x: Any) -> Any: +//| """Return the inverse sine of ``x``.""" +//| ... +//| +//| def atan(x: Any) -> Any: +//| """Return the inverse tangent of ``x``.""" +//| ... +//| +//| def atan2(y: Any, x: Any) -> Any: +//| """Return the principal value of the inverse tangent of ``y/x``.""" +//| ... +//| +//| def ceil(x: Any) -> Any: +//| """Return an integer, being ``x`` rounded towards positive infinity.""" +//| ... +//| +//| def copysign(x: Any, y: Any) -> Any: +//| """Return ``x`` with the sign of ``y``.""" +//| ... +//| +//| def cos(x: Any) -> Any: +//| """Return the cosine of ``x``.""" +//| ... +//| +//| def degrees(x: Any) -> Any: +//| """Return radians ``x`` converted to degrees.""" +//| ... +//| +//| def exp(x: Any) -> Any: +//| """Return the exponential of ``x``.""" +//| ... +//| +//| def fabs(x: Any) -> Any: +//| """Return the absolute value of ``x``.""" +//| ... +//| +//| def floor(x: Any) -> Any: +//| """Return an integer, being ``x`` rounded towards negative infinity.""" +//| ... +//| +//| def fmod(x: Any, y: Any) -> Any: +//| """Return the remainder of ``x/y``.""" +//| ... +//| +//| def frexp(x: Any) -> Any: +//| """Decomposes a floating-point number into its mantissa and exponent. +//| The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` +//| exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise +//| the relation ``0.5 <= abs(m) < 1`` holds.""" +//| ... +//| +//| def isfinite(x: Any) -> Any: +//| """Return ``True`` if ``x`` is finite.""" +//| ... +//| +//| def isinf(x: Any) -> Any: +//| """Return ``True`` if ``x`` is infinite.""" +//| ... +//| +//| def isnan(x: Any) -> Any: +//| """Return ``True`` if ``x`` is not-a-number""" +//| ... +//| +//| def ldexp(x: Any, exp: Any) -> Any: +//| """Return ``x * (2**exp)``.""" +//| ... +//| +//| def modf(x: Any) -> Any: +//| """Return a tuple of two floats, being the fractional and integral parts of +//| ``x``. Both return values have the same sign as ``x``.""" +//| ... +//| +//| def pow(x: Any, y: Any) -> Any: +//| """Returns ``x`` to the power of ``y``.""" +//| +//| def radians(x: Any) -> Any: +//| """Return degrees ``x`` converted to radians.""" +//| +//| def sin(x: Any) -> Any: +//| """Return the sine of ``x``.""" +//| ... +//| +//| def sqrt(x: Any) -> Any: +//| """Returns the square root of ``x``.""" +//| ... +//| +//| def tan(x: Any) -> Any: +//| """Return the tangent of ``x``.""" +//| ... +//| +//| def trunc(x: Any) -> Any: +//| """Return an integer, being ``x`` rounded towards 0.""" +//| ... +//| MATH_FUN_1_ERRCOND(sqrt, sqrt, (x < (mp_float_t)0.0)) MATH_FUN_2(pow, pow) MATH_FUN_1(exp, exp) #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -// Special functions -// ----------------- -// -// .. function:: expm1(x) -// -// Return ``exp(x) - 1``. -// +//| def expm1(x): +//| """Return ``exp(x) - 1``.""" +//| ... +//| MATH_FUN_1(expm1, expm1) -// .. function:: log2(x) -// -// Return the base-2 logarithm of ``x``. -// +//| def log2(x): +//| """Return the base-2 logarithm of ``x``.""" +//| ... +//| MATH_FUN_1_ERRCOND(log2, log2, (x <= (mp_float_t)0.0)) -// .. function:: log10(x) -// -// Return the base-10 logarithm of ``x``. -// +//| def log10(x): +//| """Return the base-10 logarithm of ``x``.""" +//| ... +//| MATH_FUN_1_ERRCOND(log10, log10, (x <= (mp_float_t)0.0)) -// .. function:: cosh(x) -// -// Return the hyperbolic cosine of ``x``. -// +//| def cosh(x): +//| """Return the hyperbolic cosine of ``x``.""" +//| ... +//| MATH_FUN_1(cosh, cosh) -// .. function:: sinh(x) -// -// Return the hyperbolic sine of ``x``. -// +//| def sinh(x): +//| """Return the hyperbolic sine of ``x``.""" +//| ... +//| MATH_FUN_1(sinh, sinh) -// .. function:: tanh(x) -// -// Return the hyperbolic tangent of ``x``. -// +//| def tanh(x): +//| """Return the hyperbolic tangent of ``x``.""" +//| ... +//| MATH_FUN_1(tanh, tanh) -// .. function:: acosh(x) -// -// Return the inverse hyperbolic cosine of ``x``. -// +//| def acosh(x): +//| """Return the inverse hyperbolic cosine of ``x``.""" +//| ... +//| MATH_FUN_1(acosh, acosh) -// .. function:: asinh(x) -// -// Return the inverse hyperbolic sine of ``x``. -// +//| def asinh(x): +//| """Return the inverse hyperbolic sine of ``x``.""" +//| ... +//| MATH_FUN_1(asinh, asinh) -// .. function:: atanh(x) -// -// Return the inverse hyperbolic tangent of ``x``. -// +//| def atanh(x): +//| """Return the inverse hyperbolic tangent of ``x``.""" +//| ... +//| MATH_FUN_1(atanh, atanh) #endif @@ -288,28 +280,28 @@ MATH_FUN_1_TO_INT(trunc, trunc) MATH_FUN_2(ldexp, ldexp) #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -// .. function:: erf(x) -// -// Return the error function of ``x``. -// +//| def erf(x): +//| """Return the error function of ``x``.""" +//| ... +//| MATH_FUN_1(erf, erf) -// .. function:: erfc(x) -// -// Return the complementary error function of ``x``. -// +//| def erfc(x): +//| """Return the complementary error function of ``x``.""" +//| ... +//| MATH_FUN_1(erfc, erfc) -// .. function:: gamma(x) -// -// Return the gamma function of ``x``. -// +//| def gamma(x): +//| """Return the gamma function of ``x``.""" +//| ... +//| MATH_FUN_1(gamma, tgamma) -// .. function:: lgamma(x) -// -// Return the natural logarithm of the gamma function of ``x``. -// +//| def lgamma(x): +//| """Return the natural logarithm of the gamma function of ``x``.""" +//| ... +//| MATH_FUN_1(lgamma, lgamma) #endif //TODO: factorial, fsum diff --git a/shared-bindings/ulab/__init__.pyi b/shared-bindings/ulab/__init__.pyi index d2ff7eb80..e5de1391b 100644 --- a/shared-bindings/ulab/__init__.pyi +++ b/shared-bindings/ulab/__init__.pyi @@ -1,9 +1,4 @@ - -:mod:`ulab` --- Manipulate numeric data similar to numpy -======================================================== - -.. module:: ulab - :synopsis: Manipulate numeric data similar to numpy +"""Manipulate numeric data similar to numpy `ulab` is a numpy-like module for micropython, meant to simplify and speed up common mathematical operations on arrays. The primary goal was to @@ -17,507 +12,158 @@ https://micropython-ulab.readthedocs.io/en/latest/ `ulab` is modeled after numpy, and aims to be a compatible subset where possible. Numpy's documentation can be found at -https://docs.scipy.org/doc/numpy/index.html - -.. contents:: - -.. attribute:: __version__ - -The closest corresponding version of micropython-ulab - -ulab.array -- 1- and 2- dimensional array ------------------------------------------ - -.. class:: ulab.array(values, \*, dtype=float) - - :param sequence values: Sequence giving the initial content of the array. - :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` - - The `values` sequence can either be another ~ulab.array, sequence of numbers - (in which case a 1-dimensional array is created), or a sequence where each - subsequence has the same length (in which case a 2-dimensional array is - created). - - Passing a ~ulab.array and a different dtype can be used to convert an array - from one dtype to another. - - In many cases, it is more convenient to create an array from a function - like `zeros` or `linspace`. - - `ulab.array` implements the buffer protocol, so it can be used in many - places an `array.array` can be used. - - .. attribute:: shape - - The size of the array, a tuple of length 1 or 2 - - .. attribute:: size - - The number of elements in the array - - .. attribute:: itemsize - - The number of elements in the array - - .. method:: flatten(\*, order='C') - - :param order: Whether to flatten by rows ('C') or columns ('F') - - Returns a new `ulab.array` object which is always 1 dimensional. - If order is 'C' (the default", then the data is ordered in rows; - If it is 'F', then the data is ordered in columns. "C" and "F" refer - to the typical storage organization of the C and Fortran languages. - - .. method:: sort(\*, axis=1) +https://docs.scipy.org/doc/numpy/index.html""" - :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) - .. method:: transpose() +class array: + """1- and 2- dimensional array""" + def __init__(self, values, *, dtype=float): + """:param sequence values: Sequence giving the initial content of the array. + :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` - Swap the rows and columns of a 2-dimensional array + The `values` sequence can either be another ~ulab.array, sequence of numbers + (in which case a 1-dimensional array is created), or a sequence where each + subsequence has the same length (in which case a 2-dimensional array is + created). - .. method:: __add__() + Passing a ~ulab.array and a different dtype can be used to convert an array + from one dtype to another. - Adds corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. + In many cases, it is more convenient to create an array from a function + like `zeros` or `linspace`. - .. method:: __sub__() + `ulab.array` implements the buffer protocol, so it can be used in many + places an `array.array` can be used.""" + ... - Subtracts corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. + shape: tuple = ... + """The size of the array, a tuple of length 1 or 2""" - .. method:: __mul__() + size: int = ... + """The number of elements in the array""" - Multiplies corresponding elements of the two arrays, or multiplies - all elements of the array by a number. If both arguments are arrays, - their sizes must match. + itemsize: int = ... + """The number of elements in the array""" - .. method:: __div__() + def flatten(self, *, order='C'): + """:param order: Whether to flatten by rows ('C') or columns ('F') - Multiplies corresponding elements of the two arrays, or divides - all elements of the array by a number. If both arguments are arrays, - their sizes must match. + Returns a new `ulab.array` object which is always 1 dimensional. + If order is 'C' (the default", then the data is ordered in rows; + If it is 'F', then the data is ordered in columns. "C" and "F" refer + to the typical storage organization of the C and Fortran languages.""" + ... - .. method:: __pow__() + def sort(self, *, axis=1): + """:param axis: Whether to sort elements within rows (0), columns (1), or elements (None)""" + ... - Computes the power (x**y) of corresponding elements of the the two arrays, - or one number and one array. If both arguments are arrays, their sizes - must match. + def transpose(self): + """Swap the rows and columns of a 2-dimensional array""" + ... - .. method:: __getitem__() + def __add__(self): + """Adds corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match.""" + ... - Retrieve an element of the array. + def __sub__(self): + """Subtracts corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match.""" + ... - .. method:: __setitem__() + def __mul__(self): + """Multiplies corresponding elements of the two arrays, or multiplies + all elements of the array by a number. If both arguments are arrays, + their sizes must match.""" + ... - Set an element of the array. + def __div__(self): + """Multiplies corresponding elements of the two arrays, or divides + all elements of the array by a number. If both arguments are arrays, + their sizes must match.""" + ... -Array type codes ----------------- -.. attribute:: int8 + def __pow__(): + """Computes the power (x**y) of corresponding elements of the the two arrays, + or one number and one array. If both arguments are arrays, their sizes + must match.""" + ... - Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` + def __getitem__(): + """Retrieve an element of the array.""" + ... -.. attribute:: int16 + def __setitem__(): + """Set an element of the array.""" + ... - Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` +int8 = ... +"""Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array`""" -.. attribute:: float +int16 = ... +"""Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array`""" - Type code for floating point values, like the 'f' typecode of `array.array` +float = ... +"""Type code for floating point values, like the 'f' typecode of `array.array`""" -.. attribute:: uint8 +uint8 = ... +"""Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array`""" - Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` +uint16 = ... +"""Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array`""" -.. attribute:: uint16 +def ones(shape, *, dtype=float): + """ + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) - Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` + .. param: dtype + Type of values in the array + Return a new array of the given shape with all elements set to 1.""" + ... -Basic Array defining functions ------------------------------- +def zeros(shape, *, dtype): + """ + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) -.. method:: ones(shape, \*, dtype=float) + .. param: dtype + Type of values in the array - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + Return a new array of the given shape with all elements set to 0.""" + ... - .. param: dtype - Type of values in the array - - Return a new array of the given shape with all elements set to 1. - -.. method:: zeros - - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) - - .. param: dtype - Type of values in the array - Return a new array of the given shape with all elements set to 0. +def eye(size, *, dtype=float): + """Return a new square array of size, with the diagonal elements set to 1 + and the other elements set to 0.""" + ... - -.. method:: eye(size, \*, dtype=float) - - Return a new square array of size, with the diagonal elements set to 1 - and the other elements set to 0. - -.. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) - - .. param: start +def linspace(start, stop, *, dtype=float, num=50, endpoint=True): + """ + .. param: start First value in the array - .. param: stop + .. param: stop Final value in the array - .. param int: num + .. param int: num Count of values in the array - .. param: dtype + .. param: dtype Type of values in the array - .. param bool: endpoint + .. param bool: endpoint Whether the ``stop`` value is included. Note that even when endpoint=True, the exact ``stop`` value may not be included due to the inaccuracy of floating point arithmetic. - Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. - - -:mod:`ulab.compare` --- Comparison functions -============================================ - -.. module::ulab.compare - -.. method:: clip(x1, x2, x3) - - Constrain the values from ``x1`` to be between ``x2`` and ``x3``. - ``x2`` is assumed to be less than or equal to ``x3``. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are all scalars, a 1-element - array is returned. - - Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))`` - -.. method:: maximum(x1, x2) - - Compute the element by element maximum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - -.. method:: minimum(x1, x2) - - Compute the element by element minimum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - - -:mod:`ulab.vector` --- Element-by-element functions -=================================================== - -.. module:: ulab.vector - -These functions can operate on numbers, 1-D arrays, or 2-D arrays by -applying the function to every element in the array. This is typically -much more efficient than expressing the same operation as a Python loop. - -.. method:: acos - - Computes the inverse cosine function - -.. method:: acosh - - Computes the inverse hyperbolic cosine function - -.. method:: asin - - Computes the inverse sine function - -.. method:: asinh - - Computes the inverse hyperbolic sine function - -.. method:: around(a, \*, decimals) - - Returns a new float array in which each element is rounded to - ``decimals`` places. - -.. method:: atan - - Computes the inverse tangent function; the return values are in the - range [-pi/2,pi/2]. - -.. method:: atan2(y,x) - - Computes the inverse tangent function of y/x; the return values are in - the range [-pi, pi]. - -.. method:: atanh - - Computes the inverse hyperbolic tangent function - -.. method:: ceil - - Rounds numbers up to the next whole number - -.. method:: cos - - Computes the cosine function - -.. method:: erf - - Computes the error function, which has applications in statistics - -.. method:: erfc - - Computes the complementary error function, which has applications in statistics - -.. method:: exp - - Computes the exponent function. - -.. method:: expm1 - - Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. - -.. method:: floor - - Rounds numbers up to the next whole number - -.. method:: gamma - - Computes the gamma function - -.. method:: lgamma - - Computes the natural log of the gamma function - -.. method:: log - - Computes the natural log - -.. method:: log10 - - Computes the log base 10 - -.. method:: log2 - - Computes the log base 2 - -.. method:: sin - - Computes the sine - -.. method:: sinh - - Computes the hyperbolic sine - -.. method:: sqrt - - Computes the square root - -.. method:: tan - - Computes the tangent - -.. method:: tanh - - Computes the hyperbolic tangent - -:mod:`ulab.linalg` - Linear algebra functions -============================================= - -.. module:: ulab.linalg - -.. method:: cholesky(A) - - :param ~ulab.array A: a positive definite, symmetric square matrix - :return ~ulab.array L: a square root matrix in the lower triangular form - :raises ValueError: If the input does not fulfill the necessary conditions - - The returned matrix satisfies the equation m=LL* - -.. method:: det - - :param: m, a square matrix - :return float: The determinant of the matrix - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: dot(m1, m2) - - :param ~ulab.array m1: a matrix - :param ~ulab.array m2: a matrix - - Computes the matrix product of two matrices - - **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors - -.. method:: eig(m) - - :param m: a square matrix - :return tuple (eigenvectors, eigenvalues): - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: inv(m) - - :param ~ulab.array m: a square matrix - :return: The inverse of the matrix, if it exists - :raises ValueError: if the matrix is not invertible - - Computes the inverse of a square matrix - -.. method:: size(array) - - Return the total number of elements in the array, as an integer. - -.. method:: trace(m) - - :param m: a square matrix - - Compute the trace of the matrix, the sum of its diagonal elements. - -:mod:`ulab.filter` --- Filtering functions -========================================== - -.. module:: ulab.filter - -.. method:: convolve(r, c=None) - - :param ulab.array a: - :param ulab.array v: - - Returns the discrete, linear convolution of two one-dimensional sequences. - The result is always an array of float. Only the ``full`` mode is supported, - and the ``mode`` named parameter of numpy is not accepted. Note that all other - modes can be had by slicing a ``full`` result. - - Convolution filters can implement high pass, low pass, band pass, etc., - filtering operations. Convolution filters are typically constructed ahead - of time. This can be done using desktop python with scipy, or on web pages - such as https://fiiir.com/ - - Convolution is most time-efficient when both inputs are of float type. - -:mod:`ulab.fft` --- Frequency-domain functions -============================================== - -.. module:: ulab.fft - -.. method:: fft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the FFT - - Perform a Fast Fourier Transform from the time domain into the frequency domain - - See also ~ulab.extras.spectrum, which computes the magnitude of the fft, - rather than separately returning its real and imaginary parts. - -.. method:: ifft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the inverse FFT - - Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain - -:mod:`ulab.numerical` --- Numerical and Statistical functions -============================================================= - -.. module:: ulab.numerical - -Most of these functions take an "axis" argument, which indicates whether to -operate over the flattened array (None), rows (0), or columns (1). - -.. method:: argmax(array, \*, axis=None) - - Return the index of the maximum element of the 1D array - -.. method:: argmin(array, \*, axis=None) - - Return the index of the minimum element of the 1D array - -.. method:: argsort(array, \*, axis=None) - - Returns an array which gives indices into the input array from least to greatest. - -.. method:: diff(array, \*, axis=1) - - Return the numerical derivative of successive elements of the array, as - an array. axis=None is not supported. - -.. method:: flip(array, \*, axis=None) - - Returns a new array that reverses the order of the elements along the - given axis, or along all axes if axis is None. - -.. method:: max(array, \*, axis=None) - - Return the maximum element of the 1D array - -.. method:: mean(array, \*, axis=None) - - Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. - -.. method:: min(array, \*, axis=None) - - Return the minimum element of the 1D array - -.. method:: roll(array, distance, \*, axis=None) - - Shift the content of a vector by the positions given as the second - argument. If the ``axis`` keyword is supplied, the shift is applied to - the given axis. The array is modified in place. - -.. method:: std(array, \*, axis=None) - - Return the standard deviation of the array, as a number if axis is None, otherwise as an array. - -.. method:: sum(array, \*, axis=None) - - Return the sum of the array, as a number if axis is None, otherwise as an array. - -.. method:: sort(array, \*, axis=0) - - Sort the array along the given axis, or along all axes if axis is None. - The array is modified in place. - -:mod:`ulab.poly` --- Polynomial functions -========================================= - -.. module:: ulab.poly - -.. method:: polyfit([x, ] y, degree) - - Return a polynomial of given degree that approximates the function - f(x)=y. If x is not supplied, it is the range(len(y)). - -.. method:: polyval(p, x) - - Evaluate the polynomial p at the points x. x must be an array. - -:mod:`ulab.extras` --- Additional functions not in numpy -======================================================== - -.. method:: spectrum(r): - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - - Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. - - This function is similar to scipy's ``scipy.signal.spectrogram``. + Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly.""" + ... diff --git a/shared-bindings/ulab/compare/__init__.pyi b/shared-bindings/ulab/compare/__init__.pyi new file mode 100644 index 000000000..00a9eae1e --- /dev/null +++ b/shared-bindings/ulab/compare/__init__.pyi @@ -0,0 +1,30 @@ +"""Comparison functions""" + +def clip(x1, x2, x3): + """ + Constrain the values from ``x1`` to be between ``x2`` and ``x3``. + ``x2`` is assumed to be less than or equal to ``x3``. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are all scalars, a 1-element + array is returned. + + Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))``""" + ... + +def maximum(x1, x2): + """ + Compute the element by element maximum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned""" + ... + +def minimum(x1, x2): + """Compute the element by element minimum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned""" + ... diff --git a/shared-bindings/ulab/extras/__init__.pyi b/shared-bindings/ulab/extras/__init__.pyi new file mode 100644 index 000000000..4da56a582 --- /dev/null +++ b/shared-bindings/ulab/extras/__init__.pyi @@ -0,0 +1,10 @@ +"""Additional functions not in numpy""" + +def spectrum(r): + """ + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + + Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. + + This function is similar to scipy's ``scipy.signal.spectrogram``.""" + ... diff --git a/shared-bindings/ulab/fft/__init__.pyi b/shared-bindings/ulab/fft/__init__.pyi new file mode 100644 index 000000000..401ecb644 --- /dev/null +++ b/shared-bindings/ulab/fft/__init__.pyi @@ -0,0 +1,22 @@ +"""Frequency-domain functions""" + +def fft(r, c=None): + """ + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the FFT + + Perform a Fast Fourier Transform from the time domain into the frequency domain + + See also ~ulab.extras.spectrum, which computes the magnitude of the fft, + rather than separately returning its real and imaginary parts.""" + ... + +def ifft(r, c=None): + """ + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the inverse FFT + + Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain""" + ... diff --git a/shared-bindings/ulab/filter/__init__.pyi b/shared-bindings/ulab/filter/__init__.pyi new file mode 100644 index 000000000..fff404300 --- /dev/null +++ b/shared-bindings/ulab/filter/__init__.pyi @@ -0,0 +1,19 @@ +"""Filtering functions""" + +def convolve(r, c=None): + """ + :param ulab.array a: + :param ulab.array v: + + Returns the discrete, linear convolution of two one-dimensional sequences. + The result is always an array of float. Only the ``full`` mode is supported, + and the ``mode`` named parameter of numpy is not accepted. Note that all other + modes can be had by slicing a ``full`` result. + + Convolution filters can implement high pass, low pass, band pass, etc., + filtering operations. Convolution filters are typically constructed ahead + of time. This can be done using desktop python with scipy, or on web pages + such as https://fiiir.com/ + + Convolution is most time-efficient when both inputs are of float type.""" + ... diff --git a/shared-bindings/ulab/linalg/__init__.pyi b/shared-bindings/ulab/linalg/__init__.pyi new file mode 100644 index 000000000..d16e61807 --- /dev/null +++ b/shared-bindings/ulab/linalg/__init__.pyi @@ -0,0 +1,57 @@ +"""Linear algebra functions""" + + +def cholesky(A): + """ + :param ~ulab.array A: a positive definite, symmetric square matrix + :return ~ulab.array L: a square root matrix in the lower triangular form + :raises ValueError: If the input does not fulfill the necessary conditions + + The returned matrix satisfies the equation m=LL*""" + ... + +def det(): + """ + :param: m, a square matrix + :return float: The determinant of the matrix + + Computes the eigenvalues and eigenvectors of a square matrix""" + ... + +def dot(m1, m2): + """ + :param ~ulab.array m1: a matrix + :param ~ulab.array m2: a matrix + + Computes the matrix product of two matrices + + **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors""" + ... + +def eig(m): + """ + :param m: a square matrix + :return tuple (eigenvectors, eigenvalues): + + Computes the eigenvalues and eigenvectors of a square matrix""" + ... + +def inv(m): + """ + :param ~ulab.array m: a square matrix + :return: The inverse of the matrix, if it exists + :raises ValueError: if the matrix is not invertible + + Computes the inverse of a square matrix""" + ... + +def size(array): + """Return the total number of elements in the array, as an integer.""" + ... + +def trace(m): + """ + :param m: a square matrix + + Compute the trace of the matrix, the sum of its diagonal elements.""" + ... diff --git a/shared-bindings/ulab/numerical/__init__.pyi b/shared-bindings/ulab/numerical/__init__.pyi new file mode 100644 index 000000000..759678921 --- /dev/null +++ b/shared-bindings/ulab/numerical/__init__.pyi @@ -0,0 +1,57 @@ +"""Numerical and Statistical functions + +Most of these functions take an "axis" argument, which indicates whether to +operate over the flattened array (None), rows (0), or columns (1).""" + +def argmax(array, *, axis=None): + """Return the index of the maximum element of the 1D array""" + ... + +def argmin(array, *, axis=None): + """Return the index of the minimum element of the 1D array""" + ... + +def argsort(array, *, axis=None): + """Returns an array which gives indices into the input array from least to greatest.""" + ... + +def diff(array, *, axis=1): + """Return the numerical derivative of successive elements of the array, as + an array. axis=None is not supported.""" + ... + +def flip(array, *, axis=None): + """Returns a new array that reverses the order of the elements along the + given axis, or along all axes if axis is None.""" + ... + +def max(array, *, axis=None): + """Return the maximum element of the 1D array""" + ... + +def mean(array, *, axis=None): + """Return the mean element of the 1D array, as a number if axis is None, otherwise as an array.""" + ... + +def min(array, *, axis=None): + """Return the minimum element of the 1D array""" + ... + +def roll(array, distance, *, axis=None): + """Shift the content of a vector by the positions given as the second + argument. If the ``axis`` keyword is supplied, the shift is applied to + the given axis. The array is modified in place.""" + ... + +def std(array, *, axis=None): + """Return the standard deviation of the array, as a number if axis is None, otherwise as an array.""" + ... + +def sum(array, *, axis=None): + """Return the sum of the array, as a number if axis is None, otherwise as an array.""" + ... + +def sort(array, *, axis=0): + """Sort the array along the given axis, or along all axes if axis is None. + The array is modified in place.""" + ... diff --git a/shared-bindings/ulab/poly/__init__.pyi b/shared-bindings/ulab/poly/__init__.pyi new file mode 100644 index 000000000..d051bbded --- /dev/null +++ b/shared-bindings/ulab/poly/__init__.pyi @@ -0,0 +1,10 @@ +"""Polynomial functions""" + +def polyfit(x, y, degree): + """Return a polynomial of given degree that approximates the function + f(x)=y. If x is not supplied, it is the range(len(y)).""" + ... + +def polyval(p, x): + """Evaluate the polynomial p at the points x. x must be an array.""" + ... diff --git a/shared-bindings/ulab/vector/__init__.pyi b/shared-bindings/ulab/vector/__init__.pyi new file mode 100644 index 000000000..2c7a80446 --- /dev/null +++ b/shared-bindings/ulab/vector/__init__.pyi @@ -0,0 +1,108 @@ +"""Element-by-element functions + +These functions can operate on numbers, 1-D arrays, or 2-D arrays by +applying the function to every element in the array. This is typically +much more efficient than expressing the same operation as a Python loop.""" + +def acos(): + """Computes the inverse cosine function""" + ... + +def acosh(): + """Computes the inverse hyperbolic cosine function""" + ... + +def asin(): + """Computes the inverse sine function""" + ... + +def asinh(): + """Computes the inverse hyperbolic sine function""" + ... + +def around(a, *, decimals): + """Returns a new float array in which each element is rounded to + ``decimals`` places.""" + ... + +def atan(): + """Computes the inverse tangent function; the return values are in the + range [-pi/2,pi/2].""" + ... + +def atan2(y,x): + """Computes the inverse tangent function of y/x; the return values are in + the range [-pi, pi].""" + ... + +def atanh(): + """Computes the inverse hyperbolic tangent function""" + ... + +def ceil(): + """Rounds numbers up to the next whole number""" + ... + +def cos(): + """Computes the cosine function""" + ... + +def erf(): + """Computes the error function, which has applications in statistics""" + ... + +def erfc(): + """Computes the complementary error function, which has applications in statistics""" + ... + +def exp(): + """Computes the exponent function.""" + ... + +def expm1(): + """Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function.""" + ... + +def floor(): + """Rounds numbers up to the next whole number""" + ... + +def gamma(): + """Computes the gamma function""" + ... + +def lgamma(): + """Computes the natural log of the gamma function""" + ... + +def log(): + """Computes the natural log""" + ... + +def log10(): + """Computes the log base 10""" + ... + +def log2(): + """Computes the log base 2""" + ... + +def sin(): + """Computes the sine""" + ... + +def sinh(): + """Computes the hyperbolic sine""" + ... + +def sqrt(): + """Computes the square root""" + ... + +def tan(): + """Computes the tangent""" + ... + +def tanh(): + """Computes the hyperbolic tangent""" + ... diff --git a/tools/extract_pyi.py b/tools/extract_pyi.py index 95370f761..f15f15ba6 100644 --- a/tools/extract_pyi.py +++ b/tools/extract_pyi.py @@ -6,47 +6,47 @@ import traceback top_level = sys.argv[1].strip("/") stub_directory = sys.argv[2] -if top_level.count("/") == 1: - top_level, module = top_level.split("/") - modules = [module] -else: - modules = os.listdir(top_level) - modules = sorted(modules) - -ok = 0 -total = 0 -for module in modules: - module_path = os.path.join(top_level, module) - if not os.path.isdir(module_path): - continue +def convert_folder(top_level, stub_directory): + print(top_level, stub_directory) + ok = 0 + total = 0 + filenames = sorted(os.listdir(top_level)) pyi_lines = [] - classes = os.listdir(module_path) - classes = [x for x in sorted(classes) if x.endswith(".c")] - if classes and classes[-1] == "__init__.c": - classes.insert(0, classes.pop()) - for class_file in classes: - class_path = os.path.join(module_path, class_file) - with open(class_path, "r") as f: - for line in f: - if line.startswith("//|"): - if line[3] == " ": - line = line[4:] - elif line[3] == "\n": - line = line[3:] - else: - continue - pyi_lines.append(line) + for filename in filenames: + full_path = os.path.join(top_level, filename) + file_lines = [] + if os.path.isdir(full_path): + mok, mtotal = convert_folder(full_path, os.path.join(stub_directory, filename)) + ok += mok + total += mtotal + elif filename.endswith(".c"): + with open(full_path, "r") as f: + for line in f: + if line.startswith("//|"): + if line[3] == " ": + line = line[4:] + elif line[3] == "\n": + line = line[3:] + else: + continue + file_lines.append(line) + elif filename.endswith(".pyi"): + with open(full_path, "r") as f: + file_lines.extend(f.readlines()) + + # Always put the contents from an __init__ first. + if filename.startswith("__init__."): + pyi_lines = file_lines + pyi_lines + else: + pyi_lines.extend(file_lines) - raw_stubs = [x for x in sorted(classes) if x.endswith(".pyi")] - if raw_stubs and raw_stubs[-1] == "__init__.pyi": - raw_stubs.insert(0, raw_stubs.pop()) - for raw_stub in raw_stubs: - raw_stub_path = os.path.join(module_path, raw_stub) - with open(raw_stub_path, "r") as f: - pyi_lines.extend(f.readlines()) - stub_filename = os.path.join(stub_directory, module + ".pyi") + if not pyi_lines: + return ok, total + + stub_filename = os.path.join(stub_directory, "__init__.pyi") print(stub_filename) stub_contents = "".join(pyi_lines) + os.makedirs(stub_directory, exist_ok=True) with open(stub_filename, "w") as f: f.write(stub_contents) @@ -59,6 +59,9 @@ for module in modules: e = e.__cause__ traceback.print_exception(type(e), e, e.__traceback__) print() + return ok, total + +ok, total = convert_folder(top_level, stub_directory) print(f"{ok} ok out of {total}") -- cgit v1.2.3 From 15c2d16bf927c4cbf6c4dbb9773b7c835f26c06d Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 14 May 2020 16:06:13 -0700 Subject: Fix help doc --- shared-bindings/help.rst | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/help.rst b/shared-bindings/help.rst index 63991bff2..f6d72a556 100644 --- a/shared-bindings/help.rst +++ b/shared-bindings/help.rst @@ -1,26 +1,26 @@ -# This file is part of the MicroPython project, http://micropython.org/ -# -# The MIT License (MIT) -# -# Copyright (c) 2016 Scott Shawcroft for Adafruit Industries -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -# THE SOFTWARE. +.. This file is part of the MicroPython project, http://micropython.org/ + + The MIT License (MIT) + + Copyright (c) 2016 Scott Shawcroft for Adafruit Industries + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. :func:`help` - Built-in method to provide helpful information ============================================================== -- cgit v1.2.3 From aba36e4abff80bc8897e752b93e7a2ffa4fd69e6 Mon Sep 17 00:00:00 2001 From: Sean Cross Date: Fri, 15 May 2020 10:14:09 +0800 Subject: aesio: use bufinfo rather than mp_str_bytes In order to accept both `bytes` objects and `bytearray` objects, use a `bufinfo` construct to retrieve the data rather than `mp_obj_str_get_data()`. Signed-off-by: Sean Cross --- shared-bindings/aesio/aes.c | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/aesio/aes.c b/shared-bindings/aesio/aes.c index 4ddcfa898..a8f92e251 100644 --- a/shared-bindings/aesio/aes.c +++ b/shared-bindings/aesio/aes.c @@ -103,9 +103,10 @@ STATIC mp_obj_t aesio_aes_make_new(const mp_obj_type_t *type, size_t n_args, STATIC mp_obj_t aesio_aes_rekey(size_t n_args, const mp_obj_t *pos_args) { aesio_aes_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); - size_t key_length = 0; - const uint8_t *key = - (const uint8_t *)mp_obj_str_get_data(pos_args[1], &key_length); + mp_buffer_info_t bufinfo; + mp_get_buffer_raise(pos_args[1], &bufinfo, MP_BUFFER_READ); + const uint8_t *key = bufinfo.buf; + size_t key_length = bufinfo.len; if (key == NULL) { mp_raise_ValueError(translate("No key was specified")); } @@ -115,8 +116,9 @@ STATIC mp_obj_t aesio_aes_rekey(size_t n_args, const mp_obj_t *pos_args) { const uint8_t *iv = NULL; if (n_args > 2) { - size_t iv_length = 0; - iv = (const uint8_t *)mp_obj_str_get_data(pos_args[2], &iv_length); + mp_get_buffer_raise(pos_args[2], &bufinfo, MP_BUFFER_READ); + size_t iv_length = bufinfo.len; + iv = (const uint8_t *)bufinfo.buf; if (iv_length != AES_BLOCKLEN) { mp_raise_TypeError_varg(translate("IV must be %d bytes long"), AES_BLOCKLEN); @@ -246,11 +248,8 @@ MP_DEFINE_CONST_FUN_OBJ_2(aesio_aes_set_mode_obj, aesio_aes_set_mode); const mp_obj_property_t aesio_aes_mode_obj = { .base.type = &mp_type_property, - .proxy = { - (mp_obj_t)&aesio_aes_get_mode_obj, - (mp_obj_t)&aesio_aes_set_mode_obj, - (mp_obj_t)&mp_const_none_obj - }, + .proxy = {(mp_obj_t)&aesio_aes_get_mode_obj, + (mp_obj_t)&aesio_aes_set_mode_obj, (mp_obj_t)&mp_const_none_obj}, }; STATIC const mp_rom_map_elem_t aesio_locals_dict_table[] = { -- cgit v1.2.3 From f9ed3acf6d7582f495a4b6c1ae25aff5619a55ad Mon Sep 17 00:00:00 2001 From: Sean Cross Date: Fri, 15 May 2020 10:20:49 +0800 Subject: aesio: specify writable buffers for destination buffers When calling `AES.decrypt_into()` or `AES.encrypt_into()`, the destination buffers may be any buffer kind. However, we currently aren't checking to make sure the destination buffer is actually writable. Specify `MP_BUFFER_WRITE` for the destination buffers of both of these objects so we don't inadvertently write to immutable data. Signed-off-by: Sean Cross --- shared-bindings/aesio/aes.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/aesio/aes.c b/shared-bindings/aesio/aes.c index a8f92e251..d92865b8a 100644 --- a/shared-bindings/aesio/aes.c +++ b/shared-bindings/aesio/aes.c @@ -173,7 +173,7 @@ STATIC mp_obj_t aesio_aes_encrypt_into(mp_obj_t aesio_obj, mp_obj_t src, mp_buffer_info_t srcbufinfo, destbufinfo; mp_get_buffer_raise(src, &srcbufinfo, MP_BUFFER_READ); - mp_get_buffer_raise(dest, &destbufinfo, MP_BUFFER_READ); + mp_get_buffer_raise(dest, &destbufinfo, MP_BUFFER_WRITE); validate_length(aes, srcbufinfo.len, destbufinfo.len); memcpy(destbufinfo.buf, srcbufinfo.buf, srcbufinfo.len); @@ -203,7 +203,7 @@ STATIC mp_obj_t aesio_aes_decrypt_into(mp_obj_t aesio_obj, mp_obj_t src, mp_buffer_info_t srcbufinfo, destbufinfo; mp_get_buffer_raise(src, &srcbufinfo, MP_BUFFER_READ); - mp_get_buffer_raise(dest, &destbufinfo, MP_BUFFER_READ); + mp_get_buffer_raise(dest, &destbufinfo, MP_BUFFER_WRITE); validate_length(aes, srcbufinfo.len, destbufinfo.len); memcpy(destbufinfo.buf, srcbufinfo.buf, srcbufinfo.len); -- cgit v1.2.3 From 7d167560af0e317edef2d4bc4385dfa0982f19f8 Mon Sep 17 00:00:00 2001 From: Thea Flowers Date: Fri, 15 May 2020 14:53:14 -0700 Subject: Note that nvm.ByteArray is available at microcontroller.nvm Fixes #2766 --- shared-bindings/nvm/__init__.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'shared-bindings') diff --git a/shared-bindings/nvm/__init__.c b/shared-bindings/nvm/__init__.c index 51c5bb278..cdcc285dc 100644 --- a/shared-bindings/nvm/__init__.c +++ b/shared-bindings/nvm/__init__.c @@ -34,7 +34,11 @@ //| """Non-volatile memory //| //| The `nvm` module allows you to store whatever raw bytes you wish in a -//| reserved section non-volatile memory.""" +//| reserved section non-volatile memory. +//| +//| Note that this module can't be imported and used directly. The sole +//| instance of :class:`ByteArray` is available at +//| :attr:`microcontroller.nvm`.""" //| STATIC const mp_rom_map_elem_t nvm_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_nvm) }, -- cgit v1.2.3 From db924fb01eaf267b9516d355ba8cb3ba404c7096 Mon Sep 17 00:00:00 2001 From: ppolk-nocimed Date: Sat, 16 May 2020 12:47:49 -0700 Subject: Digital In Out Type Hints --- shared-bindings/digitalio/DigitalInOut.c | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 54ced099d..0ae8b804c 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -71,7 +71,7 @@ STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| def deinit(self, ) -> Any: +//| def deinit(self) -> None: //| """Turn off the DigitalInOut and release the pin for other use.""" //| ... //| @@ -82,13 +82,13 @@ STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalinout_obj_deinit); -//| def __enter__(self, ) -> Any: +//| def __enter__(self, ) -> self: //| """No-op used by Context Managers.""" //| ... //| // Provided by context manager helper. -//| def __exit__(self, ) -> Any: +//| def __exit__(self, ) -> None: //| """Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info.""" //| ... @@ -106,12 +106,13 @@ STATIC void check_for_deinit(digitalio_digitalinout_obj_t *self) { } } -//| def switch_to_output(self, value: bool = False, drive_mode: digitalio.DriveMode = digitalio.DriveMode.PUSH_PULL) -> Any: +//| def switch_to_output(self, value: bool = False, drive_mode: digitalio.DriveMode = digitalio.DriveMode.PUSH_PULL) -> None: //| """Set the drive mode and value and then switch to writing out digital //| values. //| //| :param bool value: default value to set upon switching -//| :param ~digitalio.DriveMode drive_mode: drive mode for the output""" +//| :param ~digitalio.DriveMode drive_mode: drive mode for the output +//| """ //| ... //| STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -135,7 +136,7 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digitalio_digitalinout_switch_to_output); -//| def switch_to_input(self, pull: Pull = None) -> Any: +//| def switch_to_input(self, pull: Pull = None) -> None: //| """Set the pull and then switch to read in digital values. //| //| :param Pull pull: pull configuration for the input @@ -161,6 +162,7 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_o check_for_deinit(self); mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + digitalio_pull_t pull = PULL_NONE; if (args[ARG_pull].u_rom_obj == &digitalio_pull_up_obj) { @@ -174,7 +176,7 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_o } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_input_obj, 1, digitalio_digitalinout_switch_to_input); -//| direction: Any = ... +//| direction: Direction = ... //| """The direction of the pin. //| //| Setting this will use the defaults from the corresponding @@ -220,7 +222,7 @@ const mp_obj_property_t digitalio_digitalio_direction_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| value: Any = ... +//| value: Bool = ... //| """The digital logic level of the pin.""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_value(mp_obj_t self_in) { @@ -250,7 +252,7 @@ const mp_obj_property_t digitalio_digitalinout_value_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| drive_mode: Any = ... +//| drive_mode: DriveMode = ... //| """The pin drive mode. One of: //| //| - `digitalio.DriveMode.PUSH_PULL` @@ -294,7 +296,7 @@ const mp_obj_property_t digitalio_digitalio_drive_mode_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| pull: Any = ... +//| pull: Optional[Pull] ... //| """The pin pull direction. One of: //| //| - `digitalio.Pull.UP` -- cgit v1.2.3 From f76ff1eb698ed20d47d6cdd968dca300093836cc Mon Sep 17 00:00:00 2001 From: ppolk-nocimed Date: Sat, 16 May 2020 13:14:50 -0700 Subject: Fixed Optional[Pull] --- shared-bindings/digitalio/DigitalInOut.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 0ae8b804c..342f684ba 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -162,7 +162,7 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_o check_for_deinit(self); mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - + digitalio_pull_t pull = PULL_NONE; if (args[ARG_pull].u_rom_obj == &digitalio_pull_up_obj) { @@ -296,7 +296,7 @@ const mp_obj_property_t digitalio_digitalio_drive_mode_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| pull: Optional[Pull] ... +//| pull: Optional[Pull] = ... //| """The pin pull direction. One of: //| //| - `digitalio.Pull.UP` -- cgit v1.2.3 From c6406c74eccb585d8034b948b0228a09d6717b30 Mon Sep 17 00:00:00 2001 From: ppolk-nocimed Date: Sat, 16 May 2020 13:21:34 -0700 Subject: Added DigitalInOut suggestion --- shared-bindings/digitalio/DigitalInOut.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'shared-bindings') diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 342f684ba..0cea74da0 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -82,7 +82,7 @@ STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalinout_obj_deinit); -//| def __enter__(self, ) -> self: +//| def __enter__(self, ) -> DigitalInOut: //| """No-op used by Context Managers.""" //| ... //| -- cgit v1.2.3 From 4bbb80e31af4c5626d118995e36ade470935fafe Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Tue, 12 May 2020 21:55:18 -0700 Subject: vectorio: speed up polygon This change takes polygon from 126k pixels per second fill to 240k pps fill on a reference 5 point star 50x66px polygon, updating both location and shape at 10hz. Tested on an m4 express feather. As a curiosity, the flat-out fill rate of a shape whose get_pixel is `return 0;` fills just shy of 375k pixels per second. --- shared-bindings/vectorio/Polygon.c | 42 +------------------- shared-module/vectorio/Polygon.c | 79 +++++++++++++++++++++++++++++--------- shared-module/vectorio/Polygon.h | 5 ++- 3 files changed, 65 insertions(+), 61 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/vectorio/Polygon.c b/shared-bindings/vectorio/Polygon.c index 5f4d85e21..e9e90942a 100644 --- a/shared-bindings/vectorio/Polygon.c +++ b/shared-bindings/vectorio/Polygon.c @@ -15,41 +15,6 @@ // #define VECTORIO_POLYGON_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) -// Converts a list of points tuples to a flat list of ints for speedier internal use. -// Also validates the points. -static mp_obj_t _to_points_list(mp_obj_t points_tuple_list) { - size_t len = 0; - mp_obj_t *items; - mp_obj_list_get(points_tuple_list, &len, &items); - VECTORIO_POLYGON_DEBUG("polygon_points_list len: %d\n", len); - - if ( len == 0 ) { - mp_raise_TypeError_varg(translate("empty %q list"), MP_QSTR_point); - } - - mp_obj_t points_list = mp_obj_new_list(0, NULL); - - for ( size_t i = 0; i < len; ++i) { - size_t tuple_len = 0; - mp_obj_t *tuple_items; - mp_obj_tuple_get(items[i], &tuple_len, &tuple_items); - - if (tuple_len != 2) { - mp_raise_ValueError_varg(translate("%q must be a tuple of length 2"), MP_QSTR_point); - } - int value; - if (!mp_obj_get_int_maybe(tuple_items[0], &value)) { - mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); - } - mp_obj_list_append(points_list, MP_OBJ_NEW_SMALL_INT(value)); - if (!mp_obj_get_int_maybe(tuple_items[1], &value)) { - mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); - } - mp_obj_list_append(points_list, MP_OBJ_NEW_SMALL_INT(value)); - } - return points_list; -} -//| from typing import List, Tuple //| //| class Polygon: //| def __init__(self, points: List[ Tuple[ x, y ], ... ] ): @@ -68,12 +33,11 @@ static mp_obj_t vectorio_polygon_make_new(const mp_obj_type_t *type, size_t n_ar if (!MP_OBJ_IS_TYPE(args[ARG_points_list].u_obj, &mp_type_list)) { mp_raise_TypeError_varg(translate("%q list must be a list"), MP_QSTR_point); } - mp_obj_t points_list = _to_points_list(args[ARG_points_list].u_obj); vectorio_polygon_t *self = m_new_obj(vectorio_polygon_t); self->base.type = &vectorio_polygon_type; - common_hal_vectorio_polygon_construct(self, points_list); + common_hal_vectorio_polygon_construct(self, args[ARG_points_list].u_obj); return MP_OBJ_FROM_PTR(self); } @@ -104,9 +68,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(vectorio_polygon_get_points_obj, vectorio_polygon_obj_ STATIC mp_obj_t vectorio_polygon_obj_set_points(mp_obj_t self_in, mp_obj_t points) { vectorio_polygon_t *self = MP_OBJ_TO_PTR(self_in); - mp_obj_t points_list = _to_points_list(points); - - common_hal_vectorio_polygon_set_points(self, points_list); + common_hal_vectorio_polygon_set_points(self, points); return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_2(vectorio_polygon_set_points_obj, vectorio_polygon_obj_set_points); diff --git a/shared-module/vectorio/Polygon.c b/shared-module/vectorio/Polygon.c index 6722912c2..7e3a3acfe 100644 --- a/shared-module/vectorio/Polygon.c +++ b/shared-module/vectorio/Polygon.c @@ -4,6 +4,8 @@ #include "shared-module/displayio/area.h" #include "py/runtime.h" +#include "py/gc.h" + #include "stdlib.h" #include @@ -12,10 +14,57 @@ // #define VECTORIO_POLYGON_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) +// Converts a list of points tuples to a flat list of ints for speedier internal use. +// Also validates the points. +static void _clobber_points_list(vectorio_polygon_t *self, mp_obj_t points_tuple_list) { + size_t len = 0; + mp_obj_t *items; + mp_obj_list_get(points_tuple_list, &len, &items); + VECTORIO_POLYGON_DEBUG("polygon_points_list len: %d\n", len); + + if ( len < 3 ) { + mp_raise_TypeError_varg(translate("Polygon needs at least 3 points")); + } + + if ( self->len < 2*len ) { + if ( self->points_list != NULL ) { + gc_free( self->points_list ); + } + self->points_list = gc_alloc( 2 * len * sizeof(int), false, false ); + } + self->len = 2*len; + + for ( size_t i = 0; i < len; ++i) { + size_t tuple_len = 0; + mp_obj_t *tuple_items; + mp_obj_tuple_get(items[i], &tuple_len, &tuple_items); + + if (tuple_len != 2) { + mp_raise_ValueError_varg(translate("%q must be a tuple of length 2"), MP_QSTR_point); + } + if (!mp_obj_get_int_maybe(tuple_items[0], &self->points_list[2*i])) { + self->len = 0; + gc_free( self->points_list ); + self->points_list = NULL; + mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); + } + if (!mp_obj_get_int_maybe(tuple_items[1], &self->points_list[2*i + 1])) { + self->len = 0; + gc_free( self->points_list ); + self->points_list = NULL; + mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); + } + } +} + + + void common_hal_vectorio_polygon_construct(vectorio_polygon_t *self, mp_obj_t points_list) { VECTORIO_POLYGON_DEBUG("%p polygon_construct\n", self); - self->points_list = points_list; + self->points_list = NULL; + self->len = 0; self->on_dirty.obj = NULL; + _clobber_points_list( self, points_list ); } @@ -23,7 +72,7 @@ mp_obj_t common_hal_vectorio_polygon_get_points(vectorio_polygon_t *self) { return self->points_list; } void common_hal_vectorio_polygon_set_points(vectorio_polygon_t *self, mp_obj_t points_list) { - self->points_list = points_list; + _clobber_points_list( self, points_list ); if (self->on_dirty.obj != NULL) { self->on_dirty.event(self->on_dirty.obj); } @@ -38,21 +87,16 @@ void common_hal_vectorio_polygon_set_on_dirty(vectorio_polygon_t *self, vectorio void common_hal_vectorio_polygon_get_area(void *polygon, displayio_area_t *area) { - VECTORIO_POLYGON_DEBUG("%p polygon get_area", polygon); vectorio_polygon_t *self = polygon; - size_t len; - mp_obj_t *points; - mp_obj_list_get(self->points_list, &len, &points); - VECTORIO_POLYGON_DEBUG(" len: %2d, points: %d\n", len, len/2); area->x1 = SHRT_MAX; area->y1 = SHRT_MAX; area->x2 = SHRT_MIN; area->y2 = SHRT_MIN; - for (size_t i=0; i < len; ++i) { - mp_int_t x = mp_obj_get_int(points[i]); + for (size_t i=0; i < self->len; ++i) { + int x = self->points_list[i]; ++i; - mp_int_t y = mp_obj_get_int(points[i]); + int y = self->points_list[i]; if (x <= area->x1) area->x1 = x-1; if (y <= area->y1) area->y1 = y-1; if (x >= area->x2) area->x2 = x+1; @@ -73,22 +117,19 @@ __attribute__((always_inline)) static inline int line_side( mp_int_t x1, mp_int_ uint32_t common_hal_vectorio_polygon_get_pixel(void *obj, int16_t x, int16_t y) { VECTORIO_POLYGON_DEBUG("%p polygon get_pixel %d, %d\n", obj, x, y); vectorio_polygon_t *self = obj; - size_t len; - mp_obj_t *points; - mp_obj_list_get(self->points_list, &len, &points); - if (len == 0) { + if (self->len == 0) { return 0; } int winding_number = 0; - mp_int_t x1 = mp_obj_get_int(points[0]); - mp_int_t y1 = mp_obj_get_int(points[1]); - for (size_t i=2; i <= len + 1; ++i) { + int x1 = self->points_list[0]; + int y1 = self->points_list[1]; + for (size_t i=2; i <= self->len + 1; ++i) { VECTORIO_POLYGON_DEBUG(" {(%3d, %3d),", x1, y1); - mp_int_t x2 = mp_obj_get_int(points[i % len]); + int x2 = self->points_list[i % self->len]; ++i; - mp_int_t y2 = mp_obj_get_int(points[i % len]); + int y2 = self->points_list[i % self->len]; VECTORIO_POLYGON_DEBUG(" (%3d, %3d)}\n", x2, y2); if ( y1 <= y ) { if ( y2 > y && line_side(x1, y1, x2, y2, x, y) > 0 ) { diff --git a/shared-module/vectorio/Polygon.h b/shared-module/vectorio/Polygon.h index 1aef854a7..70de9036d 100644 --- a/shared-module/vectorio/Polygon.h +++ b/shared-module/vectorio/Polygon.h @@ -8,8 +8,9 @@ typedef struct { mp_obj_base_t base; - // A micropython List[ x, y, ... ] - mp_obj_t points_list; + // An int array[ x, y, ... ] + int *points_list; + size_t len; vectorio_event_t on_dirty; } vectorio_polygon_t; -- cgit v1.2.3 From dde66cadde44e478d7b11358f768b1debc0b03c7 Mon Sep 17 00:00:00 2001 From: warriorofwire <3454741+WarriorOfWire@users.noreply.github.com> Date: Thu, 14 May 2020 11:44:36 -0700 Subject: remove a duplication in polygon.c --- shared-bindings/vectorio/Polygon.c | 1 + shared-module/vectorio/Polygon.c | 10 +++------- 2 files changed, 4 insertions(+), 7 deletions(-) (limited to 'shared-bindings') diff --git a/shared-bindings/vectorio/Polygon.c b/shared-bindings/vectorio/Polygon.c index e9e90942a..01045d098 100644 --- a/shared-bindings/vectorio/Polygon.c +++ b/shared-bindings/vectorio/Polygon.c @@ -15,6 +15,7 @@ // #define VECTORIO_POLYGON_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) +//| from typing import List, Tuple //| //| class Polygon: //| def __init__(self, points: List[ Tuple[ x, y ], ... ] ): diff --git a/shared-module/vectorio/Polygon.c b/shared-module/vectorio/Polygon.c index 7e3a3acfe..aadf47911 100644 --- a/shared-module/vectorio/Polygon.c +++ b/shared-module/vectorio/Polygon.c @@ -42,13 +42,9 @@ static void _clobber_points_list(vectorio_polygon_t *self, mp_obj_t points_tuple if (tuple_len != 2) { mp_raise_ValueError_varg(translate("%q must be a tuple of length 2"), MP_QSTR_point); } - if (!mp_obj_get_int_maybe(tuple_items[0], &self->points_list[2*i])) { - self->len = 0; - gc_free( self->points_list ); - self->points_list = NULL; - mp_raise_ValueError_varg(translate("unsupported %q type"), MP_QSTR_point); - } - if (!mp_obj_get_int_maybe(tuple_items[1], &self->points_list[2*i + 1])) { + if ( !mp_obj_get_int_maybe(tuple_items[ 0 ], &self->points_list[2*i ]) + || !mp_obj_get_int_maybe(tuple_items[ 1 ], &self->points_list[2*i + 1]) + ) { self->len = 0; gc_free( self->points_list ); self->points_list = NULL; -- cgit v1.2.3 From 007c92ee6ab8da342dacb8967ef999b6d83596ec Mon Sep 17 00:00:00 2001 From: Mark Olsson Date: Mon, 18 May 2020 14:04:55 +0200 Subject: Enable showing the console on a debug uart --- main.c | 3 ++ ports/atmel-samd/common-hal/busio/UART.c | 3 +- ports/cxd56/common-hal/busio/UART.c | 3 +- ports/mimxrt10xx/common-hal/busio/UART.c | 3 +- ports/nrf/common-hal/busio/UART.c | 3 +- ports/stm/boards/nucleo_f746zg/mpconfigboard.h | 3 ++ ports/stm/boards/nucleo_f746zg/pins.c | 5 ++- ports/stm/common-hal/busio/UART.c | 52 ++++++++++++++++++++++---- ports/stm/common-hal/busio/UART.h | 2 + shared-bindings/busio/UART.c | 2 +- shared-bindings/busio/UART.h | 6 ++- shared-module/board/__init__.c | 2 +- supervisor/serial.h | 1 + supervisor/shared/serial.c | 52 ++++++++++++++++++++++++++ supervisor/stub/serial.c | 4 ++ 15 files changed, 128 insertions(+), 16 deletions(-) (limited to 'shared-bindings') diff --git a/main.c b/main.c index c60cded16..a3bf49fc3 100755 --- a/main.c +++ b/main.c @@ -430,6 +430,9 @@ int __attribute__((used)) main(void) { // displays init after filesystem, since they could share the flash SPI board_init(); + // Start the debug serial + serial_early_init(); + // Reset everything and prep MicroPython to run boot.py. reset_port(); reset_board(); diff --git a/ports/atmel-samd/common-hal/busio/UART.c b/ports/atmel-samd/common-hal/busio/UART.c index 1f6b75f97..30a618cca 100644 --- a/ports/atmel-samd/common-hal/busio/UART.c +++ b/ports/atmel-samd/common-hal/busio/UART.c @@ -56,7 +56,8 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, const mcu_pin_obj_t * rts, const mcu_pin_obj_t * cts, const mcu_pin_obj_t * rs485_dir, bool rs485_invert, uint32_t baudrate, uint8_t bits, uart_parity_t parity, uint8_t stop, - mp_float_t timeout, uint16_t receiver_buffer_size) { + mp_float_t timeout, uint16_t receiver_buffer_size, byte* receiver_buffer, + bool sigint_enabled) { Sercom* sercom = NULL; uint8_t sercom_index = 255; // Unset index diff --git a/ports/cxd56/common-hal/busio/UART.c b/ports/cxd56/common-hal/busio/UART.c index 3bca240e0..e455b0568 100644 --- a/ports/cxd56/common-hal/busio/UART.c +++ b/ports/cxd56/common-hal/busio/UART.c @@ -57,7 +57,8 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, const mcu_pin_obj_t * rts, const mcu_pin_obj_t * cts, const mcu_pin_obj_t * rs485_dir, bool rs485_invert, uint32_t baudrate, uint8_t bits, uart_parity_t parity, uint8_t stop, - mp_float_t timeout, uint16_t receiver_buffer_size) { + mp_float_t timeout, uint16_t receiver_buffer_size, byte* receiver_buffer, + bool sigint_enabled) { struct termios tio; if ((rts != NULL) || (cts != NULL) || (rs485_dir != NULL) || (rs485_invert)) { diff --git a/ports/mimxrt10xx/common-hal/busio/UART.c b/ports/mimxrt10xx/common-hal/busio/UART.c index e3642daf5..fbb45eeea 100644 --- a/ports/mimxrt10xx/common-hal/busio/UART.c +++ b/ports/mimxrt10xx/common-hal/busio/UART.c @@ -76,7 +76,8 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, const mcu_pin_obj_t * rts, const mcu_pin_obj_t * cts, const mcu_pin_obj_t * rs485_dir, bool rs485_invert, uint32_t baudrate, uint8_t bits, uart_parity_t parity, uint8_t stop, - mp_float_t timeout, uint16_t receiver_buffer_size) { + mp_float_t timeout, uint16_t receiver_buffer_size, byte* receiver_buffer, + bool sigint_enabled) { // TODO: Allow none rx or tx diff --git a/ports/nrf/common-hal/busio/UART.c b/ports/nrf/common-hal/busio/UART.c index dbf40ea51..89f3c9f32 100644 --- a/ports/nrf/common-hal/busio/UART.c +++ b/ports/nrf/common-hal/busio/UART.c @@ -134,7 +134,8 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, const mcu_pin_obj_t * rts, const mcu_pin_obj_t * cts, const mcu_pin_obj_t * rs485_dir, bool rs485_invert, uint32_t baudrate, uint8_t bits, uart_parity_t parity, uint8_t stop, - mp_float_t timeout, uint16_t receiver_buffer_size) { + mp_float_t timeout, uint16_t receiver_buffer_size, byte* receiver_buffer, + bool sigint_enabled) { if ((rts != NULL) || (cts != NULL) || (rs485_dir != NULL) || (rs485_invert)) { mp_raise_ValueError(translate("RTS/CTS/RS485 Not yet supported on this device")); diff --git a/ports/stm/boards/nucleo_f746zg/mpconfigboard.h b/ports/stm/boards/nucleo_f746zg/mpconfigboard.h index 1d8614919..b1abd140f 100644 --- a/ports/stm/boards/nucleo_f746zg/mpconfigboard.h +++ b/ports/stm/boards/nucleo_f746zg/mpconfigboard.h @@ -34,3 +34,6 @@ #define FLASH_PAGE_SIZE (0x4000) #define BOARD_OSC_DIV (8) + +#define DEBUG_UART_TX (&pin_PD08) +#define DEBUG_UART_RX (&pin_PD09) diff --git a/ports/stm/boards/nucleo_f746zg/pins.c b/ports/stm/boards/nucleo_f746zg/pins.c index 56b6a745f..7c6a075e2 100644 --- a/ports/stm/boards/nucleo_f746zg/pins.c +++ b/ports/stm/boards/nucleo_f746zg/pins.c @@ -58,8 +58,9 @@ STATIC const mp_rom_map_elem_t board_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR_USB_ID), MP_ROM_PTR(&pin_PA10) }, { MP_ROM_QSTR(MP_QSTR_USB_DM), MP_ROM_PTR(&pin_PA11) }, { MP_ROM_QSTR(MP_QSTR_USB_DP), MP_ROM_PTR(&pin_PA12) }, -{ MP_ROM_QSTR(MP_QSTR_VCP_TX), MP_ROM_PTR(&pin_PD08) }, -{ MP_ROM_QSTR(MP_QSTR_VCP_RX), MP_ROM_PTR(&pin_PD09) }, +// As we use these for the debug_console, we won't enable them here. +// { MP_ROM_QSTR(MP_QSTR_VCP_TX), MP_ROM_PTR(&pin_PD08) }, +// { MP_ROM_QSTR(MP_QSTR_VCP_RX), MP_ROM_PTR(&pin_PD09) }, { MP_ROM_QSTR(MP_QSTR_UART2_TX), MP_ROM_PTR(&pin_PD05) }, { MP_ROM_QSTR(MP_QSTR_UART2_RX), MP_ROM_PTR(&pin_PD06) }, { MP_ROM_QSTR(MP_QSTR_UART2_RTS), MP_ROM_PTR(&pin_PD04) }, diff --git a/ports/stm/common-hal/busio/UART.c b/ports/stm/common-hal/busio/UART.c index 54ac68d73..c83479126 100644 --- a/ports/stm/common-hal/busio/UART.c +++ b/ports/stm/common-hal/busio/UART.c @@ -28,6 +28,7 @@ #include "shared-bindings/busio/UART.h" #include "mpconfigport.h" +#include "lib/mp-readline/readline.h" #include "lib/utils/interrupt_char.h" #include "py/gc.h" #include "py/mperrno.h" @@ -39,6 +40,7 @@ //arrays use 0 based numbering: UART1 is stored at index 0 STATIC bool reserved_uart[MAX_UART]; +STATIC bool never_reset_uart[MAX_UART]; int errflag; //Used to restart read halts STATIC void uart_clock_enable(uint16_t mask); @@ -61,11 +63,16 @@ STATIC USART_TypeDef * assign_uart_or_throw(busio_uart_obj_t* self, bool pin_eva } void uart_reset(void) { + uint16_t never_reset_mask = 0x00; for (uint8_t i = 0; i < MAX_UART; i++) { - reserved_uart[i] = false; - MP_STATE_PORT(cpy_uart_obj_all)[i] = NULL; + if (!never_reset_uart[i]) { + reserved_uart[i] = false; + MP_STATE_PORT(cpy_uart_obj_all)[i] = NULL; + } else { + never_reset_mask |= 1 << i; + } } - uart_clock_disable(ALL_UARTS); + uart_clock_disable(ALL_UARTS & ~(never_reset_mask)); } void common_hal_busio_uart_construct(busio_uart_obj_t *self, @@ -73,7 +80,8 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, const mcu_pin_obj_t * rts, const mcu_pin_obj_t * cts, const mcu_pin_obj_t * rs485_dir, bool rs485_invert, uint32_t baudrate, uint8_t bits, uart_parity_t parity, uint8_t stop, - mp_float_t timeout, uint16_t receiver_buffer_size) { + mp_float_t timeout, uint16_t receiver_buffer_size, byte* receiver_buffer, + bool sigint_enabled) { //match pins to UART objects USART_TypeDef * USARTx; @@ -209,8 +217,12 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, // Init buffer for rx and claim pins if (self->rx != NULL) { - if (!ringbuf_alloc(&self->ringbuf, receiver_buffer_size, true)) { - mp_raise_ValueError(translate("UART Buffer allocation error")); + if (receiver_buffer != NULL) { + self->ringbuf = (ringbuf_t){ receiver_buffer, receiver_buffer_size }; + } else { + if (!ringbuf_alloc(&self->ringbuf, receiver_buffer_size, true)) { + mp_raise_ValueError(translate("UART Buffer allocation error")); + } } claim_pin(rx); } @@ -219,6 +231,7 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, } self->baudrate = baudrate; self->timeout_ms = timeout * 1000; + self->sigint_enabled = sigint_enabled; //start the interrupt series if ((HAL_UART_GetState(&self->handle) & HAL_UART_STATE_BUSY_RX) == HAL_UART_STATE_BUSY_RX) { @@ -234,6 +247,17 @@ void common_hal_busio_uart_construct(busio_uart_obj_t *self, errflag = HAL_OK; } +void common_hal_busio_uart_never_reset(busio_uart_obj_t *self) { + for (size_t i = 0; i < MP_ARRAY_SIZE(mcu_uart_banks); i++) { + if (mcu_uart_banks[i] == self->handle.Instance) { + never_reset_uart[i] = true; + never_reset_pin_number(self->tx->pin->port, self->tx->pin->number); + never_reset_pin_number(self->rx->pin->port, self->rx->pin->number); + break; + } + } +} + bool common_hal_busio_uart_deinited(busio_uart_obj_t *self) { return self->tx->pin == NULL; } @@ -241,6 +265,13 @@ bool common_hal_busio_uart_deinited(busio_uart_obj_t *self) { void common_hal_busio_uart_deinit(busio_uart_obj_t *self) { if (common_hal_busio_uart_deinited(self)) return; + for (size_t i = 0; i < MP_ARRAY_SIZE(mcu_uart_banks); i++) { + if (mcu_uart_banks[i] == self->handle.Instance) { + never_reset_uart[i] = false; + break; + } + } + reset_pin_number(self->tx->pin->port,self->tx->pin->number); reset_pin_number(self->rx->pin->port,self->rx->pin->number); self->tx = NULL; @@ -289,7 +320,8 @@ size_t common_hal_busio_uart_write(busio_uart_obj_t *self, const uint8_t *data, bool write_err = false; //write error shouldn't disable interrupts HAL_NVIC_DisableIRQ(self->irq); - if (HAL_UART_Transmit(&self->handle, (uint8_t*)data, len, HAL_MAX_DELAY) != HAL_OK) { + HAL_StatusTypeDef ret = HAL_UART_Transmit(&self->handle, (uint8_t*)data, len, HAL_MAX_DELAY); + if (ret != HAL_OK) { write_err = true; } HAL_UART_Receive_IT(&self->handle, &self->rx_char, 1); @@ -313,6 +345,12 @@ void HAL_UART_RxCpltCallback(UART_HandleTypeDef *handle) } ringbuf_put_n(&context->ringbuf, &context->rx_char, 1); errflag = HAL_UART_Receive_IT(handle, &context->rx_char, 1); + if (context->sigint_enabled) { + if (context->rx_char == CHAR_CTRL_C) { + common_hal_busio_uart_clear_rx_buffer(context); + mp_keyboard_interrupt(); + } + } return; } diff --git a/ports/stm/common-hal/busio/UART.h b/ports/stm/common-hal/busio/UART.h index d1971ce27..a6a69a592 100644 --- a/ports/stm/common-hal/busio/UART.h +++ b/ports/stm/common-hal/busio/UART.h @@ -52,6 +52,8 @@ typedef struct { uint32_t baudrate; uint32_t timeout_ms; + + bool sigint_enabled; } busio_uart_obj_t; void uart_reset(void); diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index f231924d5..a448abb78 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -140,7 +140,7 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, co common_hal_busio_uart_construct(self, tx, rx, rts, cts, rs485_dir, rs485_invert, args[ARG_baudrate].u_int, bits, parity, stop, timeout, - args[ARG_receiver_buffer_size].u_int); + args[ARG_receiver_buffer_size].u_int, NULL, false); return (mp_obj_t)self; } diff --git a/shared-bindings/busio/UART.h b/shared-bindings/busio/UART.h index fe71e8668..3aed4e534 100644 --- a/shared-bindings/busio/UART.h +++ b/shared-bindings/busio/UART.h @@ -29,6 +29,7 @@ #include "common-hal/microcontroller/Pin.h" #include "common-hal/busio/UART.h" +#include "py/ringbuf.h" extern const mp_obj_type_t busio_uart_type; @@ -44,7 +45,8 @@ extern void common_hal_busio_uart_construct(busio_uart_obj_t *self, const mcu_pin_obj_t * rts, const mcu_pin_obj_t * cts, const mcu_pin_obj_t * rs485_dir, bool rs485_invert, uint32_t baudrate, uint8_t bits, uart_parity_t parity, uint8_t stop, - mp_float_t timeout, uint16_t receiver_buffer_size); + mp_float_t timeout, uint16_t receiver_buffer_size, byte* receiver_buffer, + bool sigint_enabled); extern void common_hal_busio_uart_deinit(busio_uart_obj_t *self); extern bool common_hal_busio_uart_deinited(busio_uart_obj_t *self); @@ -66,4 +68,6 @@ extern uint32_t common_hal_busio_uart_rx_characters_available(busio_uart_obj_t * extern void common_hal_busio_uart_clear_rx_buffer(busio_uart_obj_t *self); extern bool common_hal_busio_uart_ready_to_tx(busio_uart_obj_t *self); +extern void common_hal_busio_uart_never_reset(busio_uart_obj_t *self); + #endif // MICROPY_INCLUDED_SHARED_BINDINGS_BUSIO_UART_H diff --git a/shared-module/board/__init__.c b/shared-module/board/__init__.c index 789318a05..0fbf916cd 100644 --- a/shared-module/board/__init__.c +++ b/shared-module/board/__init__.c @@ -123,7 +123,7 @@ mp_obj_t common_hal_board_create_uart(void) { #endif common_hal_busio_uart_construct(self, tx, rx, rts, cts, rs485_dir, rs485_invert, - 9600, 8, PARITY_NONE, 1, 1.0f, 64); + 9600, 8, PARITY_NONE, 1, 1.0f, 64, NULL, false); MP_STATE_VM(shared_uart_bus) = MP_OBJ_FROM_PTR(self); return MP_STATE_VM(shared_uart_bus); } diff --git a/supervisor/serial.h b/supervisor/serial.h index 84b3062a3..ef88ad346 100644 --- a/supervisor/serial.h +++ b/supervisor/serial.h @@ -38,6 +38,7 @@ FIL* boot_output_file; #endif +void serial_early_init(void); void serial_init(void); void serial_write(const char* text); // Only writes up to given length. Does not check for null termination at all. diff --git a/supervisor/shared/serial.c b/supervisor/shared/serial.c index a61899576..513022667 100644 --- a/supervisor/shared/serial.c +++ b/supervisor/shared/serial.c @@ -32,26 +32,73 @@ #include "shared-bindings/terminalio/Terminal.h" #include "supervisor/serial.h" #include "supervisor/usb.h" +#include "shared-bindings/microcontroller/Pin.h" #include "tusb.h" +/* + * Note: DEBUG_UART currently only works on STM32, + * enabling on another platform will cause a crash. + */ + +#if defined(DEBUG_UART_TX) && defined(DEBUG_UART_RX) +#include "shared-bindings/busio/UART.h" +busio_uart_obj_t debug_uart; +byte buf_array[64]; +#endif + +void serial_early_init(void) { +#if defined(DEBUG_UART_TX) && defined(DEBUG_UART_RX) + debug_uart.base.type = &busio_uart_type; + + const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(DEBUG_UART_RX); + const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(DEBUG_UART_TX); + + common_hal_busio_uart_construct(&debug_uart, tx, rx, NULL, NULL, NULL, + false, 115200, 8, PARITY_NONE, 1, 1.0f, 64, + buf_array, true); + common_hal_busio_uart_never_reset(&debug_uart); +#endif +} + void serial_init(void) { usb_init(); } bool serial_connected(void) { +#if defined(DEBUG_UART_TX) && defined(DEBUG_UART_RX) + return true; +#else return tud_cdc_connected(); +#endif } char serial_read(void) { +#if defined(DEBUG_UART_TX) && defined(DEBUG_UART_RX) + if (tud_cdc_connected() && tud_cdc_available() > 0) { + return (char) tud_cdc_read_char(); + } + int uart_errcode; + char text; + common_hal_busio_uart_read(&debug_uart, (uint8_t*) &text, 1, &uart_errcode); + return text; +#else return (char) tud_cdc_read_char(); +#endif } bool serial_bytes_available(void) { +#if defined(DEBUG_UART_TX) && defined(DEBUG_UART_RX) + return common_hal_busio_uart_rx_characters_available(&debug_uart) || (tud_cdc_available() > 0); +#else return tud_cdc_available() > 0; +#endif } void serial_write_substring(const char* text, uint32_t length) { + if (length == 0) { + return; + } #if CIRCUITPY_DISPLAYIO int errcode; common_hal_terminalio_terminal_write(&supervisor_terminal, (const uint8_t*) text, length, &errcode); @@ -62,6 +109,11 @@ void serial_write_substring(const char* text, uint32_t length) { count += tud_cdc_write(text + count, length - count); usb_background(); } + +#if defined(DEBUG_UART_TX) && defined(DEBUG_UART_RX) + int uart_errcode; + common_hal_busio_uart_write(&debug_uart, (const uint8_t*) text, length, &uart_errcode); +#endif } void serial_write(const char* text) { diff --git a/supervisor/stub/serial.c b/supervisor/stub/serial.c index 956551914..34b433e53 100644 --- a/supervisor/stub/serial.c +++ b/supervisor/stub/serial.c @@ -26,6 +26,10 @@ #include "supervisor/serial.h" +void serial_early_init(void) { + +} + void serial_init(void) { } -- cgit v1.2.3