Legacy Advertiser#

Legacy Advertiser.

Enumerations#

enum | sl_bt_legacy_advertiser_connection_mode_t { sl_bt_legacy_advertiser_non_connectable = 0x0, sl_bt_legacy_advertiser_connectable = 0x2, sl_bt_legacy_advertiser_scannable = 0x3 } | These values define the available connection modes of undirected legacy advertising.

Functions#

sl_status_t | sl_bt_legacy_advertiser_set_data (uint8_t advertising_set, uint8_t type, size_t data_len, const uint8_t *data)

sl_status_t | sl_bt_legacy_advertiser_generate_data (uint8_t advertising_set, uint8_t discover)

sl_status_t | sl_bt_legacy_advertiser_start (uint8_t advertising_set, uint8_t connect)

Detailed Description#

Legacy Advertiser.

The commands and events in this class are related to legacy advertising functionalities.

Enumeration Type Documentation#

◆ sl_bt_legacy_advertiser_connection_mode_t#

enum sl_bt_legacy_advertiser_connection_mode_t#

These values define the available connection modes of undirected legacy advertising.

Enumerator#

sl_bt_legacy_advertiser_non_connectable |

(0x0) Undirected non-connectable and non-scannable legacy advertising

sl_bt_legacy_advertiser_connectable |

(0x2) Undirected connectable and scannable legacy advertising

sl_bt_legacy_advertiser_scannable |

(0x3) Undirected scannable and non-connectable legacy advertising

Function Documentation#

◆ sl_bt_legacy_advertiser_set_data()#

sl_status_t sl_bt_legacy_advertiser_set_data | ( | uint8_t | advertising_set, ---|---|---|--- | | uint8_t | type, | | size_t | data_len, | | const uint8_t * | data | ) | |

Set user-defined advertising data packet or scan response packet on an advertising set. This overwrites the existing advertising data packet and scan response packet on this advertising set regardless of whether the data was set for the legacy or extended advertising. Maximum 31 bytes of data can be set with this command.

If advertising mode is currently enabled, the new advertising data will be used immediately. Advertising mode can be enabled using command sl_bt_legacy_advertiser_start.

Parameters

 [in]| `advertising_set`| Advertising set handle

---|---|--- [in]| type| Enum sl_bt_advertiser_packet_type_t. The advertising packet type [in]| data_len| Length of data in data [in]| data| Data to set

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_legacy_advertiser_generate_data()#

sl_status_t sl_bt_legacy_advertiser_generate_data | ( | uint8_t | advertising_set, ---|---|---|--- | | uint8_t | discover | ) | |

Ask the stack to generate the advertising data packet and scan response packet on an advertising set. Alternatively, the user-defined advertising data can be set using the sl_bt_legacy_advertiser_set_data command.

This overwrites the existing advertising data packet and scan response packet on this advertising set regardless of whether the data was set for the legacy or extended advertising.

If advertising mode is currently enabled, the new advertising data will be used immediately. To enable advertising mode, use command sl_bt_legacy_advertiser_start.

The stack generates the advertising data and scan response packet using the following logic.

  1. Add a flags field to advertising data.

  2. Add a TX power level field to advertising data if the TX power service exists in the local GATT database.

  3. Add a peripheral connection interval range field to advertising data if the GAP peripheral preferred connection parameters characteristic exists in the local GATT database.

  4. Add a list of 16-bit service UUIDs to advertising data if there are one or more 16-bit service UUIDs to advertise. The list is complete if all advertised 16-bit UUIDs are in advertising data. Otherwise, the list is incomplete.

  5. Add a list of 128-bit service UUIDs to advertising data if there are one or more 128-bit service UUIDs to advertise and there is still free space for this field. The list is complete if all advertised 128-bit UUIDs are in advertising data. Otherwise, the list is incomplete. Note that an advertising data packet can contain at most one 128-bit service UUID.

  6. Try to add the full local name to advertising data if the device is not in privacy mode. If the full local name does not fit into the remaining free space, the advertised name is a shortened version by cutting off the end if the free space has at least 6 bytes. Otherwise, the local name is added to scan response data.

Parameters

 [in]| `advertising_set`| Advertising set handle

---|---|--- [in]| discover| Enum sl_bt_advertiser_discovery_mode_t. The discovery mode for the Flags data field in the packet. Values:

  • sl_bt_advertiser_non_discoverable (0x0): Not discoverable

  • sl_bt_advertiser_limited_discoverable (0x1): Discoverable by both limited and general discovery procedures

  • sl_bt_advertiser_general_discoverable (0x2): Discoverable by the general discovery procedure

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_legacy_advertiser_start()#

sl_status_t sl_bt_legacy_advertiser_start | ( | uint8_t | advertising_set, ---|---|---|--- | | uint8_t | connect | ) | |

Start undirected legacy advertising on an advertising set with the specified connection mode. Use sl_bt_advertiser_stop to stop the advertising.

Use the sl_bt_legacy_advertiser_set_data or sl_bt_legacy_advertiser_generate_data comamnd to set the advertising data before calling this command. The advertising data is added into the advertising data packet and scan response packet if the connection mode is connectable and/or scannable. The data is only added into the advertising data packet when the connection mode is non- connectable and non-scannable.

The number of concurrent connectable advertisings is limited by the number of connections reserved by the user application (the SL_BT_CONFIG_MAX_CONNECTIONS configuration) and the number reserved by other software components (the SL_BT_COMPONENT_CONNECTIONS configuration). This command fails with the connection limit exceeded error if it may cause the number of connections exceeding the configured value in future. For example, only one connectable advertising can be enabled if the device has (SL_BT_CONFIG_MAX_CONNECTIONS + SL_BT_COMPONENT_CONNECTIONS - 1) connections. This limitation does not apply to non-connectable advertising.

This command fails with the invalid parameter error if non-resolvable random address is used but the connection mode is sl_bt_legacy_advertiser_connectable.

Event sl_bt_evt_connection_opened will be received when a remote device opens a connection to the advertiser on this advertising set. As a result, the advertising stops.

Event sl_bt_evt_advertiser_timeout will be received when the number of advertising events set by sl_bt_advertiser_set_timing command is done and the advertising has stopped.

Parameters

 [in]| `advertising_set`| Advertising set handle

---|---|--- [in]| connect| Enum sl_bt_legacy_advertiser_connection_mode_t. Connection mode. Values:

  • sl_bt_legacy_advertiser_non_connectable (0x0): Undirected non-connectable and non-scannable legacy advertising

  • sl_bt_legacy_advertiser_connectable (0x2): Undirected connectable and scannable legacy advertising

  • sl_bt_legacy_advertiser_scannable (0x3): Undirected scannable and non-connectable legacy advertising

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events