unleashed-firmware/lib/ST25RFAL002/include/rfal_st25tb.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_st25tb.h
 *
 *  \author Gustavo Patricio
 *
 *  \brief Implementation of ST25TB interface 
 *
 *
 * \addtogroup RFAL
 * @{
 *
 * \addtogroup RFAL-AL
 * \brief RFAL Abstraction Layer
 * @{
 *
 * \addtogroup ST25TB
 * \brief RFAL ST25TB Module
 * @{
 * 
 */


#ifndef RFAL_ST25TB_H
#define RFAL_ST25TB_H

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

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

#define RFAL_ST25TB_CHIP_ID_LEN      1U       /*!< ST25TB chip ID length       */
#define RFAL_ST25TB_CRC_LEN          2U       /*!< ST25TB CRC length           */
#define RFAL_ST25TB_UID_LEN          8U       /*!< ST25TB Unique ID length     */
#define RFAL_ST25TB_BLOCK_LEN        4U       /*!< ST25TB Data Block length    */

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



/*
******************************************************************************
* GLOBAL TYPES
******************************************************************************
*/
typedef uint8_t rfalSt25tbUID[RFAL_ST25TB_UID_LEN];        /*!< ST25TB UID type          */
typedef uint8_t rfalSt25tbBlock[RFAL_ST25TB_BLOCK_LEN];    /*!< ST25TB Block type        */


/*! ST25TB listener device (PICC) struct  */
typedef struct
{
    uint8_t           chipID;                              /*!< Device's session Chip ID */
    rfalSt25tbUID     UID;                                 /*!< Device's UID             */
    bool              isDeselected;                        /*!< Device deselect flag     */
}rfalSt25tbListenDevice;


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

/*! 
 *****************************************************************************
 * \brief  Initialize ST25TB Poller mode
 *  
 * This methods configures RFAL RF layer to perform as a 
 * ST25TB Poller/RW including all default timings
 *
 * \return ERR_WRONG_STATE  : RFAL not initialized or mode not set
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerInitialize( void );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Check Presence
 *  
 * This method checks if a ST25TB Listen device (PICC) is present on the field
 * by sending an Initiate command
 * 
 * \param[out] chipId : if successfully retrieved, the device's chip ID
 * 
 * \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, no listener device detected
 * \return ERR_RF_COLLISION : Collision detected one or more device in the field
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerCheckPresence( uint8_t *chipId );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Collision Resolution
 *  
 * This method performs ST25TB Collision resolution, selects the each device,
 * retrieves its UID and then deselects.
 * In case only one device is identified the ST25TB device is left in select
 * state.
 *   
 * \param[in]  devLimit      : device limit value, and size st25tbDevList
 * \param[out] st25tbDevList : ST35TB listener device info
 * \param[out] devCnt        : Devices found counter
 * 
 * \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, no listener device detected
 * \return ERR_RF_COLLISION : Collision detected one or more device in the field
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerCollisionResolution( uint8_t devLimit, rfalSt25tbListenDevice *st25tbDevList, uint8_t *devCnt );

/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Initiate
 *  
 * This method sends an Initiate command 
 * 
 * If a single device responds the chip ID will be retrieved
 *   
 * \param[out]  chipId      : chip ID of the device 
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerInitiate( uint8_t *chipId );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Pcall
 *  
 * This method sends a Pcall command 
 * If successful the device's chip ID will be retrieved
 *   
 * \param[out]  chipId      : Chip ID of the device 
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerPcall( uint8_t *chipId );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Slot Marker
 *  
 * This method sends a Slot Marker
 * 
 * If a single device responds the chip ID will be retrieved
 *
 * \param[in]  slotNum      : Slot Number    
 * \param[out]  chipIdRes   : Chip ID of the device 
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerSlotMarker( uint8_t slotNum, uint8_t *chipIdRes );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Select
 *  
 * This method sends a ST25TB Select command with the given chip ID.
 * 
 * If the device is already in Selected state and receives an incorrect chip 
 * ID, it goes into Deselected state
 *   
 * \param[in]  chipId       : chip ID of the device to be selected
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerSelect( uint8_t chipId );


/*! 
 *****************************************************************************
 * \brief  ST25TB Get UID
 *  
 * This method sends a Get_UID command
 * 
 * If a single device responds the chip UID will be retrieved
 *
 * \param[out]  UID      : UID of the found device
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerGetUID( rfalSt25tbUID *UID );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Read Block
 *  
 * This method reads a block of the ST25TB
 * 
 * \param[in]   blockAddress : address of the block to be read
 * \param[out]  blockData    : location to place the data read from block
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerReadBlock( uint8_t blockAddress, rfalSt25tbBlock *blockData  );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Write Block
 *  
 * This method writes a block of the ST25TB
 * 
 * \param[in]  blockAddress : address of the block to be written
 * \param[in]  blockData    : data to be written on the block
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerWriteBlock( uint8_t blockAddress, const rfalSt25tbBlock *blockData  );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Completion 
 *  
 * This method sends a completion command to the ST25TB. After the 
 * completion the card no longer will reply to any command.
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected, invalid SENSB_RES received
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerCompletion( void );


/*! 
 *****************************************************************************
 * \brief  ST25TB Poller Reset to Inventory
 *  
 * This method sends a Reset to Inventory command to the ST25TB.
 * 
 * \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, no listener device detected
 * \return ERR_PROTO        : Protocol error detected, invalid SENSB_RES received
 * \return ERR_NONE         : No error
 *****************************************************************************
 */
ReturnCode rfalSt25tbPollerResetToInventory( void );


#endif /* RFAL_ST25TB_H */

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