Transport layer Nfc library. More...

#include <toolbox/bit_buffer.h>

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
Nfc *	nfc_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, const uint16_t sys_code)
	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]	event	Nfc event, passed by value, complete with protocol type and data.
[in,out]	context	pointer 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

enum 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]	instance	pointer to the instance to be configured.
[in]	mode	required operating mode.
[in]	tech	required 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,
		const uint16_t	sys_code )

Set FeliCa collision resolution parameters in listener mode.

Configures the NFC hardware for automatic collision resolution.

Parameters

[in,out]	instance	pointer to the instance to be configured.
[in]	idm	pointer to a byte array containing the IDm.
[in]	idm_len	IDm length in bytes.
[in]	pmm	pointer to a byte array containing the PMm.
[in]	pmm_len	PMm length in bytes.
[in]	sys_code	System code from SYS_C block

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] instance pointer 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]	instance	pointer to the instance to be configured.
[in]	uid	pointer to a byte array containing the UID.
[in]	uid_len	UID length in bytes (must be supported by the protocol).
[in]	atqa	ATQA byte value.
[in]	sak	SAK 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]	instance	pointer to the instance to be used in the transaction.
[in]	tx_buffer	pointer 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]	instance	pointer to the instance to be used in the transaction.
[in]	tx_buffer	pointer to the buffer containing the data to be transmitted.
[out]	rx_buffer	pointer to the buffer to be filled with received data.
[in]	fwt	frame 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]	instance	pointer to the instance to be used in the transaction.
[in]	tx_buffer	pointer to the buffer containing the data to be transmitted.
[out]	rx_buffer	pointer to the buffer to be filled with received data.
[in]	fwt	frame 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]	instance	pointer to the instance to be used in the transaction.
[in]	frame	type of short frame to be sent.
[out]	rx_buffer	pointer to the buffer to be filled with received data.
[in]	fwt	frame 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] instance pointer 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]	instance	pointer to the instance to be used in the transaction.
[in]	tx_buffer	pointer 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]	instance	pointer to the instance to be used in the transaction.
[in]	tx_buffer	pointer to the buffer containing the data to be transmitted.
[out]	rx_buffer	pointer to the buffer to be filled with received data.
[in]	fwt	frame 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]	instance	pointer to the instance to be modified.
[in]	fdt_listen_fc	frame 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]	instance	pointer to the instance to be modified.
[in]	fdt_poll_fc	frame 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]	instance	pointer to the instance to be modified.
[in]	fdt_poll_poll_us	frame 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]	instance	pointer to the instance to be modified.
[in]	guard_time_us	guard 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]	instance	pointer to the instance to be modified.
[in]	mask_rx_time_fc	mask 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]	instance	pointer to the instance to be started.
[in]	callback	pointer to a user-defined callback function which will receive events.
[in]	context	pointer 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] instance pointer to the instance to be stopped.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ NfcEventCallback

Enumeration Type Documentation

◆ NfcCommand

◆ NfcError

◆ NfcEventType

◆ NfcMode

◆ NfcTech

Function Documentation

◆ nfc_alloc()

◆ nfc_config()

◆ nfc_felica_listener_set_sensf_res_data()

◆ nfc_free()

◆ nfc_iso14443a_listener_set_col_res_data()

◆ nfc_iso14443a_listener_tx_custom_parity()

◆ nfc_iso14443a_poller_trx_custom_parity()

◆ nfc_iso14443a_poller_trx_sdd_frame()

◆ nfc_iso14443a_poller_trx_short_frame()

◆ nfc_iso15693_listener_tx_sof()

◆ nfc_listener_tx()

◆ nfc_poller_trx()

◆ nfc_set_fdt_listen_fc()

◆ nfc_set_fdt_poll_fc()

◆ nfc_set_fdt_poll_poll_us()

◆ nfc_set_guard_time_us()

◆ nfc_set_mask_receive_time_fc()

◆ nfc_start()

◆ nfc_stop()