unleashed-firmware/lib/ST25RFAL002/include/rfal_nfca.h

/******************************************************************************
  * \attention
  *
  * <h2><center>&copy; COPYRIGHT 2020 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:   ST25R391x firmware
 *      Revision:
 *      LANGUAGE:  ISO C99
 */

/*! \file rfal_nfca.h
 *
 *  \author Gustavo Patricio
 *
 *  \brief Provides several NFC-A convenience methods and definitions
 *  
 *  It provides a Poller (ISO14443A PCD) interface and as well as 
 *  some NFC-A Listener (ISO14443A PICC) helpers.
 *
 *  The definitions and helpers methods provided by this module are only
 *  up to ISO14443-3 layer
 *  
 *  
 *  An usage example is provided here: \ref exampleRfalNfca.c
 *  \example exampleRfalNfca.c
 *  
 *  
 * \addtogroup RFAL
 * @{
 *
 * \addtogroup RFAL-AL
 * \brief RFAL Abstraction Layer
 * @{
 *
 * \addtogroup NFC-A
 * \brief RFAL NFC-A Module
 * @{
 * 
 */


#ifndef RFAL_NFCA_H
#define RFAL_NFCA_H

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

/*
 ******************************************************************************
 * GLOBAL DEFINES
 ******************************************************************************
 */

#define RFAL_NFCA_CASCADE_1_UID_LEN                           4U    /*!< UID length of cascade level 1 only tag                            */
#define RFAL_NFCA_CASCADE_2_UID_LEN                           7U    /*!< UID length of cascade level 2 only tag                            */
#define RFAL_NFCA_CASCADE_3_UID_LEN                           10U   /*!< UID length of cascade level 3 only tag                            */

#define RFAL_NFCA_SENS_RES_PLATFORM_MASK                      0x0FU /*!< SENS_RES (ATQA) platform configuration mask  Digital 1.1 Table 10 */
#define RFAL_NFCA_SENS_RES_PLATFORM_T1T                       0x0CU /*!< SENS_RES (ATQA) T1T platform configuration  Digital 1.1 Table 10  */

#define RFAL_NFCA_SEL_RES_CONF_MASK                           0x60U /*!< SEL_RES (SAK) platform configuration mask  Digital 1.1 Table 19   */
#define RFAL_NFCA_SEL_RES_CONF_T2T                            0x00U /*!< SEL_RES (SAK) T2T configuration  Digital 1.1 Table 19             */
#define RFAL_NFCA_SEL_RES_CONF_T4T                            0x20U /*!< SEL_RES (SAK) T4T configuration  Digital 1.1 Table 19             */
#define RFAL_NFCA_SEL_RES_CONF_NFCDEP                         0x40U /*!< SEL_RES (SAK) NFC-DEP configuration  Digital 1.1 Table 19         */
#define RFAL_NFCA_SEL_RES_CONF_T4T_NFCDEP                     0x60U /*!< SEL_RES (SAK) T4T and NFC-DEP configuration  Digital 1.1 Table 19 */


/*! NFC-A minimum FDT(listen) = ((n * 128 + (84)) / fc) with n_min = 9      Digital 1.1  6.10.1
 *                            = (1236)/fc
 * Relax with 3etu: (3*128)/fc as with multiple NFC-A cards, response may take longer (JCOP cards)
 *                            = (1236 + 384)/fc = 1620 / fc                                      */
#define RFAL_NFCA_FDTMIN          1620U
/*
 ******************************************************************************
 * GLOBAL MACROS
 ******************************************************************************
 */

/*! Checks if device is a T1T given its SENS_RES */
#define rfalNfcaIsSensResT1T( sensRes )          ((((rfalNfcaSensRes*)(sensRes))->platformInfo & RFAL_NFCA_SENS_RES_PLATFORM_MASK) == RFAL_NFCA_SENS_RES_PLATFORM_T1T )

/*! Checks if device is a T2T given its SENS_RES */
#define rfalNfcaIsSelResT2T( selRes )            ((((rfalNfcaSelRes*)(selRes))->sak & RFAL_NFCA_SEL_RES_CONF_MASK) == RFAL_NFCA_SEL_RES_CONF_T2T )

/*! Checks if device is a T4T given its SENS_RES */
#define rfalNfcaIsSelResT4T( selRes )            ((((rfalNfcaSelRes*)(selRes))->sak & RFAL_NFCA_SEL_RES_CONF_MASK) == RFAL_NFCA_SEL_RES_CONF_T4T )

/*! Checks if device supports NFC-DEP protocol given its SENS_RES */
#define rfalNfcaIsSelResNFCDEP( selRes )         ((((rfalNfcaSelRes*)(selRes))->sak & RFAL_NFCA_SEL_RES_CONF_MASK) == RFAL_NFCA_SEL_RES_CONF_NFCDEP )

/*! Checks if device supports ISO-DEP and NFC-DEP protocol given its SENS_RES */
#define rfalNfcaIsSelResT4TNFCDEP( selRes )      ((((rfalNfcaSelRes*)(selRes))->sak & RFAL_NFCA_SEL_RES_CONF_MASK) == RFAL_NFCA_SEL_RES_CONF_T4T_NFCDEP )

/*! Checks if a NFC-A listener device supports multiple protocols (ISO-DEP and NFC-DEP) */
#define rfalNfcaLisDevIsMultiProto( lisDev )     (((rfalNfcaListenDevice*)(lisDev))->type == RFAL_NFCA_T4T_NFCDEP )

/*
******************************************************************************
* GLOBAL TYPES
******************************************************************************
*/

/*! NFC-A Listen device types */
typedef enum {
    RFAL_NFCA_T1T        = 0x01,                                  /* Device configured for T1T  Digital 1.1 Table 9                               */
    RFAL_NFCA_T2T        = 0x00,                                  /* Device configured for T2T  Digital 1.1 Table 19                              */
    RFAL_NFCA_T4T        = 0x20,                                  /* Device configured for T4T  Digital 1.1 Table 19                              */
    RFAL_NFCA_NFCDEP     = 0x40,                                  /* Device configured for NFC-DEP  Digital 1.1 Table 19                          */
    RFAL_NFCA_T4T_NFCDEP = 0x60                                   /* Device configured for NFC-DEP and T4T  Digital 1.1 Table 19                  */
} rfalNfcaListenDeviceType;


/*! SENS_RES (ATQA) format  Digital 1.1  6.6.3 & Table 7 */
typedef struct
{ 
    uint8_t      anticollisionInfo;                               /*!< SENS_RES Anticollision Information                                         */
    uint8_t      platformInfo;                                    /*!< SENS_RES Platform Information                                              */
} rfalNfcaSensRes;


/*! SDD_REQ (Anticollision) format   Digital 1.1  6.7.1 & Table 11 */
typedef struct
{
    uint8_t      selCmd;                                          /*!< SDD_REQ SEL_CMD: cascade Level                                             */
    uint8_t      selPar;                                          /*!< SDD_REQ SEL_PAR: Byte Count[4b] | Bit Count[4b] (NVB: Number of Valid Bits)*/
} rfalNfcaSddReq;


/*! SDD_RES (UID CLn) format   Digital 1.1  6.7.2 & Table 15 */
typedef struct
{
    uint8_t      nfcid1[RFAL_NFCA_CASCADE_1_UID_LEN];             /*!< NFCID1 cascade level NFCID                                                 */
    uint8_t      bcc;                                             /*!< BCC Exclusive-OR over first 4 bytes of SDD_RES                             */
} rfalNfcaSddRes;


/*! SEL_REQ (Select) format   Digital 1.1  6.8.1 & Table 17 */
typedef struct
{
    uint8_t      selCmd;                                          /*!< SDD_REQ SEL_CMD: cascade Level                                             */
    uint8_t      selPar;                                          /*!< SDD_REQ SEL_PAR: Byte Count[4b] | Bit Count[4b] (NVB: Number of Valid Bits)*/
    uint8_t      nfcid1[RFAL_NFCA_CASCADE_1_UID_LEN];             /*!< NFCID1 data                                                                */
    uint8_t      bcc;                                             /*!< Checksum calculated as exclusive-OR over the 4 bytes of NFCID1 CLn         */
} rfalNfcaSelReq;


/*! SEL_RES (SAK) format   Digital 1.1  6.8.2 & Table 19 */
typedef struct
{
    uint8_t      sak;                                             /*!< Select Acknowledge                                                         */
} rfalNfcaSelRes;


/*! NFC-A listener device (PICC) struct  */
typedef struct
{
    rfalNfcaListenDeviceType type;                                /*!< NFC-A Listen device type                                                   */
    rfalNfcaSensRes          sensRes;                             /*!< SENS_RES (ATQA)                                                            */
    rfalNfcaSelRes           selRes;                              /*!< SEL_RES  (SAK)                                                             */
    uint8_t                  nfcId1Len;                           /*!< NFCID1 Length                                                              */
    uint8_t                  nfcId1[RFAL_NFCA_CASCADE_3_UID_LEN]; /*!< NFCID1   (UID)                                                             */
#ifdef RFAL_FEATURE_T1T
    rfalT1TRidRes            ridRes;                              /*!< RID_RES                                                                    */
#endif /* RFAL_FEATURE_T1T */
    bool                     isSleep;                             /*!< Device sleeping flag                                                       */
} rfalNfcaListenDevice;

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

/*! 
 *****************************************************************************
 * \brief  Initialize NFC-A Poller mode
 *  
 * This methods configures RFAL RF layer to perform as a 
 * NFC-A Poller/RW (ISO14443A PCD) including all default timings and bit rate
 * to 106 kbps
 
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or mode not set
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerInitialize( void );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Check Presence
 *  
 * This method checks if a NFC-A Listen device (PICC) is present on the field
 * by sending an ALL_REQ (WUPA) or SENS_REQ (REQA)
 *  
 * \param[in]  cmd     : Indicate if to send an ALL_REQ or a SENS_REQ
 * \param[out] sensRes : If received, the SENS_RES
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or incorrect mode
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error 
 * \return ERR_RF_COLLISION : Collision detected one or more device in the field
 * \return ERR_PAR          : Parity error detected, one or more device in the field
 * \return ERR_CRC          : CRC error detected, one or more device in the field
 * \return ERR_FRAMING      : Framing error detected, one or more device in the field
 * \return ERR_PROTO        : Protocol error detected, one or more device in the field
 * \return ERR_TIMEOUT      : Timeout error, no listener device detected
 * \return ERR_NONE         : No error, one or more device in the field
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerCheckPresence( rfal14443AShortFrameCmd cmd, rfalNfcaSensRes *sensRes );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Select
 *  
 * This method selects a NFC-A Listener device (PICC) 
 *  
 * \param[in]  nfcid1   : Listener device NFCID1 to be selected
 * \param[in]  nfcidLen : Length of the NFCID1 to be selected  
 * \param[out] selRes   : pointer to place the SEL_RES
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or incorrect mode
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_TIMEOUT      : Timeout error
 * \return ERR_PAR          : Parity error detected
 * \return ERR_CRC          : CRC error detected
 * \return ERR_FRAMING      : Framing error detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error, SEL_RES received
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerSelect( const uint8_t *nfcid1, uint8_t nfcidLen, rfalNfcaSelRes *selRes );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Sleep
 *  
 * This method sends a SLP_REQ (HLTA)
 * No response is expected afterwards   Digital 1.1  6.9.2.1 
 *  
 * \return ERR_WRONG_STATE  : RFAL not initialized or incorrect mode
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerSleep( void );


/*!
 *****************************************************************************
 * \brief  NFC-A Technology Detection
 *  
 * This method performs NFC-A Technology Detection as defined in the spec
 * given in the compliance mode
 *  
 * \param[in]  compMode  : compliance mode to be performed
 * \param[out] sensRes   : location to store the SENS_RES, if received
 * 
 * When compMode is set to ISO compliance a SLP_REQ (HLTA) is not sent 
 * after detection. When set to EMV a ALL_REQ (WUPA) is sent instead of 
 * a SENS_REQ (REQA)
 *  
 * \return ERR_WRONG_STATE  : RFAL not initialized or incorrect mode
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_NONE         : No error, one or more device in the field
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerTechnologyDetection( rfalComplianceMode compMode, rfalNfcaSensRes *sensRes );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Collision Resolution
 *  
 * Collision resolution for one NFC-A Listener device/card (PICC) as 
 * defined in Activity 2.1  9.3.4
 * 
 * This method executes anti collision loop and select the device with higher NFCID1
 * 
 * When devLimit = 0 it is configured to perform collision detection only. Once a collision 
 * is detected the collision resolution is aborted immidiatly. If only one device is found
 * with no collisions, it will properly resolved. 
 *
 * \param[in]  devLimit    : device limit value (CON_DEVICES_LIMIT)
 * \param[out] collPending : pointer to collision pending flag (INT_COLL_PEND)
 * \param[out] selRes      : location to store the last Select Response from listener device (PICC)
 * \param[out] nfcId1      : location to store the NFCID1 (UID), ensure RFAL_NFCA_CASCADE_3_UID_LEN
 * \param[out] nfcId1Len   : pointer to length of NFCID1 (UID)
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or mode not set
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_PROTO        : Card length invalid
 * \return ERR_IGNORE       : conDevLimit is 0 and there is a collision
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerSingleCollisionResolution( uint8_t devLimit, bool *collPending, rfalNfcaSelRes *selRes, uint8_t *nfcId1, uint8_t *nfcId1Len );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Full Collision Resolution
 *  
 * Performs a full Collision resolution as defined in Activity 2.1  9.3.4
 *
 * \param[in]  compMode    : compliance mode to be performed
 * \param[in]  devLimit    : device limit value, and size nfcaDevList
 * \param[out] nfcaDevList : NFC-A listener device info
 * \param[out] devCnt      : Devices found counter
 *
 * When compMode is set to ISO compliance it assumes that the device is
 * not sleeping and therefore no ALL_REQ (WUPA) is sent at the beginning.
 * When compMode is set to NFC compliance an additional ALL_REQ (WUPA) is sent 
 * at the beginning.
 *  
 *  
 * When devLimit = 0 it is configured to perform collision detection only. Once a collision 
 * is detected the collision resolution is aborted immidiatly. If only one device is found
 * with no collisions, it will properly resolved.
 *
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or mode not set
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerFullCollisionResolution( rfalComplianceMode compMode, uint8_t devLimit, rfalNfcaListenDevice *nfcaDevList, uint8_t *devCnt );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Full Collision Resolution with Sleep
 *  
 * Performs a full Collision resolution similar to rfalNfcaPollerFullCollisionResolution
 * but an additional SLP_REQ (HLTA) -> SENS_RES (REQA) is sent regardless if there 
 * was a collision.
 * This proprietary behaviour ensures proper activation of certain devices that suffer
 * from influence of Type B commands as foreseen in ISO14443-3 5.2.3 or were somehow
 * not detected by the first round of collision resolution
 *
 * \param[in]  devLimit    : device limit value, and size nfcaDevList
 * \param[out] nfcaDevList : NFC-A listener device info
 * \param[out] devCnt      : Devices found counter
 *  
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or mode not set
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerSleepFullCollisionResolution( uint8_t devLimit, rfalNfcaListenDevice *nfcaDevList, uint8_t *devCnt );


/*! 
 *****************************************************************************
 * \brief  NFC-A Poller Start Full Collision Resolution
 *  
 * This method starts the full Collision resolution as defined 
  * in Activity 1.0 or 1.1  9.3.4
 *
 * \param[in]  compMode    : compliance mode to be performed
 * \param[in]  devLimit    : device limit value, and size nfcaDevList
 * \param[out] nfcaDevList : NFC-A listener device info
 * \param[out] devCnt      : Devices found counter
 *
 * When compMode is set to ISO compliance it assumes that the device is
 * not sleeping and therefore no ALL_REQ (WUPA) is sent at the beginning.
 * When compMode is set to NFC compliance an additional ALL_REQ (WUPA) is sent at 
 * the beginning.
 *  
 *  
 * When devLimit = 0 it is configured to perform collision detection only. Once a collision 
 * is detected the collision resolution is aborted immidiatly. If only one device is found
 * with no collisions, it will properly resolved.
 *
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or mode not set
 * \return ERR_PARAM        : Invalid parameters
 * \return ERR_IO           : Generic internal error
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerStartFullCollisionResolution( rfalComplianceMode compMode, uint8_t devLimit, rfalNfcaListenDevice *nfcaDevList, uint8_t *devCnt );


/*!
 *****************************************************************************
 *  \brief  NFC-A Get Full Collision Resolution Status
 *
 *  Returns the Collision Resolution status
 *
 *  \return ERR_BUSY         : Operation is ongoing
 *  \return ERR_WRONG_STATE  : RFAL not initialized or incorrect mode
 *  \return ERR_PARAM        : Invalid parameters
 *  \return ERR_IO           : Generic internal error
 *  \return ERR_TIMEOUT      : Timeout error
 *  \return ERR_PAR          : Parity error detected
 *  \return ERR_CRC          : CRC error detected
 *  \return ERR_FRAMING      : Framing error detected
 *  \return ERR_PROTO        : Protocol error detected
 *  \return ERR_NONE         : No error, activation successful
 *****************************************************************************
 */
ReturnCode rfalNfcaPollerGetFullCollisionResolutionStatus( void );


/*!
 *****************************************************************************
 * \brief NFC-A Listener is SLP_REQ 
 * 
 * Checks if the given buffer contains valid NFC-A SLP_REQ (HALT)
 * 
 * \param[in] buf: buffer containing data
 * \param[in] bufLen: length of the data in buffer to be checked
 * 
 * \return true if data in buf contains a SLP_REQ ; false otherwise
 *****************************************************************************
 */
bool rfalNfcaListenerIsSleepReq( const uint8_t *buf, uint16_t bufLen );

#endif /* RFAL_NFCA_H */

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