djsundog
/
circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Did audiopwmio, bitbangio, and _bleio

This commit is contained in:
dherrada 2020-05-01 18:23:27 -04:00
parent d65e851044
commit 0e465e63b9
No known key found for this signature in database
GPG Key ID: CE2ADBAB8775CE81
19 changed files with 738 additions and 775 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
shared-bindings/_bleio/Adapter.c
View File

@ -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)
//| 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.
//|
//| 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)
//| def connect(self, address: Address, *, timeout: float/int) -> Any:
//| """Attempts a connection to the device with the given address.
//|
//| 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);

71
shared-bindings/_bleio/Address.c
View File

@ -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
//| PUBLIC: Any = ...
//| """A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits)."""
//|
//| A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits).
//| 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_STATIC
//| 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 does not change often. It may never change or may change after
//| a power cycle.
//|
//| .. data:: RANDOM_PRIVATE_RESOLVABLE
//|
//| An address that is usable when the peer knows the other device's secret Identity Resolving Key (IRK).
//|
//| .. data:: RANDOM_PRIVATE_NON_RESOLVABLE
//|
//| 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) },

58
shared-bindings/_bleio/Attribute.c
View File

@ -29,52 +29,44 @@
#include "shared-bindings/_bleio/Characteristic.h"
#include "shared-bindings/_bleio/UUID.h"
//
//| .. currentmodule:: _bleio
//| class Attribute:
//| """.. currentmodule:: _bleio
//|
//| :class:`Attribute` -- BLE Attribute
//| =========================================================
//| :class:`Attribute` -- BLE Attribute
//| =========================================================
//|
//| Definitions associated with all BLE attributes: characteristics, descriptors, etc.
//| :py:class:`~_bleio.Attribute` is, notionally, a superclass of
//| :py:class:`~Characteristic` and :py:class:`~Descriptor`,
//| but is not defined as a Python superclass of those classes.
//| 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()
//|
//| 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
//| NO_ACCESS: Any = ...
//| """security mode: access not allowed"""
//|
//| security mode: access not allowed
//| OPEN: Any = ...
//| """security_mode: no security (link is not encrypted)"""
//|
//| .. data:: OPEN
//| ENCRYPT_NO_MITM: Any = ...
//| """security_mode: unauthenticated encryption, without man-in-the-middle protection"""
//|
//| security_mode: no security (link is not encrypted)
//| ENCRYPT_WITH_MITM: Any = ...
//| """security_mode: authenticated encryption, with man-in-the-middle protection"""
//|
//| .. data:: ENCRYPT_NO_MITM
//| LESC_ENCRYPT_WITH_MITM: Any = ...
//| """security_mode: LESC encryption, with man-in-the-middle protection"""
//|
//| security_mode: unauthenticated encryption, without man-in-the-middle protection
//| SIGNED_NO_MITM: Any = ...
//| """security_mode: unauthenticated data signing, without man-in-the-middle protection"""
//|
//| .. data:: ENCRYPT_WITH_MITM
//|
//| security_mode: authenticated encryption, with man-in-the-middle protection
//|
//| .. data:: LESC_ENCRYPT_WITH_MITM
//|
//| security_mode: LESC encryption, with man-in-the-middle protection
//|
//| .. data:: SIGNED_NO_MITM
//|
//| security_mode: unauthenticated data signing, without man-in-the-middle protection
//|
//| .. data:: SIGNED_WITH_MITM
//|
//| 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) },

134
shared-bindings/_bleio/Characteristic.c
View File

@ -33,45 +33,46 @@
#include "shared-bindings/_bleio/Service.h"
#include "shared-bindings/_bleio/UUID.h"
//| .. currentmodule:: _bleio
//| class Characteristic:
//| """.. currentmodule:: _bleio
//|
//| :class:`Characteristic` -- BLE service characteristic
//| =========================================================
//| :class:`Characteristic` -- BLE service characteristic
//| =========================================================
//|
//| Stores information about a BLE service characteristic and allows reading
//| and writing of the characteristic's value.
//| Stores information about a BLE service characteristic and allows reading
//| and writing of the characteristic's value."""
//|
//| .. 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.
//| 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."""
//| ...
//|
//| .. 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)
//| 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.
//|
//| 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.
//|
//| :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.
//| :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
//| uuid: Any = ...
//| """The UUID of this characteristic. (read-only)
//|
//| 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
//| BROADCAST: Any = ...
//| """property: allowed in advertising packets"""
//|
//| property: allowed in advertising packets
//| INDICATE: Any = ...
//| """property: server will indicate to the client when the value is set and wait for a response"""
//|
//| .. data:: INDICATE
//| NOTIFY: Any = ...
//| """property: server will notify the client when the value is set"""
//|
//| property: server will indicate to the client when the value is set and wait for a response
//| READ: Any = ...
//| """property: clients may read this characteristic"""
//|
//| .. data:: NOTIFY
//| WRITE: Any = ...
//| """property: clients may write this characteristic; a response will be sent back"""
//|
//| property: server will notify the client when the value is set
//|
//| .. data:: READ
//|
//| property: clients may read this characteristic
//|
//| .. data:: WRITE
//|
//| property: clients may write this characteristic; a response will be sent back
//|
//| .. data:: WRITE_NO_RESPONSE
//|
//| 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) },

81
shared-bindings/_bleio/CharacteristicBuffer.c
View File

@ -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);

105
shared-bindings/_bleio/Connection.c
View File

@ -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)
//| 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.
//|
//| 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);

72
shared-bindings/_bleio/Descriptor.c
View File

@ -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);

73
shared-bindings/_bleio/PacketBuffer.c
View File

@ -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)
//| 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.
//|
//| 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)
//| 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.
//|
//| 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);

54
shared-bindings/_bleio/ScanEntry.c
View File

@ -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);

31
shared-bindings/_bleio/ScanResults.c
View File

@ -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 = {

51
shared-bindings/_bleio/Service.c
View File

@ -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
//| uuid: Any = ...
//| """The UUID of this service. (read-only)
//|
//| 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);

67
shared-bindings/_bleio/UUID.c
View File

@ -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)
//| def __init__(self, value: Any):
//| """Create a new UUID or UUID object encapsulating the uuid value.
//| The value can be one of:
//|
//| 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
//| uuid16: Any = ...
//| """The 16-bit part of the UUID. (read-only)
//|
//| 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) {

38
shared-bindings/_bleio/__init__.c
View File

@ -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, ...) {

160
shared-bindings/audiopwmio/PWMAudioOut.c
View File

@ -36,66 +36,67 @@
#include "shared-bindings/util.h"
#include "supervisor/shared/translate.h"
//| .. currentmodule:: audiopwmio
//| class PWMAudioOut:
//| """.. currentmodule:: audiopwmio
//|
//| :class:`PWMAudioOut` -- Output an analog audio signal
//| ========================================================
//| :class:`PWMAudioOut` -- Output an analog audio signal
//| ========================================================
//|
//| AudioOut can be used to output an analog audio signal on a given pin.
//| AudioOut can be used to output an analog audio signal on a given pin."""
//|
//| .. class:: PWMAudioOut(left_channel, *, right_channel=None, quiescent_value=0x8000)
//| 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.
//|
//| 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.
//|
//| :param ~microcontroller.Pin left_channel: The pin to output the left channel to
//| :param ~microcontroller.Pin right_channel: The pin to output the right channel to
//| :param int quiescent_value: The output value when no signal is present. Samples should start
//| and end with this value to prevent audible popping.
//| Simple 8ksps 440 Hz sin wave::
//|
//| Simple 8ksps 440 Hz sin wave::
//| import audiocore
//| import audiopwmio
//| import board
//| import array
//| import time
//| import math
//|
//| 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)
//|
//| # 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()
//|
//| 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::
//|
//| Playing a wave file from flash::
//| import board
//| import audiocore
//| import audiopwmio
//| import digitalio
//|
//| 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)
//|
//| # 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)
//|
//| 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")
//| 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);

4
shared-bindings/audiopwmio/__init__.c
View File

@ -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[] = {

152
shared-bindings/bitbangio/I2C.c
View File

@ -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)
//| 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.
//|
//| 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)
//| 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.
//|
//| 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 };

80
shared-bindings/bitbangio/OneWire.c
View File

@ -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()
//| def read_bit(self, ) -> Any:
//| """Read in a bit
//|
//| 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);

127
shared-bindings/bitbangio/SPI.c
View File

@ -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)
//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any:
//| """Configures the SPI bus. Only valid when locked.
//|
//| 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)
//| 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.
//|
//| 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 };

4
shared-bindings/bitbangio/__init__.c
View File

@ -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[] = {