uploaded 1 month ago
Espressif defined BLE OTA profile


ESP BLE OTA Component description

esp ble ota is a firmware upgrade component for data sending and receiving based on customized BLE Services. The firmware to be upgraded will be subcontracted by the client and transmitted sequentially. After receiving data from the client, packet sequence and CRC check will be checked and ACK will be returned.


You can create a project from this example by the following command: create-project-from-example "espressif/ble_ota^0.1.8:ble_ota"

Note: For the examples downloaded by using this command, you need to comment out the override_path line in the main/idf_component.yml.



v0.1.0 - 2023-01-04


  • BLE-OTA:
    • The initial version.

v0.1.1 - 2023-01-17


  • BLE-OTA:
    • Deleted subscribe command support, no longer needed for protocomm.

    • Added finish command support to indicated end of OTA.

v0.1.2 - 2023-01-18

  • Fixed warnings

v0.1.3 - 2023-02-09

  • BLE-OTA:
    • Added support for IDF release v4.4
    • Fixed github ble_ota link in idf_component.yml

v0.1.4 - 2023-02-13

  • BLE-OTA:
    • Added support for bluedroid BLE 5.0 features.

v0.1.5 - 2023-02-15

  • BLE-OTA:
    • Added support for pre-encrypted OTA.

v0.1.6 - 2023-02-17

  • BLE-OTA:
    • Added support for nimble extended advertising.

v0.1.7 - 2023-03-09

  • BLE-OTA:
    • Use cu_pkg_define_version to define the version of this component.

v0.1.8 - 2023-03-31

  • BLE-OTA:
    • Fixed errors for release v4.4

readme of ble_ota example

ESP BLE OTA Demo description

ble ota demo is based on the ble ota component, it receives firmware via BLE and writes it to flash, sector by sector, until the upgrade is complete.

1. Services definition

The component contains two services:

  • DIS Service: Displays software and hardware version information

  • OTA Service: It is used for OTA upgrade and contains 4 characteristics, as shown in the following table:

Characteristics UUID Prop description
RECV_FW_CHAR 0x8020 Write, notify Firmware received, send ACK
PROGRESS_BAR_CHAR 0x8021 Read, notify Read the progress bar and report the progress bar
COMMAND_CHAR 0x8022 Write, notify Send the command and ACK
CUSTOMER_CHAR 0x8023 Write, notify User-defined data to send and receive

2. Data transmission

2.1 Command package format

unit Command_ID PayLoad CRC16
Byte Byte: 0 ~ 1 Byte: 2 ~ 17 Byte: 18 ~ 19


  • 0x0001: Start OTA, Payload bytes(2 to 5), indicates the length of the firmware. Other Payload is set to 0 by default. CRC16 calculates bytes(0 to 17).
  • 0x0002: Stop OTA, and the remaining Payload will be set to 0. CRC16 calculates bytes(0 to 17).
  • 0x0003: The Payload bytes(2 or 3) is the payload of the Command_ID for which the response will be sent. Payload bytes(4 to 5) is a response to the command. 0x0000 indicates accept, 0x0001 indicates reject. Other payloads are set to 0. CRC16 computes bytes(0 to 17).

2.2 Firmware package format

The format of the firmware package sent by the client is as follows:

unit Sector_Index Packet_Seq PayLoad
Byte Byte: 0 ~ 1 Byte: 2 Byte: 3 ~ (MTU_size - 4)
  • Sector_Index:Indicates the number of sectors, sector number increases from 0, cannot jump, must be send 4K data and then start transmit the next sector, otherwise it will immediately send the error ACK for request retransmission.
  • Packet_Seq:If Packet_Seq is 0xFF, it indicates that this is the last packet of the sector, and the last 2 bytes of Payload is the CRC16 value of 4K data for the entire sector, the remaining bytes will set to 0x0. Server will check the total length and CRC of the data from the client, reply the correct ACK, and then start receive the next sector of firmware data.

The format of the reply packet is as follows:

unit Sector_Index ACK_Status CRC6
Byte Byte: 0 ~ 1 Byte: 2 ~ 3 Byte: 18 ~ 19


  • 0x0000: Success
  • 0x0001: CRC error
  • 0x0002: Sector_Index error, bytes(4 ~ 5) indicates the desired Sector_Index
  • 0x0003:Payload length error

3. Sample APP


4. Sample code



Configure the Project

` menuconfig'

- Component config → Bluetooth → Bluetooth → Host → NimBLE - BLE only

Note: For maximum throughput, set maximum MTU using

- Component config → Bluetooth → NimBLE Options → Preferred MTU size in octets as 517

5.1 OTA with Protocomm

Configure the Project

` menuconfig`

- Example Configuration → Type of OTA → Use protocomm layer for security

- Component config → OTA Manager → Type of OTA → Enable protocomm level security

5.2 Pre encrypted OTA

  • For using pre encrypted OTA, the OTA file needs to be encrypted using private key
  • For more info regarding encrypting file refer : esp_encrypted_img

Configure the Project

` menuconfig`

- If using ESP32S3 set Component config → Bluetooth → Bluetooth → NimBLE Options → NimBLE Host task stack size as 8192 

- Example Configuration → Type of OTA → Use Pre-Encrypted OTA

- Component config → OTA Manager → Type of OTA → Enable pre encrypted OTA


License: Apache-2.0

To add this component to your project, run: add-dependency "espressif/ble_ota^0.1.8"

or download archive


  • espressif/cmake_utilities 0.*
  • espressif/esp_encrypted_img ^2.0.1
  • ESP-IDF >=4.4
  • Examples:


    more details


    • Downloaded in total
      Downloaded in total 88 times
    • Downloaded this version
      This version: 13 times


    espressif/ble_ota version: 0.1.8 |