Legacy Advertiser#

Legacy Advertiser.

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

Enumerations#

enum
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.

enum
sl_bt_legacy_advertiser_high_duty_directed_connectable = 0x1
sl_bt_legacy_advertiser_low_duty_directed_connectable = 0x5
}

These values define the available connection modes of directed 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)
sl_status_t
sl_bt_legacy_advertiser_start_directed(uint8_t advertising_set, uint8_t connect, bd_addr peer_addr, uint8_t peer_addr_type)

Enumeration Documentation#

sl_bt_legacy_advertiser_connection_mode_t#

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


Definition at line 2846 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_legacy_advertiser_directed_connection_mode_t#

sl_bt_legacy_advertiser_directed_connection_mode_t

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

Enumerator
sl_bt_legacy_advertiser_high_duty_directed_connectable

(0x1) High duty cycle directed connectable legacy advertising

sl_bt_legacy_advertiser_low_duty_directed_connectable

(0x5) Low duty cycle directed connectable legacy advertising


Definition at line 2864 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

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)
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

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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2901 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_legacy_advertiser_generate_data#

sl_status_t sl_bt_legacy_advertiser_generate_data (uint8_t advertising_set, uint8_t discover)
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

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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2955 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_legacy_advertiser_start#

sl_status_t sl_bt_legacy_advertiser_start (uint8_t advertising_set, uint8_t connect)
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

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 command 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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 3012 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_legacy_advertiser_start_directed#

sl_status_t sl_bt_legacy_advertiser_start_directed (uint8_t advertising_set, uint8_t connect, bd_addr peer_addr, uint8_t peer_addr_type)
Parameters
[in]advertising_set

Advertising set handle

[in]connect

Enum sl_bt_legacy_advertiser_directed_connection_mode_t. Connection mode. Values:

  • sl_bt_legacy_advertiser_high_duty_directed_connectable (0x1): High duty cycle directed connectable legacy advertising

  • sl_bt_legacy_advertiser_low_duty_directed_connectable (0x5): Low duty cycle directed connectable legacy advertising

[in]peer_addr

Address of the peer target device the advertising is directed to

[in]peer_addr_type

Enum sl_bt_gap_address_type_t.

Peer target device address type.

If the application does not include the bluetooth_feature_use_accurate_api_address_types component, peer_addr_type uses the following values:

  • 0: Public address

  • 1: Random address

If the application includes the bluetooth_feature_use_accurate_api_address_types component, peer_addr_type uses enum sl_bt_gap_address_type_t values:

  • sl_bt_gap_public_address (0x0): Public device address

  • sl_bt_gap_static_address (0x1): Static device address

  • sl_bt_gap_random_resolvable_address (0x2): Resolvable private random address

  • sl_bt_gap_random_nonresolvable_address (0x3): Non-resolvable private random address

  • sl_bt_gap_public_address_resolved_from_rpa (0x4): Public identity address resolved from a resolvable private address (RPA)

  • sl_bt_gap_static_address_resolved_from_rpa (0x5): Static identity address resolved from a resolvable private address (RPA)

Start directed legacy advertising on an advertising set with the specified peer target device and connection mode. Use sl_bt_advertiser_stop to stop the advertising.

Directed legacy advertising does not allow any advertising data. When the connection mode is sl_bt_legacy_advertiser_high_duty_directed_connectable, the stack defaults the advertising duration to 0.64 s if the application has not set the parameter. The duration is reduced to 1.28 s if the application has set a larger duration value.

The number of concurrent connectable advertisings is limited by the connection number configuration. See sl_bt_legacy_advertiser_start for more details.

This command fails with the invalid parameter error if non-resolvable random address is set as the advertising address.

Event sl_bt_evt_connection_opened will be received when the target 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 advertising stops and no Bluetooth connection is opened to it.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 3088 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_legacy_advertiser_set_data_id#

#define sl_bt_cmd_legacy_advertiser_set_data_id
Value:
0x00560020

Definition at line 2833 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_legacy_advertiser_generate_data_id#

#define sl_bt_cmd_legacy_advertiser_generate_data_id
Value:
0x01560020

Definition at line 2834 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_legacy_advertiser_start_id#

#define sl_bt_cmd_legacy_advertiser_start_id
Value:
0x02560020

Definition at line 2835 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_legacy_advertiser_start_directed_id#

#define sl_bt_cmd_legacy_advertiser_start_directed_id
Value:
0x03560020

Definition at line 2836 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_legacy_advertiser_set_data_id#

#define sl_bt_rsp_legacy_advertiser_set_data_id
Value:
0x00560020

Definition at line 2837 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_legacy_advertiser_generate_data_id#

#define sl_bt_rsp_legacy_advertiser_generate_data_id
Value:
0x01560020

Definition at line 2838 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_legacy_advertiser_start_id#

#define sl_bt_rsp_legacy_advertiser_start_id
Value:
0x02560020

Definition at line 2839 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_legacy_advertiser_start_directed_id#

#define sl_bt_rsp_legacy_advertiser_start_directed_id
Value:
0x03560020

Definition at line 2840 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h