Immediate Alert Service

[中文]

The Immediate Alert Service (IAS) is a Bluetooth SIG GATT service that exposes the Alert Level characteristic so a connected peer can request an immediate alert on the device (for example, sound or vibration when finding a peripheral).

The Alert Level is a single octet: no alert, mild alert, or high alert (ESP_BLE_IAS_ALERT_LEVEL_NO_ALERT, ESP_BLE_IAS_ALERT_LEVEL_MILD_ALERT, ESP_BLE_IAS_ALERT_LEVEL_HIGH_ALERT, i.e. 0x00, 0x01, and 0x02).

To use this service in an application:

Enable CONFIG_BLE_IAS in menuconfig.
Initialize the BLE connection manager with esp_ble_conn_init() (and related setup such as the default event loop if your project requires it).
After the connection manager has been initialized, call esp_ble_ias_init() to register the IAS on the GATT server. Do this before esp_ble_conn_start() in the usual example flow.
Call esp_ble_ias_register_alert_cb() after esp_ble_ias_init() so the service exists before you install the handler that runs on valid Alert Level writes.

There is no dedicated example project for this service; follow the initialization pattern used in other BLE service examples.

API Reference

Header File

components/bluetooth/ble_services/ias/include/esp_ias.h

Functions

esp_err_t esp_ble_ias_register_alert_cb(esp_ble_ias_alert_cb_t cb, void *priv)

Register a callback for Alert Level writes.

Parameters

cb – [in] Callback function; pass NULL to unregister.
priv – [in] Opaque pointer passed to cb.

Returns

ESP_OK on success

esp_err_t esp_ble_ias_get_alert_level(uint8_t *level)

Read the last Alert Level written by a GATT client.

Parameters

level – [out] The pointer to store the Alert Level (default ESP_BLE_IAS_ALERT_LEVEL_NO_ALERT).

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if level is NULL

esp_err_t esp_ble_ias_init(void)

Register the Immediate Alert Service (0x1802) with esp_ble_conn_mgr.

Returns

ESP_OK on success
ESP_FAIL on failure from esp_ble_conn_add_svc()

Macros

BLE_IAS_UUID16: Primary service: Immediate Alert Service (16-bit UUID)

BLE_IAS_CHR_UUID16_ALERT_LEVEL: Alert Level characteristic (16-bit UUID)

ESP_BLE_IAS_ALERT_LEVEL_NO_ALERT: No alert

ESP_BLE_IAS_ALERT_LEVEL_MILD_ALERT: Mild alert

ESP_BLE_IAS_ALERT_LEVEL_HIGH_ALERT: High alert

Type Definitions

typedef void (*esp_ble_ias_alert_cb_t)(uint8_t alert_level, void *priv)

Callback invoked when a connected client writes the Alert Level characteristic with a valid value.

Param alert_level: [in] Value written by the client. One of ESP_BLE_IAS_ALERT_LEVEL_NO_ALERT, ESP_BLE_IAS_ALERT_LEVEL_MILD_ALERT, or ESP_BLE_IAS_ALERT_LEVEL_HIGH_ALERT.
Param priv: [in] User context registered with esp_ble_ias_register_alert_cb.

Provide feedback about this document