Over-The-Air(OTA) Upgrader

Introduction

This architecture-agnostic component adds support for Over-The-Air upgrades.

Usage

1. Add COMPONENT_DEPENDS += Ota to your application component.mk file.

2. Add these lines to your application:

   #include <Ota/Manager.h>
   

After that you will have access to a global OtaManager instance that can be used to manage your OTA upgrade process.

3. You can use OtaManager to get information about the bootable partitions and update them. The code below will display the current bootable and running partition:

   void init()
   {
   
       // ...
       auto partition = OtaManager.getRunningPartition();
   
       Serial.printf("\r\nCurrently running %s @ 0x%08x.\r\n", partition.name().c_str(), partition.address());
   
   }
   

4. If needed you can also create your own instance of the of OtaUpgrader as shown below:

   // Call when IP address has been obtained
   void onIp(IpAddress ip, IpAddress mask, IpAddress gateway)
   {
      // ...
   
      OtaUpgrader ota;
   
      auto part = ota.getNextBootPartition();
   
      ota.begin(part);
   
      // ... write all the data to the partition
   
      ota.end();
   
      // ...
   }
   

See the Basic Ota sample application.

API Documentation

namespace Ota

class IdfUpgrader : public Ota::UpgraderBase

#include <IdfUpgrader.h>

ESP32 OTA Upgrader implementation.

Public Functions

virtual bool begin(Partition partition, size_t size = 0) override

Prepares a partition for an upgrade. The preparation is bootloader and architecture dependent.

Parameters:

• partition –

• size –

Return values:

bool –

virtual size_t write(const uint8_t *buffer, size_t size) override

Writes chunk of data to the partition set in begin().

Parameters:

• buffer –

• size –

Return values:

size_t – actually written bytes

inline virtual bool end() override

Finalizes the partition upgrade.

inline virtual bool abort() override

Aborts a partition upgrade.

inline virtual bool setBootPartition(Partition partition, bool save = true) override

Sets the default partition from where the application will be booted on next restart.

Parameters:

• partition –

• save – if true the change is persisted on the flash, otherwise it will be valid only for the next boot

Return values:

bool –

inline virtual Partition getBootPartition() override

Gets information about the partition that is set as the default one to boot.

Note

The returned partition can be different than the current running partition.

Return values:

partition –

inline virtual Partition getRunningPartition() override

Gets information about the partition from which the current application is running.

Note

The returned partition can be different than the default boot partition.

Return values:

partition –

inline virtual Partition getNextBootPartition(Partition startFrom = {}) override

Gets the next bootable partition that can be used after successful OTA upgrade.

Parameters:

startFrom – - optional

Return values:

partition –

class RbootUpgrader : public Ota::UpgraderBase

#include <RbootUpgrader.h>

ESP8266 rBoot OTA Upgrader implementation.

Public Functions

virtual bool begin(Partition partition, size_t size = 0) override

Prepare the partition for.

virtual size_t write(const uint8_t *buffer, size_t size) override

Writes chunk of data to the partition set in begin().

Parameters:

• buffer –

• size –

Return values:

size_t – actually written bytes

inline virtual bool end() override

Finalizes the partition upgrade.

virtual bool setBootPartition(Partition partition, bool save = true) override

Sets the default partition from where the application will be booted on next restart.

Parameters:

• partition –

• save – if true the change is persisted on the flash, otherwise it will be valid only for the next boot

Return values:

bool –

inline virtual Partition getBootPartition() override

Gets information about the partition that is set as the default one to boot.

Note

The returned partition can be different than the current running partition.

Return values:

partition –

virtual Partition getRunningPartition() override

Gets information about the partition from which the current application is running.

Note

The returned partition can be different than the default boot partition.

Return values:

partition –

inline virtual Partition getNextBootPartition(Partition startFrom = {}) override

Gets the next bootable partition that can be used after successful OTA upgrade.

Parameters:

startFrom – - optional

Return values:

partition –

class UpgradeOutputStream : public ReadWriteStream

#include <UpgradeOutputStream.h>

Write-only stream type used during firmware upgrade.

Public Functions

inline UpgradeOutputStream(Partition partition, size_t maxLength = 0)

Construct a stream for the given partition.

Parameters:

partition –

virtual size_t write(const uint8_t *data, size_t size) override

Write chars to stream.

Note

Although this is defined in the Print class, ReadWriteStream uses this as the core output method so descendants are required to implement it

Parameters:

• buffer – Pointer to buffer to write to the stream

• size – Quantity of chars to write

Return values:

size_t – Quantity of chars written to stream

inline virtual StreamType getStreamType() const override

Get the stream type.

Return values:

StreamType – The stream type.

inline virtual uint16_t readMemoryBlock(char*, int) override

Read a block of memory.

Todo:

Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Parameters:

• data – Pointer to the data to be read

• bufSize – Quantity of chars to read

Return values:

uint16_t – Quantity of chars read

inline virtual bool seek(int) override

Move read cursor.

Parameters:

len – Relative cursor adjustment

Return values:

bool – True on success.

inline virtual int available() override

Return the total length of the stream.

Return values:

int – -1 is returned when the size cannot be determined

inline virtual bool isFinished() override

Check if all data has been read.

Return values:

bool – True on success.

class UpgraderBase

#include <UpgraderBase.h>

Subclassed by Ota::IdfUpgrader, Ota::RbootUpgrader

Public Functions

virtual bool begin(Partition partition, size_t size = 0) = 0

Prepares a partition for an upgrade. The preparation is bootloader and architecture dependent.

Parameters:

• partition –

• size –

Return values:

bool –

virtual size_t write(const uint8_t *buffer, size_t size) = 0

Writes chunk of data to the partition set in begin().

Parameters:

• buffer –

• size –

Return values:

size_t – actually written bytes

virtual bool end() = 0

Finalizes the partition upgrade.

inline virtual bool abort()

Aborts a partition upgrade.

virtual bool setBootPartition(Partition partition, bool save = true) = 0

Sets the default partition from where the application will be booted on next restart.

Parameters:

• partition –

• save – if true the change is persisted on the flash, otherwise it will be valid only for the next boot

Return values:

bool –

virtual Partition getBootPartition() = 0

Gets information about the partition that is set as the default one to boot.

Note

The returned partition can be different than the current running partition.

Return values:

partition –

virtual Partition getRunningPartition() = 0

Gets information about the partition from which the current application is running.

Note

The returned partition can be different than the default boot partition.

Return values:

partition –

virtual Partition getNextBootPartition(Partition startFrom = {}) = 0

Gets the next bootable partition that can be used after successful OTA upgrade.

Parameters:

startFrom – - optional

Return values:

partition –

inline Storage::Iterator getBootPartitions()

Gets information about all bootable partitions.

Return values:

Storage::Iterator –

inline uint8_t getSlot(Partition partition)

Gets slot number for a partition.

Parameters:

partition –

Return values:

uint8_t – slot number

namespace Network

Variables

constexpr uint8_t NO_ROM_SWITCH = {0xff}

Magic value for ROM slot indicating slot won’t change after successful OTA.

class HttpUpgrader : protected HttpClient

#include <HttpUpgrader.h>

Public Functions

inline bool addItem(const String &firmwareFileUrl, Partition partition, ReadWriteStream *stream = nullptr)

Add an item to update.

Parameters:

• firmwareFileUrl –

• partition – Target partition to write

• stream –

Return values:

bool –

inline void switchToRom(uint8_t romSlot)

On completion, switch to the given ROM slot.

Parameters:

romSlot – specify NO_ROM_SWITCH (the default) to cancel any previously set switch

inline void setBaseRequest(HttpRequest *request)

Sets the base request that can be used to pass.

   - default request parameters, like request headers...
   - default SSL options
   - default SSL fingeprints
   - default SSL client certificates

Parameters:

request –

inline const ItemList &getItems() const

Allow read access to item list.

struct Item

#include <HttpUpgrader.h>

class ItemList : public Vector<Item>

#include <HttpUpgrader.h>

References

• Source Code

• rBoot

Used by

• Graphic Editor Sample

• Over-The-Air(OTA) Network Upgrader Library

• Over-the-Air Firmware Upgrade Library

• OTA Firmware Upgrade via MQTT Library

Environment Variables

• RBOOT_RTC_ENABLED

SoC support

• esp8266

• host