/******************************************************************************
  * \attention
  *
  * <h2><center>&copy; COPYRIGHT 2016 STMicroelectronics</center></h2>
  *
  * Licensed under ST MYLIBERTY SOFTWARE LICENSE AGREEMENT (the "License");
  * You may not use this file except in compliance with the License.
  * You may obtain a copy of the License at:
  *
  *        www.st.com/myliberty
  *
  * Unless required by applicable law or agreed to in writing, software 
  * distributed under the License is distributed on an "AS IS" BASIS, 
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
  * AND SPECIFICALLY DISCLAIMING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
  * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
******************************************************************************/


/*
 *      PROJECT:   ST25R3911 firmware
 *      Revision:
 *      LANGUAGE:  ISO C99
 */

/*! \file
 *
 *  \author Ulrich Herrmann
 *
 *  \brief ST25R3911 declaration file
 *
 * API:
 * - Initialize ST25R3911 driver: #st25r3911Initialize
 * - Deinitialize ST25R3911 driver: #st25r3911Deinitialize
 *
 *
 * \addtogroup RFAL
 * @{
 *
 * \addtogroup RFAL-HAL
 * \brief RFAL Hardware Abstraction Layer
 * @{
 *
 * \addtogroup ST25R3911
 * \brief RFAL ST25R3911 Driver
 * @{
 * 
 * \addtogroup ST25R3911_Driver
 * \brief RFAL ST25R3911 Driver
 * @{
 * 
 */

#ifndef ST25R3911_H
#define ST25R3911_H

/*
******************************************************************************
* INCLUDES
******************************************************************************
*/
#include "platform.h"
#include "st_errno.h"

/*
******************************************************************************
* GLOBAL DATATYPES
******************************************************************************
*/

/*! Parameters how the stream mode should work */
struct st25r3911StreamConfig {
    uint8_t useBPSK;                                    /*!< 0: subcarrier, 1:BPSK                                      */
    uint8_t din;                                        /*!< the divider for the in subcarrier frequency: fc/2^din      */
    uint8_t dout;                                       /*!< the divider for the in subcarrier frequency fc/2^dout      */
    uint8_t report_period_length;                       /*!< the length of the reporting period 2^report_period_length  */
};


/*
******************************************************************************
* GLOBAL DEFINES
******************************************************************************
*/
#define ST25R3911_FDT_NONE                     0x00U    /*!< Value indicating not to perform FDT                        */

#define MS_TO_64FCS(A)                  ((A) * 212U)    /*!< Converts from ms to 64/fc steps                            */
#define MS_FROM_64FCS(A)                ((A) / 212U)    /*!< Converts from 64/fc steps to ms                            */

/* ST25R3911 direct commands */
#define ST25R3911_CMD_SET_DEFAULT              0xC1U    /*!< Puts the chip in default state (same as after power-up)    */
#define ST25R3911_CMD_CLEAR_FIFO               0xC2U    /*!< Stops all activities and clears FIFO                       */
#define ST25R3911_CMD_TRANSMIT_WITH_CRC        0xC4U    /*!< Transmit with CRC                                          */
#define ST25R3911_CMD_TRANSMIT_WITHOUT_CRC     0xC5U    /*!< Transmit without CRC                                       */
#define ST25R3911_CMD_TRANSMIT_REQA            0xC6U    /*!< Transmit REQA                                              */
#define ST25R3911_CMD_TRANSMIT_WUPA            0xC7U    /*!< Transmit WUPA                                              */
#define ST25R3911_CMD_INITIAL_RF_COLLISION     0xC8U    /*!< NFC transmit with Initial RF Collision Avoidance           */
#define ST25R3911_CMD_RESPONSE_RF_COLLISION_N  0xC9U    /*!< NFC transmit with Response RF Collision Avoidance          */
#define ST25R3911_CMD_RESPONSE_RF_COLLISION_0  0xCAU    /*!< NFC transmit with Response RF Collision Avoidance with n=0 */
#define ST25R3911_CMD_NORMAL_NFC_MODE          0xCBU    /*!< NFC switch to normal NFC mode                              */
#define ST25R3911_CMD_ANALOG_PRESET            0xCCU    /*!< Analog Preset                                              */
#define ST25R3911_CMD_MASK_RECEIVE_DATA        0xD0U    /*!< Mask recive data                                           */
#define ST25R3911_CMD_UNMASK_RECEIVE_DATA      0xD1U    /*!< Unmask recive data                                         */
#define ST25R3911_CMD_MEASURE_AMPLITUDE        0xD3U    /*!< Measure singal amplitude on RFI inputs                     */
#define ST25R3911_CMD_SQUELCH                  0xD4U    /*!< Squelch                                                    */
#define ST25R3911_CMD_CLEAR_SQUELCH            0xD5U    /*!< Clear Squelch                                              */
#define ST25R3911_CMD_ADJUST_REGULATORS        0xD6U    /*!< Adjust regulators                                          */
#define ST25R3911_CMD_CALIBRATE_MODULATION     0xD7U    /*!< Calibrate modulation depth                                 */
#define ST25R3911_CMD_CALIBRATE_ANTENNA        0xD8U    /*!< Calibrate antenna                                          */
#define ST25R3911_CMD_MEASURE_PHASE            0xD9U    /*!< Measure phase between RFO and RFI signal                   */
#define ST25R3911_CMD_CLEAR_RSSI               0xDAU    /*!< clear RSSI bits and restart the measurement                */
#define ST25R3911_CMD_TRANSPARENT_MODE         0xDCU    /*!< Transparent mode                                           */
#define ST25R3911_CMD_CALIBRATE_C_SENSOR       0xDDU    /*!< Calibrate the capacitive sensor                            */
#define ST25R3911_CMD_MEASURE_CAPACITANCE      0xDEU    /*!< Measure capacitance                                        */
#define ST25R3911_CMD_MEASURE_VDD              0xDFU    /*!< Measure power supply voltage                               */
#define ST25R3911_CMD_START_GP_TIMER           0xE0U    /*!< Start the general purpose timer                            */
#define ST25R3911_CMD_START_WUP_TIMER          0xE1U    /*!< Start the wake-up timer                                    */
#define ST25R3911_CMD_START_MASK_RECEIVE_TIMER 0xE2U    /*!< Start the mask-receive timer                               */
#define ST25R3911_CMD_START_NO_RESPONSE_TIMER  0xE3U    /*!< Start the no-repsonse timer                                */
#define ST25R3911_CMD_TEST_CLEARA              0xFAU    /*!< Clear Test register                                        */
#define ST25R3911_CMD_TEST_CLEARB              0xFBU    /*!< Clear Test register                                        */
#define ST25R3911_CMD_TEST_ACCESS              0xFCU    /*!< Enable R/W access to the test registers                    */
#define ST25R3911_CMD_LOAD_PPROM               0xFDU    /*!< Load data from the poly fuses to RAM                       */
#define ST25R3911_CMD_FUSE_PPROM               0xFEU    /*!< Fuse poly fuses with data from the RAM                     */


#define ST25R3911_FIFO_DEPTH                   96U      /*!< Depth of FIFO                                              */

#define ST25R3911_THRESHOLD_DO_NOT_SET         0xFFU    /*!< Indicates not to change this Threshold                     */

#define ST25R3911_BR_DO_NOT_SET                0xFFU    /*!< Indicates not to change this Bit Rate                      */
#define ST25R3911_BR_106                       0x00U    /*!< ST25R3911 Bit Rate 106 kbit/s (fc/128)                     */
#define ST25R3911_BR_212                       0x01U    /*!< ST25R3911 Bit Rate 212 kbit/s (fc/64)                      */
#define ST25R3911_BR_424                       0x02U    /*!< ST25R3911 Bit Rate 424 kbit/s (fc/32)                      */
#define ST25R3911_BR_848                       0x03U    /*!< ST25R3911 Bit Rate 848 kbit/s (fc/16)                      */
#define ST25R3911_BR_1695                      0x04U    /*!< ST25R3911 Bit Rate 1696 kbit/s (fc/8)                      */
#define ST25R3911_BR_3390                      0x05U    /*!< ST25R3911 Bit Rate 3390 kbit/s (fc/4)                      */
#define ST25R3911_BR_6780                      0x06U    /*!< ST25R3911 Bit Rate 6780 kbit/s (fc/2)                      */

/*
******************************************************************************
* GLOBAL MACROS
******************************************************************************
*/

/*! Checks if General Purpose Timer is still running by reading gpt_on flag */
#define st25r3911IsGPTRunning( )     ( st25r3911CheckReg(ST25R3911_REG_REGULATOR_RESULT, ST25R3911_REG_REGULATOR_RESULT_gpt_on, ST25R3911_REG_REGULATOR_RESULT_gpt_on) )

/*! Checks if CRC is configured to be in FIFO                               */
#define st25r3911IsCRCinFIFO( )      ( st25r3911CheckReg(ST25R3911_REG_AUX, ST25R3911_REG_AUX_crc_2_fifo, ST25R3911_REG_AUX_crc_2_fifo) )

/*! Checks if External Filed is detected by reading ST25R3911 External Field  
 * Detector output                                                          */
#define st25r3911IsExtFieldOn()      ( st25r3911CheckReg(ST25R3911_REG_AUX_DISPLAY, ST25R3911_REG_AUX_DISPLAY_efd_o, ST25R3911_REG_AUX_DISPLAY_efd_o ) )

/*! Checks if Transmitter is enabled (Field On) */
#define st25r3911IsTxEnabled()       ( st25r3911CheckReg(ST25R3911_REG_OP_CONTROL, ST25R3911_REG_OP_CONTROL_tx_en, ST25R3911_REG_OP_CONTROL_tx_en ) )

/*! Turn Off Tx (Field Off) */
#define st25r3911TxOff()              st25r3911ClrRegisterBits(ST25R3911_REG_OP_CONTROL, ST25R3911_REG_OP_CONTROL_tx_en );

/*! Checks if last FIFO byte is complete */
#define st25r3911IsLastFIFOComplete() st25r3911CheckReg( ST25R3911_REG_FIFO_RX_STATUS2, ST25R3911_REG_FIFO_RX_STATUS2_mask_fifo_lb, 0 )

/*! Checks if the Oscillator is enabled  */
#define st25r3911IsOscOn()            st25r3911CheckReg( ST25R3911_REG_OP_CONTROL, ST25R3911_REG_OP_CONTROL_en, ST25R3911_REG_OP_CONTROL_en )

/*
******************************************************************************
* GLOBAL FUNCTION PROTOTYPES
******************************************************************************
*/

/*! 
 *****************************************************************************
 *  \brief  Turn on Oscillator and Regulator
 *  
 *  This function turn on oscillator and regulator and wait for the oscillator to 
 *  become stable.
 * 
 *****************************************************************************
 */
extern void st25r3911OscOn( void );

/*! 
 *****************************************************************************
 *  \brief  Turn On Tx and Rx
 *
 *  This function turns On Tx and Rx (Field On)
 *
 *****************************************************************************
 */
extern void st25r3911TxRxOn( void );

/*! 
 *****************************************************************************
 *  \brief  Turn Off Tx and Rx
 *
 *  This function turns Off Tx and Rx (Field Off)
 *
 *****************************************************************************
 */
extern void st25r3911TxRxOff( void );

/*! 
 *****************************************************************************
 *  \brief  Initialise ST25R3911 driver
 *
 *  This function initialises the ST25R3911 driver.
 *
 *****************************************************************************
 */
extern void st25r3911Initialize( void );

/*! 
 *****************************************************************************
 *  \brief  Deinitialize ST25R3911 driver
 *
 *  Calling this function deinitializes the ST25R3911 driver.
 *
 *****************************************************************************
 */
extern void st25r3911Deinitialize( void );


/*! 
 *****************************************************************************
 *  \brief  Sets the bitrate registers
 *
 *  This function sets the bitrate register for rx and tx
 *
 *  \param txRate : speed is 2^txrate * 106 kb/s
 *                  0xff : don't set txrate
 *  \param rxRate : speed is 2^rxrate * 106 kb/s
 *                  0xff : don't set rxrate
 *
 *  \return ERR_NONE : No error, both bit rates were set
 *  \return ERR_PARAM: At least one bit rate was invalid
 *
 *****************************************************************************
 */
extern ReturnCode st25r3911SetBitrate( uint8_t txRate, uint8_t rxRate );

/*! 
 *****************************************************************************
 *  \brief  Adjusts supply regulators according to the current supply voltage
 *
 *  On this function the power level is measured in maximum load conditions and
 *  the regulated voltage reference is set to 250mV below this level.
 *  Execution of this function lasts arround 5ms. 
 *
 *  The regulated voltages will be set to the result of Adjust Regulators
 *  
 *  \param [out] result_mV : Result of calibration in milliVolts.
 *
 *  \return ERR_IO : Error during communication with ST25R3911.
 *  \return ERR_NONE : No error.
 *
 *****************************************************************************
 */
extern ReturnCode st25r3911AdjustRegulators( uint16_t* result_mV );

/*! 
 *****************************************************************************
 *  \brief  Measure Amplitude
 *
 *  This function measured the amplitude on the RFI inputs and stores the
 *  result in parameter \a result.
 *
 *  \param[out] result: 8 bit long result of RF measurement.
 *
 *****************************************************************************
 */
extern void st25r3911MeasureAmplitude( uint8_t* result );

/*! 
 *****************************************************************************
 *  \brief  Measure Capacitance
 *
 *  This function performs the capacitance measurement and stores the
 *  result in parameter \a result.
 *
 *  \param[out] result: 8 bit long result of RF measurement.
 *
 *****************************************************************************
 */
extern void st25r3911MeasureCapacitance( uint8_t* result );

/*! 
 *****************************************************************************
 *  \brief  Measure Voltage
 *
 *  This function measures the voltage on one of VDD and VSP_*
 *  result in parameter \a result.
 *
 *  \param[in] mpsv : one of ST25R3911_REG_REGULATOR_CONTROL_mpsv_vdd
 *                           ST25R3911_REG_REGULATOR_CONTROL_mpsv_vsp_rf
 *                           ST25R3911_REG_REGULATOR_CONTROL_mpsv_vsp_a
 *                    or     ST25R3911_REG_REGULATOR_CONTROL_mpsv_vsp_d
 *
 *  \return the measured voltage raw values
 *
 *****************************************************************************
 */
extern uint8_t st25r3911MeasurePowerSupply( uint8_t mpsv );

/*! 
 *****************************************************************************
 *  \brief  Measure Voltage
 *
 *  This function measures the voltage on one of VDD and VSP_*
 *  result in parameter \a result.
 *
 *  \param[in] mpsv : one of ST25R3911_REG_REGULATOR_CONTROL_mpsv_vdd
 *                           ST25R3911_REG_REGULATOR_CONTROL_mpsv_vsp_rf
 *                           ST25R3911_REG_REGULATOR_CONTROL_mpsv_vsp_a
 *                    or     ST25R3911_REG_REGULATOR_CONTROL_mpsv_vsp_d
 *
 *  \return the measured voltage in mV
 *
 *****************************************************************************
 */
extern uint16_t st25r3911MeasureVoltage( uint8_t mpsv );

/*! 
 *****************************************************************************
 *  \brief  Calibrate antenna
 *
 *  This function is used to calibrate the antenna using a special sequence.
 *  The result is stored in the \a result parameter.
 *
 *  \param[out] result: 8 bit long result of antenna calibration algorithm.
 *
 *****************************************************************************
 */
extern void st25r3911CalibrateAntenna( uint8_t* result );

/*! 
 *****************************************************************************
 *  \brief  Measure Phase
 *
 *  This function performs a Phase measurement.
 *  The result is stored in the \a result parameter.
 *
 *  \param[out] result: 8 bit long result of the measurement.
 *
 *****************************************************************************
 */
extern void st25r3911MeasurePhase( uint8_t* result );

/*! 
 *****************************************************************************
 *  \brief  Calibrate modulation depth
 *
 *  This function is used to calibrate the modulation depth using a special sequence.
 *  The result is stored in the \a result parameter.
 *
 *  \param[out] result: 8 bit long result of antenna calibration algorithm.
 *
 *****************************************************************************
 */
extern void st25r3911CalibrateModulationDepth( uint8_t* result );


/*! 
 *****************************************************************************
 *  \brief  Calibrate Capacitive Sensor
 *
 *  This function performs automatic calibration of the capacitive sensor 
 *  and stores the result in parameter \a result.
 *
 * \warning To avoid interference with Xtal oscillator and reader magnetic 
 *          field, it is strongly recommended to perform calibration
 *          in Power-down mode only.
 *          This method does not modify the Oscillator nor transmitter state, 
 *          these should be configured before by user.
 *
 *  \param[out] result: 5 bit long result of the calibration.
 *                      Binary weighted, step 0.1 pF, max 3.1 pF
 *
 * 
 *  \return ERR_PARAM : Invalid parameter
 *  \return ERR_IO    : The calibration was not successful 
 *  \return ERR_NONE  : No error
 *
 *****************************************************************************
 */
extern ReturnCode st25r3911CalibrateCapacitiveSensor( uint8_t* result );

/*! 
 *****************************************************************************
 *  \brief  set no response time
 *
 *  This function executes sets the no response time to the defines value
 *
 *  \param nrt_64fcs : no response time in 64/fc = 4.72us
 *                    completion interrupt
 *
 *  \return ERR_PARAM : if time is too large
 */
extern ReturnCode st25r3911SetNoResponseTime_64fcs( uint32_t nrt_64fcs );

/*! 
 *****************************************************************************
 *  \brief  set no response time
 *
 *  This function executes sets and immediately start the no response timer
 *   to the defines value
 *   This is used when needs to add more time before timeout whitout Tx
 *
 *  \param nrt_64fcs : no response time in 64/fc = 4.72us
 *                    completion interrupt
 *
 *  \return ERR_PARAM : if time is too large
 */
extern ReturnCode st25r3911SetStartNoResponseTime_64fcs( uint32_t nrt_64fcs );

/*! 
 *****************************************************************************
 *  \brief  Perform Collision Avoidance
 *
 *  Performs Collision Avoidance with the given threshold and with the  
 *  n number of TRFW 
 *  
 *  \param[in] FieldONCmd  : Field ON command to be executed ST25R3911_CMD_INITIAL_RF_COLLISION
 *                           or ST25R3911_CMD_RESPONSE_RF_COLLISION_0/N    
 *  \param[in] pdThreshold : Peer Detection Threshold  (ST25R3916_REG_FIELD_THRESHOLD_trg_xx)
 *                           0xff : don't set Threshold (ST25R3916_THRESHOLD_DO_NOT_SET)
 *  \param[in] caThreshold : Collision Avoidance Threshold (ST25R3916_REG_FIELD_THRESHOLD_rfe_xx)
 *                           0xff : don't set Threshold (ST25R3916_THRESHOLD_DO_NOT_SET)
 *  \param[in] nTRFW       : Number of TRFW
 * 
 *  \return ERR_NONE : no collision detected
 *  \return ERR_RF_COLLISION : collision detected
 */
extern ReturnCode st25r3911PerformCollisionAvoidance( uint8_t FieldONCmd, uint8_t pdThreshold, uint8_t caThreshold, uint8_t nTRFW );


/*! 
 *****************************************************************************
 *  \brief  Get amount of bits of the last FIFO byte if incomplete
 *  
 *  Gets the number of bits of the last FIFO byte if incomplete
 *  
 *  \return the number of bits of the last FIFO byte if incomplete, 0 if 
 *          the last byte is complete
 *    
 *****************************************************************************
 */
extern uint8_t st25r3911GetNumFIFOLastBits( void );

/*! 
 *****************************************************************************
 *  \brief  Get NRT time
 *
 *  This returns the last value set on the NRT
 *   
 *  \warning it does not reads chip register, just the sw var that contains the 
 *  last value set before
 *
 *  \return the value of the NRT
 */
extern uint32_t st25r3911GetNoResponseTime_64fcs( void );

/*! 
 *****************************************************************************
 *  \brief  set general purpose timer timeout
 *
 *  This function sets the proper registers but does not start the timer actually
 *
 *  \param gpt_8fcs : general purpose timer timeout in 8/fc = 590ns
 *
 */
extern void st25r3911SetGPTime_8fcs( uint16_t gpt_8fcs );
/*! 
 *****************************************************************************
 *  \brief  Starts GPT with given timeout
 *
 *  This function starts the general purpose timer with the given timeout
 *
 *  \param gpt_8fcs : general purpose timer timeout in 8/fc = 590ns
 *  \param trigger_source : no trigger, start of Rx, end of Rx, end of Tx in NFC mode 
 */
extern void st25r3911StartGPTimer_8fcs( uint16_t gpt_8fcs, uint8_t trigger_source );

/*! 
 *****************************************************************************
 *  \brief  Checks if register contains a expected value
 *
 *  This function checks if the given reg contains a value that once masked
 *  equals the expected value
 *
 *  \param reg  : the register to check the value
 *  \param mask : the mask apply on register value
 *  \param value  : expected value to be compared to
 *    
 *  \return  true when reg contains the expected value | false otherwise
 */
bool st25r3911CheckReg( uint8_t reg, uint8_t mask, uint8_t value );

/*! 
 *****************************************************************************
 *  \brief  Sets the number Tx Bits
 *  
 *  Sets ST25R3911 internal registers with correct number of complete bytes and
 *  bits to be sent
 *
 *  \param nBits : the number bits to be transmitted  
 *****************************************************************************
 */
void st25r3911SetNumTxBits( uint32_t nBits );

/*! 
 *****************************************************************************
 *  \brief  Check Identity
 *
 *  Checks if the chip ID is as expected.
 *  
 *  5 bit IC type code for ST25R3911: 00001
 *  The 3 lsb contain the IC revision code
 *  
 *
 *  \param[out] rev  : the IC revision code 
 *    
 *  \return  true when IC type is as expected
 *  
 *****************************************************************************
 */
bool st25r3911CheckChipID( uint8_t *rev );

/*! 
 *****************************************************************************
 *  \brief  Check if command is valid
 *
 *  Checks if the given command is a valid ST25R3911 command
 *
 *  \param[in] cmd: Command to check
 *  
 *  \return  true if is a valid command
 *  \return  false otherwise
 *
 *****************************************************************************
 */
bool st25r3911IsCmdValid( uint8_t cmd );

/*! 
 *****************************************************************************
 *  \brief  Configure the stream mode of ST25R3911
 *
 *  This function initializes the stream with the given parameters
 *
 *  \param[in] config : all settings for bitrates, type, etc.

 *  \return ERR_NONE : No error, stream mode driver initialized.
 *
 *****************************************************************************
 */
extern ReturnCode st25r3911StreamConfigure( const struct st25r3911StreamConfig *config );

/*! 
 *****************************************************************************
 *  \brief  Retrieves all  internal registers from st25r3911
 */
extern ReturnCode st25r3911GetRegsDump( uint8_t* resRegDump, uint8_t* sizeRegDump );


/*! 
 *****************************************************************************
 *  \brief  Gets the RSSI values
 *
 *  This function gets the RSSI value of the previous reception taking into 
 *  account the gain reductions that were used. 
 *  RSSI value for both AM and PM channel can be retrieved.
 *
 *  \param[out] amRssi: the RSSI on the AM channel expressed in mV 
 *  \param[out] pmRssi: the RSSI on the PM channel expressed in mV 
 *  
 *  \return ERR_PARAM : Invalid parameter
 *  \return ERR_NONE  : No error
 *  
 *****************************************************************************
 */
ReturnCode st25r3911GetRSSI( uint16_t *amRssi, uint16_t *pmRssi );


#endif /* ST25R3911_H */

/**
  * @}
  *
  * @}
  *
  * @}
  * 
  * @}
  */