Skip to content

Class UpdateClass

ClassList > UpdateClass

Public Types

Type Name
typedef std::function< void(size_t, size_t)> THandlerFunction_Progress

Public Functions

Type Name
void abort ()
Same as end() .
bool begin (size_t size=UPDATE_SIZE_UNKNOWN, int command=U_FLASH, int ledPin=-1, uint8_t ledOn=LOW, const char * label=nullptr)
Initialize the update process.
void clearError ()
Clear all errors. This is NOT recommended.
bool end (bool evenIfRemaining=false)
Finalize the update process. Check for errors and update completion, then activate the new firmware image.
const char * errorString () const
Get a textual description of the error.
const char * getBoardName ()
Get target board name from UF2 info.
UpdateError getError () const
Get Arduino error code of the update.
uint16_t getErrorCode () const
Get combined error code of the update.
const char * getFirmwareName ()
Get firmware name from UF2 info.
const char * getFirmwareVersion ()
Get firmware version from UF2 info.
const char * getLibreTinyVersion ()
Get LibreTiny version from UF2 info.
uf2_err_t getUF2Error () const
Get UF2OTA error code of the update.
bool hasError () const
Check if any error has occurred (incl. aborting the update).
bool isFinished ()
Check if the update process hasn't been started or has been completed.
bool isRunning ()
Check if the update process has been started.
void md5 (uint8_t * result)
Get calculated MD5 digest of the firmware.
String md5String ()
Return a hexadecimal string of calculated firmware MD5 sum.
UpdateClass & onProgress (THandlerFunction_Progress handler)
Set the callback invoked after writing data to flash.
void printError (Print & out) const
Print string error info to the stream.
size_t progress ()
Return amount of bytes already written.
size_t remaining ()
Return amount of bytes remaining to write.
bool setMD5 (const char * md5)
Set the expected MD5 of the firmware (hexadecimal string).
size_t size ()
Return complete update image size.
size_t write (const uint8_t * data, size_t len)
Write a chunk of data to the buffer or flash memory.
size_t writeStream (Stream & data)
Write all data remaining in the given stream.

Public Static Functions

Type Name
bool canRollBack ()
Check if OTA rollback is possible (switching the stored index to another partition).
bool rollBack ()
Try to switch OTA index to the other image. For single-OTA chips, only check if the upgrade image is valid.

Public Types Documentation

typedef THandlerFunction_Progress

typedef std::function<void(size_t, size_t)> UpdateClass::THandlerFunction_Progress;

Public Functions Documentation

function abort

inline void UpdateClass::abort ()

function begin

Initialize the update process. 

bool UpdateClass::begin (
    size_t size=UPDATE_SIZE_UNKNOWN,
    int command=U_FLASH,
    int ledPin=-1,
    uint8_t ledOn=LOW,
    const char * label=nullptr
)

Parameters:

  • size total UF2 file size
  • command must be U_FLASH

Returns:

false if parameters are invalid or update is running, true otherwise

function clearError

void UpdateClass::clearError ()

function end

Finalize the update process. Check for errors and update completion, then activate the new firmware image. 

bool UpdateClass::end (
    bool evenIfRemaining=false
)

Parameters:

  • evenIfRemaining don't raise errors if still in progress

Returns:

false in case of errors or no update running; true otherwise

function errorString

const char * UpdateClass::errorString () const

function getBoardName

inline const char * UpdateClass::getBoardName ()

function getError

inline UpdateError UpdateClass::getError () const

function getErrorCode

uint16_t UpdateClass::getErrorCode () const

function getFirmwareName

inline const char * UpdateClass::getFirmwareName ()

function getFirmwareVersion

inline const char * UpdateClass::getFirmwareVersion ()

function getLibreTinyVersion

inline const char * UpdateClass::getLibreTinyVersion ()

function getUF2Error

inline uf2_err_t UpdateClass::getUF2Error () const

function hasError

bool UpdateClass::hasError () const

function isFinished

inline bool UpdateClass::isFinished ()

function isRunning

inline bool UpdateClass::isRunning ()

function md5

void UpdateClass::md5 (
    uint8_t * result
)

function md5String

String UpdateClass::md5String ()

function onProgress

UpdateClass & UpdateClass::onProgress (
    THandlerFunction_Progress handler
)

function printError

void UpdateClass::printError (
    Print & out
) const

function progress

inline size_t UpdateClass::progress ()

function remaining

inline size_t UpdateClass::remaining ()

function setMD5

bool UpdateClass::setMD5 (
    const char * md5
)

function size

inline size_t UpdateClass::size ()

function write

Write a chunk of data to the buffer or flash memory. 

size_t UpdateClass::write (
    const uint8_t * data,
    size_t len
)

It's advised to write in 512-byte chunks (or its multiples).

Parameters:

  • data chunk of data
  • len length of the chunk

Returns:

size_t amount of bytes written

function writeStream

Write all data remaining in the given stream. 

size_t UpdateClass::writeStream (
    Stream & data
)

If the stream doesn't produce any data within UPDATE_TIMEOUT_MS, the update process will be aborted.

Parameters:

  • data stream to read from

Returns:

size_t amount of bytes written

Public Static Functions Documentation

function canRollBack

Check if OTA rollback is possible (switching the stored index to another partition). 

static bool UpdateClass::canRollBack ()

Note that this is not the same as "switching" OTA with revert=true.

Returns:

true if 2nd image is valid and the chip is dual-OTA; false otherwise

function rollBack

Try to switch OTA index to the other image. For single-OTA chips, only check if the upgrade image is valid. 

static bool UpdateClass::rollBack ()

This can be used to "activate" the upgrade after flashing.

Parameters:

  • revert switch if (and only if) the other image is already marked as active (i.e. switch back to the running image)

Returns:

false if the second image (or upgrade image) is not valid; false if writing failed; true otherwise

The documentation for this class was generated from the following file cores/common/arduino/libraries/common/Update/Update.h