BLE OTA Profile

[中文]

The BLE OTA Profile provides sector-based firmware transfer over BLE on top of esp_ble_conn_mgr. It uses the OTA service UUID 0x8018 and parses START/STOP commands plus firmware packets from the host.

The profile validates:

  • command packet CRC16

  • sector index and packet sequence continuity

  • sector CRC16 before delivering data to application callback

Examples

bluetooth/ble_profiles/ble_ota.

API Reference

Header File

Functions

void esp_ble_ota_raw_set_ota_begin_cb(esp_ble_ota_raw_ota_begin_cb_t cb)

Register OTA flash begin hook (e.g. esp_ota_begin).

Call from the application before the host may send START. May be NULL to skip.

void esp_ble_ota_raw_set_sector_send_window_for_ringbuf(uint32_t ringbuf_capacity_bytes)

Derive sector send window from firmware ring buffer capacity.

Window is ringbuf_capacity_bytes / 4096 (one sector), clamped to 1..64, and sent in START ACK byte 6 (byte 7 reserved). Call with the same capacity passed to xRingbufferCreate (e.g. example default BLE_OTA_RAW_RINGBUF_DEFAULT_SIZE gives window 3).

Parameters

ringbuf_capacity_bytes – Ring buffer size in bytes.

esp_err_t esp_ble_ota_raw_init(void)

Initialize BLE OTA profile over ble_conn_mgr.

Registers OTA service (0x8018) and DIS service. BLE connection manager init/start is done by the application.

Returns

  • ESP_OK: success

  • Others: error from dependent service initialization

esp_err_t esp_ble_ota_raw_deinit(void)

Deinitialize BLE OTA profile over ble_conn_mgr.

Returns

  • ESP_OK: success

  • Others: error from OTA service deinitialization

esp_err_t esp_ble_ota_raw_recv_fw_data_callback(esp_ble_ota_raw_recv_fw_cb_t callback)

Register OTA firmware receive callback for conn_mgr backend.

Callback is invoked when one full sector passes CRC check. Register this before processing START command from the host.

Parameters

callback – [in] Firmware receive callback.

Returns

  • ESP_OK: success

uint32_t esp_ble_ota_raw_get_fw_length(void)

Get current OTA firmware total length.

Returns UINT32_MAX before START command is received.

Returns

Total firmware size in bytes, or UINT32_MAX when OTA is not started.

Type Definitions

typedef void (*esp_ble_ota_raw_recv_fw_cb_t)(uint8_t *buf, uint32_t length)

Firmware data callback from BLE OTA profile.

Param buf

[in] Firmware data buffer (owned by profile, valid only during callback).

Param length

[in] Data length in bytes.

typedef esp_err_t (*esp_ble_ota_raw_ota_begin_cb_t)(uint32_t image_size_bytes)

Optional hook to open the flash OTA session (e.g. esp_ota_begin) on START.

Invoked with the firmware length from START after RAM is allocated, before start_ota is set and before START CMD ACK is sent. If this returns non-ESP_OK, START is rejected.

Param image_size_bytes

[in] Total firmware size from START payload.

Return

ESP_OK on success, or an error from the application OTA begin path.

Provide feedback about this document