From 06977239f9f9d25944b8785e27ff83d838d67dbf Mon Sep 17 00:00:00 2001 From: Gilles Boccon-Gibod Date: Tue, 26 Dec 2023 14:47:50 -0800 Subject: [PATCH] add doc --- bumble/device.py | 43 +++++++++++++++++++++++++-- examples/run_cig_setup.py | 1 - examples/run_csis_servers.py | 8 +---- examples/run_extended_advertiser.py | 12 ++++---- examples/run_extended_advertiser_2.py | 3 +- examples/run_unicast_server.py | 1 - tests/device_test.py | 2 -- 7 files changed, 47 insertions(+), 23 deletions(-) diff --git a/bumble/device.py b/bumble/device.py index 91d229e30..9169e0428 100644 --- a/bumble/device.py +++ b/bumble/device.py @@ -674,6 +674,7 @@ async def set_advertising_data(self, advertising_data: bytes) -> None: self.advertising_data = advertising_data async def set_scan_response_data(self, scan_response_data: bytes) -> None: + # pylint: disable=line-too-long if ( scan_response_data and not self.advertising_parameters.advertising_event_properties.is_scannable @@ -684,7 +685,6 @@ async def set_scan_response_data(self, scan_response_data: bytes) -> None: ) return - # pylint: disable=line-too-long await self.device.send_command( HCI_LE_Set_Extended_Scan_Response_Data_Command( advertising_handle=self.advertising_handle, @@ -2004,6 +2004,7 @@ async def start_advertising( if self.supports_le_extended_advertising: # Use extended advertising commands with legacy PDUs. self.legacy_advertising_set = await self.create_advertising_set( + auto_start=True, auto_restart=auto_restart, random_address=self.random_address, advertising_parameters=AdvertisingParameters( @@ -2024,8 +2025,6 @@ async def start_advertising( self.scan_response_data if advertising_type.is_scannable else b'' ), ) - - await self.legacy_advertising_set.start() else: # Use legacy commands. self.legacy_advertiser = LegacyAdvertiser( @@ -2056,8 +2055,37 @@ async def create_advertising_set( scan_response_data: bytes = b'', periodic_advertising_parameters: Optional[PeriodicAdvertisingParameters] = None, periodic_advertising_data: bytes = b'', + auto_start: bool = True, auto_restart: bool = False, ) -> AdvertisingSet: + """ + Create an advertising set. + + This method allows the creation of advertising sets for controllers that + support extended advertising. + + Args: + advertising_parameters: + The parameters to use for this set. If None, default parameters are used. + random_address: + The random address to use (only relevant when the parameters specify that + own_address_type is random). + advertising_data: + Initial value for the set's advertising data. + scan_response_data: + Initial value for the set's scan response data. + periodic_advertising_parameters: + The parameters to use for periodic advertising (if needed). + periodic_advertising_data: + Initial value for the set's periodic advertising data. + auto_start: + True if the set should be automatically started upon creation. + auto_restart: + True if the set should be automatically restated after a disconnection. + + Returns: + An AdvertisingSet instance. + """ # Allocate a new handle try: advertising_handle = next( @@ -2133,6 +2161,15 @@ async def create_advertising_set( # Remember the set. self.extended_advertising_sets[advertising_handle] = advertising_set + # Try to start the set if requested. + if auto_start: + try: + await advertising_set.start() + except Exception as error: + logger.exception(f'failed to start advertising set: {error}') + await advertising_set.remove() + raise + return advertising_set @property diff --git a/examples/run_cig_setup.py b/examples/run_cig_setup.py index e5ea3a9eb..29a54adf2 100644 --- a/examples/run_cig_setup.py +++ b/examples/run_cig_setup.py @@ -63,7 +63,6 @@ async def main() -> None: await asyncio.gather(*[device.power_on() for device in devices]) advertising_set = await devices[0].create_advertising_set() - await advertising_set.start() connection = await devices[1].connect( devices[0].public_address, own_address_type=OwnAddressType.PUBLIC diff --git a/examples/run_csis_servers.py b/examples/run_csis_servers.py index 88d49a169..985352331 100644 --- a/examples/run_csis_servers.py +++ b/examples/run_csis_servers.py @@ -98,13 +98,7 @@ async def main() -> None: ) + csis.get_advertising_data() ) - await device.start_extended_advertising( - advertising_properties=( - HCI_LE_Set_Extended_Advertising_Parameters_Command.AdvertisingProperties.CONNECTABLE_ADVERTISING - ), - own_address_type=OwnAddressType.RANDOM, - advertising_data=advertising_data, - ) + await device.create_advertising_set(advertising_data=advertising_data) await asyncio.gather( *[hci_transport.source.terminated for hci_transport in hci_transports] diff --git a/examples/run_extended_advertiser.py b/examples/run_extended_advertiser.py index bcd08474a..6605cfa91 100644 --- a/examples/run_extended_advertiser.py +++ b/examples/run_extended_advertiser.py @@ -59,14 +59,12 @@ async def main() -> None: sys.argv[1], hci_transport.source, hci_transport.sink ) await device.power_on() - await ( - await device.create_advertising_set( - advertising_parameters=AdvertisingParameters( - advertising_event_properties=advertising_properties, - peer_address=peer_address, - ) + await device.create_advertising_set( + advertising_parameters=AdvertisingParameters( + advertising_event_properties=advertising_properties, + peer_address=peer_address, ) - ).start() + ) await hci_transport.source.terminated diff --git a/examples/run_extended_advertiser_2.py b/examples/run_extended_advertiser_2.py index 8ea944420..6e6f57240 100644 --- a/examples/run_extended_advertiser_2.py +++ b/examples/run_extended_advertiser_2.py @@ -59,7 +59,6 @@ async def main() -> None: advertising_data=bytes(advertising_data1), ) print("Selected TX power 1:", set1.selected_tx_power) - await set1.start() advertising_data2 = AdvertisingData( [(AdvertisingData.COMPLETE_LOCAL_NAME, "Bumble 2".encode("utf-8"))] @@ -70,6 +69,7 @@ async def main() -> None: random_address=Address("F0:F0:F0:F0:F0:F1"), advertising_parameters=AdvertisingParameters(), advertising_data=bytes(advertising_data2), + auto_start=False, auto_restart=True, ) print("Selected TX power 2:", set2.selected_tx_power) @@ -90,7 +90,6 @@ async def main() -> None: scan_response_data=bytes(scan_response_data3), ) print("Selected TX power 3:", set2.selected_tx_power) - await set3.start() await hci_transport.source.terminated diff --git a/examples/run_unicast_server.py b/examples/run_unicast_server.py index db0d82b66..7418b8bf1 100644 --- a/examples/run_unicast_server.py +++ b/examples/run_unicast_server.py @@ -181,7 +181,6 @@ def on_cis(cis_link: CisLink): advertising_set = await device.create_advertising_set( advertising_data=advertising_data, ) - await advertising_set.start() await hci_transport.source.terminated diff --git a/tests/device_test.py b/tests/device_test.py index e5e7892dc..874e9e538 100644 --- a/tests/device_test.py +++ b/tests/device_test.py @@ -318,7 +318,6 @@ async def test_extended_advertising(): # Start advertising advertising_set = await device.create_advertising_set() - await advertising_set.start() assert device.extended_advertising_sets assert advertising_set.enabled @@ -339,7 +338,6 @@ async def test_extended_advertising_connection(own_address_type): advertising_set = await device.create_advertising_set( advertising_parameters=AdvertisingParameters(own_address_type=own_address_type) ) - await advertising_set.start() device.on_connection( 0x0001, BT_LE_TRANSPORT,