|
Этот программный модуль предназначен для поддержки оповещения по радио (BLE advertising) с возможностью подключения к устройству.
Advertising Module обрабатывает оповещения о возможности соединения (connectable advertising) для приложения устройства BLE. Модуль может быть сконфигурирован с нужными режимами оповещения, чтобы соответствовать наиболее типичным сценариям использования. Ваше основное приложение может реагировать на изменения режимов advertising, если предоставлен обработчик события (event handler).
Замечание: Advertising Module поддерживает только те приложения, у которых используется одиночный линк периферийного устройства.
Приложение должно передавать события стека BLE в этот модуль путем вызова ble_advertising_on_ble_evt(), и также должно передавать системные события вызовом ble_advertising_on_sys_evt().
[Используемые перечисления]
ble_adv_evt_t. Это перечисление используется для событий адвертайзинга.
typedef enum
{
BLE_ADV_EVT_IDLE,
BLE_ADV_EVT_DIRECTED,
BLE_ADV_EVT_DIRECTED_SLOW,
BLE_ADV_EVT_FAST,
BLE_ADV_EVT_SLOW,
BLE_ADV_EVT_FAST_WHITELIST,
BLE_ADV_EVT_SLOW_WHITELIST,
BLE_ADV_EVT_WHITELIST_REQUEST,
BLE_ADV_EVT_PEER_ADDR_REQUEST
} ble_adv_evt_t;
Эти события передаются в основное приложение (main), если во время инициализации Advertising Module был предоставлен обработчик. События для режимов, которые не используются, могут игнорироваться. Подобным образом могут игнорироваться события BLE_ADV_EVT_WHITELIST_REQUEST иd BLE_ADV_EVT_PEER_ADDR_REQUEST, если не используется белый список (whitelist) и прямое оповещение (direct advertising).
BLE_ADV_EVT_IDLE Ожидание. Оповещение с возможностью подключения (connectable advertising) не производится.
BLE_ADV_EVT_DIRECTED Запущен режим прямого оповещения (direct advertising).
BLE_ADV_EVT_DIRECTED_SLOW Был запущен direct advertising с низкой частотой повторений.
BLE_ADV_EVT_FAST Был запущен режим быстрого оповещения.
BLE_ADV_EVT_SLOW Был запущен режим медленного оповещения.
BLE_ADV_EVT_FAST_WHITELIST Был запущен режим быстрого оповещения с использованием белого списка.
BLE_ADV_EVT_SLOW_WHITELIST Был запущен режим медленного оповещения с использованием белого списка.
BLE_ADV_EVT_WHITELIST_REQUEST Запрос белого списка из основного приложения. Чтобы мог работать whitelist advertising, должен быть установлен белый список, когда сработало это событие.
BLE_ADV_EVT_PEER_ADDR_REQUEST Запрос адреса пира из основного приложения. Чтобы мог работать directed advertising, должен быть установлен адрес пира, когда сработало это событие.
ble_adv_mode_t. Это перечисление используется для режимов адвертайзинга.
typedef enum
{
BLE_ADV_MODE_IDLE,
BLE_ADV_MODE_DIRECTED,
BLE_ADV_MODE_DIRECTED_SLOW,
BLE_ADV_MODE_FAST,
BLE_ADV_MODE_SLOW
} ble_adv_mode_t;
BLE_ADV_MODE_IDLE Ожидание. Оповещение с возможностью подключения (connectable advertising) не производится.
BLE_ADV_MODE_DIRECTED Режим направленного оповещения, когда осуществляется попытка соединиться с последним узлом, с которым была связь.
BLE_ADV_MODE_DIRECTED_SLOW Режим направленного оповещения (с низкой частотой повторений), когда осуществляется попытка соединиться с последним узлом, с которым была связь.
BLE_ADV_MODE_FAST Быстрое оповещение, которое будет запускать соединение с любым пиром, либо фильтровать подключение пира по белому списку, если он был задан.
BLE_ADV_MODE_SLOW Медленное оповещение, которое работает аналогично быстрому. По умолчанию этот режим использует увеличенный интервал и таймаут по сравнению с режимом быстрого оповещения. Однако эти опции настраиваются пользователем.
[Функции]
ble_advertising_init. Функция для инициализации Advertising Module.
uint32_t ble_advertising_init (ble_advdata_t const * p_advdata,
ble_advdata_t const * p_srdata,
ble_adv_modes_config_t const * p_config,
ble_advertising_evt_handler_t const evt_handler,
ble_advertising_error_handler_t const error_handler);
Кодирует требуемые данные оповещения (advertising data) и передает их в стек. Также выстраивает структуру для передачи в стек, когда запускается адвертайзинг. Предоставленные данные адвертайзинга копируются в локальную структуру и обрабатываются в зависимости от того, какие режимы адвертайзинга были запущены в ble_advertising_start.
Параметры:
[in] p_advdata Данные адвертайзинга: имя, видимость (appearance), флаги обнаружения (discovery flags) и многое другое.
[in] p_srdata Данные для ответа на сканирование (scan response data): довесок к данным адвертайзинга.
[in] p_config Выбирает, какой режим адвертайзинга используется, и какие в нем заданы интервалы.
[in] evt_handler Обработчик события, который будет вызван при событиях адвертайзинга (см. перечисление ble_adv_evt_t).
[in] error_handler Обработчик ошибки, который будет передавать внутренние ошибки в основное приложение.
В случае успеха вернет NRF_SUCCESS, иначе будет возвращен код ошибки.
ble_advertising_on_ble_evt. Функция для обработки событий BLE.
void ble_advertising_on_ble_evt (const ble_evt_t *const p_ble_evt);
Эта функция должна вызываться из диспетчера событий стека BLE для модуля, чтобы обрабатывать события BLE, которые имеют отношение к Advertising Module.
Параметры:
[in] p_ble_evt Событие стека BLE.
ble_advertising_on_sys_evt. Функция для обработки системных событий.
void ble_advertising_on_sys_evt (uint32_t sys_evt);
Эта функция должна вызваться для обработки системных событий, которые имеют отношение к Advertising Module. В частности, Advertising Module не может использовать SoftDevice, пока существует ожидающая завершения операция записи в память FLASH. Этот обработчик события был разработан для задержки адвертайзинга до тех пор, пока не завершится операция с памятью FLASH.
Параметры:
[in] sys_evt Событие системы.
ble_advertising_peer_addr_reply. Функция для установки адреса пира.
uint32_t ble_advertising_peer_addr_reply (ble_gap_addr_t * p_peer_addr);
При получении события BLE_ADV_EVT_PEER_ADDR_REQUEST приложением должен быть установлен адрес пира. Без адреса пира режим прямого оповещения (directed advertising) не будет запущен.
Параметры:
[in] p_peer_addr Указатель на адрес пира.
Возвращаемые значения:
NRF_SUCCESS В модуле был успешно сохранен указатель на адрес пира.
NRF_ERROR_INVALID_STATE Если ответ не ожидался.
ble_advertising_restart_without_whitelist. Функция запрета адвертайзинга по белому списку.
uint32_t ble_advertising_restart_without_whitelist (void);
Эта функция временно запретит whitelist advertising. Вызов этой функции сбросит текущий обратный отсчет таймаута.
Вернет NRF_SUCCESS в случае успеха, либо сообщение об ошибке, которое было передано из Softdevice.
ble_advertising_start. Функция запускает оповещение BLE.
uint32_t ble_advertising_start (ble_adv_mode_t advertising_mode);
Вы можете запустить advertising в любом режиме, который был разрешен во время инициализации.
Параметры:
[in] advertising_mode Режим оповещения.
Возвращаемые значения:
NRF_SUCCESS В случае успеха, либо код ошибки, сообщающий о причине отказа.
NRF_ERROR_INVALID_STATE Если модуль не был инициализирован.
ble_advertising_whitelist_reply. Функция для установки белого списка.
uint32_t ble_advertising_whitelist_reply (ble_gap_addr_t const * p_gap_addrs,
uint32_t addr_cnt,
ble_gap_irk_t const * p_gap_irks,
uint32_t irk_cnt);
Приложение должно установить whitelist при получении события BLE_ADV_EVT_WHITELIST_REQUEST. Без белого списка не может быть запущен режим быстрого или медленного оповещения.
Параметры:
[in] p_gap_addrs Список GAP-адресов для белого списка.
[in] addr_cnt Количество GAP-адресов для белого списка.
[in] p_gap_irks Список ключей IRK пира для белого списка.
[in] irk_cnt Количество ключей IRK пира для белого списка.
Возвращаемые значения:
NRF_SUCCESS Если операция была успешной.
NRF_ERROR_INVALID_STATE Если вызов этой функции был сделан без получения события BLE_ADV_EVT_WHITELIST_REQUEST.
[Ссылки]
1. nRF5 SDK Advertising Module site:nordicsemi.com.
2. Оповещения BLE, руководство для начинающих. |
