Classes
class	app_description
	Application description from a firmware image. More...

class	error_category
	Error category for OTA errors. More...

struct	sequential_erase_tag
	Tag type for sequential (incremental) flash erase mode. More...

class	update
	RAII OTA update session. More...

Enumerations
enum class	errc : esp_err_t { partition_conflict = 0x1501 , select_info_invalid = 0x1502 , validate_failed = 0x1503 , small_sec_ver = 0x1504 , rollback_failed = 0x1505 , rollback_invalid_state = 0x1506 }
	Error codes for OTA operations. More...

enum class	image_state : uint32_t { new_image = 0x0U , pending_verify = 0x1U , valid = 0x2U , invalid = 0x3U , aborted = 0x4U , undefined = 0xFFFFFFFFU }
	OTA image state. More...

Functions
void	set_boot_partition (const partition &part)
	Sets the boot partition for the next reboot.

partition	boot_partition ()
	Returns the currently configured boot partition.

partition	running_partition ()
	Returns the partition of the currently running application.

partition	next_update_partition (const partition *start_from=nullptr)
	Returns the next OTA app partition to write an update to.

result< void >	try_set_boot_partition (const partition &part)
	Sets the boot partition for the next reboot.

result< partition >	try_boot_partition ()
	Returns the currently configured boot partition.

result< partition >	try_running_partition ()
	Returns the partition of the currently running application.

result< partition >	try_next_update_partition (const partition *start_from=nullptr)
	Returns the next OTA app partition to write an update to.

app_description	partition_description (const partition &part)
	Returns the application description from a partition.

result< app_description >	try_partition_description (const partition &part)
	Returns the application description from a partition.

void	mark_valid ()
	Marks the running app as valid, cancelling any pending rollback.

void	mark_invalid_and_rollback ()
	Marks the running app as invalid and triggers a rollback with reboot.

image_state	partition_state (const partition &part)
	Returns the OTA image state for a partition.

result< void >	try_mark_valid ()
	Marks the running app as valid, cancelling any pending rollback.

result< void >	try_mark_invalid_and_rollback ()
	Marks the running app as invalid and triggers a rollback with reboot.

result< image_state >	try_partition_state (const partition &part)
	Returns the OTA image state for a partition.

bool	rollback_possible ()
	Checks whether a rollback to a previous firmware is possible.

partition	last_invalid_partition ()
	Returns the last partition with invalid state.

result< partition >	try_last_invalid_partition ()
	Returns the last partition with invalid state.

void	erase_last_boot_app_partition ()
	Erases the previous boot application partition and its OTA data.

void	invalidate_inactive_ota_data_slot ()
	Invalidates the OTA data slot for the last boot application partition.

result< void >	try_erase_last_boot_app_partition ()
	Erases the previous boot application partition and its OTA data.

result< void >	try_invalidate_inactive_ota_data_slot ()
	Invalidates the OTA data slot for the last boot application partition.

size_t	app_partition_count ()
	Returns the number of OTA app partitions in the partition table.

const error_category &	ota_category () noexcept
	Returns a reference to the OTA error category singleton.

std::error_code	make_error_code (errc e) noexcept
	Creates an error code from an idfxx::ota::errc value.

std::unexpected< std::error_code >	ota_error (esp_err_t e)
	Creates an unexpected error from an ESP-IDF error code, mapping to OTA error codes where possible.

Variables
constexpr sequential_erase_tag	sequential_erase {}
	Tag value for sequential (incremental) flash erase mode.

Enumeration Type Documentation

◆ errc

enum class idfxx::ota::errc : esp_err_t

strong

Error codes for OTA operations.

Enumerator
partition_conflict	Cannot update the currently running partition.
select_info_invalid	OTA data partition contains invalid content.
validate_failed	OTA app image is invalid.
small_sec_ver	Firmware secure version is less than the running firmware.
rollback_failed	No valid firmware in passive partition for rollback.
rollback_invalid_state	Running app is still pending verification; confirm before updating.

Definition at line 52 of file ota.hpp.

◆ image_state

enum class idfxx::ota::image_state : uint32_t

strong

OTA image state.

Describes the lifecycle state of a firmware image in the OTA data partition.

Enumerator
new_image	Newly written image, not yet booted.
pending_verify	First boot completed, awaiting confirmation.
valid	Confirmed as workable.
invalid	Confirmed as non-workable.
aborted	Failed to confirm workability during first boot.
undefined	No OTA state recorded for this partition.

Definition at line 80 of file ota.hpp.

Function Documentation

◆ app_partition_count()

size_t idfxx::ota::app_partition_count ( )

Returns the number of OTA app partitions in the partition table.

Returns: The number of OTA app partitions.

◆ boot_partition()

partition idfxx::ota::boot_partition ( )

Returns the currently configured boot partition.

Returns: The boot partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::not_found if not available.

◆ erase_last_boot_app_partition()

void idfxx::ota::erase_last_boot_app_partition ( )

Erases the previous boot application partition and its OTA data.

Call after the current app has been marked valid.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ invalidate_inactive_ota_data_slot()

void idfxx::ota::invalidate_inactive_ota_data_slot ( )

Invalidates the OTA data slot for the last boot application partition.

Erases the OTA data slot without erasing the partition contents.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ last_invalid_partition()

partition idfxx::ota::last_invalid_partition ( )

Returns the last partition with invalid state.

Returns the last partition with state image_state::invalid or image_state::aborted.

Returns: The last invalid partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::not_found if no invalid partition exists.

◆ make_error_code()

std::error_code idfxx::ota::make_error_code ( errc e )

inlinenoexcept

Creates an error code from an idfxx::ota::errc value.

Definition at line 791 of file ota.hpp.

References ota_category().

◆ mark_invalid_and_rollback()

void idfxx::ota::mark_invalid_and_rollback ( )

Marks the running app as invalid and triggers a rollback with reboot.

On success this function reboots the device and does not return.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ mark_valid()

void idfxx::ota::mark_valid ( )

Marks the running app as valid, cancelling any pending rollback.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ next_update_partition()

partition idfxx::ota::next_update_partition ( const partition * start_from = nullptr )

Returns the next OTA app partition to write an update to.

Finds the next partition round-robin, starting from the current running partition.

Parameters

start_from If not null, use this partition as the starting point instead of the running partition.

Returns: The next update partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::not_found if no eligible partition exists.

◆ ota_category()

const error_category & idfxx::ota::ota_category ( )

noexcept

Returns a reference to the OTA error category singleton.

Returns: Reference to the singleton ota::error_category instance.

Referenced by make_error_code().

◆ ota_error()

std::unexpected< std::error_code > idfxx::ota::ota_error ( esp_err_t e )

Creates an unexpected error from an ESP-IDF error code, mapping to OTA error codes where possible.

Converts the ESP-IDF error code to an OTA-specific error code if a mapping exists, otherwise falls back to the default IDFXX error category.

Parameters

e	The ESP-IDF error code.

Returns: An unexpected value suitable for returning from result-returning functions.

◆ partition_description()

app_description idfxx::ota::partition_description ( const partition & part )

Returns the application description from a partition.

Parameters

part	An application partition to read from.

Returns: The app description.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ partition_state()

image_state idfxx::ota::partition_state ( const partition & part )

Returns the OTA image state for a partition.

Parameters

part	The partition to query.

Returns: The image state.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ rollback_possible()

bool idfxx::ota::rollback_possible ( )

Checks whether a rollback to a previous firmware is possible.

Returns: true if at least one valid app exists (besides the running one).

◆ running_partition()

partition idfxx::ota::running_partition ( )

Returns the partition of the currently running application.

Returns: The running partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::not_found if not available.

◆ set_boot_partition()

void idfxx::ota::set_boot_partition ( const partition & part )

Sets the boot partition for the next reboot.

Parameters

part	Partition containing the app image to boot.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ try_boot_partition()

result< partition > idfxx::ota::try_boot_partition ( )

Returns the currently configured boot partition.

Returns: The boot partition, or an error.

Return values

idfxx::errc::not_found if the partition table is invalid or a flash read failed.

◆ try_erase_last_boot_app_partition()

result< void > idfxx::ota::try_erase_last_boot_app_partition ( )

Erases the previous boot application partition and its OTA data.

Call after the current app has been marked valid.

Returns: Success, or an error.

◆ try_invalidate_inactive_ota_data_slot()

result< void > idfxx::ota::try_invalidate_inactive_ota_data_slot ( )

Invalidates the OTA data slot for the last boot application partition.

Erases the OTA data slot without erasing the partition contents.

Returns: Success, or an error.

◆ try_last_invalid_partition()

result< partition > idfxx::ota::try_last_invalid_partition ( )

Returns the last partition with invalid state.

Returns the last partition with state image_state::invalid or image_state::aborted.

Returns: The last invalid partition, or an error.

Return values

idfxx::errc::not_found if no invalid partition exists.

◆ try_mark_invalid_and_rollback()

result< void > idfxx::ota::try_mark_invalid_and_rollback ( )

Marks the running app as invalid and triggers a rollback with reboot.

On success this function reboots the device and does not return.

Returns: An error (only returns on failure).

Return values

ota::errc::rollback_failed if no valid firmware exists for rollback.

◆ try_mark_valid()

result< void > idfxx::ota::try_mark_valid ( )

Marks the running app as valid, cancelling any pending rollback.

Returns: Success, or an error.

◆ try_next_update_partition()

result< partition > idfxx::ota::try_next_update_partition ( const partition * start_from = nullptr )

Returns the next OTA app partition to write an update to.

Finds the next partition round-robin, starting from the current running partition.

Parameters

start_from If not null, use this partition as the starting point instead of the running partition.

Returns: The next update partition, or an error.

Return values

idfxx::errc::not_found if no eligible partition exists.

◆ try_partition_description()

result< app_description > idfxx::ota::try_partition_description ( const partition & part )

Returns the application description from a partition.

Parameters

part	An application partition to read from.

Returns: The app description, or an error.

Return values

idfxx::errc::not_found if the partition does not contain a valid app descriptor.

◆ try_partition_state()

result< image_state > idfxx::ota::try_partition_state ( const partition & part )

Returns the OTA image state for a partition.

Parameters

part	The partition to query.

Returns: The image state, or an error.

◆ try_running_partition()

result< partition > idfxx::ota::try_running_partition ( )

Returns the partition of the currently running application.

Returns: The running partition, or an error.

Return values

idfxx::errc::not_found if no partition is found or a flash read failed.

◆ try_set_boot_partition()

result< void > idfxx::ota::try_set_boot_partition ( const partition & part )

Sets the boot partition for the next reboot.

Parameters

part	Partition containing the app image to boot.

Returns: Success, or an error.

Return values

ota::errc::validate_failed if the partition contains an invalid app image.

Variable Documentation

◆ sequential_erase

constexpr sequential_erase_tag idfxx::ota::sequential_erase {}

inlineconstexpr

Tag value for sequential (incremental) flash erase mode.

See also: sequential_erase_tag

Definition at line 47 of file ota.hpp.

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ errc

◆ image_state

Function Documentation

◆ app_partition_count()

◆ boot_partition()

◆ erase_last_boot_app_partition()

◆ invalidate_inactive_ota_data_slot()

◆ last_invalid_partition()

◆ make_error_code()

◆ mark_invalid_and_rollback()

◆ mark_valid()

◆ next_update_partition()

◆ ota_category()

◆ ota_error()

◆ partition_description()

◆ partition_state()

◆ rollback_possible()

◆ running_partition()

◆ set_boot_partition()

◆ try_boot_partition()

◆ try_erase_last_boot_app_partition()

◆ try_invalidate_inactive_ota_data_slot()

◆ try_last_invalid_partition()

◆ try_mark_invalid_and_rollback()

◆ try_mark_valid()

◆ try_next_update_partition()

◆ try_partition_description()

◆ try_partition_state()

◆ try_running_partition()

◆ try_set_boot_partition()

Variable Documentation

◆ sequential_erase