libnfc  1.4.2
Functions
nfc.c File Reference

NFC library implementation. More...

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <string.h>
#include <nfc/nfc.h>
#include "chips.h"
#include "drivers.h"
#include <nfc/nfc-messages.h>

Go to the source code of this file.

Functions

nfc_device_desc_tnfc_pick_device (void)
 Probe for the first discoverable supported devices (ie. only available for some drivers)
nfc_device_tnfc_connect (nfc_device_desc_t *pndd)
 Connect to a NFC device.
void nfc_disconnect (nfc_device_t *pnd)
 Disconnect from a NFC device.
void nfc_list_devices (nfc_device_desc_t pnddDevices[], size_t szDevices, size_t *pszDeviceFound)
 Probe for discoverable supported devices (ie. only available for some drivers)
bool nfc_configure (nfc_device_t *pnd, const nfc_device_option_t ndo, const bool bEnable)
 Configure advanced NFC device settings.
bool nfc_initiator_init (nfc_device_t *pnd)
 Initialize NFC device as initiator (reader)
bool nfc_initiator_select_passive_target (nfc_device_t *pnd, const nfc_modulation_t nm, const byte_t *pbtInitData, const size_t szInitData, nfc_target_t *pnt)
 Select a passive or emulated tag.
bool nfc_initiator_list_passive_targets (nfc_device_t *pnd, const nfc_modulation_t nm, nfc_target_t ant[], const size_t szTargets, size_t *pszTargetFound)
 List passive or emulated tags.
bool nfc_initiator_poll_targets (nfc_device_t *pnd, const nfc_modulation_t *pnmModulations, const size_t szModulations, const byte_t btPollNr, const byte_t btPeriod, nfc_target_t *pntTargets, size_t *pszTargetFound)
 Polling for NFC targets.
bool nfc_initiator_select_dep_target (nfc_device_t *pnd, const nfc_dep_mode_t ndm, const nfc_baud_rate_t nbr, const nfc_dep_info_t *pndiInitiator, nfc_target_t *pnt)
 Select a target and request active or passive mode for D.E.P. (Data Exchange Protocol)
bool nfc_initiator_transceive_bytes (nfc_device_t *pnd, const byte_t *pbtTx, const size_t szTx, byte_t *pbtRx, size_t *pszRx)
 Send data to target then retrieve data from target.
bool nfc_initiator_transceive_bits (nfc_device_t *pnd, const byte_t *pbtTx, const size_t szTxBits, const byte_t *pbtTxPar, byte_t *pbtRx, size_t *pszRxBits, byte_t *pbtRxPar)
 Transceive raw bit-frames to a target.
bool nfc_target_init (nfc_device_t *pnd, nfc_target_t *pnt, byte_t *pbtRx, size_t *pszRx)
 Initialize NFC device as an emulated tag.
bool nfc_target_send_bytes (nfc_device_t *pnd, const byte_t *pbtTx, const size_t szTx)
 Send bytes and APDU frames.
bool nfc_target_receive_bytes (nfc_device_t *pnd, byte_t *pbtRx, size_t *pszRx)
 Receive bytes and APDU frames.
bool nfc_target_send_bits (nfc_device_t *pnd, const byte_t *pbtTx, const size_t szTxBits, const byte_t *pbtTxPar)
 Send raw bit-frames.
bool nfc_target_receive_bits (nfc_device_t *pnd, byte_t *pbtRx, size_t *pszRxBits, byte_t *pbtRxPar)
 Receive bit-frames.
const char * nfc_strerror (const nfc_device_t *pnd)
 Return the PCD error string.
int nfc_strerror_r (const nfc_device_t *pnd, char *pcStrErrBuf, size_t szBufLen)
 Renders the PCD error in pcStrErrBuf for a maximum size of szBufLen chars.
void nfc_perror (const nfc_device_t *pnd, const char *pcString)
 Display the PCD error a-la perror.
const char * nfc_device_name (nfc_device_t *pnd)
 Returns the device name.
const char * nfc_version (void)
 Returns the library version.

Detailed Description

NFC library implementation.

Definition in file nfc.c.


Function Documentation

bool nfc_configure ( nfc_device_t pnd,
const nfc_device_option_t  ndo,
const bool  bEnable 
)

Configure advanced NFC device settings.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
ndonfc_device_option_t struct that contains option to set to device
bEnableboolean to activate/disactivate the option

Configures parameters and registers that control for example timing, modulation, frame and error handling. There are different categories for configuring the PN53X chip features (handle, activate, infinite and accept).

Definition at line 235 of file nfc.c.

Connect to a NFC device.

Parameters:
pndddevice description if specific device is wanted, NULL otherwise
Returns:
Returns pointer to a nfc_device_t struct if successfull; otherwise returns NULL value.

If pndd is NULL, the first available NFC device is claimed. It will automatically search the system using all available drivers to determine a device is NFC-enabled.

If pndd is passed then this function will try to claim the right device using information provided by the nfc_device_desc_t struct.

When it has successfully claimed a NFC device, memory is allocated to save the device information. It will return a pointer to a nfc_device_t struct. This pointer should be supplied by every next functions of libnfc that should perform an action with this device.

Note:
During this function, the device will be configured with default options:
  • Crc is handled by the device (NDO_HANDLE_CRC = true)
  • Parity is handled the device (NDO_HANDLE_PARITY = true)
  • Cryto1 cipher is disabled (NDO_ACTIVATE_CRYPTO1 = false)
  • Easy framing is enabled (NDO_EASY_FRAMING = true)
  • Auto-switching in ISO14443-4 mode is enabled (NDO_AUTO_ISO14443_4 = true)
  • Invalid frames are not accepted (NDO_ACCEPT_INVALID_FRAMES = false)
  • Multiple frames are not accepted (NDO_ACCEPT_MULTIPLE_FRAMES = false)

Definition at line 71 of file nfc.c.

const char* nfc_device_name ( nfc_device_t pnd)

Returns the device name.

Returns:
Returns a string with the device name

Definition at line 694 of file nfc.c.

void nfc_disconnect ( nfc_device_t pnd)

Disconnect from a NFC device.

Parameters:
pndnfc_device_t struct pointer that represent currently used device

Initiator's selected tag is disconnected and the device, including allocated nfc_device_t struct, is released.

Definition at line 161 of file nfc.c.

Initialize NFC device as initiator (reader)

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t 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.

Definition at line 252 of file nfc.c.

bool nfc_initiator_list_passive_targets ( nfc_device_t pnd,
const nfc_modulation_t  nm,
nfc_target_t  ant[],
const size_t  szTargets,
size_t *  pszTargetFound 
)

List passive or emulated tags.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
nmdesired modulation
[out]antarray of nfc_target_t that will be filled with targets info
szTargetssize of ant (will be the max targets listed)
[out]pszTargetFoundpointer where target found counter will be stored

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 358 of file nfc.c.

bool nfc_initiator_poll_targets ( nfc_device_t pnd,
const nfc_modulation_t pnmModulations,
const size_t  szModulations,
const byte_t  btPollNr,
const byte_t  btPeriod,
nfc_target_t pntTargets,
size_t *  pszTargetFound 
)

Polling for NFC targets.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
ppttTargetTypesarray of desired target types
szTargetTypesppttTargetTypes count
btPollNrspecifies the number of polling
Note:
one polling is a polling for each desired target type
Parameters:
btPeriodindicates the polling period in units of 150 ms
[out]pntTargetspointer on array of 2 nfc_target_t (over)writables struct
[out]pszTargetFoundfound targets count

Definition at line 433 of file nfc.c.

bool nfc_initiator_select_dep_target ( nfc_device_t pnd,
const nfc_dep_mode_t  ndm,
const nfc_baud_rate_t  nbr,
const nfc_dep_info_t pndiInitiator,
nfc_target_t pnt 
)

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

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
ndmdesired D.E.P. mode (NDM_ACTIVE or NDM_PASSIVE for active, respectively passive mode)
ndiInitiatorpointer nfc_dep_info_t struct that contains NFCID3 and General Bytes to set to the initiator device (optionnal, can be NULL)
[out]pntis a nfc_target_t struct pointer where target information will be put.

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_t will be returned when the target was acquired successfully.

Definition at line 460 of file nfc.c.

bool nfc_initiator_select_passive_target ( nfc_device_t pnd,
const nfc_modulation_t  nm,
const byte_t *  pbtInitData,
const size_t  szInitData,
nfc_target_t pnt 
)

Select a passive or emulated tag.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
nmdesired modulation
pbtInitDataoptional initiator data used for Felica, ISO14443B, Topaz polling or to select a specific UID in ISO14443A.
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);
  • for a FeliCa modulation, pbbInitData contains polling payload (see ISO/IEC 18092 11.2.2.5).
Parameters:
[out]pntnfc_target_t 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 292 of file nfc.c.

bool nfc_initiator_transceive_bits ( nfc_device_t pnd,
const byte_t *  pbtTx,
const size_t  szTxBits,
const byte_t *  pbtTxPar,
byte_t *  pbtRx,
size_t *  pszRxBits,
byte_t *  pbtRxPar 
)

Transceive raw bit-frames to a target.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
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 tag
[out]pszRxBitspbtRx length in bits
[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 550 of file nfc.c.

bool nfc_initiator_transceive_bytes ( nfc_device_t pnd,
const byte_t *  pbtTx,
const size_t  szTx,
byte_t *  pbtRx,
size_t *  pszRx 
)

Send data to target then retrieve data from target.

Returns:
Returns true if action was successfully performed; otherwise returns false.

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 NDO_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 NDO_HANDLE_PARITY must be set to true (the default value).

Definition at line 506 of file nfc.c.

void nfc_list_devices ( nfc_device_desc_t  pnddDevices[],
size_t  szDevices,
size_t *  pszDeviceFound 
)

Probe for discoverable supported devices (ie. only available for some drivers)

Parameters:
[out]pnddDevicesarray of nfc_device_desc_t previously allocated by the caller.
szDevicessize of the pnddDevices array.
[out]pszDeviceFoundnumber of devices found.

Definition at line 201 of file nfc.c.

Probe for the first discoverable supported devices (ie. only available for some drivers)

Returns:
nfc_device_desc_t struct pointer

Definition at line 178 of file nfc.c.

const char* nfc_strerror ( const nfc_device_t pnd)

Return the PCD error string.

Returns:
Returns a string

Definition at line 663 of file nfc.c.

int nfc_strerror_r ( const nfc_device_t pnd,
char *  pcStrErrBuf,
size_t  szBufLen 
)

Renders the PCD error in pcStrErrBuf for a maximum size of szBufLen chars.

Returns:
Returns 0 upon success

Definition at line 673 of file nfc.c.

bool nfc_target_init ( nfc_device_t pnd,
nfc_target_t pnt,
byte_t *  pbtRx,
size_t *  pszRx 
)

Initialize NFC device as an emulated tag.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
ntmtarget mode restriction that you want to emulate (eg. NTM_PASSIVE_ONLY)
pntpointer to nfc_target_t struct that represents the wanted emulated target
Note:
pnt can be updated by this function: if you set NBR_UNDEFINED and/or NDM_UNDEFINED (ie. for DEP mode), these fields will be updated.
Parameters:
[out]pbtRxRx buffer pointer
[out]pszRxreceived bytes count

This function initialize NFC device in target mode in order to emulate a tag using the specified nfc_target_mode_t.

Warning:
Be aware that this function will wait (hang) until a command is received that is not part of the anti-collision. The RATS command for example would wake up the emulator. After this is received, the send and receive functions can be used.

Definition at line 581 of file nfc.c.

bool nfc_target_receive_bits ( nfc_device_t pnd,
byte_t *  pbtRx,
size_t *  pszRxBits,
byte_t *  pbtRxPar 
)

Receive bit-frames.

Returns:
Returns true if action was successfully performed; otherwise returns false.

This function makes it possible to receive (raw) bit-frames. It returns all the messages that are stored in the FIFO buffer of the PN53x chip. It does not require to send any frame and thereby could be used to snoop frames that are transmitted by a nearby initiator.

Note:
Check out the NDO_ACCEPT_MULTIPLE_FRAMES configuration option to avoid losing transmitted frames.

Definition at line 651 of file nfc.c.

bool nfc_target_receive_bytes ( nfc_device_t pnd,
byte_t *  pbtRx,
size_t *  pszRx 
)

Receive bytes and APDU frames.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
[out]pbtRxpointer to Rx buffer
[out]pszRxreceived byte count

This function retrieves bytes frames (e.g. ADPU) sent by the initiator to the NFC device (configured as target).

Definition at line 617 of file nfc.c.

bool nfc_target_send_bits ( nfc_device_t pnd,
const byte_t *  pbtTx,
const size_t  szTxBits,
const byte_t *  pbtTxPar 
)

Send raw bit-frames.

Returns:
Returns true if action was successfully performed; otherwise returns false.

This function can be used to transmit (raw) bit-frames to the initiator using the specified NFC device (configured as target).

Definition at line 632 of file nfc.c.

bool nfc_target_send_bytes ( nfc_device_t pnd,
const byte_t *  pbtTx,
const size_t  szTx 
)

Send bytes and APDU frames.

Returns:
Returns true if action was successfully performed; otherwise returns false.
Parameters:
pndnfc_device_t struct pointer that represent currently used device
pbtTxpointer to Tx buffer
szTxsize of Tx buffer

This function make the NFC device (configured as target) send byte frames (e.g. APDU responses) to the initiator.

Definition at line 600 of file nfc.c.

const char* nfc_version ( void  )

Returns the library version.

Returns:
Returns a string with the library version

Definition at line 706 of file nfc.c.