Advertising Procedure APIs

This group includes advertising APIs.

Data Structures
struct	at_ble_adv_data_update_on_the_fly_t
	use this structure when calling the api at_ble_adv_data_update_on_the_fly to set the advertising data on the fly More...

Functions
at_ble_status_t	at_ble_adv_channel_map_get (at_ble_adv_channel_map_t *ch)
	get advertising channel. More...
at_ble_status_t	at_ble_adv_channel_map_set (at_ble_adv_channel_map_t ch)
	Set advertising channel using one of at_ble_adv_channel_map_t. More...
at_ble_status_t	at_ble_adv_data_set (uint8_t const *const adv_data, uint8_t adv_data_len, uint8_t const *const scan_resp_data, uint8_t scan_response_data_len)
	Set, clear or update advertisement and scan response data. More...
at_ble_status_t	at_ble_adv_data_update_on_the_fly (at_ble_adv_data_update_on_the_fly_t *update_on_the_fly_data)
	Set, clear or update advertising data or scan response data or both on the fly (while an advertising operation is ongoing) . More...
at_ble_status_t	at_ble_adv_start (at_ble_adv_type_t type, at_ble_adv_mode_t mode, at_ble_addr_t *peer_addr, at_ble_filter_type_t filtered, uint16_t interval, uint16_t timeout, bool disable_randomness)
	Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). More...
at_ble_status_t	at_ble_adv_stop (void)
	Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). More...
at_ble_status_t	at_ble_en_recv_adv_cmp_event (bool en_adv_notification)
	Enable/Disable receiving advertising complete event AT_BLE_ADV_CMP_EVENT with the end of advertising event. More...
at_ble_status_t	at_ble_get_adv_cnt (uint32_t *adv_pdu_cnt)
	Get the count of Advertising frame. More...
at_ble_status_t	at_ble_rst_adv_cnt (void)
	Reset the count of Advertising frame. More...

at_ble_status_t at_ble_adv_channel_map_get

(

at_ble_adv_channel_map_t *

ch

)

get advertising channel.

Parameters

[in]

ch

used advertising channels at_ble_adv_channel_map_t.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

at_ble_status_t at_ble_adv_channel_map_set

(

at_ble_adv_channel_map_t

ch

)

Set advertising channel using one of at_ble_adv_channel_map_t.

Note

Default value is AT_BLE_ADV_ALL_CHNLS_EN

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

at_ble_status_t at_ble_adv_data_set	(	uint8_t const *const	adv_data,
		uint8_t	adv_data_len,
		uint8_t const *const	scan_resp_data,
		uint8_t	scan_response_data_len
	)

Set, clear or update advertisement and scan response data.

Note

• To clear the advertisement data and set it to a 0-length packet, simply provide a valid pointer (pAdvData/pSrData) with its corresponding length (dlen/srdlen) set to 0.
• The call will fail if pAdvData and pSrData are both NULL since this would have no effect.

Parameters

[in]	adv_data	Raw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
[in]	adv_data_len	Data length for adv_data. Max size 28 bytes, 3 bytes are reserved to set advertising AD type flags , shall not be set in advertising data.
[in]	scan_resp_data	Raw data to be placed in scan response packet. If NULL, no changes are made to the current scan response packet data.
[in]	scan_response_data_len	Data length for scan_resp_data. Max size 31 bytes.

Note

The First three bytes in advertising data have been reserved in order to Fill Flags(0x01) AD type. This data is set according to advertising mode selected.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Note

• To clear the advertisement data and set it to a 0-length packet, simply provide a valid pointer (pAdvData/pSrData) with its corresponding length (dlen/srdlen) set to 0.
• The call will fail if pAdvData and pSrData are both NULL since this would have no effect.

Parameters

[in]	adv_data	Raw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
[in]	adv_data_len	Data length for adv_data.
[in]	scan_resp_data	Raw data to be placed in scan response packet. If NULL, no changes are made to the current scan response packet data.
[in]	scan_response_data_len	Data length for scan_resp_data

Returns

AT_BLE_SUCCESS Advertisement data successfully updated or cleared.

AT_BLE_INVALID_PARAM One of the length parameters is invalid.

AT_BLE_FAILURE Both pointer parameters are invalid.

References device_info::ADVData, device_info::advLen, AT_BLE_ADV_MAX_SIZE, AT_BLE_FAILURE, AT_BLE_INVALID_PARAM, AT_BLE_SUCCESS, device, NULL, device_info::SrData, and device_info::srLen.

at_ble_status_t at_ble_adv_data_update_on_the_fly

(

at_ble_adv_data_update_on_the_fly_t *

update_on_the_fly_data

)

Set, clear or update advertising data or scan response data or both on the fly (while an advertising operation is ongoing) .

Note

• to do any operation on Advertising data (clear or set) you must set the bit mask at_ble_adv_data_update_on_the_fly_t::presence_bit_mask inside at_ble_adv_data_update_on_the_fly_t to ADV_DATA_PRESENT (0x01)
• to do any operation on scan response data (clear or set) you must set the bit mask at_ble_adv_data_update_on_the_fly_t::presence_bit_mask inside at_ble_adv_data_update_on_the_fly_t to SCN_RESP_DATA_PRESENT (0x02)
• if the bit mask at_ble_adv_data_update_on_the_fly_t::presence_bit_mask inside at_ble_adv_data_update_on_the_fly_t is not set at all the call will fail
• to clear Advertising data send at_ble_adv_data_update_on_the_fly_t::adv_data_len in at_ble_adv_data_update_on_the_fly_t with value = 0
• to clear scan response data send at_ble_adv_data_update_on_the_fly_t::scan_response_data_len in at_ble_adv_data_update_on_the_fly_t with value = 0
• Use this API only while an advertising activity has started by at_ble_adv_start
• the new advertise/scan response you set/clear by this API will be on the Air immediately and it will be stored and be used for future advertise events
• to Set, clear or update the adv data while no Advertising activity is ongoing, use at_ble_adv_data_set
• The First three bytes in advertising data have been reserved in order to Fill Flags(0x01) AD type. This data is set according to advertising mode selected.

Parameters

[in]

update_on_the_fly_data

update on the fly request parameters, refer to at_ble_adv_data_update_on_the_fly_t

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Referenced by eddystone_adv_start().

at_ble_status_t at_ble_adv_start	(	at_ble_adv_type_t	type,
		at_ble_adv_mode_t	mode,
		at_ble_addr_t *	peer_addr,
		at_ble_filter_type_t	filtered,
		uint16_t	interval,
		uint16_t	timeout,
		bool	disable_randomness
	)

Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).

Parameters

[in]	type	Advertising type, see at_ble_adv_type_t for more info
[in]	mode	either non-discoverable,General, Limited or Broadcaster , at_ble_adv_mode_t for more details
[in]	peer_addr	For AT_BLE_ADV_TYPE_DIRECTED mode only, known peer address
[in]	filtered	policy at_ble_filter_type_t for more details
[in]	interval	Advertising interval between AT_BLE_ADV_INTERVAL_MIN and AT_BLE_ADV_INTERVAL_MAX in 0.625 ms units (20ms to 10.24s). This parameter must be set to 0 if type equals AT_BLE_ADV_TYPE_DIRECTED
[in]	timeout	Advertising time-out between 0x0001 and 0x028F in scale of Seconds, 0x0000 disables time-out. This parameter must be set to 0 if type equals AT_BLE_ADV_TYPE_DIRECTED. Timeout only valid with AT_BLE_ADV_GEN_DISCOVERABLE and AT_BLE_ADV_LIM_DISCOVERABLE.
[in]	disable_randomness	if True the device will advertise at the exact interval without adding the random 10msec

Precondition

If it is required to change BD address, at_ble_addr_set should be used otherwise default address will be used

Note

AT_BLE_ADV_REPORT will be received with error code in case of stack can not start advertising; refer to at_ble_status_t

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Parameters

[in]	type	Advertising type, see at_ble_adv_type_t for more info
[in]	mode	either non-discoverable,General, Limited or Broadcaster , at_ble_adv_mode_t for more details
[in]	peer_addr	For AT_BLE_ADV_TYPE_DIRECTED mode only, known peer address
[in]	filtered	policy at_ble_filter_type_t for more details
[in]	interval	Advertising interval between 0x0020 and 0x4000 in 0.625 ms units (20ms to 10.24s). This parameter must be set to 0 if type equals AT_BLE_ADV_TYPE_DIRECTED
[in]	timeout	Advertising time-out between 0x0001 and 0x3FFF in seconds, 0x0000 disables time-out. This parameter must be set to 0 if type equals AT_BLE_ADV_TYPE_DIRECTED
[in]	disable_randomness	if True the device will advertise at the exact interval without adding the random 10msec

Precondition

If it is required to change BD address, at_ble_addr_set should be used otherwise default address will be used

Warning

Advertising time-out "timeout" and randomness "disable_randomness" features are not supported.

Returns

AT_BLE_SUCCESS The BLE stack has started advertising

AT_BLE_PRIVACY_CFG_PB Advertising type conflicts with local device address type

AT_BLE_INVALID_PARAM Invalid parameter supplied

AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, device_info::addr_auto_gen, adv_type, device_info::ADVData, device_info::advLen, at_ble_addr_get(), AT_BLE_ADDRESS_PUBLIC, AT_BLE_ADDRESS_RANDOM_PRIVATE_NON_RESOLVABLE, AT_BLE_ADDRESS_RANDOM_PRIVATE_RESOLVABLE, AT_BLE_ADV_BROADCASTER_MODE, AT_BLE_ADV_INTERVAL_MAX, AT_BLE_ADV_INTERVAL_MIN, AT_BLE_ADV_NONCON_INTERVAL_MIN, AT_BLE_ADV_TYPE_DIRECTED, AT_BLE_ADV_TYPE_NONCONN_UNDIRECTED, AT_BLE_ADV_TYPE_SCANNABLE_UNDIRECTED, AT_BLE_ADV_TYPE_UNDIRECTED, AT_BLE_INVALID_PARAM, AT_BLE_PRIVACY_CFG_PB, AT_BLE_SUCCESS, device_info::at_dev_addr, device, gapm_get_adv_type(), gapm_get_device_address_type(), gapm_start_adv_cmd_handler(), NULL, device_info::renew_dur, device_info::SrData, device_info::srLen, status, and at_ble_addr_t::type.

at_ble_status_t at_ble_adv_stop

(

void

)

Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

AT_BLE_SUCCESS The BLE stack has stopped advertising

AT_BLE_FAILURE Error to stop advertising (most probably not in advertising state)

References gapm_cancel_cmd_handler().

at_ble_status_t at_ble_en_recv_adv_cmp_event

(

bool

en_adv_notification

)

Enable/Disable receiving advertising complete event AT_BLE_ADV_CMP_EVENT with the end of advertising event.

Parameters

[in]

en_adv_notification

enable/disable receiving advertising complete event

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

at_ble_status_t at_ble_get_adv_cnt

(

uint32_t *

adv_pdu_cnt

)

Get the count of Advertising frame.

Parameters

[in]

adv_pdu_cnt

the count of advertising frame since start of advertising.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Referenced by eddystone_create_tlm_frame(), and main().

at_ble_status_t at_ble_rst_adv_cnt

(

void

)

Reset the count of Advertising frame.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t