gap_advertise()

Start or stop GAP advertisements from the XBee device.

ble.gap_advertise(interval_us, adv_data=None, adv_mode=ble.BLE_ADV_LEGACY_MODE)

<interval_us>

If using legacy or extended advertising modes

Start advertising at the specified interval, in microseconds. This value will be rounded down to the nearest multiple of 625 microseconds. The interval, if not None, must be at least 20,000 microseconds (20 milliseconds) and no larger than approximately 40.96 seconds (40,959,375 microseconds).

If using periodic advertising mode

Start periodic advertising at the specified interval, in microseconds. This value will be rounded down to the nearest multiple of 1250 microseconds. The interval, if not None, must be at least 7,500 microseconds (7.5 milliseconds) and no larger than approximately 81.92 seconds (81,918,750 microseconds).

To stop advertising in any mode, set <interval_us> to None.

<adv_data>

This is the payload that will be included in GAP advertisement broadcasts. <adv_data> can be a bytes or bytearray object up to 31 bytes in length if using Legacy advertising, or 191 bytes if using Extended or Periodic advertising, or None.

If <adv_data> is empty—for example b''—then GAP advertising will return to the default XBee behavior, which is to advertise the product name—such as XBee3 Zigbee, or the value in ATBI.

If <adv_data> is None or not specified, then the data passed to the previous call to gap_advertise is used, unless there was no previous call or the previous data was empty, in which case the behavior will be as if an empty value—b''—was passed.

Otherwise, <adv_data> should consist of one or more Advertising Data (AD) elements, as defined in the Bluetooth Core Specification Supplement, Part A Section 1.

• Each AD element consists of a length byte, a data type byte, and one or more bytes of data. The length byte indicates how long the rest of the element is, for example a Complete Local Name element with value My XBee would have a length byte 0x08 – 1 byte for type plus 7 bytes for the value.
• The Bluetooth SIG provides the list of defined Advertising Data element types here: https://www.bluetooth.com/specifications/assigned-numbers/generic-access-profile/

Be aware that <adv_data> must be formatted as one or more Advertising Data elements in order to be interpreted as a valid Bluetooth Low Energy advertisement by other devices. For example, to advertise the name My XBee:

ble.gap_advertise(200000, b"\x08\x09My XBee")	

<adv_mode>

This bitfield is used to select which advertising mode to use. Only one mode can be used at a time.

If it is not specified, advertising will default to legacy advertising. If set to None, the previous mode set will be used. Otherwise, the given advertising mode will be used.

Currently supported advertising modes are:

• ble.BLE_ADV_LEGACY_MODE

• ble.BLE_ADV_EXTENDED_MODE

• ble.BLE_ADV_PERIODIC_MODE

This field was introduced in the following firmware versions:

• XBee3 ZigBee: version 1014

• XBee3 802.15.4: version 2014

• XBee3 DigiMesh 2.4: version 3014

Note XBee3 ZigBee, 802.15.4, and DigiMesh 2.4 modules do not currently support the extended or periodic advertising modes.

Return value

gap_advertise returns None—i.e. it has no return value.

If BLE functionality is not currently active—see active()—gap_advertise will raise an OSError.