ota_backend.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/component.h"
#include "esphome/core/defines.h"
#include "esphome/core/helpers.h"
 
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <type_traits>
 
#ifdef USE_OTA_STATE_LISTENER
#include <vector>
#endif
 
namespace esphome::ota {
 
enum OTAResponseTypes {
  OTA_RESPONSE_OK = 0x00,
  OTA_RESPONSE_REQUEST_AUTH = 0x01,
  OTA_RESPONSE_REQUEST_SHA256_AUTH = 0x02,
 
  OTA_RESPONSE_HEADER_OK = 0x40,
  OTA_RESPONSE_AUTH_OK = 0x41,
  OTA_RESPONSE_UPDATE_PREPARE_OK = 0x42,
  OTA_RESPONSE_BIN_MD5_OK = 0x43,
  OTA_RESPONSE_RECEIVE_OK = 0x44,
  OTA_RESPONSE_UPDATE_END_OK = 0x45,
  OTA_RESPONSE_SUPPORTS_COMPRESSION = 0x46,
  OTA_RESPONSE_CHUNK_OK = 0x47,
  OTA_RESPONSE_FEATURE_FLAGS = 0x48,
 
  OTA_RESPONSE_ERROR_MAGIC = 0x80,
  OTA_RESPONSE_ERROR_UPDATE_PREPARE = 0x81,
  OTA_RESPONSE_ERROR_AUTH_INVALID = 0x82,
  OTA_RESPONSE_ERROR_WRITING_FLASH = 0x83,
  OTA_RESPONSE_ERROR_UPDATE_END = 0x84,
  OTA_RESPONSE_ERROR_INVALID_BOOTSTRAPPING = 0x85,
  OTA_RESPONSE_ERROR_WRONG_CURRENT_FLASH_CONFIG = 0x86,
  OTA_RESPONSE_ERROR_WRONG_NEW_FLASH_CONFIG = 0x87,
  OTA_RESPONSE_ERROR_ESP8266_NOT_ENOUGH_SPACE = 0x88,
  OTA_RESPONSE_ERROR_ESP32_NOT_ENOUGH_SPACE = 0x89,
  OTA_RESPONSE_ERROR_NO_UPDATE_PARTITION = 0x8A,
  OTA_RESPONSE_ERROR_MD5_MISMATCH = 0x8B,
  OTA_RESPONSE_ERROR_RP2040_NOT_ENOUGH_SPACE = 0x8C,
  OTA_RESPONSE_ERROR_SIGNATURE_INVALID = 0x8D,
  OTA_RESPONSE_ERROR_UNSUPPORTED_OTA_TYPE = 0x8E,
  OTA_RESPONSE_ERROR_PARTITION_TABLE_VERIFY = 0x8F,
  OTA_RESPONSE_ERROR_PARTITION_TABLE_UPDATE = 0x90,
  OTA_RESPONSE_ERROR_BOOTLOADER_VERIFY = 0x91,
  OTA_RESPONSE_ERROR_BOOTLOADER_UPDATE = 0x92,
  OTA_RESPONSE_ERROR_VERSION_DOWNGRADE = 0x93,
  OTA_RESPONSE_ERROR_ENCRYPTION_REQUIRED = 0x94,
  OTA_RESPONSE_ERROR_UPDATE_BUSY = 0x95,
  OTA_RESPONSE_ERROR_UNKNOWN = 0xFF,
};
 
bool version_is_older(const char *candidate, const char *reference);
 
// 64 KiB flash block; the erase granularity the ESP-IDF backend erases ahead with.
static constexpr size_t OTA_BLOCK_ERASE_SIZE = 64 * 1024;
 
constexpr size_t next_erase_end(size_t write_end, size_t partition_size) {
  const size_t rounded = (write_end + OTA_BLOCK_ERASE_SIZE - 1) & ~(OTA_BLOCK_ERASE_SIZE - 1);
  return rounded < partition_size ? rounded : partition_size;
}
 
enum OTAState {
  OTA_COMPLETED = 0,
  OTA_STARTED,
  OTA_IN_PROGRESS,
  OTA_ABORT,
  OTA_ERROR,
};
 
enum OTAType : uint8_t {
  OTA_TYPE_UPDATE_APP = 0x00,
  OTA_TYPE_UPDATE_PARTITION_TABLE = 0x01,
  OTA_TYPE_UPDATE_BOOTLOADER = 0x02,
};
 
class UpdateLock {
 public:
  UpdateLock() = default;
  ~UpdateLock() { this->release(); }
  UpdateLock(const UpdateLock &) = delete;
  UpdateLock &operator=(const UpdateLock &) = delete;
 
  bool try_acquire();
  void release();
  bool is_held() const { return this->held_; }
  void hold_until_reboot() { this->held_ = false; }
 
 protected:
  static void force_release();
 
  bool held_{false};
};
 
// The OTA backend method surface. Exactly one backend exists per build,
// selected in ota_backend_factory.h where this concept is asserted on
// make_ota_backend()'s return type. Semantics beyond the signatures:
// - begin: prepare for an image of the given size; 0 means the size is unknown
//   (web_server upload) and the backend allows the largest image it can take.
//   ota_type defaults to an app update, so both call forms must be accepted.
// - set_update_md5: expected digest of the incoming image, hex string.
// - write: consume the next chunk; end: finalize and mark bootable.
// - abort: safe to call in any state, including after end().
// - supports_compression: constexpr, whether a gzip image is stored as is and
//   inflated at reboot.
template<typename T>
concept OTABackendContract = requires(T backend, size_t image_size, uint8_t *data, size_t len, const char *md5) {
  { backend.begin(image_size, OTA_TYPE_UPDATE_APP) } -> std::same_as<OTAResponseTypes>;
  { backend.begin(image_size) } -> std::same_as<OTAResponseTypes>;
  backend.set_update_md5(md5);
  { backend.write(data, len) } -> std::same_as<OTAResponseTypes>;
  { backend.end() } -> std::same_as<OTAResponseTypes>;
  backend.abort();
  { T::supports_compression() } -> std::same_as<bool>;
  // The value must be a constant expression
  typename std::bool_constant<T::supports_compression()>;
};
 
class OTAStateListener {
 public:
  virtual ~OTAStateListener() = default;
  virtual void on_ota_state(OTAState state, float progress, uint8_t error) = 0;
};
 
class OTAComponent : public Component {
#ifdef USE_OTA_STATE_LISTENER
 public:
  void add_state_listener(OTAStateListener *listener) { this->state_listeners_.push_back(listener); }
 
 protected:
  void notify_state_(OTAState state, float progress, uint8_t error);
 
  void notify_state_deferred_(OTAState state, float progress, uint8_t error);
 
  std::vector<OTAStateListener *> state_listeners_;
#endif
};
 
#ifdef USE_OTA_STATE_LISTENER
 
class OTAGlobalStateListener {
 public:
  virtual ~OTAGlobalStateListener() = default;
  virtual void on_ota_global_state(OTAState state, float progress, uint8_t error, OTAComponent *component) = 0;
};
 
class OTAGlobalCallback {
 public:
  void add_global_state_listener(OTAGlobalStateListener *listener) { this->global_listeners_.push_back(listener); }
 
  void notify_ota_state(OTAState state, float progress, uint8_t error, OTAComponent *component) {
    for (auto *listener : this->global_listeners_) {
      listener->on_ota_global_state(state, progress, error, component);
    }
  }
 
 protected:
  std::vector<OTAGlobalStateListener *> global_listeners_;
};
 
OTAGlobalCallback *get_global_ota_callback();
 
// OTA implementations should use:
// - notify_state_() when already in main loop (e.g., esphome OTA)
// - notify_state_deferred_() when in separate task (e.g., web_server OTA)
// This ensures proper listener execution in all contexts.
#endif
}  // namespace esphome::ota