diff options
| -rw-r--r-- | shared-bindings/_bleio/Adapter.c | 151 | ||||
| -rw-r--r-- | shared-bindings/_bleio/Address.c | 71 | ||||
| -rw-r--r-- | shared-bindings/_bleio/Attribute.c | 58 | ||||
| -rw-r--r-- | shared-bindings/_bleio/Characteristic.c | 148 | ||||
| -rw-r--r-- | shared-bindings/_bleio/CharacteristicBuffer.c | 81 | ||||
| -rw-r--r-- | shared-bindings/_bleio/Connection.c | 105 | ||||
| -rw-r--r-- | shared-bindings/_bleio/Descriptor.c | 72 | ||||
| -rw-r--r-- | shared-bindings/_bleio/PacketBuffer.c | 73 | ||||
| -rw-r--r-- | shared-bindings/_bleio/ScanEntry.c | 54 | ||||
| -rw-r--r-- | shared-bindings/_bleio/ScanResults.c | 31 | ||||
| -rw-r--r-- | shared-bindings/_bleio/Service.c | 51 | ||||
| -rw-r--r-- | shared-bindings/_bleio/UUID.c | 67 | ||||
| -rw-r--r-- | shared-bindings/_bleio/__init__.c | 38 | ||||
| -rw-r--r-- | shared-bindings/audiopwmio/PWMAudioOut.c | 186 | ||||
| -rw-r--r-- | shared-bindings/audiopwmio/__init__.c | 4 | ||||
| -rw-r--r-- | shared-bindings/bitbangio/I2C.c | 152 | ||||
| -rw-r--r-- | shared-bindings/bitbangio/OneWire.c | 80 | ||||
| -rw-r--r-- | shared-bindings/bitbangio/SPI.c | 127 | ||||
| -rw-r--r-- | shared-bindings/bitbangio/__init__.c | 4 |
19 files changed, 758 insertions, 795 deletions
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 //| <Address c8:1d:f5:ed:a8:35> //| >>> _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[] = { |