blatann.gap.advertising module

class blatann.gap.advertising.Advertiser(ble_device, client, conn_tag=0)

Bases: object

Class which manages the advertising state of the BLE Device

ADVERTISE_FOREVER = 0

Special value used to indicate that the BLE device should advertise indefinitely until either a central is connected or stopped manually.

property on_advertising_timeout: Event[Advertiser, None]

Event generated whenever advertising times out and finishes with no connections made

Note

If auto-restart advertising is enabled, this will trigger on each advertising timeout configured

Returns:

an Event which can have handlers registered to and deregistered from

property is_advertising: bool

Read Only

Current state of advertising

property min_interval_ms: float

Read Only

The minimum allowed advertising interval, in millseconds. This is defined by the Bluetooth specification.

property max_interval_ms: float

Read Only

The maximum allowed advertising interval, in milliseconds. This is defined by the Bluetooth specification.

property auto_restart: bool

Enables/disables whether or not the device should automatically restart advertising when an advertising timeout occurs or the client is disconnected.

Note

Auto-restart is disabled automatically when stop() is called

Getter:

Gets the auto-restart flag

Setter:

Sets/clears the auto-restart flag

set_channel_mask(ch37_enabled=True, ch38_enabled=True, ch39_enabled=True)

Enables/disables which channels advertising packets are sent out on. By default, all 3 channels (37, 38, 39) are enabled. At least one of the 3 channels MUST be enabled, otherwise a ValueError exception will be raised.

This mask will take effect the next time advertising is started or restarted due to timeout/disconnect.

Parameters:

  • ch37_enabled – True to enable advertising on channel 37, False to disable

  • ch38_enabled – True to enable advertising on channel 38, False to disable

  • ch39_enabled – True to enable advertising on channel 39, False to disable

set_advertise_data(advertise_data=AdvertisingData(), scan_response=AdvertisingData())

Sets the advertising and scan response data which will be broadcasted to peers during advertising

Note

BLE Restricts advertise and scan response data to an encoded length of 31 bytes each. Use AdvertisingData.check_encoded_length() to determine if the payload is too large

Parameters:

  • advertise_data (AdvertisingData) – The advertising data to use

  • scan_response (AdvertisingData) – The scan response data to use. This data is only sent when a scanning device requests the scan response packet (active scanning)

Raises:

InvalidOperationException if one of the payloads is too large

set_default_advertise_params(advertise_interval_ms, timeout_seconds, advertise_mode=BLEGapAdvType.connectable_undirected)

Sets the default advertising parameters so they do not need to be specified on each start

Parameters:

  • advertise_interval_ms (float) – The advertising interval, in milliseconds. Should be a multiple of 0.625ms, otherwise it’ll be rounded down to the nearest 0.625ms

  • timeout_seconds (int) – How long to advertise for before timing out, in seconds. For no timeout, use ADVERTISE_FOREVER (0)

  • advertise_mode (BLEGapAdvType) – The mode the advertiser should use

start(adv_interval_ms=None, timeout_sec=None, auto_restart=None, advertise_mode=None)

Starts advertising with the given parameters. If none given, will use the default set through set_default_advertise_params()

Parameters:

  • adv_interval_ms (Optional[float]) – The interval at which to send out advertise packets, in milliseconds. Should be a multiple of 0.625ms, otherwise it’ll be round down to the nearest 0.625ms

  • timeout_sec (Optional[int]) – The duration which to advertise for. For no timeout, use ADVERTISE_FOREVER (0)

  • auto_restart (Optional[bool]) – Flag indicating that advertising should restart automatically when the timeout expires, or when the client disconnects

  • advertise_mode (Optional[BLEGapAdvType]) – The mode the advertiser should use

Returns:

A waitable that will expire either when the timeout occurs or a client connects. The waitable will return either None on timeout or Client on successful connection

Return type:

ClientConnectionWaitable

stop()

Stops advertising and disables the auto-restart functionality (if enabled)