/**
 * @file    ota_agent.h
 * @brief   OTA Upgrade Agent (runs in App firmware)
 *
 * Responsibilities:
 *   1. Connect to MQTT broker via 4G module
 *   2. Subscribe to OTA command topic
 *   3. Download encrypted firmware from cloud
 *   4. Store to SPI Flash buffer
 *   5. Verify download integrity
 *   6. Set upgrade flag and reset to Bootloader
 */

#ifndef _OTA_AGENT_H_
#define _OTA_AGENT_H_

#include <stdint.h>
#include <stdbool.h>

/* OTA status codes reported to cloud */
#define OTA_STATUS_IDLE             0
#define OTA_STATUS_CHECKING         1
#define OTA_STATUS_DOWNLOADING      2
#define OTA_STATUS_DOWNLOADED       3
#define OTA_STATUS_VERIFYING        4
#define OTA_STATUS_VERIFIED         5
#define OTA_STATUS_FAILED           0xFF

/* MQTT topics */
#define OTA_TOPIC_CMD       "/orpc/ota/cmd"       /* Subscribe: cloud -> device */
#define OTA_TOPIC_STATUS    "/orpc/ota/status"     /* Publish: device -> cloud */
#define OTA_TOPIC_PROGRESS  "/orpc/ota/progress"   /* Publish: download % */
#define OTA_TOPIC_VERSION   "/orpc/device/version" /* Publish: current version */

/* MQTT payload formats (JSON strings) */
#define OTA_CMD_START       "{\"cmd\":\"start\",\"url\":\"%s\",\"size\":%u,\"crc32\":%u,\"version\":%u}"
#define OTA_STATUS_RSP      "{\"status\":%u,\"version\":%u}"
#define OTA_PROGRESS_RSP    "{\"percent\":%u}"

/**
 * @brief Initialize the OTA agent
 *
 * Called once at system startup.
 * Starts MQTT connection in background if 4G network is available.
 */
void OTA_Agent_Init(void);

/**
 * @brief Periodic OTA agent task
 *
 * Call from main loop or RTOS task.
 * Handles MQTT keep-alive, download state machine, report status.
 */
void OTA_Agent_Task(void);

/**
 * @brief Start firmware download
 *
 * Called when OTA command is received from cloud.
 *
 * @param url       HTTP(S) URL to download firmware
 * @param file_size Expected file size in bytes
 * @param file_crc  Expected CRC32 of the file
 * @param version   New firmware version code
 * @return true if download started, false on error
 */
bool OTA_StartDownload(const char *url, uint32_t file_size,
                       uint32_t file_crc, uint32_t version);

/**
 * @brief Get current OTA status
 * @return OTA_STATUS_* code
 */
uint8_t OTA_GetStatus(void);

/**
 * @brief Get download progress (0-100)
 * @return Percentage complete
 */
uint8_t OTA_GetProgress(void);

/**
 * @brief Abort current download
 */
void OTA_Abort(void);

/**
 * @brief Check if OTA is in progress
 * @return true if actively downloading or verifying
 */
bool OTA_IsBusy(void);

/**
 * @brief Process incoming MQTT message (called from MQTT client)
 *
 * @param topic     MQTT topic
 * @param payload   Message payload
 * @param len       Payload length
 */
void OTA_ProcessMQTTMessage(const char *topic, const uint8_t *payload, uint16_t len);

#endif /* _OTA_AGENT_H_ */