Add Gitea OTA firmware update, dual-slot partition layout, and Gitea Actions release workflow

main/ota_manager.h

@@ -0,0 +1,95 @@
+/*
+ * MTG RFID Companion - OTA Firmware Update Manager
+ *
+ * Checks Gitea release API, downloads firmware updates, and flashes them
+ * to the passive OTA slot with rollback protection.
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    OTA_STATUS_IDLE,
+    OTA_STATUS_CHECKING,
+    OTA_STATUS_UPDATE_AVAILABLE,
+    OTA_STATUS_UP_TO_DATE,
+    OTA_STATUS_DOWNLOADING,
+    OTA_STATUS_SUCCESS_REBOOTING,
+    OTA_STATUS_FAILED
+} ota_status_t;
+
+typedef struct {
+    char tag_name[32];         /* e.g. "v1.2.0" */
+    char release_title[64];    /* e.g. "Release 1.2.0" */
+    char download_url[256];    /* URL to mtg-rfid-companion.bin */
+    size_t binary_size;        /* in bytes, or 0 if unknown */
+    bool is_newer;
+} ota_release_info_t;
+
+/**
+ * @brief Initialize OTA manager, validates running partition, and cancels rollback.
+ */
+esp_err_t ota_manager_init(void);
+
+/**
+ * @brief Current firmware version string (e.g. "1.0.0").
+ */
+const char *ota_manager_get_current_version(void);
+
+/**
+ * @brief Get current OTA state.
+ */
+ota_status_t ota_manager_get_status(void);
+
+/**
+ * @brief Get human-readable status message or error details.
+ */
+const char *ota_manager_get_message(void);
+
+/**
+ * @brief Get percentage of download progress (0-100).
+ */
+int ota_manager_get_progress(void);
+
+/**
+ * @brief Get bytes downloaded so far and total bytes.
+ */
+void ota_manager_get_bytes(size_t *read_bytes, size_t *total_bytes);
+
+/**
+ * @brief Get the latest discovered release metadata.
+ */
+const ota_release_info_t *ota_manager_get_release_info(void);
+
+/**
+ * @brief Kick off an asynchronous release check against the configured Gitea instance.
+ * @return ESP_OK if started, ESP_ERR_INVALID_STATE if already in progress.
+ */
+esp_err_t ota_manager_check_update_async(void);
+
+/**
+ * @brief Kick off asynchronous firmware download and flash.
+ * @return ESP_OK if started.
+ */
+esp_err_t ota_manager_start_update_async(void);
+
+/**
+ * @brief Abort any running OTA operation and reset status to IDLE.
+ */
+void ota_manager_cancel(void);
+
+/**
+ * @brief Clear state back to IDLE.
+ */
+void ota_manager_reset(void);
+
+#ifdef __cplusplus
+}
+#endif