nRF5 SDK: модуль BLE Advertising | arm

Этот программный модуль предназначен для поддержки оповещения по радио (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.

ble_advertising_on_sys_evt. Функция для обработки системных событий.

void ble_advertising_on_sys_evt (uint32_t sys_evt);

Эта функция должна вызваться для обработки системных событий, которые имеют отношение к Advertising Module. В частности, Advertising Module не может использовать SoftDevice, пока существует ожидающая завершения операция записи в память FLASH. Этот обработчик события был разработан для задержки адвертайзинга до тех пор, пока не завершится операция с памятью FLASH.

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) не будет запущен.

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 в любом режиме, который был разрешен во время инициализации.

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.