diff options
Diffstat (limited to 'shared-bindings/_bleio/Adapter.c')
| -rw-r--r-- | shared-bindings/_bleio/Adapter.c | 150 |
1 files changed, 73 insertions, 77 deletions
diff --git a/shared-bindings/_bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c index 921667f0f..4816294f7 100644 --- a/shared-bindings/_bleio/Adapter.c +++ b/shared-bindings/_bleio/Adapter.c @@ -47,35 +47,32 @@ #define INTERVAL_MAX_STRING "40.959375" #define WINDOW_DEFAULT (0.1f) -//| .. 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 +95,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 +111,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 +135,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 +193,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 +206,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) -//| -//| Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are -//| filtered and returned separately. +//| 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. //| -//| :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 +279,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 +292,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 +309,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 +325,12 @@ const mp_obj_property_t bleio_adapter_connections_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. method:: connect(address, *, timeout) -//| -//| Attempts a connection to the device with the given address. +//| def connect(self, address: Address, *, timeout: float/int) -> Any: +//| """Attempts a connection to the device with the given address. //| -//| :param Address address: The address of the peripheral to connect to -//| :param float/int timeout: Try to connect for timeout seconds. +//| :param Address address: The address of the peripheral to connect to +//| :param float/int timeout: Try to connect for timeout seconds.""" +//| ... //| STATIC mp_obj_t bleio_adapter_connect(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { bleio_adapter_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -360,9 +355,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); |