/**
 * @file    at_driver.h
 * @brief   4G Cat.1 Module AT Command Driver
 *
 * Supports Air724UG (China) and EC200U (EU/Global).
 * Provides a unified API for:
 *   - Module power on/off / reset
 *   - Network registration check
 *   - PDP context (GPRS/APN) setup
 *   - TCP/UDP socket connection
 *   - HTTP GET/POST
 *   - MQTT (via AT+QMTCFG / AT+QMTOPEN if module supports)
 *   - Signal quality
 *   - SIM card status
 */

#ifndef _AT_DRIVER_H_
#define _AT_DRIVER_H_

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

/* ==================== Module status ==================== */

typedef enum {
    AT_MODULE_OFF = 0,
    AT_MODULE_POWERING_ON,
    AT_MODULE_READY,
    AT_MODULE_ERROR,
    AT_MODULE_LOW_POWER
} AT_ModuleState_t;

typedef enum {
    AT_NET_NOT_REGISTERED = 0,
    AT_NET_REGISTERED_HOME,
    AT_NET_REGISTERED_ROAMING,
    AT_NET_REGISTERED_DENIED,
    AT_NET_UNKNOWN,
    AT_NET_REGISTERED_SMS_ONLY_HOME,
    AT_NET_REGISTERED_SMS_ONLY_ROAMING
} AT_NetRegState_t;

typedef enum {
    AT_SIM_ABSENT = 0,
    AT_SIM_READY,
    AT_SIM_PIN_REQUIRED,
    AT_SIM_ERROR
} AT_SIMState_t;

/* ==================== Initialization ==================== */

/**
 * @brief Initialize AT driver, UART, and GPIO pins
 */
void AT_Init(void);

/**
 * @brief Power on the 4G module (PWRKEY pulse)
 * @return true if power-on sequence started
 */
bool AT_PowerOn(void);

/**
 * @brief Power off the 4G module
 */
void AT_PowerOff(void);

/**
 * @brief Reset module via AT+CRESET (software reset)
 * @return true if reset command accepted
 */
bool AT_Reset(void);

/**
 * @brief Wait for module to become ready after power-on
 * @param timeout_ms  Max wait time
 * @return true if module responded OK
 */
bool AT_WaitReady(uint32_t timeout_ms);

/* ==================== Status queries ==================== */

/**
 * @brief Get module state
 */
AT_ModuleState_t AT_GetState(void);

/**
 * @brief Check SIM card status
 * @return SIM state
 */
AT_SIMState_t AT_CheckSIM(void);

/**
 * @brief Get network registration status
 * @return Network registration state
 */
AT_NetRegState_t AT_CheckNetwork(void);

/**
 * @brief Get signal quality (CSQ)
 * @return RSSI value (0-31, 99 = not detectable)
 */
uint8_t AT_GetSignalQuality(void);

/* ==================== Network connection ==================== */

/**
 * @brief Configure APN and activate PDP context
 *
 * @param apn     APN string (e.g., "cmnet" or "internet")
 * @param user    Username (can be NULL)
 * @param pass    Password (can be NULL)
 * @return true if PDP context activated
 */
bool AT_SetupAPN(const char *apn, const char *user, const char *pass);

/**
 * @brief Check if PDP context is active and get IP
 * @param ip_buf  Buffer for IP string (at least 16 bytes)
 * @return true if connected and IP obtained
 */
bool AT_GetIP(char *ip_buf);

/**
 * @brief Deactivate PDP context
 */
void AT_DisconnectNetwork(void);

/* ==================== HTTP operations (module-level) ==================== */

/**
 * @brief Download a file via HTTP/HTTPS GET
 *
 * Uses module's built-in HTTP AT commands if supported.
 * Falls back to TCP socket + manual HTTP request otherwise.
 *
 * @param url       URL to download
 * @param timeout_s Max time in seconds
 * @return true if download complete
 */
bool AT_HTTP_GET(const char *url, uint32_t timeout_s);

/**
 * @brief Get size of last HTTP download
 * @return Number of bytes received
 */
uint32_t AT_HTTP_GetDownloadSize(void);

/**
 * @brief Read HTTP download data from module buffer
 *
 * @param offset    Byte offset to start reading
 * @param buffer    Output buffer
 * @param len       Number of bytes to read
 * @return Number of bytes actually read
 */
uint32_t AT_HTTP_ReadData(uint32_t offset, uint8_t *buffer, uint32_t len);

/* ==================== MQTT (module-level, if supported) ==================== */

/**
 * @brief Configure MQTT client on the module
 *
 * @param client_id  MQTT client ID (unique device ID)
 * @param username   MQTT username (can be NULL)
 * @param password   MQTT password (can be NULL)
 * @return true if configuration accepted
 */
bool AT_MQTT_Configure(const char *client_id,
                       const char *username, const char *password);

/**
 * @brief Open MQTT connection to broker
 *
 * @param host    Broker hostname or IP
 * @param port    Broker port (typically 1883 or 8883 for TLS)
 * @return true if connection established
 */
bool AT_MQTT_Connect(const char *host, uint16_t port);

/**
 * @brief Subscribe to a topic
 *
 * @param topic   Topic string
 * @param qos     QoS level (0 or 1)
 * @return true if subscribed
 */
bool AT_MQTT_Subscribe(const char *topic, uint8_t qos);

/**
 * @brief Publish a message
 *
 * @param topic   Topic string
 * @param payload Message data
 * @param len     Message length
 * @param qos     QoS level
 * @return true if published
 */
bool AT_MQTT_Publish(const char *topic, const uint8_t *payload,
                     uint16_t len, uint8_t qos);

/**
 * @brief Disconnect MQTT
 */
void AT_MQTT_Disconnect(void);

/**
 * @brief Check if MQTT is connected
 */
bool AT_MQTT_IsConnected(void);

/* ==================== Low power ==================== */

/**
 * @brief Enter sleep mode (AT+CSCLK)
 */
void AT_EnterSleep(void);

/**
 * @brief Wake up module from sleep
 */
void AT_WakeUp(void);

/* ==================== UART receive callback ==================== */

/**
 * @brief Process received UART data (call from UART IRQ)
 *
 * @param byte  Received byte
 */
void AT_UART_RxCallback(uint8_t byte);

/**
 * @brief Check if a specific AT response line is available
 *
 * @param tag   Expected response prefix (e.g., "+QMTRECV:")
 * @param buf   Output buffer for full response line
 * @param len   Buffer size
 * @return true if matching line found
 */
bool AT_CheckResponse(const char *tag, char *buf, uint16_t len);

/**
 * @brief Clear response buffer
 */
void AT_ClearResponse(void);

#endif /* _AT_DRIVER_H_ */