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 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 usescan_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.625mstimeout_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.625mstimeout_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 disconnectsadvertise_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 orClient
on successful connection- Return type
- stop()¶
Stops advertising and disables the auto-restart functionality (if enabled)