NXP NFC Reader Library  v4.040.05.011646

All Public Functions of the NFC Library. More...

Collaboration diagram for NXP NFC Library Functions:

Functions

phNfcLib_Status_t phNfcLib_Init (void)
 Initialize the NFC Library. More...
 
phNfcLib_Status_t phNfcLib_DeInit (void)
 Deinitialize the NFC Library. More...
 
phNfcLib_Status_t phNfcLib_Activate (uint16_t wTechnologyMask, phNfcLib_PeerInfo_t *peerInfo, pphNfcLib_ErrCallbck ErrCallbck)
 Run the Activation Procedure. More...
 
phNfcLib_Status_t phNfcLib_Transmit (void *const pTxBuffer, uint16_t wTxBufferLength)
 Send Data to an Activated Peer. More...
 
phNfcLib_Status_t phNfcLib_Receive (uint8_t *const pRxBuffer, uint16_t *pNumberOfBytes, uint8_t *pMoreDataAvailable)
 Receive Data from an Activated Peer. More...
 
phNfcLib_Status_t phNfcLib_SetConfig (uint8_t bConfigTag, const uint8_t *pConfigParam, uint16_t wConfigParamLength)
 Set Configuration Parameter. More...
 
phNfcLib_Status_t phNfcLib_SetConfig_Value (uint8_t bConfigTag, uint32_t dwValue)
 Set Configuration Parameter using a Value. More...
 
phNfcLib_Status_t phNfcLib_GetConfig (uint8_t bConfigTag, uint8_t *pConfigParam, uint16_t *pConfigParamLength)
 Retrieve a configuration parameter value. More...
 
phNfcLib_Status_t phNfcLib_Deactivate (uint8_t bDeactivateMode, phNfcLib_PeerInfo_t *peerInfo)
 Deactivate an Activated Peer. More...
 
void * phNfcLib_GetDataParams (uint16_t wComponent)
 Retrieve the pointer to the dataparams structure of an internal NFC Reader Library component. More...
 
phNfcLib_Status_t phNfcLib_AsyncAbort (void)
 Used to asynchronously stop HAL waiting for RF event and exit from HAL. More...
 

Detailed Description

All Public Functions of the NFC Library.

Function Documentation

§ phNfcLib_Init()

phNfcLib_Status_t phNfcLib_Init ( void  )

Initialize the NFC Library.

Calling this function initializes the NFC library including all its relevant protocol and hardware abstraction layers. It also calls the initialization functions for the underlying platform. After calling this function all other functions of the phNfcLib module may be used.

Precondition
NFC library must be in state RESET
Postcondition
All APIs are allowed to be called. NFC Library is in state INITIALIZED
Return values
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.

§ phNfcLib_DeInit()

phNfcLib_Status_t phNfcLib_DeInit ( void  )

Deinitialize the NFC Library.

Calling this function resets all internal structures to its default values, releases all allocated resources and calls DeInit of all underlying layers.

Precondition
NFC Library must be in state INITIALIZED
Postcondition
NFC Library is in state RESET. Only phNfcLib_Init is allowed to be called.
Return values
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.

§ phNfcLib_Activate()

phNfcLib_Status_t phNfcLib_Activate ( uint16_t  wTechnologyMask,
phNfcLib_PeerInfo_t peerInfo,
pphNfcLib_ErrCallbck  ErrCallbck 
)

Run the Activation Procedure.

This command starts the activation procedure which in fact implements a discovery loop. This loop performs technology detection (for given technologies using bit mask wTechnologyMask) and, if a technology has been detected, the activation with the associated peer is performed.

The activation procedure can be configured by calling phNfcLib_SetConfig_Value or phNfcLib_SetConfig and appropriate configuration tags (see nfc_lib_config_tags_activation), for instance PH_NFCLIB_CONFIG_ACTIVATION_BLOCKING. These configuration parameters influence the behavior of the activation procedure. The activation procedure also establishes a logical channel which depends on the configured activation_profile. This channel defines how data is being encapsulated when calling phNfcLib_Transmit or phNfcLib_Receive, respectively.

Once a peer has been activated and a channel could be established peerInfo is set with peer_info about the peer and the established link. phNfcLib_Transmit and phNfcLib_Receive may then be used in order to perform data exchange over the established link. In order to deactivate an activated peer/connection phNfcLib_Deactivate has to be called.

Note
  • The activation procedure will always try to resolve collisions (except for activation profile PH_NFCLIB_ACTIVATION_PROFILE_EMVCO). So even if there a multiple peers in proximity (except in case of ISO156936 and ISO18000p3m3), the activation procedure will activate only one peer. The priority (i.e. the order in which technology detection is performed) depends on the configured activation_profile and additionally on the configured activation_prio
  • When polling for multiple technologies, activation procedure always uses bail out after first technology is detected and doesn't poll further for other technologies.
  • When multiple tags/peers are detected, activation procedure uses different mechanism for each technology to resolve and activate tag/peer. Type A : Collision resolution of Type A always resolves the tag with highest UID value, Type B : The first tag to reply to the slot marker command which can be any random tag will be activated ISO 15693 : In Type V, when single tag is placed in vicinity, tag will be moved to selected state using select command (TBD : If detected tag doesn't support Select command) and in case of multiple tags in vicinity, based on discovery loop PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED macro value collision will be resolved and PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED number of tag UID's in proximity are returned to User. ISO 18000p3m3 : When single tag is placed in vicinity, tag will be moved to Open state using Req_Rn command and handle is available which is used to communicate with tag. In case of multiple tags in vicinity, based on discovery loop PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED macro value collision will be resolved and PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED number of tag UII's in proximity are returned to User.
  • In case PH_NFCLIB_ACTIVATION_PROFILE_NFC is configured as activation_profile and underlying protocol is ISO18092 this procedure also tries to perform LLCP activation in order to be able to transmit NDEF messages over SNEP when using phNfcLib_Transmit and phNfcLib_Receive.
Precondition
NFC Library must be in state INITIALIZED or ACTIVATED
Postcondition
After successful activation (PH_NFCLIB_STATUS_PEER_ACTIVATION_DONE) NFC library is in state ACTIVATED.
Return values
PH_NFCLIB_STATUS_PEER_ACTIVATION_DONEActivation procedure could activate a peer and establish a channel. peerInfo holds detailed information about the peer and the associated connection.
PH_NFCLIB_STATUS_MULTIPLE_PEERS_DETECTEDActivation procedure detected multiple peers in RF field based on the discovery loop macro PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED for Type V and 18000p3m3 and these tag identifiers are returned to user as collision need not be resolved to communicate in case of activation_profile is ISO. Detected a collision and was not able to resolve it in case of activation_profile is EMVCo.
PH_NFCLIB_STATUS_PEER_ACTIVATION_FAILEDActivation procedure detected a peer/technology but was not able to properly activate it. Example: PH_NFCLIB_ACTIVATION_PROFILE_NFC is the configure profile but peer does not support LLCP.
PH_NFCLIB_STATUS_NO_PEER_DISCOVEREDIn case activation procedure is configured for activation_blocking non-blocking execution and no peer has been detected within one iteration, activation returns with this status code.
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
Parameters
[in]wTechnologyMaskA bit mask indicating all nfc_lib_definitions_rf_techno activation procedure shall handle during its discovery loop execution.
[out]peerInfoPointer to a phNfcLib_PeerInfo_t structure, to be allocated by the caller. On successful activation of a peer, activation procedure fills the structure with detailed information.
[in]ErrCallbckError callback specific to PH_NFCLIB_ACTIVATION_PROFILE_EMVCO to intimate about errors during polling for EMVCo.

§ phNfcLib_Transmit()

phNfcLib_Status_t phNfcLib_Transmit ( void *const  pTxBuffer,
uint16_t  wTxBufferLength 
)

Send Data to an Activated Peer.

Once a peer has been activated this function can be used to send data to the peer. The channel over which the data is sent to the peer is defined by the configured activation_profile .

Note
Behavior in NFC PROFILE

Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_NFC

  • In case underlying protocol is ISO18092 this function acts as a SNEP client, i.e. connecting to a server in order to push the NDEF record.
  • In case underlying protocol is ISO14443-4 host card emulation, this function is used to read the record of the NDEF emulation.
Behavior in ISO PROFILE

Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_ISO

  • In case detected card is Mifare Ultralight, Classic or Desfire, input to phNfcLib_Transmit will be pointer of type nfc_lib_transmit_metadata. User needs to provide correct information in metadata to communicate with tags.
Precondition
NFC Library must be in state ACTIVATED
Return values
PH_NFCLIB_STATUS_SUCCESSwTxBufferLength bytes given in pTxBuffer have been successfully sent to the peer.
PH_NFCLIB_STATUS_BUFFER_OVERFLOWReceived bytes could not be stored in NFCLIB buffer. User needs to call phNfcLib_Receive API to copy data from NFCLIB buffer to application and then call phNfcLib_Transmit API with pTxBuffer as NULL to receive next set of data.
PH_NFCLIB_STATUS_RF_TIMEOUT_ERRORSent data not acknowledged in time.
PH_NFCLIB_STATUS_RF_PEER_LOSTPeer lost during communication.
PH_NFCLIB_STATUS_RF_PROTOCOL_ERRORGeneral RF protocol violation.
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
Parameters
[in]pTxBufferByte array containing the data to be sent or Metadata in ISO mode.
[in]wTxBufferLengthNumber of bytes to be sent, in fact size of byte array or Zero in case Metadata is sent.

§ phNfcLib_Receive()

phNfcLib_Status_t phNfcLib_Receive ( uint8_t *const  pRxBuffer,
uint16_t pNumberOfBytes,
uint8_t pMoreDataAvailable 
)

Receive Data from an Activated Peer.

This function can be called in order to receive data from an activated peer, in fact after phNfcLib_Activate returned with status PH_NFCLIB_STATUS_PEER_ACTIVATION_DONE. Like phNfcLib_Transmit, data received using this function may get decapsulated from underlying protocol headers, depending on activation_profile configured. See phNfcLib_Transmit for more details.

Note
  • Caller is responsible for implementing correct sequence of phNfcLib_Transmit and phNfcLib_Receive. So depending on the underlying protocol the two APIs have the be called alternately, starting with either transmit or receive, depending on the underlying technology (initiator vs. target).
  • Similar to phNfcLib_Transmit, in case PH_NFCLIB_ACTIVATION_PROFILE_NFC is the active activation_profile and underlying protocol is ISO18092 calling
Behavior in case of NFC PROFILE

Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_NFC

  • In case underlying protocol is ISO18092 this API waits for receiving an NDEF message via SNEP (i.e. phNfcLib_Activate starts a SNEP server and data received via that server socket can be read by this function).
  • In case underlying protocol is ISO14443-4 host card emulation, this function is used to write the record of the NDEF emulation.
    Precondition
    NFC Library must be in state ACTIVATED
    See also
    phNfcLib_Transmit
    Return values
    PH_NFCLIB_STATUS_SUCCESSpNumberOfBytes bytes read from peer and stored in pRxBuffer.
    PH_NFCLIB_STATUS_RF_TIMEOUT_ERRORTimeout waiting for data from peer.
    PH_NFCLIB_STATUS_RF_PEER_LOSTPeer lost during communication (for ISO18092 target and or active communication).
    PH_NFCLIB_STATUS_RF_PROTOCOL_ERRORGeneral RF protocol violation.
    PH_NFCLIB_STATUS_RF_TRANSMISSION_ERRORTransmission error detected, e.g. RF integrity error.
    PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
    PH_NFCLIB_STATUS_BUFFER_OVERFLOWpMoreDataAvailable parameter is set to NULL and pRxBuffer is too small to receive all data.
Parameters
[out]pRxBufferAllocated byte array to which the received data has to be written.
[in,out]pNumberOfBytesMaximum receive size, in fact size of pRxBuffer. On function return it contains the actual number of bytes received, but in case when receiving from 18000p3m3 tag actual number of bits are returned.
[out]pMoreDataAvailableSet to 1, if not all data could be stored and phNfcLib_Receive needs to be called again to receive the remaining data. If all data could be received, this parameter is set to 0. If this parameter is set to NULL and pRxBuffer is too small to receive all data, PH_NFCLIB_STATUS_BUFFER_OVERFLOW is returned.

§ phNfcLib_SetConfig()

phNfcLib_Status_t phNfcLib_SetConfig ( uint8_t  bConfigTag,
const uint8_t pConfigParam,
uint16_t  wConfigParamLength 
)

Set Configuration Parameter.

This function is used to configure the phNfcLib module. It takes the parameter indicated by bConfigTag which should be one of the available configuration tags and sets it to the value given by pConfigParam.

Note
  • For pure integer parameter the helper function phNfcLib_SetConfig_Value can be used instead.
  • phNfcLib_Init resets all configuration parameters to its default value.
Precondition
NFC Library need to be in state INITIALIZED, i.e. after calling phNfcLib_Init, phNfcLib_Deactivate or as long as no activation happened.
Return values
PH_NFCLIB_STATUS_SUCCESSParameter Value successfully set.
PH_NFCLIB_STATUS_INVALID_PARAMETERUnknown configuration tag or wrong length given (wConfigParamLength)
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
Parameters
[in]bConfigTagA configuration tag indicating the parameter to set.
[in]pConfigParamAn array holding the value to be set for the given parameter.
[in]wConfigParamLengthLength of the parameter value, in fact length of pConfigParam

§ phNfcLib_SetConfig_Value()

phNfcLib_Status_t phNfcLib_SetConfig_Value ( uint8_t  bConfigTag,
uint32_t  dwValue 
)

Set Configuration Parameter using a Value.

Like phNfcLib_SetConfig this function is used to configure the phNfcLib module. All configuration tags which take an unsigned integer as value can be set using this function. In fact it's a convenient short cut for the actual phNfcLib_SetConfig function, which does not require passing in a pointer in case only an integer value needs to be set.

Note
  • phNfcLib_Init resets all configuration parameters to its default value.
Precondition
NFC Library need to be in state INITIALIZED, i.e. after calling phNfcLib_Init, phNfcLib_Deactivate or as long as no activation happened for Activation configurations. In case of De-activation configuration NFC Library should not be in state RESET state.
See also
phNfcLib_SetConfig
Return values
PH_NFCLIB_STATUS_SUCCESSParameter Value successfully set.
PH_NFCLIB_STATUS_INVALID_PARAMETERUnknown configuration tag.
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
Parameters
[in]bConfigTagA configuration tag indicating the parameter to set.
[in]dwValueThe value which has to be set for parameter indicated by bConfigTag

§ phNfcLib_GetConfig()

phNfcLib_Status_t phNfcLib_GetConfig ( uint8_t  bConfigTag,
uint8_t pConfigParam,
uint16_t pConfigParamLength 
)

Retrieve a configuration parameter value.

This is the counterpart to phNfcLib_SetConfig, i.e. it can be used to read out the value for a given parameter.

See also
phNfcLib_SetConfig
Precondition
NFC Library need to be in state INITIALIZED or ACTIVATED as no activation happened.
Return values
PH_NFCLIB_STATUS_SUCCESSParameter Value successfully read out.
PH_NFCLIB_STATUS_INVALID_PARAMETERUnknown configuration tag or provided buffer too small.
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
Parameters
[in]bConfigTagA configuration tag indicating the parameter whose value needs to be read out.
[out]pConfigParamAllocated byte array to which the read out value will be written to.
[in,out]pConfigParamLengthSize of pConfigParam. On function return, it holds the actual number of bytes read.

§ phNfcLib_Deactivate()

phNfcLib_Status_t phNfcLib_Deactivate ( uint8_t  bDeactivateMode,
phNfcLib_PeerInfo_t peerInfo 
)

Deactivate an Activated Peer.

The deactivation procedure can be configured by calling phNfcLib_SetConfig_Value with configuration tag De-activation_blocking. This configuration parameter influence the behavior of the deactivation procedure only in EMVCo profile.

After a peer has been activated using phNfcLib_Activate and the caller wants to release it again (e.g. after communication sequences using phNfcLib_Transmit and phNfcLib_Receive have been finished) this API has to be called. Depending on bDeactivateMode parameter the peer gets released using defined release procedure according to the activation_profile. This for instance could indicate if the removal procedure should be performed for PH_NFCLIB_ACTIVATION_PROFILE_EMVCO. In ISO profile, deactivation procedures like HLTA, HLTB, DSL_REQ etc is performed and allows starting a new activation procedure. To releases all RF related resources this function should be called with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RF_OFF. If Deactivation with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RELEASE fails due to card being removed out of proximity or due to some RF irregularity the user may call Deactivation with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RELEASE again or Deactivation with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RF_OFF according to the scenario requirements.

Precondition
NFC Library must be in state ACTIVATED
Postcondition
NFC Library is in state INITIALIZED
Return values
PH_NFCLIB_STATUS_SUCCESSPeer successfully deactivated and released.
PH_NFCLIB_STATUS_INVALID_STATENFC Library had been in a wrong state when calling this function.
PH_NFCLIB_STATUS_PEER_DEACTIVATION_FAILEDPeer deactivation is not successful (this error code is returned only when config De-activation_blocking is set to PH_OFF). Internal state move to Deactivation Ongoing State. phNfcLib_Deactivate has to be called in loop to check if peer deactivation is successful.
Parameters
[in]bDeactivateModeDeactivation mode/behavior. Refer to nfc_lib_definitions_deactivation_mode for more information.
[in]peerInfoPointer to a phNfcLib_PeerInfo_t structure updated by /ref phNfcLib_Activate API.

§ phNfcLib_GetDataParams()

void* phNfcLib_GetDataParams ( uint16_t  wComponent)

Retrieve the pointer to the dataparams structure of an internal NFC Reader Library component.

The NfcLib encapsulates all relevant NFC Reader Library components. In case a caller needs to directly access one of the components a pointer to the dataparams is required. This function returns the pointer to the dataparams structure of the component indicated with wComponent.

Example
// manually switch on the RF field
Returns
Pointer to the component's dataparam structure. NULL in case phNfcLib is not managing the component indicated by wComponent or NFC library is in state RESET.
Parameters
[in]wComponentThe component ID for which the data params pointer should be returned. For possible value refer to ph_Status.h, PH_COMP_*

§ phNfcLib_AsyncAbort()

phNfcLib_Status_t phNfcLib_AsyncAbort ( void  )

Used to asynchronously stop HAL waiting for RF event and exit from HAL.

Note: This function will post an 'abort' event which is used by the HAL to move into 'Idle' state and exit from polling for RF Event. The functions that were waiting for a HAL event will return PH_ERR_ABORTED error code once this function is executed.

This function shall be called in a task other than the task where reader library is running. This API can be called at any time after the phNfcLib_Init(); and any of the NFCLIB operations like transmit and receive are in progress.

Return values
PH_NFCLIB_STATUS_SUCCESSOperation successful.