BLE OTA Service

[中文]

BLE OTA Service defines GATT service 0x8018 and the following characteristics:

  • 0x8020 (RECV_FW): firmware data and firmware ACK notifications

  • 0x8021 (PROGRESS_BAR): progress value (read and notify)

  • 0x8022 (COMMAND): OTA command and command ACK notifications

  • 0x8023 (CUSTOMER): vendor-defined payload channel

This service is transport-level and can be reused by different OTA profile logic. When used with ble_ota_raw, command and firmware payload parsing is handled by that profile.

Examples

bluetooth/ble_profiles/ble_ota.

API Reference

Header File

Functions

void esp_ble_ota_recv_fw_data(const uint8_t *data, uint16_t len)

Weak hook: payload written to RECV_FW_CHAR (0x8020).

Invoked after the service validates ATT payload length. Override with a strong symbol in profile/application layer.

Parameters

  • data – [in] ATT write payload (valid for the duration of the call).

  • len – [in] Payload length in octets.

void esp_ble_ota_recv_cmd_data(const uint8_t *data, uint16_t len)

Weak hook: payload written to COMMAND_CHAR (0x8022).

Parameters

  • data – [in] ATT write payload.

  • len – [in] Payload length in octets.

void esp_ble_ota_recv_customer_data(const uint8_t *data, uint16_t len)

Weak hook: payload written to CUSTOMER_CHAR (0x8023).

Parameters

  • data – [in] ATT write payload.

  • len – [in] Payload length in octets.

esp_err_t esp_ble_ota_svc_init(void)

Register the 0x8018 OTA GATT service with esp_ble_conn_mgr.

Returns

  • ESP_OK on success

  • Error code from esp_ble_conn_add_svc() on failure

esp_err_t esp_ble_ota_svc_deinit(void)

Remove the 0x8018 OTA GATT service from esp_ble_conn_mgr.

Returns

  • ESP_OK on success

  • Error code from esp_ble_conn_remove_svc() on failure

uint16_t esp_ble_ota_progress_bar_local_get(void)

Read local PROGRESS_BAR as a single uint16_t.

Return value matches the two stored octets in native byte order (on little-endian: low 8 bits = integer part, high 8 bits = hundredths).

Returns

Current local PROGRESS_BAR value encoded as one uint16_t.

esp_err_t esp_ble_ota_notify_recv_fw_raw(const uint8_t *data, uint16_t len)

Send a Notify on RECV_FW_CHAR (0x8020) with raw payload.

Parameters
Returns

esp_err_t esp_ble_ota_notify_progress_bar_raw(uint8_t low_octet, uint8_t high_octet)

Notify PROGRESS_BAR_CHAR (0x8021) and update the local value used for GATT Read.

Air order: low_octet (integer) first, then high_octet (hundredths).

Parameters

  • low_octet – [in] Integer part (0–100), sent first on air.

  • high_octet – [in] Hundredths (0–99), sent second on air; when low_octet is 100, must be 0.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if values are out of range

  • Error from esp_ble_conn_notify() otherwise

esp_err_t esp_ble_ota_notify_command_raw(const uint8_t *data, uint16_t len)

Send a Notify on COMMAND_CHAR (0x8022) with raw payload.

Parameters
Returns

esp_err_t esp_ble_ota_notify_customer_raw(const uint8_t *data, uint16_t len)

Send a Notify on CUSTOMER_CHAR (0x8023) with raw payload.

Parameters
Returns

Macros

BLE_OTA_SERVICE_UUID16

Primary service, 16-bit ESP BLE OTA GATT service UUID

BLE_OTA_CHR_UUID16_RECV_FW

RECV_FW_CHAR: firmware in; Write w/o rsp + Notify (ACK as Notify)

BLE_OTA_CHR_UUID16_PROGRESS_BAR

PROGRESS_BAR_CHAR: 0–100.00; Read + Notify

BLE_OTA_CHR_UUID16_COMMAND

COMMAND_CHAR: host commands; Write w/o rsp + Notify (ACK as Notify)

BLE_OTA_CHR_UUID16_CUSTOMER

CUSTOMER_CHAR: vendor data; Write w/o rsp + Notify

BLE_OTA_PROGRESS_BAR_LEN

Progress value size: integer octet (0–100) then hundredths (0–99)

BLE_OTA_ATT_PAYLOAD_MAX_LEN

Max ATT write / notify payload for this service

esp_ble_ota_on_recv_fw

Backward-compatible alias of esp_ble_ota_recv_fw_data.

Deprecated:

Prefer esp_ble_ota_recv_fw_data.

esp_ble_ota_on_command

Backward-compatible alias of esp_ble_ota_recv_cmd_data.

Deprecated:

Prefer esp_ble_ota_recv_cmd_data.

esp_ble_ota_on_customer

Backward-compatible alias of esp_ble_ota_recv_customer_data.

Deprecated:

Prefer esp_ble_ota_recv_customer_data.

Provide feedback about this document