Functions
int	nfc_initiator_init (nfc_device *pnd)
	Initialize NFC device as initiator (reader)
int	nfc_initiator_init_secure_element (nfc_device *pnd)
	Initialize NFC device as initiator with its secure element initiator (reader)
int	nfc_initiator_select_passive_target (nfc_device pnd, const nfc_modulation nm, const uint8_t pbtInitData, const size_t szInitData, nfc_target *pnt)
	Select a passive or emulated tag.
int	nfc_initiator_list_passive_targets (nfc_device *pnd, const nfc_modulation nm, nfc_target ant[], const size_t szTargets)
	List passive or emulated tags.
int	nfc_initiator_poll_target (nfc_device pnd, const nfc_modulation pnmModulations, const size_t szModulations, const uint8_t uiPollNr, const uint8_t uiPeriod, nfc_target *pnt)
	Polling for NFC targets.
int	nfc_initiator_select_dep_target (nfc_device pnd, const nfc_dep_mode ndm, const nfc_baud_rate nbr, const nfc_dep_info pndiInitiator, nfc_target *pnt, const int timeout)
	Select a target and request active or passive mode for D.E.P. (Data Exchange Protocol)
int	nfc_initiator_poll_dep_target (struct nfc_device pnd, const nfc_dep_mode ndm, const nfc_baud_rate nbr, const nfc_dep_info pndiInitiator, nfc_target *pnt, const int timeout)
	Poll a target and request active or passive mode for D.E.P. (Data Exchange Protocol)
int	nfc_initiator_transceive_bytes (nfc_device pnd, const uint8_t pbtTx, const size_t szTx, uint8_t *pbtRx, const size_t szRx, int timeout)
	Send data to target then retrieve data from target.
int	nfc_initiator_transceive_bits (nfc_device pnd, const uint8_t pbtTx, const size_t szTxBits, const uint8_t pbtTxPar, uint8_t pbtRx, const size_t szRx, uint8_t *pbtRxPar)
	Transceive raw bit-frames to a target.
int	nfc_initiator_transceive_bytes_timed (nfc_device pnd, const uint8_t pbtTx, const size_t szTx, uint8_t pbtRx, const size_t szRx, uint32_t cycles)
	Send data to target then retrieve data from target.
int	nfc_initiator_target_is_present (nfc_device pnd, const nfc_target pnt)
	Check target presence.
int	nfc_initiator_transceive_bits_timed (nfc_device pnd, const uint8_t pbtTx, const size_t szTxBits, const uint8_t pbtTxPar, uint8_t pbtRx, const size_t szRx, uint8_t pbtRxPar, uint32_t cycles)
	Transceive raw bit-frames to a target.

Detailed Description

This page details how to act as "reader".

Function Documentation

int nfc_initiator_init ( nfc_device * pnd )

Initialize NFC device as initiator (reader)

Returns:: Returns 0 on success, otherwise returns libnfc's error code (negative value)

Parameters:

pnd	nfc_device struct pointer that represent currently used device

The NFC device is configured to function as RFID reader. After initialization it can be used to communicate to passive RFID tags and active NFC devices. The reader will act as initiator to communicate peer 2 peer (NFCIP) to other active NFC devices.

Crc is handled by the device (NP_HANDLE_CRC = true)
Parity is handled the device (NP_HANDLE_PARITY = true)
Cryto1 cipher is disabled (NP_ACTIVATE_CRYPTO1 = false)
Easy framing is enabled (NP_EASY_FRAMING = true)
Auto-switching in ISO14443-4 mode is enabled (NP_AUTO_ISO14443_4 = true)
Invalid frames are not accepted (NP_ACCEPT_INVALID_FRAMES = false)
Multiple frames are not accepted (NP_ACCEPT_MULTIPLE_FRAMES = false)
14443-A mode is activated (NP_FORCE_ISO14443_A = true)
speed is set to 106 kbps (NP_FORCE_SPEED_106 = true)
Let the device try forever to find a target (NP_INFINITE_SELECT = true)
RF field is shortly dropped (if it was enabled) then activated again

Definition at line 452 of file nfc.c.

int nfc_initiator_init_secure_element ( nfc_device * pnd )

Initialize NFC device as initiator with its secure element initiator (reader)

Returns:: Returns 0 on success, otherwise returns libnfc's error code (negative value)

Parameters:

pnd	nfc_device struct pointer that represent currently used device

The NFC device is configured to function as secure element reader. After initialization it can be used to communicate with the secure element.

Note:: RF field is desactvated in order to some power

Definition at line 492 of file nfc.c.

int nfc_initiator_list_passive_targets	(	nfc_device *	pnd,
		const nfc_modulation	nm,
		nfc_target	ant[],
		const size_t	szTargets
	)

List passive or emulated tags.

Returns:: Returns the number of targets found on success, otherwise returns libnfc's error code (negative value)

Parameters:

	pnd	nfc_device struct pointer that represent currently used device
	nm	desired modulation
[out]	ant	array of nfc_target that will be filled with targets info
	szTargets	size of ant (will be the max targets listed)

The NFC device will try to find the available passive tags. Some NFC devices are capable to emulate passive tags. The standards (ISO18092 and ECMA-340) describe the modulation that can be used for reader to passive communications. The chip needs to know with what kind of tag it is dealing with, therefore the initial modulation and speed (106, 212 or 424 kbps) should be supplied.

Definition at line 561 of file nfc.c.

int nfc_initiator_poll_dep_target	(	struct nfc_device *	pnd,
		const nfc_dep_mode	ndm,
		const nfc_baud_rate	nbr,
		const nfc_dep_info *	pndiInitiator,
		nfc_target *	pnt,
		const int	timeout
	)

Poll a target and request active or passive mode for D.E.P. (Data Exchange Protocol)

Returns:: Returns selected D.E.P targets count on success, otherwise returns libnfc's error code (negative value).

Parameters:

	pnd	nfc_device struct pointer that represent currently used device
	ndm	desired D.E.P. mode (NDM_ACTIVE or NDM_PASSIVE for active, respectively passive mode)
	nbr	desired baud rate
	ndiInitiator	pointer nfc_dep_info struct that contains NFCID3 and General Bytes to set to the initiator device (optionnal, can be NULL)
[out]	pnt	is a nfc_target struct pointer where target information will be put.
	timeout	in milliseconds

The NFC device will try to find an available D.E.P. target. The standards (ISO18092 and ECMA-340) describe the modulation that can be used for reader to passive communications.

Note:: nfc_dep_info will be returned when the target was acquired successfully.

Definition at line 682 of file nfc.c.

int nfc_initiator_poll_target	(	nfc_device *	pnd,
		const nfc_modulation *	pnmModulations,
		const size_t	szModulations,
		const uint8_t	uiPollNr,
		const uint8_t	uiPeriod,
		nfc_target *	pnt
	)

Polling for NFC targets.

Returns:: Returns polled targets count, otherwise returns libnfc's error code (negative value).

Parameters:

pnd	nfc_device struct pointer that represent currently used device
pnmModulations	desired modulations
szModulations	size of pnmModulations
uiPollNr	specifies the number of polling (0x01 – 0xFE: 1 up to 254 polling, 0xFF: Endless polling)

Note:: one polling is a polling for each desired target type

Parameters:

uiPeriod indicates the polling period in units of 150 ms (0x01 – 0x0F: 150ms – 2.25s)

Note:: e.g. if uiPeriod=10, it will poll each desired target type during 1.5s

Parameters:

[out] pnt pointer on nfc_target (over)writable struct

Definition at line 627 of file nfc.c.

int nfc_initiator_select_dep_target	(	nfc_device *	pnd,
		const nfc_dep_mode	ndm,
		const nfc_baud_rate	nbr,
		const nfc_dep_info *	pndiInitiator,
		nfc_target *	pnt,
		const int	timeout
	)

Select a target and request active or passive mode for D.E.P. (Data Exchange Protocol)

Returns:: Returns selected D.E.P targets count on success, otherwise returns libnfc's error code (negative value).

Parameters:

	pnd	nfc_device struct pointer that represent currently used device
	ndm	desired D.E.P. mode (NDM_ACTIVE or NDM_PASSIVE for active, respectively passive mode)
	nbr	desired baud rate
	ndiInitiator	pointer nfc_dep_info struct that contains NFCID3 and General Bytes to set to the initiator device (optionnal, can be NULL)
[out]	pnt	is a nfc_target struct pointer where target information will be put.
	timeout	in milliseconds

The NFC device will try to find an available D.E.P. target. The standards (ISO18092 and ECMA-340) describe the modulation that can be used for reader to passive communications.

Note:: nfc_dep_info will be returned when the target was acquired successfully.

If timeout equals to 0, the function blocks indefinitely (until an error is raised or function is completed) If timeout equals to -1, the default timeout will be used

Definition at line 657 of file nfc.c.

int nfc_initiator_select_passive_target	(	nfc_device *	pnd,
		const nfc_modulation	nm,
		const uint8_t *	pbtInitData,
		const size_t	szInitData,
		nfc_target *	pnt
	)

Select a passive or emulated tag.

Returns:: Returns selected passive target count on success, otherwise returns libnfc's error code (negative value)

Parameters:

pnd	nfc_device struct pointer that represent currently used device
nm	desired modulation
pbtInitData	optional initiator data, NULL for using the default values.
szInitData	length of initiator data pbtInitData.

Note:

pbtInitData is used with different kind of data depending on modulation type:

for an ISO/IEC 14443 type A modulation, pbbInitData contains the UID you want to select;
for an ISO/IEC 14443 type B modulation, pbbInitData contains Application Family Identifier (AFI) (see ISO/IEC 14443-3) and optionally a second byte = 0x01 if you want to use probabilistic approach instead of timeslot approach;
for a FeliCa modulation, pbbInitData contains a 5-byte polling payload (see ISO/IEC 18092 11.2.2.5).
for ISO14443B', ASK CTx and ST SRx, see corresponding standards
if NULL, default values adequate for the chosen modulation will be used.

Parameters:

[out] pnt nfc_target struct pointer which will filled if available

The NFC device will try to find one available passive tag or emulated tag.

The chip needs to know with what kind of tag it is dealing with, therefore the initial modulation and speed (106, 212 or 424 kbps) should be supplied.

Definition at line 521 of file nfc.c.

int nfc_initiator_target_is_present	(	nfc_device *	pnd,
		const nfc_target *	pnt
	)

Check target presence.

Returns:: Returns 0 on success, otherwise returns libnfc's error code.

Parameters:

pnd	nfc_device struct pointer that represent currently used device
pnt	a nfc_target struct pointer where desired target information was stored (optionnal, can be NULL). This function tests if nfc_target (or last selected tag if NULL) is currently present on NFC device.

Warning:: The target have to be selected before check its presence; To run the test, one or more commands will be sent to target

Definition at line 862 of file nfc.c.

int nfc_initiator_transceive_bits	(	nfc_device *	pnd,
		const uint8_t *	pbtTx,
		const size_t	szTxBits,
		const uint8_t *	pbtTxPar,
		uint8_t *	pbtRx,
		const size_t	szRx,
		uint8_t *	pbtRxPar
	)

Transceive raw bit-frames to a target.

Returns:: Returns received bits count on success, otherwise returns libnfc's error code

Parameters:

pnd	nfc_device struct pointer that represents currently used device
pbtTx	contains a byte array of the frame that needs to be transmitted.
szTxBits	contains the length in bits.

Note:: For example the REQA (0x26) command (first anti-collision command of ISO14443-A) must be precise 7 bits long. This is not possible by using nfc_initiator_transceive_bytes(). With that function you can only communicate frames that consist of full bytes. When you send a full byte (8 bits + 1 parity) with the value of REQA (0x26), a tag will simply not respond. More information about this can be found in the anti-collision example (nfc-anticol).

Parameters:

pbtTxPar parameter contains a byte array of the corresponding parity bits needed to send per byte.

Note:: For example if you send the SELECT_ALL (0x93, 0x20) = [ 10010011, 00100000 ] command, you have to supply the following parity bytes (0x01, 0x00) to define the correct odd parity bits. This is only an example to explain how it works, if you just are sending two bytes with ISO14443-A compliant parity bits you better can use the nfc_initiator_transceive_bytes() function.

Parameters:

[out]	pbtRx	response from the target
	szRx	size of pbtRx (Will return NFC_EOVFLOW if RX exceeds this size)
[out]	pbtRxPar	parameter contains a byte array of the corresponding parity bits

The NFC device (configured as initiator) will transmit low-level messages where only the modulation is handled by the PN53x chip. Construction of the frame (data, CRC and parity) is completely done by libnfc. This can be very useful for testing purposes. Some protocols (e.g. MIFARE Classic) require to violate the ISO14443-A standard by sending incorrect parity and CRC bytes. Using this feature you are able to simulate these frames.

Definition at line 807 of file nfc.c.

int nfc_initiator_transceive_bits_timed	(	nfc_device *	pnd,
		const uint8_t *	pbtTx,
		const size_t	szTxBits,
		const uint8_t *	pbtTxPar,
		uint8_t *	pbtRx,
		const size_t	szRx,
		uint8_t *	pbtRxPar,
		uint32_t *	cycles
	)

Transceive raw bit-frames to a target.

Returns:: Returns received bits count on success, otherwise returns libnfc's error code

This function is similar to nfc_initiator_transceive_bits() with the following differences:

A precise cycles counter will indicate the number of cycles between emission & reception of frames.
It only supports mode with NP_EASY_FRAMING option disabled and CRC must be handled manually.
Overall communication with the host is heavier and slower.

Timer control: By default timer configuration tries to maximize the precision, which also limits the maximum cycles count before saturation/timeout. E.g. with PN53x it can count up to 65535 cycles, so about 4.8ms, with a precision of about 73ns.

If you're ok with the defaults, set *cycles = 0 before calling this function.
If you need to count more cycles, set *cycles to the maximum you expect but don't forget you'll loose in precision and it'll take more time before timeout, so don't abuse!

Warning:: The configuration option NP_EASY_FRAMING must be set to false.; The configuration option NP_HANDLE_CRC must be set to false.; The configuration option NP_HANDLE_PARITY must be set to true (the default value).

Definition at line 889 of file nfc.c.

int nfc_initiator_transceive_bytes	(	nfc_device *	pnd,
		const uint8_t *	pbtTx,
		const size_t	szTx,
		uint8_t *	pbtRx,
		const size_t	szRx,
		int	timeout
	)

Send data to target then retrieve data from target.

Returns:: Returns received bytes count on success, otherwise returns libnfc's error code

Parameters:

	pnd	nfc_device struct pointer that represents currently used device
	pbtTx	contains a byte array of the frame that needs to be transmitted.
	szTx	contains the length in bytes.
[out]	pbtRx	response from the target
	szRx	size of pbtRx (Will return NFC_EOVFLOW if RX exceeds this size)
	timeout	in milliseconds

The NFC device (configured as initiator) will transmit the supplied bytes (pbtTx) to the target. It waits for the response and stores the received bytes in the pbtRx byte array.

If NP_EASY_FRAMING option is disabled the frames will sent and received in raw mode: PN53x will not handle input neither output data.

The parity bits are handled by the PN53x chip. The CRC can be generated automatically or handled manually. Using this function, frames can be communicated very fast via the NFC initiator to the tag.

Tests show that on average this way of communicating is much faster than using the regular driver/middle-ware (often supplied by manufacturers).

Warning:: The configuration option NP_HANDLE_PARITY must be set to true (the default value).

Note:: When used with MIFARE Classic, NFC_EMFCAUTHFAIL error is returned if authentication command failed. You need to re-select the tag to operate with.

If timeout equals to 0, the function blocks indefinitely (until an error is raised or function is completed) If timeout equals to -1, the default timeout will be used

Definition at line 764 of file nfc.c.

int nfc_initiator_transceive_bytes_timed	(	nfc_device *	pnd,
		const uint8_t *	pbtTx,
		const size_t	szTx,
		uint8_t *	pbtRx,
		const size_t	szRx,
		uint32_t *	cycles
	)

Send data to target then retrieve data from target.

Returns:: Returns received bytes count on success, otherwise returns libnfc's error code.

Parameters:

	pnd	nfc_device struct pointer that represents currently used device
	pbtTx	contains a byte array of the frame that needs to be transmitted.
	szTx	contains the length in bytes.
[out]	pbtRx	response from the target
	szRx	size of pbtRx (Will return NFC_EOVFLOW if RX exceeds this size)

This function is similar to nfc_initiator_transceive_bytes() with the following differences:

A precise cycles counter will indicate the number of cycles between emission & reception of frames.
It only supports mode with NP_EASY_FRAMING option disabled.
Overall communication with the host is heavier and slower.

Timer control: By default timer configuration tries to maximize the precision, which also limits the maximum cycles count before saturation/timeout. E.g. with PN53x it can count up to 65535 cycles, so about 4.8ms, with a precision of about 73ns.

If you're ok with the defaults, set *cycles = 0 before calling this function.
If you need to count more cycles, set *cycles to the maximum you expect but don't forget you'll loose in precision and it'll take more time before timeout, so don't abuse!

Warning:: The configuration option NP_EASY_FRAMING must be set to false.; The configuration option NP_HANDLE_PARITY must be set to true (the default value).

Definition at line 843 of file nfc.c.

Functions

Detailed Description

Function Documentation