/*******************************************************************************
 * @file    dr_piezo.h
 * @brief   Piezo Transducer Driver (2MHz Signal Generator)
 * @author  Charles KWON
 * @date    2025-12-09
 *
 * @note    Hardware: nRF52840 + MD1822K6-G MOSFET Driver + TC7920K6-G MOSFET
 *          Output: +/-20V at 2MHz, 3~5 cycles
 *
 * @details Timing Sequence:
 *          1. PE = HIGH (enable)
 *          2. P_OUT/N_OUT = 2MHz pulses (3~5 cycles)
 *          3. DMP = HIGH (dump)
 *          4. DMP = LOW
 *          5. PE = LOW (disable)
 *
 *          All signals (P_OUT, N_OUT, DMP) operate within PE HIGH period.
 ******************************************************************************/

/*******************************************************************************
 * [한국어 설명] 피에조 초음파 트랜스듀서 드라이버 헤더
 *
 * === 개요 ===
 * 방광 측정용 초음파 송신기의 핀 할당, 설정값, 함수 선언을 정의.
 * nRF52840 + MD1822K6-G(MOSFET 드라이버) + TC7920K6-G(MOSFET) 하드웨어 구성.
 * 출력: +/-20V, 2MHz, 3~7 사이클 버스트.
 *
 * === 핀 할당 ===
 * 전원 제어:
 *   - DR_PIEZO_PWR_EN (P1.9): DC/DC 컨버터 활성화 -> +/-20V 고전압 생성
 *
 * TX 신호 핀 (MOSFET 드라이버 제어):
 *   - PE  (P0.25): Pulse Enable - 전체 시퀀스 활성화/비활성화
 *   - DMP (P1.0):  Dump - 펄스 후 피에조 잔류 에너지 방전
 *   - P_OUT (P1.7): Positive Output - 피에조 양극 구동
 *   - N_OUT (P1.6): Negative Output - 피에조 음극 구동 (P_OUT과 역상)
 *
 * MUX 제어 핀 (8채널 에코 신호 경로 선택):
 *   - EN_MUXA (P0.21): MUXA 활성화 (CH0~CH3 담당)
 *   - EN_MUXB (P0.23): MUXB 활성화 (CH4~CH7 담당)
 *   - SEL0 (P1.10): MUX 내부 채널 주소 비트 0
 *   - SEL1 (P0.28): MUX 내부 채널 주소 비트 1
 *
 * === MUX 채널 매핑 (8채널) ===
 * CH0 = MUXA 입력0: EN_A=1, EN_B=0, SEL0=0, SEL1=0
 * CH1 = MUXA 입력2: EN_A=1, EN_B=0, SEL0=1, SEL1=0
 * CH2 = MUXA 입력1: EN_A=1, EN_B=0, SEL0=0, SEL1=1
 * CH3 = MUXA 입력3: EN_A=1, EN_B=0, SEL0=1, SEL1=1
 * CH4 = MUXB 입력0: EN_A=0, EN_B=1, SEL0=1, SEL1=1
 * CH5 = MUXB 입력1: EN_A=0, EN_B=1, SEL0=0, SEL1=1
 * CH6 = MUXB 입력2: EN_A=0, EN_B=1, SEL0=1, SEL1=0
 * CH7 = MUXB 입력3: EN_A=0, EN_B=1, SEL0=0, SEL1=0
 *
 * === 두 가지 버스트 모드 ===
 * 1) 하드웨어 버스트 (dr_piezo_burst): Timer2 + PPI + GPIOTE 사용, CPU 비의존적
 * 2) 소프트웨어 버스트 (dr_piezo_burst_sw_XXmhz): CPU NOP 기반 정밀 타이밍
 *    - 주파수별 전용 함수: 1.7/1.8/1.9/2.0/2.1/2.2 MHz
 ******************************************************************************/

#ifndef DR_PIEZO_H
#define DR_PIEZO_H

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

/*==============================================================================
 * 전원 제어 핀 (DC/DC 컨버터 +/-20V)
 * DR_PIEZO_PWR_EN: HIGH로 설정 시 DC/DC 컨버터가 +/-20V 고전압 생성
 *============================================================================*/
#define DR_PIEZO_PWR_EN       NRF_GPIO_PIN_MAP(1, 9)  /** Power Enable   jhChun 0128 */

/*==============================================================================
 * TX 신호 핀 (MOSFET 드라이버 제어)
 * PE:    Pulse Enable - 전체 TX 시퀀스 활성화/비활성화
 * DMP:   Dump - 펄스 후 피에조 잔류 에너지 방전용
 * P_OUT: Positive Output - 피에조 양극 구동 (N_OUT과 역상)
 * N_OUT: Negative Output - 피에조 음극 구동 (P_OUT과 역상)
 * 주의: 이전 핀 할당(주석 처리)에서 새 보드 레이아웃으로 변경됨 (jhChun 0128)
 *============================================================================*/
#define DR_PIEZO_PIN_PE         NRF_GPIO_PIN_MAP(0, 25)   /**< Pulse Enable */           // P1.05 -> P0.25
#define DR_PIEZO_PIN_DMP        NRF_GPIO_PIN_MAP(1, 0)    /**< Dump control */            // P1.9 -> P1.0
#define DR_PIEZO_PIN_P_OUT      NRF_GPIO_PIN_MAP(1, 7)    /**< Positive output */         // P1.3 -> P1.7
#define DR_PIEZO_PIN_N_OUT      NRF_GPIO_PIN_MAP(1, 6)    /**< Negative output */         // P1.2 -> P1.6  jhChun 0128
 
/*==============================================================================
 * MUX 제어 핀 (에코 신호 경로 선택)
 * 8채널 아날로그 MUX로 피에조 센서 채널을 선택한다.
 * MUXA(CH0~CH3)와 MUXB(CH4~CH7) 두 개의 4채널 MUX 사용.
 * EN_MUXA/EN_MUXB: 각 MUX 활성화 (동시에 하나만 HIGH)
 * SEL0/SEL1: MUX 내부 4채널 중 하나를 선택하는 주소 비트
 *============================================================================*/
/* Piezo MUX pins (8ch)    jhChun 0129 */
#define DR_PIEZO_EN_MUXA        NRF_GPIO_PIN_MAP(0, 21)  /**< MUXA Enable */
#define DR_PIEZO_EN_MUXB        NRF_GPIO_PIN_MAP(0, 23)  /**< MUXB Enable */
#define DR_PIEZO_MUX_SEL0       NRF_GPIO_PIN_MAP(1, 10)  /**< MUX Select 0 */
#define DR_PIEZO_MUX_SEL1       NRF_GPIO_PIN_MAP(0, 28)  /**< MUX Select 1 */

/*==============================================================================
 * 설정값
 * DR_PIEZO_FREQ_HZ: 목표 주파수 (실제 동작 주파수는 dr_piezo.c에서 결정)
 * DR_PIEZO_DEFAULT_CYCLES: 기본 버스트 사이클 수 (5)
 * DR_PIEZO_MIN/MAX_CYCLES: 허용 사이클 범위 (3~7)
 * DR_PIEZO_MUX_SETTLING_US: MUX 채널 전환 후 아날로그 경로 안정화 대기 시간
 *============================================================================*/
/**
 * @note Actual operating frequency is defined in dr_piezo.c as PIEZO_FREQ_MHZ.
 *       Change PIEZO_FREQ_MHZ in dr_piezo.c to adjust the burst frequency.
 *       Current setting: 2.1 MHz
 */
#define DR_PIEZO_FREQ_HZ        2100000     /**< Target frequency (set PIEZO_FREQ_MHZ in .c) */
#define DR_PIEZO_DEFAULT_CYCLES 5           /**< Default burst cycles (3~5) */
#define DR_PIEZO_MIN_CYCLES     3
#define DR_PIEZO_MAX_CYCLES     7
#define DR_PIEZO_MUX_SETTLING_US 1300       /**< MUX settling delay (us) */

/*==============================================================================
 * 전원 제어 함수
 * DC/DC 컨버터(+/-20V)를 ON/OFF하여 피에조 구동 고전압을 제어한다.
 *============================================================================*/

/**
 * @brief Power ON piezo system (+/-20V DC/DC converter)
 */
void dr_piezo_power_on(void);

/**
 * @brief Power OFF piezo system
 */
void dr_piezo_power_off(void);

/**
 * @brief 피에조 전원 상태 확인
 * @return true: 전원 ON, false: 전원 OFF
 */
bool dr_piezo_is_power_on(void);

/*==============================================================================
 * TX 드라이버 함수
 * 초음파 송신 관련: 초기화, 버스트 송신, 활성화/비활성화, 주파수 설정
 *============================================================================*/

/**
 * @brief Initialize piezo TX driver (Timer + PPI + GPIOTE)
 */
void dr_piezo_init(void);

/**
 * @brief Uninitialize piezo TX driver
 */
void dr_piezo_uninit(void);

/**
 * @brief Transmit a burst of 2MHz pulses
 * @param cycles Number of cycles to transmit (3~10)
 */
void dr_piezo_burst(uint8_t cycles);

/**
 * @brief Transmit default burst (5 cycles)
 */
void dr_piezo_pulse(void);

/**
 * @brief Enable TX output (prepare for transmission)
 */
void dr_piezo_enable(void);

/**
 * @brief Disable TX output (return to idle state)
 */
void dr_piezo_disable(void);

/**
 * @brief Check if TX is currently active
 * @return true if transmitting
 */
bool dr_piezo_is_busy(void);

/**
 * @brief Set TX frequency (for testing)
 * @param freq_hz Frequency in Hz (100kHz ~ 4MHz)
 */
void dr_piezo_set_frequency(uint32_t freq_hz);

/**
 * @brief Test all pins manually (for debugging with oscilloscope)
 */
void dr_piezo_test_pins(void);

/**
 * @brief Initialize MUX control pins for echo signal path
 */
void dr_piezo_mux_init(void);

/**
 * @brief Select piezo channel (0~7) via 8ch MUX
 * @param channel Piezo channel number (0~7)
 *
 * Channel mapping (EN_MUXA, EN_MUXB, SEL0, SEL1):
 *   CH0=A0(1,0,0,0) CH1=A2(1,0,1,0) CH2=A1(1,0,0,1) CH3=A3(1,0,1,1)
 *   CH4=B0(0,1,1,1) CH5=B1(0,1,0,1) CH6=B2(0,1,1,0) CH7=B3(0,1,0,0)
 *
 * @note MUX settling time: 1.3ms delay after switching
 */
void dr_piezo_select_channel(uint8_t channel);

/*==============================================================================
 * 시스템 함수 (전원 + TX 통합 제어)
 * 전원 ON/OFF와 TX 드라이버 초기화/해제를 한 번에 수행하는 편의 함수.
 * 소프트웨어 버스트(burst_sw) 계열: CPU NOP 기반 정밀 타이밍.
 *   - Timer/PPI 없이 CPU에서 직접 GPIO를 제어
 *   - 인터럽트 비활성화 상태에서 동작하여 타이밍 정확도 보장
 *   - 주파수별 전용 함수 제공 (NOP 개수가 다름)
 *============================================================================*/

/**
 * @brief Full system initialization (power + TX driver)
 */
void dr_piezo_system_init(void);

/**
 * @brief Full system shutdown
 */
void dr_piezo_system_uninit(void);

/**
 * @brief Transmit with power check
 * @param cycles Number of cycles
 */
void dr_piezo_transmit(uint8_t cycles);

/**
 * @brief Software-based burst (CPU-controlled, no Timer/PPI)
 * @param cycles Number of cycles (1~20)
 * @note Default frequency: 2.1 MHz
 */
void dr_piezo_burst_sw(uint8_t cycles);

/**
 * @brief Software-based burst at 1.8 MHz
 * @param cycles Number of cycles (1~20)
 * @note Fixed frequency: 1.8 MHz
 */
void dr_piezo_burst_sw_18mhz(uint8_t cycles);

/**
 * @brief Software-based burst at 2.0 MHz
 * @param cycles Number of cycles (1~20)
 * @note Fixed frequency: 2.0 MHz
 */
void dr_piezo_burst_sw_20mhz(uint8_t cycles);

/**
 * @brief Software-based burst at 2.2 MHz
 * @param cycles Number of cycles (1~20)
 * @note Fixed frequency: 2.2 MHz
 */
void dr_piezo_burst_sw_22mhz(uint8_t cycles);

/**
 * @brief Software-based burst at 1.7 MHz
 * @param cycles Number of cycles (1~20)
 * @note Fixed frequency: 1.7 MHz
 */
void dr_piezo_burst_sw_17mhz(uint8_t cycles);

/**
 * @brief Software-based burst at 1.9 MHz
 * @param cycles Number of cycles (1~20)
 * @note Fixed frequency: 1.9 MHz
 */
void dr_piezo_burst_sw_19mhz(uint8_t cycles);

#endif /* DR_PIEZO_H */