add doc

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

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

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]

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
 
 

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
 

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
 

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,