Flipper Zero Firmware
Loading...
Searching...
No Matches
nfc.h File Reference

Transport layer Nfc library. More...

#include <toolbox/bit_buffer.h>

Go to the source code of this file.

Data Structures

struct  NfcEventData
 Nfc event data structure. More...
 
struct  NfcEvent
 Nfc event structure. More...
 

Typedefs

typedef struct Nfc Nfc
 Nfc opaque type definition.
 
typedef NfcCommand(* NfcEventCallback) (NfcEvent event, void *context)
 Nfc event callback type.
 

Enumerations

enum  NfcEventType {
  NfcEventTypeUserAbort , NfcEventTypeFieldOn , NfcEventTypeFieldOff , NfcEventTypeTxStart ,
  NfcEventTypeTxEnd , NfcEventTypeRxStart , NfcEventTypeRxEnd , NfcEventTypeListenerActivated ,
  NfcEventTypePollerReady
}
 Enumeration of possible Nfc event types. More...
 
enum  NfcCommand { NfcCommandContinue , NfcCommandReset , NfcCommandStop , NfcCommandSleep }
 Enumeration of possible Nfc commands. More...
 
enum  NfcMode { NfcModePoller , NfcModeListener , NfcModeNum }
 Enumeration of possible operating modes. More...
 
enum  NfcTech {
  NfcTechIso14443a , NfcTechIso14443b , NfcTechIso15693 , NfcTechFelica ,
  NfcTechNum
}
 Enumeration of available technologies. More...
 
enum  NfcError {
  NfcErrorNone , NfcErrorInternal , NfcErrorTimeout , NfcErrorIncompleteFrame ,
  NfcErrorDataFormat
}
 Enumeration of possible Nfc error codes. More...
 
enum  NfcIso14443aShortFrame { NfcIso14443aShortFrameSensReq , NfcIso14443aShortFrameAllReqa }
 Enumeration of possible ISO14443-3A short frame types.
 

Functions

Nfcnfc_alloc (void)
 Allocate an Nfc instance.
 
void nfc_free (Nfc *instance)
 Delete an Nfc instance.
 
void nfc_config (Nfc *instance, NfcMode mode, NfcTech tech)
 Configure the Nfc instance to work in a particular mode.
 
void nfc_set_fdt_poll_fc (Nfc *instance, uint32_t fdt_poll_fc)
 Set poller frame delay time.
 
void nfc_set_fdt_listen_fc (Nfc *instance, uint32_t fdt_listen_fc)
 Set listener frame delay time.
 
void nfc_set_mask_receive_time_fc (Nfc *instance, uint32_t mask_rx_time_fc)
 Set mask receive time.
 
void nfc_set_fdt_poll_poll_us (Nfc *instance, uint32_t fdt_poll_poll_us)
 Set frame delay time.
 
void nfc_set_guard_time_us (Nfc *instance, uint32_t guard_time_us)
 Set guard time.
 
void nfc_start (Nfc *instance, NfcEventCallback callback, void *context)
 Start the Nfc instance.
 
void nfc_stop (Nfc *instance)
 Stop Nfc instance.
 
NfcError nfc_poller_trx (Nfc *instance, const BitBuffer *tx_buffer, BitBuffer *rx_buffer, uint32_t fwt)
 Transmit and receive a data frame in poller mode.
 
NfcError nfc_listener_tx (Nfc *instance, const BitBuffer *tx_buffer)
 Transmit a data frame in listener mode.
 
NfcError nfc_iso14443a_poller_trx_short_frame (Nfc *instance, NfcIso14443aShortFrame frame, BitBuffer *rx_buffer, uint32_t fwt)
 Transmit an ISO14443-3A short frame and receive the response in poller mode.
 
NfcError nfc_iso14443a_poller_trx_sdd_frame (Nfc *instance, const BitBuffer *tx_buffer, BitBuffer *rx_buffer, uint32_t fwt)
 Transmit an ISO14443-3A SDD frame and receive the response in poller mode.
 
NfcError nfc_iso14443a_poller_trx_custom_parity (Nfc *instance, const BitBuffer *tx_buffer, BitBuffer *rx_buffer, uint32_t fwt)
 Transmit an ISO14443-3A data frame with custom parity bits and receive the response in poller mode.
 
NfcError nfc_iso14443a_listener_tx_custom_parity (Nfc *instance, const BitBuffer *tx_buffer)
 Transmit an ISO14443-3A frame with custom parity bits in listener mode.
 
NfcError nfc_iso14443a_listener_set_col_res_data (Nfc *instance, uint8_t *uid, uint8_t uid_len, uint8_t *atqa, uint8_t sak)
 Set ISO14443-3A collision resolution parameters in listener mode.
 
NfcError nfc_felica_listener_set_sensf_res_data (Nfc *instance, const uint8_t *idm, const uint8_t idm_len, const uint8_t *pmm, const uint8_t pmm_len)
 Set FeliCa collision resolution parameters in listener mode.
 
NfcError nfc_iso15693_listener_tx_sof (Nfc *instance)
 Send ISO15693 Start of Frame pattern in listener mode.
 

Detailed Description

Transport layer Nfc library.

The Nfc layer is responsible for setting the operating mode (poller or listener) and technology (ISO14443-3A/B, ISO15693, ...), data exchange between higher protocol-specific levels and underlying NFC hardware, as well as timings handling.

In applications using the NFC protocol system there is no need to neiter explicitly create an Nfc instance nor call any of its functions, as it is all handled automatically under the hood.

If the NFC protocol system is not suitable for the application's intended purpose or there is need of having direct access to the NFC transport layer, then an Nfc instance must be allocated and the below functions shall be used to implement the required logic.

Typedef Documentation

◆ NfcEventCallback

typedef NfcCommand(* NfcEventCallback) (NfcEvent event, void *context)

Nfc event callback type.

A function of this type must be passed as the callback parameter upon start of a an Nfc instance.

Parameters
[in]eventNfc event, passed by value, complete with protocol type and data.
[in,out]contextpointer to the user-specific context (set when starting an Nfc instance).
Returns
command which the event producer must execute.

Enumeration Type Documentation

◆ NfcCommand

enum NfcCommand

Enumeration of possible Nfc commands.

The event callback must return one of these to determine the next action.

Enumerator
NfcCommandContinue 

Continue operation normally.

NfcCommandReset 

Reset the current state.

NfcCommandStop 

Stop the current operation.

NfcCommandSleep 

Switch Nfc hardware to low-power mode.

◆ NfcError

enum NfcError

Enumeration of possible Nfc error codes.

Enumerator
NfcErrorNone 

No error has occurred.

NfcErrorInternal 

An unknown error has occured on the lower level.

NfcErrorTimeout 

Operation is taking too long (e.g.

card does not respond).

NfcErrorIncompleteFrame 

An incomplete data frame has been received.

NfcErrorDataFormat 

Data has not been parsed due to wrong/unknown format.

◆ NfcEventType

Enumeration of possible Nfc event types.

Not all technologies implement all events (this is due to hardware limitations).

Enumerator
NfcEventTypeUserAbort 

User code explicitly aborted the current operation.

NfcEventTypeFieldOn 

Reader's field was detected by the NFC hardware.

NfcEventTypeFieldOff 

Reader's field was lost.

NfcEventTypeTxStart 

Data transmission has started.

NfcEventTypeTxEnd 

Data transmission has ended.

NfcEventTypeRxStart 

Data reception has started.

NfcEventTypeRxEnd 

Data reception has ended.

NfcEventTypeListenerActivated 

The listener has been activated by the reader.

NfcEventTypePollerReady 

The card has been activated by the poller.

◆ NfcMode

enum NfcMode

Enumeration of possible operating modes.

Not all technologies implement the listener operating mode.

Enumerator
NfcModePoller 

Configure the Nfc instance as a poller.

NfcModeListener 

Configure the Nfc instance as a listener.

NfcModeNum 

Operating mode count.

Internal use.

◆ NfcTech

enum NfcTech

Enumeration of available technologies.

Enumerator
NfcTechIso14443a 

Configure the Nfc instance to use the ISO14443-3A technology.

NfcTechIso14443b 

Configure the Nfc instance to use the ISO14443-3B technology.

NfcTechIso15693 

Configure the Nfc instance to use the ISO15693 technology.

NfcTechFelica 

Configure the Nfc instance to use the FeliCa technology.

NfcTechNum 

Technologies count.

Internal use.

Function Documentation

◆ nfc_alloc()

Nfc * nfc_alloc ( void )

Allocate an Nfc instance.

Will exclusively take over the NFC HAL until deleted.

Returns
pointer to the allocated Nfc instance.

◆ nfc_config()

void nfc_config ( Nfc * instance,
NfcMode mode,
NfcTech tech )

Configure the Nfc instance to work in a particular mode.

Not all technologies implement the listener operating mode.

Parameters
[in,out]instancepointer to the instance to be configured.
[in]moderequired operating mode.
[in]techrequired technology configuration.

◆ nfc_felica_listener_set_sensf_res_data()

NfcError nfc_felica_listener_set_sensf_res_data ( Nfc * instance,
const uint8_t * idm,
const uint8_t idm_len,
const uint8_t * pmm,
const uint8_t pmm_len )

Set FeliCa collision resolution parameters in listener mode.

Configures the NFC hardware for automatic collision resolution.

Parameters
[in,out]instancepointer to the instance to be configured.
[in]idmpointer to a byte array containing the IDm.
[in]idm_lenIDm length in bytes.
[in]pmmpointer to a byte array containing the PMm.
[in]pmm_lenPMm length in bytes.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_free()

void nfc_free ( Nfc * instance)

Delete an Nfc instance.

Will release the NFC HAL lock, making it available for use by others.

Parameters
[in,out]instancepointer to the instance to be deleted.

◆ nfc_iso14443a_listener_set_col_res_data()

NfcError nfc_iso14443a_listener_set_col_res_data ( Nfc * instance,
uint8_t * uid,
uint8_t uid_len,
uint8_t * atqa,
uint8_t sak )

Set ISO14443-3A collision resolution parameters in listener mode.

Configures the NFC hardware for automatic collision resolution.

Parameters
[in,out]instancepointer to the instance to be configured.
[in]uidpointer to a byte array containing the UID.
[in]uid_lenUID length in bytes (must be supported by the protocol).
[in]atqaATQA byte value.
[in]sakSAK byte value.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_iso14443a_listener_tx_custom_parity()

NfcError nfc_iso14443a_listener_tx_custom_parity ( Nfc * instance,
const BitBuffer * tx_buffer )

Transmit an ISO14443-3A frame with custom parity bits in listener mode.

Same as nfc_listener_tx(), but uses the parity bits provided by the user code instead of calculating them automatically.

Parameters
[in,out]instancepointer to the instance to be used in the transaction.
[in]tx_bufferpointer to the buffer containing the data to be transmitted.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_iso14443a_poller_trx_custom_parity()

NfcError nfc_iso14443a_poller_trx_custom_parity ( Nfc * instance,
const BitBuffer * tx_buffer,
BitBuffer * rx_buffer,
uint32_t fwt )

Transmit an ISO14443-3A data frame with custom parity bits and receive the response in poller mode.

Same as nfc_poller_trx(), but uses the parity bits provided by the user code instead of calculating them automatically.

Parameters
[in,out]instancepointer to the instance to be used in the transaction.
[in]tx_bufferpointer to the buffer containing the data to be transmitted.
[out]rx_bufferpointer to the buffer to be filled with received data.
[in]fwtframe wait time (response timeout), in carrier cycles.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_iso14443a_poller_trx_sdd_frame()

NfcError nfc_iso14443a_poller_trx_sdd_frame ( Nfc * instance,
const BitBuffer * tx_buffer,
BitBuffer * rx_buffer,
uint32_t fwt )

Transmit an ISO14443-3A SDD frame and receive the response in poller mode.

Parameters
[in,out]instancepointer to the instance to be used in the transaction.
[in]tx_bufferpointer to the buffer containing the data to be transmitted.
[out]rx_bufferpointer to the buffer to be filled with received data.
[in]fwtframe wait time (response timeout), in carrier cycles.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_iso14443a_poller_trx_short_frame()

NfcError nfc_iso14443a_poller_trx_short_frame ( Nfc * instance,
NfcIso14443aShortFrame frame,
BitBuffer * rx_buffer,
uint32_t fwt )

Transmit an ISO14443-3A short frame and receive the response in poller mode.

Parameters
[in,out]instancepointer to the instance to be used in the transaction.
[in]frametype of short frame to be sent.
[out]rx_bufferpointer to the buffer to be filled with received data.
[in]fwtframe wait time (response timeout), in carrier cycles.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_iso15693_listener_tx_sof()

NfcError nfc_iso15693_listener_tx_sof ( Nfc * instance)

Send ISO15693 Start of Frame pattern in listener mode.

Parameters
[in,out]instancepointer to the instance to be configured.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_listener_tx()

NfcError nfc_listener_tx ( Nfc * instance,
const BitBuffer * tx_buffer )

Transmit a data frame in listener mode.

Used to transmit a response to the reader request in listener mode.

The data being transmitted may be either bit- or byte-oriented. It shall not contain any technology-specific sequences as start or stop bits and/or other special symbols, as this is handled on the underlying HAL level.

Must ONLY be used inside the callback function.

Parameters
[in,out]instancepointer to the instance to be used in the transaction.
[in]tx_bufferpointer to the buffer containing the data to be transmitted.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_poller_trx()

NfcError nfc_poller_trx ( Nfc * instance,
const BitBuffer * tx_buffer,
BitBuffer * rx_buffer,
uint32_t fwt )

Transmit and receive a data frame in poller mode.

The rx_buffer will be filled with any data received as a response to data sent from tx_buffer, with a timeout defined by the fwt parameter.

The data being transmitted and received may be either bit- or byte-oriented. It shall not contain any technology-specific sequences as start or stop bits and/or other special symbols, as this is handled on the underlying HAL level.

Must ONLY be used inside the callback function.

Parameters
[in,out]instancepointer to the instance to be used in the transaction.
[in]tx_bufferpointer to the buffer containing the data to be transmitted.
[out]rx_bufferpointer to the buffer to be filled with received data.
[in]fwtframe wait time (response timeout), in carrier cycles.
Returns
NfcErrorNone on success, any other error code on failure.

◆ nfc_set_fdt_listen_fc()

void nfc_set_fdt_listen_fc ( Nfc * instance,
uint32_t fdt_listen_fc )

Set listener frame delay time.

Parameters
[in,out]instancepointer to the instance to be modified.
[in]fdt_listen_fcframe delay time, in carrier cycles.

◆ nfc_set_fdt_poll_fc()

void nfc_set_fdt_poll_fc ( Nfc * instance,
uint32_t fdt_poll_fc )

Set poller frame delay time.

Parameters
[in,out]instancepointer to the instance to be modified.
[in]fdt_poll_fcframe delay time, in carrier cycles.

◆ nfc_set_fdt_poll_poll_us()

void nfc_set_fdt_poll_poll_us ( Nfc * instance,
uint32_t fdt_poll_poll_us )

Set frame delay time.

Frame delay time is the minimum time between two consecutive poll frames.

Parameters
[in,out]instancepointer to the instance to be modified.
[in]fdt_poll_poll_usframe delay time, in microseconds.

◆ nfc_set_guard_time_us()

void nfc_set_guard_time_us ( Nfc * instance,
uint32_t guard_time_us )

Set guard time.

Parameters
[in,out]instancepointer to the instance to be modified.
[in]guard_time_usguard time, in microseconds.

◆ nfc_set_mask_receive_time_fc()

void nfc_set_mask_receive_time_fc ( Nfc * instance,
uint32_t mask_rx_time_fc )

Set mask receive time.

Parameters
[in,out]instancepointer to the instance to be modified.
[in]mask_rx_time_fcmask receive time, in carrier cycles.

◆ nfc_start()

void nfc_start ( Nfc * instance,
NfcEventCallback callback,
void * context )

Start the Nfc instance.

The instance must be configured to work with a specific technology in a specific operating mode with a nfc_config() call before starting.

Once started, the user code will be receiving events through the provided callback which must handle them according to the logic required.

Parameters
[in,out]instancepointer to the instance to be started.
[in]callbackpointer to a user-defined callback function which will receive events.
[in]contextpointer to a user-specific context (will be passed to the callback).

◆ nfc_stop()

void nfc_stop ( Nfc * instance)

Stop Nfc instance.

The instance can only be stopped if it is running.

Parameters
[in,out]instancepointer to the instance to be stopped.