/*******************************************************************************
 * @file    main.h
 * @brief   Main application header for BLE Bladder Patch NIRS device
 * @author  Charles KWON <charleskwon@medithings.co.kr>
 * @version V2.0.0
 * @date    2025-12-31
 *
 * Copyright (c) 2025 Medithings Inc.
 * All rights reserved.
 *
 * This file contains type definitions, enumerations, and function prototypes
 * for the main application module of the BLE-enabled NIRS bladder monitoring
 * device based on nRF52840.
 ******************************************************************************/

#ifndef MAIN_H__
#define MAIN_H__

/*============================================================================*/
/* Includes - Charles KWON                                                    */
/*============================================================================*/
#include <stdio.h>
#include <string.h>
#include <stdarg.h>
#include <stdbool.h>
#include "boards.h"

/*============================================================================*/
/* Type Definitions - Charles KWON                                            */
/*============================================================================*/

/**
 * @brief Generic ON/OFF control enumeration
 * - Charles KWON
 *
 * Used for controlling power states of various device components
 * such as LEDs, photodetectors, and other peripherals.
 */
typedef enum
{
    OFF = 0,    /**< Device/component is OFF */
    ON  = 1     /**< Device/component is ON */
} on_off_cont_t;

/**
 * @brief Command source type enumeration
 * - Charles KWON
 *
 * Identifies the source of incoming commands to route
 * responses appropriately.
 */
typedef enum
{
    CMD_BLE  = 0,   /**< Command received via BLE (Nordic UART Service) */
    CMD_UART = 1    /**< Command received via physical UART interface */
} which_cmd_t;

#if FEATURE_CHAMBER_AUTO_TEST
/**
 * @brief Automatic measurement mode enumeration
 * - Charles KWON
 *
 * Defines different automatic testing modes for chamber calibration
 * and production testing scenarios.
 */
typedef enum
{
    SIMPLE_AUTO_MODE = 0,   /**< Simple automatic measurement mode */
    HALF_AUTO_MODE   = 1,   /**< Semi-automatic measurement mode */
    FULL_AUTO_MODE   = 2,   /**< Full automatic measurement mode */
    NONE_AUTO_MODE   = 3    /**< Manual mode (no automation) */
} auto_meas_mode_t;
#endif

/**
 * @brief BLE connection status enumeration
 * - Charles KWON
 *
 * Tracks the current BLE connection state for controlling
 * device behavior based on connectivity.
 */
typedef enum
{
    BLE_DISCONNECTED_ST = 0,    /**< BLE is disconnected */
    BLE_CONNECTED_ST    = 1     /**< BLE is connected to a central device */
} ble_status_t;

/*============================================================================*/
/* Function Prototypes - Command Processing - Charles KWON                    */
/*============================================================================*/

/**
 * @brief Process received command data
 * - Charles KWON
 *
 * Parses and executes commands received from BLE or UART.
 * Commands control measurement modes, device settings, and queries.
 *
 * @param[in] data_array Pointer to received command data buffer
 * @param[in] cmd_t      Source of the command (BLE or UART)
 * @param[in] length     Length of the command data in bytes
 */
void received_command_process(uint8_t const *data_array, which_cmd_t cmd_t, uint8_t length);

/*============================================================================*/
/* Function Prototypes - Data Transmission - Charles KWON                     */
/*============================================================================*/

/**
 * @brief Transmit ASCII string data
 * - Charles KWON
 *
 * Sends null-terminated string data over the active communication
 * channel (BLE NUS or UART) with flow control.
 *
 * @param[in] p_data_to_send Pointer to null-terminated string to transmit
 */
void data_tx_handler(char const *p_data_to_send);

/**
 * @brief Transmit binary data
 * - Charles KWON
 *
 * Sends raw binary data over BLE NUS with specified length.
 * Used for transmitting measurement data and binary payloads.
 *
 * @param[in] ble_bin_buff Pointer to binary data buffer
 * @param[in] length       Number of bytes to transmit
 */
void binary_tx_handler(uint8_t const *ble_bin_buff, uint16_t length);

/**
 * @brief Format single 16-bit value with tag
 * - Charles KWON
 *
 * Creates a tagged binary packet containing a single 16-bit value.
 * Format: [tag bytes][value_high][value_low]
 *
 * @param[out] buffer Destination buffer for formatted data
 * @param[in]  tag    4-character tag string identifier
 * @param[in]  value  16-bit value to encode
 */
void single_format_data(uint8_t *buffer, const char *tag, const uint16_t value);

/**
 * @brief Format 16-bit array with tag
 * - Charles KWON
 *
 * Creates a tagged binary packet containing an array of 16-bit values.
 * Format: [tag bytes][data_0_high][data_0_low]...[data_n_high][data_n_low]
 *
 * @param[out] buffer     Destination buffer for formatted data
 * @param[in]  tag        4-character tag string identifier
 * @param[in]  data_array Pointer to array of 16-bit values
 * @param[in]  length     Number of elements in the array
 */
void format_data(uint8_t *buffer, const char *tag, const uint16_t *data_array, size_t length);

/**
 * @brief Format 8-bit array with tag
 * - Charles KWON
 *
 * Creates a tagged binary packet containing an array of 8-bit values.
 * Format: [tag bytes][data_0]...[data_n]
 *
 * @param[out] buffer     Destination buffer for formatted data
 * @param[in]  tag        4-character tag string identifier
 * @param[in]  data_array Pointer to array of 8-bit values
 * @param[in]  length     Number of elements in the array
 */
void format_data_byte(uint8_t *buffer, const char *tag, const uint8_t *data_array, size_t length);

/**
 * @brief Format ASCII string with tag
 * - Charles KWON
 *
 * Creates a tagged packet containing ASCII string data.
 * Format: [tag bytes][ascii_char_0]...[ascii_char_n]
 *
 * @param[out] buffer     Destination buffer for formatted data
 * @param[in]  tag        4-character tag string identifier
 * @param[in]  data_ascii Pointer to ASCII string data
 * @param[in]  length     Number of characters to include
 */
void ascii_format_data(uint8_t *buffer, const char *tag, const char *data_ascii, size_t length);

/*============================================================================*/
/* External Variables - Charles KWON                                          */
/*============================================================================*/

/**
 * @brief Flag indicating BLE TX operation in progress
 *
 * Set to true when a BLE transmission is pending completion.
 * Used to prevent overlapping transmissions and implement flow control.
 */
extern volatile bool data_tx_in_progress;

/**
 * @brief Current BLE connection status
 *
 * True when device is connected to a BLE central.
 * Used to control device behavior based on connectivity state.
 */
extern volatile bool ble_connection_st;

/**
 * @brief Flag indicating command processing in progress
 *
 * Set to true during command execution to prevent
 * concurrent command processing.
 */
extern volatile bool processing;

#endif /* MAIN_H__ */
