libnfc  1.7.1
Functions
NFC initiator

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

Initialize NFC device as initiator (reader)

Returns:
Returns 0 on success, otherwise returns libnfc's error code (negative value)
Parameters:
pndnfc_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.

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:
pndnfc_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:
pndnfc_device struct pointer that represent currently used device
nmdesired modulation
[out]antarray of nfc_target that will be filled with targets info
szTargetssize 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:
pndnfc_device struct pointer that represent currently used device
ndmdesired D.E.P. mode (NDM_ACTIVE or NDM_PASSIVE for active, respectively passive mode)
nbrdesired baud rate
ndiInitiatorpointer nfc_dep_info struct that contains NFCID3 and General Bytes to set to the initiator device (optionnal, can be NULL)
[out]pntis a nfc_target struct pointer where target information will be put.
timeoutin 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:
pndnfc_device struct pointer that represent currently used device
pnmModulationsdesired modulations
szModulationssize of pnmModulations
uiPollNrspecifies 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:
uiPeriodindicates 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]pntpointer 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:
pndnfc_device struct pointer that represent currently used device
ndmdesired D.E.P. mode (NDM_ACTIVE or NDM_PASSIVE for active, respectively passive mode)
nbrdesired baud rate
ndiInitiatorpointer nfc_dep_info struct that contains NFCID3 and General Bytes to set to the initiator device (optionnal, can be NULL)
[out]pntis a nfc_target struct pointer where target information will be put.
timeoutin 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:
pndnfc_device struct pointer that represent currently used device
nmdesired modulation
pbtInitDataoptional initiator data, NULL for using the default values.
szInitDatalength 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]pntnfc_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:
pndnfc_device struct pointer that represent currently used device
pnta 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:
pndnfc_device struct pointer that represents currently used device
pbtTxcontains a byte array of the frame that needs to be transmitted.
szTxBitscontains 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:
pbtTxParparameter 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]pbtRxresponse from the target
szRxsize of pbtRx (Will return NFC_EOVFLOW if RX exceeds this size)
[out]pbtRxParparameter 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:
pndnfc_device struct pointer that represents currently used device
pbtTxcontains a byte array of the frame that needs to be transmitted.
szTxcontains the length in bytes.
[out]pbtRxresponse from the target
szRxsize of pbtRx (Will return NFC_EOVFLOW if RX exceeds this size)
timeoutin 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:
pndnfc_device struct pointer that represents currently used device
pbtTxcontains a byte array of the frame that needs to be transmitted.
szTxcontains the length in bytes.
[out]pbtRxresponse from the target
szRxsize 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.