ota.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
#include <idfxx/partition>
 
#include <cstddef>
#include <cstdint>
#include <esp_app_desc.h>
#include <span>
#include <string_view>
 
typedef uint32_t esp_ota_handle_t;
 
namespace idfxx::ota {
 
struct sequential_erase_tag {};
 
inline constexpr sequential_erase_tag sequential_erase{};
 
enum class errc : esp_err_t {
    // clang-format off
    partition_conflict     = 0x1501, 
    select_info_invalid    = 0x1502, 
    validate_failed        = 0x1503, 
    small_sec_ver          = 0x1504, 
    rollback_failed        = 0x1505, 
    rollback_invalid_state = 0x1506, 
    // clang-format on
};
 
class error_category : public std::error_category {
public:
    [[nodiscard]] const char* name() const noexcept override final;
 
    [[nodiscard]] std::string message(int ec) const override final;
};
 
enum class image_state : uint32_t {
    // clang-format off
    new_image      = 0x0U,        
    pending_verify = 0x1U,        
    valid          = 0x2U,        
    invalid        = 0x3U,        
    aborted        = 0x4U,        
    undefined      = 0xFFFFFFFFU, 
    // clang-format on
};
 
class app_description {
public:
    [[nodiscard]] std::string_view version() const;
 
    [[nodiscard]] std::string_view project_name() const;
 
    [[nodiscard]] std::string_view time() const;
 
    [[nodiscard]] std::string_view date() const;
 
    [[nodiscard]] std::string_view idf_ver() const;
 
    [[nodiscard]] uint32_t secure_version() const;
 
    [[nodiscard]] std::span<const uint8_t, 32> app_elf_sha256() const;
 
    [[nodiscard]] const esp_app_desc_t& idf_handle() const { return _desc; }
 
private:
    friend result<app_description> try_partition_description(const partition&);
 
    explicit app_description(const esp_app_desc_t& desc);
 
    esp_app_desc_t _desc;
};
 
class update {
public:
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit update(const partition& part);
 
    [[nodiscard]] explicit update(const partition& part, size_t image_size);
 
    [[nodiscard]] explicit update(const partition& part, sequential_erase_tag);
 
    [[nodiscard]] static update resume(const partition& part, size_t offset);
 
    [[nodiscard]] static update resume(const partition& part, size_t offset, size_t erase_size);
 
    [[nodiscard]] static update resume(const partition& part, size_t offset, sequential_erase_tag);
#endif
 
    [[nodiscard]] static result<update> make(const partition& part);
 
    [[nodiscard]] static result<update> make(const partition& part, size_t image_size);
 
    [[nodiscard]] static result<update> make(const partition& part, sequential_erase_tag);
 
    [[nodiscard]] static result<update> try_resume(const partition& part, size_t offset);
 
    [[nodiscard]] static result<update> try_resume(const partition& part, size_t offset, size_t erase_size);
 
    [[nodiscard]] static result<update> try_resume(const partition& part, size_t offset, sequential_erase_tag);
 
    ~update();
 
    update(const update&) = delete;
    update& operator=(const update&) = delete;
 
    update(update&& other) noexcept;
 
    update& operator=(update&& other) noexcept;
 
    // =========================================================================
    // Final partition
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_final_partition(const partition& final_part, bool copy = true);
#endif
 
    [[nodiscard]] result<void> try_set_final_partition(const partition& final_part, bool copy = true);
 
    // =========================================================================
    // Write
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write(const void* data, size_t size);
 
    void write(std::span<const uint8_t> data);
 
    void write_with_offset(uint32_t offset, const void* data, size_t size);
 
    void write_with_offset(uint32_t offset, std::span<const uint8_t> data);
#endif
 
    [[nodiscard]] result<void> try_write(const void* data, size_t size);
 
    [[nodiscard]] result<void> try_write(std::span<const uint8_t> data);
 
    [[nodiscard]] result<void> try_write_with_offset(uint32_t offset, const void* data, size_t size);
 
    [[nodiscard]] result<void> try_write_with_offset(uint32_t offset, std::span<const uint8_t> data);
 
    // =========================================================================
    // End / Abort
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void end();
 
    void abort();
#endif
 
    [[nodiscard]] result<void> try_end();
 
    result<void> try_abort();
 
private:
    explicit update(esp_ota_handle_t handle);
 
    esp_ota_handle_t _handle = 0;
};
 
// =============================================================================
// Free functions - Boot partition management
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_boot_partition(const partition& part);
 
[[nodiscard]] partition boot_partition();
 
[[nodiscard]] partition running_partition();
 
[[nodiscard]] partition next_update_partition(const partition* start_from = nullptr);
#endif
 
[[nodiscard]] result<void> try_set_boot_partition(const partition& part);
 
[[nodiscard]] result<partition> try_boot_partition();
 
[[nodiscard]] result<partition> try_running_partition();
 
[[nodiscard]] result<partition> try_next_update_partition(const partition* start_from = nullptr);
 
// =============================================================================
// Free functions - App description
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] app_description partition_description(const partition& part);
#endif
 
[[nodiscard]] result<app_description> try_partition_description(const partition& part);
 
// =============================================================================
// Free functions - State management
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void mark_valid();
 
[[noreturn]] void mark_invalid_and_rollback();
 
[[nodiscard]] image_state partition_state(const partition& part);
#endif
 
[[nodiscard]] result<void> try_mark_valid();
 
[[nodiscard]] result<void> try_mark_invalid_and_rollback();
 
[[nodiscard]] result<image_state> try_partition_state(const partition& part);
 
// =============================================================================
// Free functions - Rollback checking
// =============================================================================
 
[[nodiscard]] bool rollback_possible();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] partition last_invalid_partition();
#endif
 
[[nodiscard]] result<partition> try_last_invalid_partition();
 
// =============================================================================
// Free functions - Partition maintenance
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void erase_last_boot_app_partition();
 
void invalidate_inactive_ota_data_slot();
#endif
 
[[nodiscard]] result<void> try_erase_last_boot_app_partition();
 
[[nodiscard]] result<void> try_invalidate_inactive_ota_data_slot();
 
// =============================================================================
// Free functions - Partition count
// =============================================================================
 
[[nodiscard]] size_t app_partition_count();
 
[[nodiscard]] const error_category& ota_category() noexcept;
 
[[nodiscard]] inline std::error_code make_error_code(errc e) noexcept {
    return {std::to_underlying(e), ota_category()};
}
 
[[nodiscard]] std::unexpected<std::error_code> ota_error(esp_err_t e);
 
} // namespace idfxx::ota
 
namespace std {
template<>
struct is_error_code_enum<idfxx::ota::errc> : true_type {};
} // namespace std