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.

  1. 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());
    
    }
    
  2. 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

Returns

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

Returns

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

Returns

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.

Returns

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.

Returns

partition

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

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

Parameters

startFrom – - optional

Returns

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

Returns

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

Returns

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.

Returns

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.

Returns

partition

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

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

Parameters

startFrom – - optional

Returns

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

Returns

size_t – Quantity of chars written to stream

inline virtual StreamType getStreamType() const override

Get the stream type.

Returns

StreamType – The stream type.

inline virtual uint16_t readMemoryBlock(char *data, int bufSize) 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

Returns

uint16_t – Quantity of chars read

inline virtual bool seek(int len) override

Move read cursor.

Parameters

len – Relative cursor adjustment

Returns

bool – True on success.

inline virtual int available() override

Return the total length of the stream.

Returns

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

inline virtual bool isFinished() override

Check if all data has been read.

Returns

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

Returns

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

Returns

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

Returns

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.

Returns

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.

Returns

partition

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

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

Parameters

startFrom – - optional

Returns

partition

inline Storage::Iterator getBootPartitions()

Gets information about all bootable partitions.

Returns

Storage::Iterator

inline uint8_t getSlot(Partition partition)

Gets slot number for a partition.

Parameters

partition

Returns

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

Returns

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

Used by

Environment Variables

SoC support

  • esp8266

  • host