firmware-test/project/ble_peripheral/dr_piezo/dr_piezo.h

/*******************************************************************************
 * @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: <20>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.
 ******************************************************************************/

#ifndef DR_PIEZO_H
#define DR_PIEZO_H

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

/*==============================================================================
 * POWER CONTROL PINS (DC/DC Converter +/-20V)
 *============================================================================*/
#define DR_PIEZO_PWR_SHDN       NRF_GPIO_PIN_MAP(0, 21)  /**< SHDN_VPP/VNN (LT3463) */
#define DR_PIEZO_PWR_EN_10V     NRF_GPIO_PIN_MAP(0, 22)  /**< EN_+10V (MCP1804) */

/*==============================================================================
 * TX SIGNAL PINS (MOSFET Driver Control)
 *============================================================================*/
#define DR_PIEZO_PIN_PE         NRF_GPIO_PIN_MAP(1, 5)   /**< Pulse Enable */
#define DR_PIEZO_PIN_DMP        NRF_GPIO_PIN_MAP(1, 9)   /**< Dump control */
#define DR_PIEZO_PIN_P_OUT      NRF_GPIO_PIN_MAP(1, 3)   /**< Positive output */
#define DR_PIEZO_PIN_N_OUT      NRF_GPIO_PIN_MAP(1, 2)   /**< Negative output */

/*==============================================================================
 * MUX CONTROL PINS (Echo Signal Path Selection)
 *============================================================================*/
#define DR_PIEZO_MUX_SEL1       NRF_GPIO_PIN_MAP(1, 13)  /**< MUX Select 1 (HIGH) */
#define DR_PIEZO_MUX_SEL2       NRF_GPIO_PIN_MAP(1, 12)  /**< MUX Select 2 (LOW) */
#define DR_PIEZO_MUX_SEL3       NRF_GPIO_PIN_MAP(1, 11)  /**< MUX Select 3 (LOW) */

/*==============================================================================
 * CONFIGURATION
 *============================================================================*/
/**
 * @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     10

/*==============================================================================
 * POWER CONTROL FUNCTIONS
 *============================================================================*/

/**
 * @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);

/*==============================================================================
 * TX DRIVER FUNCTIONS
 *============================================================================*/

/**
 * @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
 * @note Sets P1.13=HIGH, P1.12=LOW, P1.11=LOW
 */
void dr_piezo_mux_init(void);

/*==============================================================================
 * SYSTEM FUNCTIONS (Power + TX combined)
 *============================================================================*/

/**
 * @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 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);

#endif /* DR_PIEZO_H */