idfxx::ota::update Class Reference

RAII OTA update session. More...

Public Member Functions
	update (const partition &part)
	Begins an OTA update, erasing the entire partition.
	update (const partition &part, size_t image_size)
	Begins an OTA update, erasing space for the specified image size.
	update (const partition &part, sequential_erase_tag)
	Begins an OTA update with sequential (incremental) flash erase.
	~update ()
	update (const update &)=delete
update &	operator= (const update &)=delete
	update (update &&other) noexcept
	Move constructor.
update &	operator= (update &&other) noexcept
	Move assignment.
void	set_final_partition (const partition &final_part, bool copy=true)
	Redirects the validated image to a different final partition.
result< void >	try_set_final_partition (const partition &final_part, bool copy=true)
	Redirects the validated image to a different final partition.
void	write (const void *data, size_t size)
	Writes data sequentially to the OTA partition.
void	write (std::span< const uint8_t > data)
	Writes data sequentially to the OTA partition.
void	write_with_offset (uint32_t offset, const void *data, size_t size)
	Writes data at a specific offset in the OTA partition.
void	write_with_offset (uint32_t offset, std::span< const uint8_t > data)
	Writes data at a specific offset in the OTA partition.
result< void >	try_write (const void *data, size_t size)
	Writes data sequentially to the OTA partition.
result< void >	try_write (std::span< const uint8_t > data)
	Writes data sequentially to the OTA partition.
result< void >	try_write_with_offset (uint32_t offset, const void *data, size_t size)
	Writes data at a specific offset in the OTA partition.
result< void >	try_write_with_offset (uint32_t offset, std::span< const uint8_t > data)
	Writes data at a specific offset in the OTA partition.
void	end ()
	Finalizes the OTA update and validates the written image.
void	abort ()
	Aborts the OTA update and frees associated resources.
result< void >	try_end ()
	Finalizes the OTA update and validates the written image.
result< void >	try_abort ()
	Aborts the OTA update and frees associated resources.

Static Public Member Functions
static update	resume (const partition &part, size_t offset)
	Resumes an interrupted OTA update, erasing all remaining flash.
static update	resume (const partition &part, size_t offset, size_t erase_size)
	Resumes an interrupted OTA update, erasing the specified amount of flash.
static update	resume (const partition &part, size_t offset, sequential_erase_tag)
	Resumes an interrupted OTA update with sequential (incremental) flash erase.
static result< update >	make (const partition &part)
	Begins an OTA update, erasing the entire partition.
static result< update >	make (const partition &part, size_t image_size)
	Begins an OTA update, erasing space for the specified image size.
static result< update >	make (const partition &part, sequential_erase_tag)
	Begins an OTA update with sequential (incremental) flash erase.
static result< update >	try_resume (const partition &part, size_t offset)
	Resumes an interrupted OTA update, erasing all remaining flash.
static result< update >	try_resume (const partition &part, size_t offset, size_t erase_size)
	Resumes an interrupted OTA update, erasing the specified amount of flash.
static result< update >	try_resume (const partition &part, size_t offset, sequential_erase_tag)
	Resumes an interrupted OTA update with sequential (incremental) flash erase.

Detailed Description

RAII OTA update session.

Manages an OTA update operation, including writing firmware data and finalizing the update. The destructor aborts the update if end() has not been called. This type is non-copyable and move-only. A moved-from object must not be used: any operation other than destruction or assignment is undefined behavior.

auto part = idfxx::ota::next_update_partition();
idfxx::ota::update upd(part);
upd.write(data.data(), data.size());
upd.end();
idfxx::ota::set_boot_partition(part);

Definition at line 150 of file ota.hpp.

Constructor & Destructor Documentation

update() [1/5]

idfxx::ota::update::update ( const partition &  part )

explicit

Begins an OTA update, erasing the entire partition.

Parameters

part	Target partition for the update.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

update() [2/5]

idfxx::ota::update::update ( const partition &  part, size_t  image_size  )

explicit

Begins an OTA update, erasing space for the specified image size.

Parameters

part	Target partition for the update.
image_size	Expected image size in bytes.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

update() [3/5]

idfxx::ota::update::update ( const partition &  part, sequential_erase_tag    )

explicit

Begins an OTA update with sequential (incremental) flash erase.

Flash is erased incrementally as data is written, rather than all at once.

Parameters

part	Target partition for the update.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

~update()

idfxx::ota::update::~update

(

)

update() [4/5]

idfxx::ota::update::update ( const update &  )

delete

update() [5/5]

idfxx::ota::update::update ( update &&  other )

noexcept

Move constructor.

Transfers session ownership.

Member Function Documentation

abort()

void idfxx::ota::update::abort

(

)

Aborts the OTA update and frees associated resources.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

end()

void idfxx::ota::update::end

(

)

Finalizes the OTA update and validates the written image.

After calling end(), the handle is invalidated and the session is complete.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

make() [1/3]

static result< update > idfxx::ota::update::make ( const partition &  part )

static

Begins an OTA update, erasing the entire partition.

Parameters

part	Target partition for the update.

Returns

The update session, or an error.

Return values

ota::errc::partition_conflict	if the partition is the currently running partition.
ota::errc::rollback_invalid_state	if the running app has not confirmed state.

make() [2/3]

static result< update > idfxx::ota::update::make ( const partition &  part, sequential_erase_tag    )

static

Begins an OTA update with sequential (incremental) flash erase.

Flash is erased incrementally as data is written, rather than all at once.

Parameters

part	Target partition for the update.

Returns

The update session, or an error.

Return values

ota::errc::partition_conflict	if the partition is the currently running partition.
ota::errc::rollback_invalid_state	if the running app has not confirmed state.

make() [3/3]

static result< update > idfxx::ota::update::make ( const partition &  part, size_t  image_size  )

static

Begins an OTA update, erasing space for the specified image size.

Parameters

part	Target partition for the update.
image_size	Expected image size in bytes.

Returns

The update session, or an error.

Return values

idfxx::errc::invalid_arg	if image_size is a reserved sentinel value.
ota::errc::partition_conflict	if the partition is the currently running partition.
ota::errc::rollback_invalid_state	if the running app has not confirmed state.

operator=() [1/2]

update & idfxx::ota::update::operator= ( const update &  )

delete

operator=() [2/2]

update & idfxx::ota::update::operator= ( update &&  other )

noexcept

Move assignment.

Aborts any active session before transferring.

resume() [1/3]

static update idfxx::ota::update::resume ( const partition &  part, size_t  offset  )

static

Resumes an interrupted OTA update, erasing all remaining flash.

Continues writing to the partition from the specified offset without re-erasing already-written data.

Parameters

part	Target partition for the update.
offset	Byte offset from which to resume writing.

Returns

The resumed update session.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

resume() [2/3]

static update idfxx::ota::update::resume ( const partition &  part, size_t  offset, sequential_erase_tag    )

static

Resumes an interrupted OTA update with sequential (incremental) flash erase.

Continues writing to the partition from the specified offset without re-erasing already-written data. Flash is erased incrementally as data is written.

Parameters

part	Target partition for the update.
offset	Byte offset from which to resume writing.

Returns

The resumed update session.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

resume() [3/3]

static update idfxx::ota::update::resume ( const partition &  part, size_t  offset, size_t  erase_size  )

static

Resumes an interrupted OTA update, erasing the specified amount of flash.

Continues writing to the partition from the specified offset without re-erasing already-written data.

Parameters

part	Target partition for the update.
offset	Byte offset from which to resume writing.
erase_size	Amount of flash to erase ahead in bytes.

Returns

The resumed update session.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

set_final_partition()

void idfxx::ota::update::set_final_partition	(	const partition &	final_part,
		bool	copy = true
	)

Redirects the validated image to a different final partition.

Must be called before the first write(). If copy is true, end() will automatically copy the staging partition to the final partition.

Parameters

final_part	The final destination partition.
copy	If true, end() copies staging to final automatically.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

try_abort()

result< void > idfxx::ota::update::try_abort

(

)

Aborts the OTA update and frees associated resources.

Returns

Success, or an error.

try_end()

result< void > idfxx::ota::update::try_end

(

)

Finalizes the OTA update and validates the written image.

After calling try_end(), the handle is invalidated and the session is complete.

Returns

Success, or an error.

Return values

ota::errc::validate_failed

if the image is invalid.

try_resume() [1/3]

static result< update > idfxx::ota::update::try_resume ( const partition &  part, size_t  offset  )

static

Resumes an interrupted OTA update, erasing all remaining flash.

Continues writing to the partition from the specified offset without re-erasing already-written data.

Parameters

part	Target partition for the update.
offset	Byte offset from which to resume writing.

Returns

The resumed update session, or an error.

Return values

ota::errc::partition_conflict

if the partition is the currently running partition.

try_resume() [2/3]

static result< update > idfxx::ota::update::try_resume ( const partition &  part, size_t  offset, sequential_erase_tag    )

static

Resumes an interrupted OTA update with sequential (incremental) flash erase.

Continues writing to the partition from the specified offset without re-erasing already-written data. Flash is erased incrementally as data is written.

Parameters

part	Target partition for the update.
offset	Byte offset from which to resume writing.

Returns

The resumed update session, or an error.

Return values

ota::errc::partition_conflict

if the partition is the currently running partition.

try_resume() [3/3]

static result< update > idfxx::ota::update::try_resume ( const partition &  part, size_t  offset, size_t  erase_size  )

static

Resumes an interrupted OTA update, erasing the specified amount of flash.

Continues writing to the partition from the specified offset without re-erasing already-written data.

Parameters

part	Target partition for the update.
offset	Byte offset from which to resume writing.
erase_size	Amount of flash to erase ahead in bytes.

Returns

The resumed update session, or an error.

Return values

idfxx::errc::invalid_arg	if erase_size is a reserved sentinel value.
ota::errc::partition_conflict	if the partition is the currently running partition.

try_set_final_partition()

result< void > idfxx::ota::update::try_set_final_partition	(	const partition &	final_part,
		bool	copy = true
	)

Redirects the validated image to a different final partition.

Must be called before the first write(). If copy is true, end() will automatically copy the staging partition to the final partition.

Parameters

final_part	The final destination partition.
copy	If true, end() copies staging to final automatically.

Returns

Success, or an error.

try_write() [1/2]

result< void > idfxx::ota::update::try_write	(	const void *	data,
		size_t	size
	)

Writes data sequentially to the OTA partition.

Parameters

data	Pointer to the data buffer.
size	Number of bytes to write.

Returns

Success, or an error.

Return values

ota::errc::validate_failed

if the first byte contains an invalid image magic byte.

try_write() [2/2]

result< void > idfxx::ota::update::try_write

(

std::span< const uint8_t >

data

)

Writes data sequentially to the OTA partition.

Parameters

data	Data to write.

Returns

Success, or an error.

Return values

ota::errc::validate_failed

if the first byte contains an invalid image magic byte.

try_write_with_offset() [1/2]

result< void > idfxx::ota::update::try_write_with_offset	(	uint32_t	offset,
		const void *	data,
		size_t	size
	)

Writes data at a specific offset in the OTA partition.

Supports non-contiguous writes. If flash encryption is enabled, data should be 16-byte aligned.

Parameters

offset	Offset within the partition.
data	Pointer to the data buffer.
size	Number of bytes to write.

Returns

Success, or an error.

try_write_with_offset() [2/2]

result< void > idfxx::ota::update::try_write_with_offset	(	uint32_t	offset,
		std::span< const uint8_t >	data
	)

Writes data at a specific offset in the OTA partition.

Supports non-contiguous writes. If flash encryption is enabled, data should be 16-byte aligned.

Parameters

offset	Offset within the partition.
data	Data to write.

Returns

Success, or an error.

write() [1/2]

void idfxx::ota::update::write	(	const void *	data,
		size_t	size
	)

Writes data sequentially to the OTA partition.

Parameters

data	Pointer to the data buffer.
size	Number of bytes to write.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

write() [2/2]

void idfxx::ota::update::write

(

std::span< const uint8_t >

data

)

Writes data sequentially to the OTA partition.

Parameters

data	Data to write.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

write_with_offset() [1/2]

void idfxx::ota::update::write_with_offset	(	uint32_t	offset,
		const void *	data,
		size_t	size
	)

Writes data at a specific offset in the OTA partition.

Supports non-contiguous writes. If flash encryption is enabled, data should be 16-byte aligned.

Parameters

offset	Offset within the partition.
data	Pointer to the data buffer.
size	Number of bytes to write.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

write_with_offset() [2/2]

void idfxx::ota::update::write_with_offset	(	uint32_t	offset,
		std::span< const uint8_t >	data
	)

Writes data at a specific offset in the OTA partition.

Supports non-contiguous writes. If flash encryption is enabled, data should be 16-byte aligned.

Parameters

offset	Offset within the partition.
data	Data to write.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

---

The documentation for this class was generated from the following file:

• idfxx_ota/include/idfxx/ota.hpp