Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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]chused 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_dataRaw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
[in]adv_data_lenData 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_dataRaw 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_lenData 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_dataRaw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
[in]adv_data_lenData length for adv_data.
[in]scan_resp_dataRaw 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_lenData 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
Parameters
[in]update_on_the_fly_dataupdate 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]typeAdvertising type, see at_ble_adv_type_t for more info
[in]modeeither non-discoverable,General, Limited or Broadcaster , at_ble_adv_mode_t for more details
[in]peer_addrFor AT_BLE_ADV_TYPE_DIRECTED mode only, known peer address
[in]filteredpolicy at_ble_filter_type_t for more details
[in]intervalAdvertising 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]timeoutAdvertising 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_randomnessif 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]typeAdvertising type, see at_ble_adv_type_t for more info
[in]modeeither non-discoverable,General, Limited or Broadcaster , at_ble_adv_mode_t for more details
[in]peer_addrFor AT_BLE_ADV_TYPE_DIRECTED mode only, known peer address
[in]filteredpolicy at_ble_filter_type_t for more details
[in]intervalAdvertising 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]timeoutAdvertising 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_randomnessif 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_notificationenable/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_cntthe 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