Skip to content

Commit 0e465e6

Browse files
evaherradaevaherrada
committed
Did audiopwmio, bitbangio, and _bleio
1 parent d65e851 commit 0e465e6

19 files changed

Lines changed: 758 additions & 795 deletions

‎shared-bindings/_bleio/Adapter.c‎

Lines changed: 75 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -47,35 +47,35 @@
4747
#define INTERVAL_MAX_STRING "40.959375"
4848
#define WINDOW_DEFAULT (0.1f)
4949

50-
//| .. currentmodule:: _bleio
50+
//| class Adapter:
51+
//| """.. currentmodule:: _bleio
5152
//|
52-
//| :class:`Adapter` --- BLE adapter
53-
//| ----------------------------------------------------
53+
//| :class:`Adapter` --- BLE adapter
54+
//| ----------------------------------------------------
5455
//|
55-
//| The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices.
56-
//| This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP).
56+
//| The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices.
57+
//| This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP).
5758
//|
58-
//| Discovery of other devices happens during a scanning process that listens for small packets of
59-
//| information, known as advertisements, that are broadcast unencrypted. The advertising packets
60-
//| have two different uses. The first is to broadcast a small piece of data to anyone who cares and
61-
//| and nothing more. These are known as Beacons. The second class of advertisement is to promote
62-
//| additional functionality available after the devices establish a connection. For example, a
63-
//| BLE keyboard may advertise that it can provide key information, but not what the key info is.
59+
//| Discovery of other devices happens during a scanning process that listens for small packets of
60+
//| information, known as advertisements, that are broadcast unencrypted. The advertising packets
61+
//| have two different uses. The first is to broadcast a small piece of data to anyone who cares and
62+
//| and nothing more. These are known as Beacons. The second class of advertisement is to promote
63+
//| additional functionality available after the devices establish a connection. For example, a
64+
//| BLE keyboard may advertise that it can provide key information, but not what the key info is.
6465
//|
65-
//| The built-in BLE adapter can do both parts of this process: it can scan for other device
66-
//| advertisements and it can advertise its own data. Furthermore, Adapters can accept incoming
67-
//| connections and also initiate connections.
66+
//| The built-in BLE adapter can do both parts of this process: it can scan for other device
67+
//| advertisements and it can advertise its own data. Furthermore, Adapters can accept incoming
68+
//| connections and also initiate connections."""
6869
//|
6970

70-
//| .. class:: Adapter()
71-
//|
72-
//| You cannot create an instance of `_bleio.Adapter`.
73-
//| Use `_bleio.adapter` to access the sole instance available.
71+
//| def __init__(self, ):
72+
//| """You cannot create an instance of `_bleio.Adapter`.
73+
//| Use `_bleio.adapter` to access the sole instance available."""
74+
//| ...
7475
//|
7576

76-
//| .. attribute:: enabled
77-
//|
78-
//| State of the BLE adapter.
77+
//| enabled: Any = ...
78+
//| """State of the BLE adapter."""
7979
//|
8080
STATIC mp_obj_t bleio_adapter_get_enabled(mp_obj_t self) {
8181
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 = {
9898
(mp_obj_t)&mp_const_none_obj },
9999
};
100100

101-
//| .. attribute:: address
102-
//|
103-
//| MAC address of the BLE adapter. (read-only)
101+
//| address: Any = ...
102+
//| """MAC address of the BLE adapter. (read-only)"""
104103
//|
105104
STATIC mp_obj_t bleio_adapter_get_address(mp_obj_t self) {
106105
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 = {
115114
(mp_obj_t)&mp_const_none_obj },
116115
};
117116

118-
//| .. attribute:: name
119-
//|
120-
//| name of the BLE adapter used once connected.
121-
//| The name is "CIRCUITPY" + the last four hex digits of ``adapter.address``,
122-
//| to make it easy to distinguish multiple CircuitPython boards.
117+
//| name: Any = ...
118+
//| """name of the BLE adapter used once connected.
119+
//| The name is "CIRCUITPY" + the last four hex digits of ``adapter.address``,
120+
//| to make it easy to distinguish multiple CircuitPython boards."""
123121
//|
124122
STATIC mp_obj_t bleio_adapter_get_name(mp_obj_t self) {
125123
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 = {
140138
(mp_obj_t)&mp_const_none_obj },
141139
};
142140

143-
//| .. method:: start_advertising(data, *, scan_response=None, connectable=True, interval=0.1)
144-
//|
145-
//| Starts advertising until `stop_advertising` is called or if connectable, another device
146-
//| connects to us.
141+
//| def start_advertising(self, data: buf, *, scan_response: buf = None, connectable: bool = True, interval: float = 0.1) -> Any:
142+
//| """Starts advertising until `stop_advertising` is called or if connectable, another device
143+
//| connects to us.
147144
//|
148-
//| .. warning: If data is longer than 31 bytes, then this will automatically advertise as an
149-
//| extended advertisement that older BLE 4.x clients won't be able to scan for.
145+
//| .. warning: If data is longer than 31 bytes, then this will automatically advertise as an
146+
//| extended advertisement that older BLE 4.x clients won't be able to scan for.
150147
//|
151-
//| :param buf data: advertising data packet bytes
152-
//| :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
153-
//| :param bool connectable: If `True` then other devices are allowed to connect to this peripheral.
154-
//| :param float interval: advertising interval, in seconds
148+
//| :param buf data: advertising data packet bytes
149+
//| :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
150+
//| :param bool connectable: If `True` then other devices are allowed to connect to this peripheral.
151+
//| :param float interval: advertising interval, in seconds"""
152+
//| ...
155153
//|
156154
STATIC mp_obj_t bleio_adapter_start_advertising(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
157155
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
198196
}
199197
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_adapter_start_advertising_obj, 2, bleio_adapter_start_advertising);
200198

201-
//| .. method:: stop_advertising()
199+
//| def stop_advertising(self, ) -> Any:
200+
//| """Stop sending advertising packets."""
201+
//| ...
202202
//|
203-
//| Stop sending advertising packets.
204203
STATIC mp_obj_t bleio_adapter_stop_advertising(mp_obj_t self_in) {
205204
bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(self_in);
206205

@@ -210,25 +209,25 @@ STATIC mp_obj_t bleio_adapter_stop_advertising(mp_obj_t self_in) {
210209
}
211210
STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_advertising_obj, bleio_adapter_stop_advertising);
212211

213-
//| .. method:: start_scan(prefixes=b"", \*, buffer_size=512, extended=False, timeout=None, interval=0.1, window=0.1, minimum_rssi=-80, active=True)
212+
//| 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:
213+
//| """Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are
214+
//| filtered and returned separately.
214215
//|
215-
//| Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are
216-
//| filtered and returned separately.
217-
//|
218-
//| :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets
219-
//| with. A packet without an advertising structure that matches one of the prefixes is
220-
//| ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated.
221-
//| :param int buffer_size: the maximum number of advertising bytes to buffer.
222-
//| :param bool extended: When True, support extended advertising packets. Increasing buffer_size is recommended when this is set.
223-
//| :param float timeout: the scan timeout in seconds. If None, will scan until `stop_scan` is called.
224-
//| :param float interval: the interval (in seconds) between the start of two consecutive scan windows
225-
//| Must be in the range 0.0025 - 40.959375 seconds.
226-
//| :param float window: the duration (in seconds) to scan a single BLE channel.
227-
//| window must be <= interval.
228-
//| :param int minimum_rssi: the minimum rssi of entries to return.
229-
//| :param bool active: retrieve scan responses for scannable advertisements.
230-
//| :returns: an iterable of `_bleio.ScanEntry` objects
231-
//| :rtype: iterable
216+
//| :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets
217+
//| with. A packet without an advertising structure that matches one of the prefixes is
218+
//| ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated.
219+
//| :param int buffer_size: the maximum number of advertising bytes to buffer.
220+
//| :param bool extended: When True, support extended advertising packets. Increasing buffer_size is recommended when this is set.
221+
//| :param float timeout: the scan timeout in seconds. If None, will scan until `stop_scan` is called.
222+
//| :param float interval: the interval (in seconds) between the start of two consecutive scan windows
223+
//| Must be in the range 0.0025 - 40.959375 seconds.
224+
//| :param float window: the duration (in seconds) to scan a single BLE channel.
225+
//| window must be <= interval.
226+
//| :param int minimum_rssi: the minimum rssi of entries to return.
227+
//| :param bool active: retrieve scan responses for scannable advertisements.
228+
//| :returns: an iterable of `_bleio.ScanEntry` objects
229+
//| :rtype: iterable"""
230+
//| ...
232231
//|
233232
STATIC mp_obj_t bleio_adapter_start_scan(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
234233
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
283282
}
284283
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_adapter_start_scan_obj, 1, bleio_adapter_start_scan);
285284

286-
//| .. method:: stop_scan()
285+
//| def stop_scan(self, ) -> Any:
286+
//| """Stop the current scan."""
287+
//| ...
287288
//|
288-
//| Stop the current scan.
289289
STATIC mp_obj_t bleio_adapter_stop_scan(mp_obj_t self_in) {
290290
bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(self_in);
291291

@@ -295,10 +295,9 @@ STATIC mp_obj_t bleio_adapter_stop_scan(mp_obj_t self_in) {
295295
}
296296
STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_scan_obj, bleio_adapter_stop_scan);
297297

298-
//| .. attribute:: connected
299-
//|
300-
//| True when the adapter is connected to another device regardless of who initiated the
301-
//| connection. (read-only)
298+
//| connected: Any = ...
299+
//| """True when the adapter is connected to another device regardless of who initiated the
300+
//| connection. (read-only)"""
302301
//|
303302
STATIC mp_obj_t bleio_adapter_get_connected(mp_obj_t self) {
304303
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 = {
313312
(mp_obj_t)&mp_const_none_obj },
314313
};
315314

316-
//| .. attribute:: connections
317-
//|
318-
//| Tuple of active connections including those initiated through
319-
//| :py:meth:`_bleio.Adapter.connect`. (read-only)
315+
//| connections: Any = ...
316+
//| """Tuple of active connections including those initiated through
317+
//| :py:meth:`_bleio.Adapter.connect`. (read-only)"""
320318
//|
321319
STATIC mp_obj_t bleio_adapter_get_connections(mp_obj_t self) {
322320
return common_hal_bleio_adapter_get_connections(self);
@@ -330,12 +328,12 @@ const mp_obj_property_t bleio_adapter_connections_obj = {
330328
(mp_obj_t)&mp_const_none_obj },
331329
};
332330

333-
//| .. method:: connect(address, *, timeout)
334-
//|
335-
//| Attempts a connection to the device with the given address.
331+
//| def connect(self, address: Address, *, timeout: float/int) -> Any:
332+
//| """Attempts a connection to the device with the given address.
336333
//|
337-
//| :param Address address: The address of the peripheral to connect to
338-
//| :param float/int timeout: Try to connect for timeout seconds.
334+
//| :param Address address: The address of the peripheral to connect to
335+
//| :param float/int timeout: Try to connect for timeout seconds."""
336+
//| ...
339337
//|
340338
STATIC mp_obj_t bleio_adapter_connect(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
341339
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
360358
}
361359
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_adapter_connect_obj, 2, bleio_adapter_connect);
362360

363-
//| .. method:: erase_bonding()
361+
//| def erase_bonding(self, ) -> Any:
362+
//| """Erase all bonding information stored in flash memory."""
363+
//| ...
364364
//|
365-
//| Erase all bonding information stored in flash memory.
366365
STATIC mp_obj_t bleio_adapter_erase_bonding(mp_obj_t self_in) {
367366
bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(self_in);
368367

‎shared-bindings/_bleio/Address.c‎

Lines changed: 33 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -34,22 +34,23 @@
3434
#include "shared-bindings/_bleio/Address.h"
3535
#include "shared-module/_bleio/Address.h"
3636

37-
//| .. currentmodule:: _bleio
37+
//| class Address:
38+
//| """.. currentmodule:: _bleio
3839
//|
39-
//| :class:`Address` -- BLE address
40-
//| =========================================================
40+
//| :class:`Address` -- BLE address
41+
//| =========================================================
4142
//|
42-
//| Encapsulates the address of a BLE device.
43+
//| Encapsulates the address of a BLE device."""
4344
//|
4445

45-
//| .. class:: Address(address, address_type)
46+
//| def __init__(self, address: buf, address_type: Any):
47+
//| """Create a new Address object encapsulating the address value.
48+
//| The value itself can be one of:
4649
//|
47-
//| Create a new Address object encapsulating the address value.
48-
//| The value itself can be one of:
49-
//|
50-
//| :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
51-
//| :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`,
52-
//| `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`.
50+
//| :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
51+
//| :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`,
52+
//| `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`."""
53+
//| ...
5354
//|
5455
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) {
5556
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,
8182
return MP_OBJ_FROM_PTR(self);
8283
}
8384

84-
//| .. attribute:: address_bytes
85-
//|
86-
//| The bytes that make up the device address (read-only).
85+
//| address_bytes: Any = ...
86+
//| """The bytes that make up the device address (read-only).
8787
//|
8888
//| Note that the ``bytes`` object returned is in little-endian order:
8989
//| 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,
9797
//| >>> _bleio.adapter.address
9898
//| <Address c8:1d:f5:ed:a8:35>
9999
//| >>> _bleio.adapter.address.address_bytes
100-
//| b'5\xa8\xed\xf5\x1d\xc8'
100+
//| b'5\xa8\xed\xf5\x1d\xc8'"""
101101
//|
102102
STATIC mp_obj_t bleio_address_get_address_bytes(mp_obj_t self_in) {
103103
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 = {
113113
(mp_obj_t)&mp_const_none_obj},
114114
};
115115

116-
//| .. attribute:: type
117-
//|
118-
//| The address type (read-only).
116+
//| type: Any = ...
117+
//| """The address type (read-only).
119118
//|
120119
//| One of the integer values: `PUBLIC`, `RANDOM_STATIC`, `RANDOM_PRIVATE_RESOLVABLE`,
121-
//| or `RANDOM_PRIVATE_NON_RESOLVABLE`.
120+
//| or `RANDOM_PRIVATE_NON_RESOLVABLE`."""
122121
//|
123122
STATIC mp_obj_t bleio_address_get_type(mp_obj_t self_in) {
124123
bleio_address_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -134,9 +133,9 @@ const mp_obj_property_t bleio_address_type_obj = {
134133
(mp_obj_t)&mp_const_none_obj},
135134
};
136135

137-
//| .. method:: __eq__(other)
138-
//|
139-
//| Two Address objects are equal if their addresses and address types are equal.
136+
//| def __eq__(self, other: Any) -> Any:
137+
//| """Two Address objects are equal if their addresses and address types are equal."""
138+
//| ...
140139
//|
141140
STATIC mp_obj_t bleio_address_binary_op(mp_binary_op_t op, mp_obj_t lhs_in, mp_obj_t rhs_in) {
142141
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
160159
}
161160
}
162161

163-
//| .. method:: __hash__()
164-
//|
165-
//| Returns a hash for the Address data.
162+
//| def __hash__(self, ) -> Any:
163+
//| """Returns a hash for the Address data."""
164+
//| ...
166165
//|
167166
STATIC mp_obj_t bleio_address_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
168167
switch (op) {
@@ -193,22 +192,18 @@ STATIC void bleio_address_print(const mp_print_t *print, mp_obj_t self_in, mp_pr
193192
buf[5], buf[4], buf[3], buf[2], buf[1], buf[0]);
194193
}
195194

196-
//| .. data:: PUBLIC
197-
//|
198-
//| A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits).
199-
//|
200-
//| .. data:: RANDOM_STATIC
201-
//|
202-
//| A randomly generated address that does not change often. It may never change or may change after
203-
//| a power cycle.
204-
//|
205-
//| .. data:: RANDOM_PRIVATE_RESOLVABLE
195+
//| PUBLIC: Any = ...
196+
//| """A publicly known address, with a company ID (high 24 bits)and company-assigned part (low 24 bits)."""
206197
//|
207-
//| An address that is usable when the peer knows the other device's secret Identity Resolving Key (IRK).
198+
//| RANDOM_STATIC: Any = ...
199+
//| """A randomly generated address that does not change often. It may never change or may change after
200+
//| a power cycle."""
208201
//|
209-
//| .. data:: RANDOM_PRIVATE_NON_RESOLVABLE
202+
//| RANDOM_PRIVATE_RESOLVABLE: Any = ...
203+
//| """An address that is usable when the peer knows the other device's secret Identity Resolving Key (IRK)."""
210204
//|
211-
//| A randomly generated address that changes on every connection.
205+
//| RANDOM_PRIVATE_NON_RESOLVABLE: Any = ...
206+
//| """A randomly generated address that changes on every connection."""
212207
//|
213208
STATIC const mp_rom_map_elem_t bleio_address_locals_dict_table[] = {
214209
{ MP_ROM_QSTR(MP_QSTR_address_bytes), MP_ROM_PTR(&bleio_address_address_bytes_obj) },

0 commit comments

Comments
 (0)