Device driver for the NXP MFRC522 RFID controller. More...

Detailed Description

Device driver for the NXP MFRC522 RFID controller.

With this driver MIFARE and NTAG tags/keys can be read and written contactless.

Supported features:

Communication (Crypto1) with MIFARE Classic (1k, 4k, Mini)
Communication (Crypto1) with MIFARE Classic compatible PICCs
Firmware self check of MFRC522
Set the UID, write to sector 0, and unbrick Chinese UID changeable MIFARE cards

Partially supported features:

Communication with MIFARE Ultralight
Other PICCs (Ntag216)

Data sheet available here: https://www.nxp.com/docs/en/data-sheet/MFRC522.pdf

This driver is a port of a driver originally written for Arduino, you can find the original here: https://github.com/miguelbalboa/rfid (currently based on commit 0a568b45baf1852883630e90ea125786e88f5322)

Author: Hendrik van Essen hendr.nosp@m.ik.v.nosp@m.e@fu-.nosp@m.berl.nosp@m.in.de

Files
file	mfrc522.h

file	mfrc522_regs.h
	Register definitions for the MFRC522 controller.

Data Structures
struct	mfrc522_params_t
	MFRC522 device initialization parameters. More...

struct	mfrc522_t
	MFRC522 device data structure type. More...

struct	mfrc522_uid_t
	A struct used for passing the UID of a PICC. More...

struct	mfrc522_mifare_key_t
	A struct used for passing a MIFARE Crypto1 key. More...

Macros
#define	MFRC522_UID_MAX_SIZE 10
	Maximum size for uid byte array.

#define	MFRC522_MF_ACK 0xA
	The MIFARE Classic uses a 4 bit ACK/NAK.

#define	MFRC522_MF_KEY_SIZE 6
	A Mifare Crypto1 key is 6 bytes.

Enumerations
enum	mfrc522_picc_type_t { MFRC522_PICC_TYPE_ISO_14443_4 , MFRC522_PICC_TYPE_ISO_18092 , MFRC522_PICC_TYPE_MIFARE_MINI , MFRC522_PICC_TYPE_MIFARE_1K , MFRC522_PICC_TYPE_MIFARE_4K , MFRC522_PICC_TYPE_MIFARE_UL , MFRC522_PICC_TYPE_MIFARE_PLUS , MFRC522_PICC_TYPE_MIFARE_DESFIRE , MFRC522_PICC_TYPE_TNP3XXX , MFRC522_PICC_TYPE_NOT_COMPLETE , MFRC522_PICC_TYPE_UNKNOWN }
	PICC types. More...

Functions
void	mfrc522_pcd_set_register_bitmask (mfrc522_t *dev, mfrc522_pcd_register_t reg, uint8_t mask)
	Sets the bits given in mask in register reg.

void	mfrc522_pcd_clear_register_bitmask (mfrc522_t *dev, mfrc522_pcd_register_t reg, uint8_t mask)
	Clears the bits given in mask from register reg.

int	mfrc522_pcd_calculate_crc (mfrc522_t dev, const uint8_t data, uint8_t length, uint8_t *result)
	Use the CRC coprocessor in the MFRC522 to calculate a CRC_A.

int	mfrc522_pcd_init (mfrc522_t dev, const mfrc522_params_t params)
	Initialization.

void	mfrc522_pcd_reset (mfrc522_t *dev)
	Performs a soft reset on the MFRC522 chip and waits for it to be ready again.

void	mfrc522_pcd_antenna_on (mfrc522_t *dev)
	Turns the antenna on by enabling pins TX1 and TX2.

void	mfrc522_pcd_antenna_off (mfrc522_t *dev)
	Turns the antenna off by disabling pins TX1 and TX2.

mfrc522_pcd_rx_gain_t	mfrc522_pcd_get_antenna_gain (mfrc522_t *dev)
	Get the current MFRC522 receiver gain.

void	mfrc522_pcd_set_antenna_gain (mfrc522_t *dev, mfrc522_pcd_rx_gain_t rx_gain)
	Set the MFRC522 receiver gain.

void	mfrc522_pcd_soft_power_down (mfrc522_t *dev)
	Set the MFRC522 to soft power-down mode.

void	mfrc522_pcd_soft_power_up (mfrc522_t *dev)
	Set the MFRC522 to leave soft power-down mode.

int	mfrc522_pcd_transceive_data (mfrc522_t dev, const uint8_t send_data, uint8_t send_len, uint8_t back_data, uint8_t back_len, uint8_t *valid_bits, uint8_t rx_align, bool check_crc)
	Executes MFRC522_CMD_TRANSCEIVE.

int	mfrc522_pcd_communicate_with_picc (mfrc522_t dev, mfrc522_pcd_command_t command, uint8_t wait_irq, const uint8_t send_data, uint8_t send_len, uint8_t back_data, uint8_t back_len, uint8_t *valid_bits, uint8_t rx_align, bool check_crc)
	Transfers data to MFRC522's FIFO, executes a command, waits for completion and transfers data back from the FIFO.

int	mfrc522_picc_request_a (mfrc522_t dev, uint8_t buffer_atqa, uint8_t *buffer_size)
	Transmits REQA, Type A.

int	mfrc522_picc_wakeup_a (mfrc522_t dev, uint8_t buffer_atqa, uint8_t *buffer_size)
	Transmits WUPA, Type A.

int	mfrc522_picc_reqa_or_wupa (mfrc522_t dev, mfrc522_picc_command_t command, uint8_t buffer_atqa, uint8_t *buffer_size)
	Transmits REQA (Type A) or WUPA (Type A) commands.

int	mfrc522_picc_select (mfrc522_t dev, mfrc522_uid_t uid, uint8_t valid_bits)
	Transmits SELECT/ANTICOLLISION commands to select a single PICC.

int	mfrc522_picc_halt_a (mfrc522_t *dev)
	Instructs a PICC in state ACTIVE(*) to go to state HALT.

int	mfrc522_pcd_authenticate (mfrc522_t dev, mfrc522_picc_command_t command, uint8_t block_addr, const mfrc522_mifare_key_t key, const mfrc522_uid_t *uid)
	Executes the MFRC522 MFAuthent command.

void	mfrc522_pcd_stop_crypto1 (mfrc522_t *dev)
	Used to exit the PCD from its authenticated state.

int	mfrc522_mifare_read (mfrc522_t dev, uint8_t block_addr, uint8_t buffer, uint8_t *buffer_size)
	Read 16 bytes (+ 2 bytes CRC_A) from the active PICC.

int	mfrc522_mifare_write (mfrc522_t dev, uint8_t block_addr, const uint8_t buffer, uint8_t buffer_size)
	Write 16 bytes to the active PICC.

int	mfrc522_mifare_ultralight_write (mfrc522_t dev, uint8_t page, const uint8_t buffer)
	Write a 4 byte page to the active MIFARE Ultralight PICC.

int	mfrc522_mifare_decrement (mfrc522_t *dev, uint8_t block_addr, int32_t delta)
	Subtract the operand from the value of the addressed block, and store the result in the Transfer Buffer.

int	mfrc522_mifare_increment (mfrc522_t *dev, uint8_t block_addr, int32_t delta)
	Add the operand to the value of the addressed block, and store the result in the Transfer Buffer.

int	mfrc522_mifare_restore (mfrc522_t *dev, uint8_t block_addr)
	Copies the value of the addressed block into the Transfer Buffer.

int	mfrc522_mifare_transfer (mfrc522_t *dev, uint8_t block_addr)
	Write the value from the Transfer Buffer into destination block.

int	mfrc522_mifare_get_value (mfrc522_t dev, uint8_t block_addr, int32_t value)
	Helper routine to read the current value from a Value Block.

int	mfrc522_mifare_set_value (mfrc522_t *dev, uint8_t block_addr, int32_t value)
	Helper routine to write a specific value into a Value Block.

int	mfrc522_pcd_ntag216_auth (mfrc522_t dev, const uint8_t password, uint8_t p_ack[])
	Authenticate with a NTAG216.

int	mfrc522_pcd_mifare_transceive (mfrc522_t dev, const uint8_t send_data, uint8_t send_len, bool accept_timeout)
	Wrapper for MIFARE protocol communication.

mfrc522_picc_type_t	mfrc522_picc_get_type (uint8_t sak)
	Translates the SAK (Select Acknowledge) to a PICC type.

const char *	mfrc522_picc_get_type_string (mfrc522_picc_type_t picc_type)
	Returns the name for the PICC type.

void	mfrc522_mifare_set_access_bits (uint8_t *access_bit_buffer, uint8_t g0, uint8_t g1, uint8_t g2, uint8_t g3)
	Calculates the bit pattern needed for the specified access bits.

int	mfrc522_mifare_open_uid_backdoor (mfrc522_t *dev)
	Performs the "magic sequence" needed to get Chinese UID changeable Mifare cards to allow writing to sector 0, where the card UID is stored.

int	mfrc522_mifare_set_uid (mfrc522_t dev, mfrc522_uid_t uid, const uint8_t *new_uid, uint8_t new_uid_size)
	Read entire block 0, including all manufacturer data, and overwrites that block with the new UID, a freshly calculated BCC, and the original manufacturer data.

int	mfrc522_mifare_unbrick_uid_sector (mfrc522_t *dev)
	Reset entire sector 0 to zeroes, so the card can be read again by readers.

bool	mfrc522_picc_is_new_card_present (mfrc522_t *dev)
	Checks whether a new card could be detected.

int	mfrc522_picc_read_card_serial (mfrc522_t dev, mfrc522_uid_t uid)
	Simple wrapper around mfrc522_picc_select()

void	mfrc522_pcd_dump_version_to_serial (mfrc522_t *dev)
	Dump debug info about the connected PCD to stdout.

void	mfrc522_picc_dump_to_serial (mfrc522_t dev, mfrc522_uid_t uid)
	Dump debug info about the selected PICC to stdout.

void	mfrc522_picc_dump_details_to_serial (mfrc522_uid_t *uid)
	Dump card info (UID, SAK, Type) about the selected PICC to stdout.

void	mfrc522_picc_dump_mifare_classic_to_serial (mfrc522_t dev, mfrc522_uid_t uid, mfrc522_picc_type_t picc_type, mfrc522_mifare_key_t *key)
	Dump memory contents of a MIFARE Classic PICC to stdout.

void	mfrc522_picc_dump_mifare_classic_sector_to_serial (mfrc522_t dev, mfrc522_uid_t uid, mfrc522_mifare_key_t *key, uint8_t sector)
	Dump memory contents of a sector of a MIFARE Classic PICC to stdout.

void	mfrc522_picc_dump_mifare_ultralight_to_serial (mfrc522_t *dev)
	Dump memory contents of a MIFARE Ultralight PICC to stdout.

bool	mfrc522_pcd_perform_self_test (mfrc522_t *dev)
	Perform a self-test of the MFRC522.

Macro Definition Documentation

◆ MFRC522_MF_ACK

#define MFRC522_MF_ACK 0xA

The MIFARE Classic uses a 4 bit ACK/NAK.

Any other value than 0xA is NAK

Definition at line 60 of file mfrc522.h.

◆ MFRC522_MF_KEY_SIZE

#define MFRC522_MF_KEY_SIZE 6

A Mifare Crypto1 key is 6 bytes.

Definition at line 65 of file mfrc522.h.

◆ MFRC522_UID_MAX_SIZE

#define MFRC522_UID_MAX_SIZE 10

Maximum size for uid byte array.

Definition at line 55 of file mfrc522.h.

Enumeration Type Documentation

◆ mfrc522_picc_type_t

enum mfrc522_picc_type_t

PICC types.

Enumerator
MFRC522_PICC_TYPE_ISO_14443_4	PICC compliant with ISO/IEC 14443-4.
MFRC522_PICC_TYPE_ISO_18092	PICC compliant with ISO/IEC 18092 (NFC)
MFRC522_PICC_TYPE_MIFARE_MINI	MIFARE Classic protocol, 320 bytes.
MFRC522_PICC_TYPE_MIFARE_1K	MIFARE Classic protocol, 1KB.
MFRC522_PICC_TYPE_MIFARE_4K	MIFARE Classic protocol, 4KB.
MFRC522_PICC_TYPE_MIFARE_UL	MIFARE Ultralight or Ultralight C.
MFRC522_PICC_TYPE_MIFARE_PLUS	MIFARE Plus.
MFRC522_PICC_TYPE_MIFARE_DESFIRE	MIFARE DESFire.
MFRC522_PICC_TYPE_TNP3XXX	Only mentioned in NXP AN 10833 MIFARE Type Identification Procedure.
MFRC522_PICC_TYPE_NOT_COMPLETE	SAK indicates UID is not complete.
MFRC522_PICC_TYPE_UNKNOWN	unknown type

Definition at line 107 of file mfrc522.h.

Function Documentation

◆ mfrc522_mifare_decrement()

int mfrc522_mifare_decrement	(	mfrc522_t *	dev,
		uint8_t	block_addr,
		int32_t	delta
	)

Subtract the operand from the value of the addressed block, and store the result in the Transfer Buffer.

MIFARE Decrement subtracts the delta from the value of the addressed block, and stores the result in a volatile memory. For MIFARE Classic only. The sector containing the block must be authenticated before calling this function. Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001]. Use MIFARE_Transfer() to store the result in a block.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	Block (0-0xff) number
[in]	delta	Number to be subtracted from the value of block block_addr

Return values

0	on success
-ECANCELED	on internal error

◆ mfrc522_mifare_get_value()

int mfrc522_mifare_get_value	(	mfrc522_t *	dev,
		uint8_t	block_addr,
		int32_t *	value
	)

Helper routine to read the current value from a Value Block.

Note: Only for MIFARE Classic and only for blocks in "value block" mode, that is with access bits [C1 C2 C3] = [110] or [001]. The sector containing the block must be authenticated before calling this function.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	Block (0x00-0xff) number
[out]	value	Current value of the Value Block

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_increment()

int mfrc522_mifare_increment	(	mfrc522_t *	dev,
		uint8_t	block_addr,
		int32_t	delta
	)

Add the operand to the value of the addressed block, and store the result in the Transfer Buffer.

MIFARE Increment adds the delta to the value of the addressed block, and stores the result in a volatile memory. For MIFARE Classic only. The sector containing the block must be authenticated before calling this function. Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001]. Use MIFARE_Transfer() to store the result in a block.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	Block (0-0xff) number
[in]	delta	Number to be added to the value of block block_addr

Return values

0	on success
-ECANCELED	on internal error

◆ mfrc522_mifare_open_uid_backdoor()

int mfrc522_mifare_open_uid_backdoor ( mfrc522_t * dev )

Performs the "magic sequence" needed to get Chinese UID changeable Mifare cards to allow writing to sector 0, where the card UID is stored.

Note: Note that you do not need to have selected the card through REQA or WUPA, this sequence works immediately when the card is in the reader vicinity. This means you can use this method even on "bricked" cards that your reader does not recognise anymore (see mfrc522_mifare_unbrick_uid_sector). Of course with non-bricked devices, you are free to select them before calling this function.

Parameters

[in] dev Device descriptor of the MFRC522

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_read()

int mfrc522_mifare_read	(	mfrc522_t *	dev,
		uint8_t	block_addr,
		uint8_t *	buffer,
		uint8_t *	buffer_size
	)

Read 16 bytes (+ 2 bytes CRC_A) from the active PICC.

Note: For MIFARE Classic the sector containing the block must be authenticated before calling this function.

For MIFARE Ultralight only addresses 00h to 0Fh are decoded. The MF0ICU1 returns a NAK for higher addresses. The MF0ICU1 responds to the READ command by sending 16 bytes starting from the page address defined by the command argument. For example; if block_addr is 03h then pages 03h, 04h, 05h, 06h are returned. A roll-back is implemented: If block_addr is 0Eh, then the contents of pages 0Eh, 0Fh, 00h and 01h are returned.

The buffer must be at least 18 bytes because a CRC_A is also returned. Checks the CRC_A before returning.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	MIFARE Classic: The block (0-0xff) number. MIFARE Ultralight: The first page to return data from.
[out]	buffer	Buffer to store the data in
[in,out]	buffer_size	Buffer size, at least 18 bytes. Also number of bytes returned on success.

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_restore()

int mfrc522_mifare_restore	(	mfrc522_t *	dev,
		uint8_t	block_addr
	)

Copies the value of the addressed block into the Transfer Buffer.

MIFARE Restore copies the value of the addressed block into a volatile memory. For MIFARE Classic only. The sector containing the block must be authenticated before calling this function. Only for blocks in "value block" mode, i.e. with access bits [C1 C2 C3] = [110] or [001]. Use mfrc522_mifare_transfer() to store the result in a block.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	Block (0-0xff) number

Return values

0	on success
-ECANCELED	on internal error

◆ mfrc522_mifare_set_access_bits()

void mfrc522_mifare_set_access_bits	(	uint8_t *	access_bit_buffer,
		uint8_t	g0,
		uint8_t	g1,
		uint8_t	g2,
		uint8_t	g3
	)

Calculates the bit pattern needed for the specified access bits.

In the [C1 C2 C3] tuples C1 is MSB (=4) and C3 is LSB (=1).

Parameters

[out]	access_bit_buffer	Pointer to byte 6, 7 and 8 in the sector trailer. Bytes [0..2] will be set.
[in]	g0	Access bits [C1 C2 C3] for block 0 (for sectors 0-31) or blocks 0-4 (for sectors 32-39)
[in]	g1	Access bits [C1 C2 C3] for block 1 (for sectors 0-31) or blocks 5-9 (for sectors 32-39)
[in]	g2	Access bits [C1 C2 C3] for block 2 (for sectors 0-31) or blocks 10-14 (for sectors 32-39)
[in]	g3	Access bits [C1 C2 C3] for the sector trailer, block 3 (for sectors 0-31) or block 15 (for sectors 32-39)

◆ mfrc522_mifare_set_uid()

int mfrc522_mifare_set_uid	(	mfrc522_t *	dev,
		mfrc522_uid_t *	uid,
		const uint8_t *	new_uid,
		uint8_t	new_uid_size
	)

Read entire block 0, including all manufacturer data, and overwrites that block with the new UID, a freshly calculated BCC, and the original manufacturer data.

Note: It assumes a default KEY A of 0xFFFFFFFFFFFF. Make sure to have selected the PICC before this function is called and that the UID of the PICC is changeable.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	uid	PICC's UID
[in]	new_uid	New UID to set on PICC
[in]	new_uid_size	Size of new UID

Return values

0	on success
-ECANCELED	on internal error
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_set_value()

int mfrc522_mifare_set_value	(	mfrc522_t *	dev,
		uint8_t	block_addr,
		int32_t	value
	)

Helper routine to write a specific value into a Value Block.

Note: Only for MIFARE Classic and only for blocks in "value block" mode, that is with access bits [C1 C2 C3] = [110] or [001]. The sector containing the block must be authenticated before calling this function.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	Block (0x00-0xff) number
[in]	value	New value of the Value Block

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_transfer()

int mfrc522_mifare_transfer	(	mfrc522_t *	dev,
		uint8_t	block_addr
	)

Write the value from the Transfer Buffer into destination block.

MIFARE Transfer writes the value stored in the volatile memory into one MIFARE Classic block. For MIFARE Classic only. The sector containing the block must be authenticated before calling this function. Only for blocks in "value block" mode, ie with access bits [C1 C2 C3] = [110] or [001].

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	Block (0-0xff) number

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_ultralight_write()

int mfrc522_mifare_ultralight_write	(	mfrc522_t *	dev,
		uint8_t	page,
		const uint8_t *	buffer
	)

Write a 4 byte page to the active MIFARE Ultralight PICC.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	page	The page (2-15) to write to
[in]	buffer	The 4 bytes to write to the PICC

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_unbrick_uid_sector()

int mfrc522_mifare_unbrick_uid_sector ( mfrc522_t * dev )

Reset entire sector 0 to zeroes, so the card can be read again by readers.

Parameters

[in] dev Device descriptor of the MFRC522

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_mifare_write()

int mfrc522_mifare_write	(	mfrc522_t *	dev,
		uint8_t	block_addr,
		const uint8_t *	buffer,
		uint8_t	buffer_size
	)

Write 16 bytes to the active PICC.

Note: For MIFARE Classic the sector containing the block must be authenticated before calling this function.

For MIFARE Ultralight the operation is called "COMPATIBILITY WRITE". Even though 16 bytes are transferred to the Ultralight PICC, only the least significant 4 bytes (bytes 0 to 3) are written to the specified address. It is recommended to set the remaining bytes 04h to 0Fh to all logic 0.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	block_addr	MIFARE Classic: The block (0-0xff) number. MIFARE Ultralight: The page (2-15) to write to.
[in]	buffer	The 16 bytes to write to the PICC
[in]	buffer_size	Buffer size, must be at least 16 bytes. Exactly 16 bytes are written.

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_pcd_antenna_off()

void mfrc522_pcd_antenna_off ( mfrc522_t * dev )

Turns the antenna off by disabling pins TX1 and TX2.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_antenna_on()

void mfrc522_pcd_antenna_on ( mfrc522_t * dev )

Turns the antenna on by enabling pins TX1 and TX2.

After a reset these pins are disabled.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_authenticate()

int mfrc522_pcd_authenticate	(	mfrc522_t *	dev,
		mfrc522_picc_command_t	command,
		uint8_t	block_addr,
		const mfrc522_mifare_key_t *	key,
		const mfrc522_uid_t *	uid
	)

Executes the MFRC522 MFAuthent command.

This command manages MIFARE authentication to enable a secure communication to any MIFARE Mini, MIFARE 1K and MIFARE 4K card. The authentication is described in the MFRC522 datasheet section 10.3.1.9 and http://www.nxp.com/documents/data_sheet/MF1S503x.pdf section 10.1. For use with MIFARE Classic PICCs. The PICC must be selected - i.e. in state ACTIVE(*) - before calling this function. Remember to call mfrc522_pcd_stop_crypto1() after communicating with the authenticated PICC - otherwise no new communications can start.

All keys are set to FFFFFFFFFFFFh at chip delivery.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	command	MFRC522_PICC_CMD_MF_AUTH_KEY_A or PICC_CMD_MF_AUTH_KEY_B
[in]	block_addr	Block number. See numbering in the comments in the .h file.
[in]	key	Crypteo1 key to use (6 bytes)
[in]	uid	PICC's UID

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_pcd_calculate_crc()

int mfrc522_pcd_calculate_crc	(	mfrc522_t *	dev,
		const uint8_t *	data,
		uint8_t	length,
		uint8_t *	result
	)

Use the CRC coprocessor in the MFRC522 to calculate a CRC_A.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	data	Data to transfer to the FIFO for CRC calculation
[in]	length	Number of bytes to transfer
[out]	result	Result buffer. Result is written to result[0..1], low byte first.

Return values

0	on success
-ETIMEDOUT	on timeout

◆ mfrc522_pcd_clear_register_bitmask()

void mfrc522_pcd_clear_register_bitmask	(	mfrc522_t *	dev,
		mfrc522_pcd_register_t	reg,
		uint8_t	mask
	)

Clears the bits given in mask from register reg.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	reg	Register to write to
[in]	mask	Bitmask with the bits to clear

◆ mfrc522_pcd_communicate_with_picc()

int mfrc522_pcd_communicate_with_picc	(	mfrc522_t *	dev,
		mfrc522_pcd_command_t	command,
		uint8_t	wait_irq,
		const uint8_t *	send_data,
		uint8_t	send_len,
		uint8_t *	back_data,
		uint8_t *	back_len,
		uint8_t *	valid_bits,
		uint8_t	rx_align,
		bool	check_crc
	)

Transfers data to MFRC522's FIFO, executes a command, waits for completion and transfers data back from the FIFO.

Note: CRC validation can only be done if back_data and back_len are specified

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	command	The command to execute
[in]	wait_irq	The bits in the ComIrqReg register that signals successful completion of the command
[in]	send_data	Data to transfer to the FIFO
[in]	send_len	Number of bytes to transfer to the FIFO
[out]	back_data	Buffer if data should be read back after executing the command, otherwise NULL
[in,out]	back_len	Max number of bytes to write to *back_data. Returns number of bytes returned.
[in,out]	valid_bits	Number of valid bits in the last byte. 0 for 8 valid bits.
[in]	rx_align	Defines the bit position in back_data[0] for the first bit received
[in]	check_crc	True => The last two bytes of the response is assumed to be a CRC_A that must be validated

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_pcd_dump_version_to_serial()

void mfrc522_pcd_dump_version_to_serial ( mfrc522_t * dev )

Dump debug info about the connected PCD to stdout.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_get_antenna_gain()

mfrc522_pcd_rx_gain_t mfrc522_pcd_get_antenna_gain ( mfrc522_t * dev )

Get the current MFRC522 receiver gain.

Parameters

[in] dev Device descriptor of the MFRC522

Returns: Receiver gain

◆ mfrc522_pcd_init()

int mfrc522_pcd_init	(	mfrc522_t *	dev,
		const mfrc522_params_t *	params
	)

Initialization.

Parameters

[out]	dev	Device descriptor of the MFRC522
[in]	params	Parameters for device initialization

Return values

0	Success
-EINVAL	Invalid CS pin/line
-ENXIO	Invalid device

◆ mfrc522_pcd_mifare_transceive()

int mfrc522_pcd_mifare_transceive	(	mfrc522_t *	dev,
		const uint8_t *	send_data,
		uint8_t	send_len,
		bool	accept_timeout
	)

Wrapper for MIFARE protocol communication.

Adds CRC_A, executes the Transceive command and checks that the response is MFRC522_MF_ACK or a timeout.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	send_data	Data to transfer to the FIFO. Do NOT include the CRC_A.
[in]	send_len	Number of bytes in send_data
[in]	accept_timeout	If true, then a timeout is also a success

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_pcd_ntag216_auth()

int mfrc522_pcd_ntag216_auth	(	mfrc522_t *	dev,
		const uint8_t *	password,
		uint8_t	p_ack[]
	)

Authenticate with a NTAG216.

Note: Only for NTAG216

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	password	Password (must have a size of exactly 4 bytes)
[out]	p_ack	result (must have a size of exactly 2 bytes)

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_pcd_perform_self_test()

bool mfrc522_pcd_perform_self_test ( mfrc522_t * dev )

Perform a self-test of the MFRC522.

(See section 16.1.1)

Parameters

[in] dev Device descriptor of the MFRC522

Returns: true if the test passed, false otherwise and if no firmware reference is available.

◆ mfrc522_pcd_reset()

void mfrc522_pcd_reset ( mfrc522_t * dev )

Performs a soft reset on the MFRC522 chip and waits for it to be ready again.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_set_antenna_gain()

void mfrc522_pcd_set_antenna_gain	(	mfrc522_t *	dev,
		mfrc522_pcd_rx_gain_t	rx_gain
	)

Set the MFRC522 receiver gain.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	rx_gain	Antenna gain

◆ mfrc522_pcd_set_register_bitmask()

void mfrc522_pcd_set_register_bitmask	(	mfrc522_t *	dev,
		mfrc522_pcd_register_t	reg,
		uint8_t	mask
	)

Sets the bits given in mask in register reg.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	reg	Register to write to
[in]	mask	Bitmask with the bits to set

◆ mfrc522_pcd_soft_power_down()

void mfrc522_pcd_soft_power_down ( mfrc522_t * dev )

Set the MFRC522 to soft power-down mode.

Note: Only soft power down mode is available through software.; Calling any other function that uses MFRC522_REG_COMMAND will disable soft power down mode! For more details about power control, refer to the datasheet - page 33 (8.6)

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_soft_power_up()

void mfrc522_pcd_soft_power_up ( mfrc522_t * dev )

Set the MFRC522 to leave soft power-down mode.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_stop_crypto1()

void mfrc522_pcd_stop_crypto1 ( mfrc522_t * dev )

Used to exit the PCD from its authenticated state.

Note: Remember to call this function after communicating with an authenticated PICC - otherwise no new communications can start.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_pcd_transceive_data()

int mfrc522_pcd_transceive_data	(	mfrc522_t *	dev,
		const uint8_t *	send_data,
		uint8_t	send_len,
		uint8_t *	back_data,
		uint8_t *	back_len,
		uint8_t *	valid_bits,
		uint8_t	rx_align,
		bool	check_crc
	)

Executes MFRC522_CMD_TRANSCEIVE.

Note: CRC validation can only be done if back_data and back_len are specified

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	send_data	Data to transfer to the FIFO
[in]	send_len	Number of bytes to transfer to the FIFO
[out]	back_data	Buffer if data should be read back after executing the command, otherwise NULL
[in,out]	back_len	Max number of bytes to write to *back_data. Returns number of bytes returned.
[in,out]	valid_bits	Number of valid bits in the last byte. 0 for 8 valid bits
[in]	rx_align	Defines the bit position in back_data[0] for the first bit received
[in]	check_crc	If true, the last two bytes of the response are assumed to be a CRC_A that must be validated

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_picc_dump_details_to_serial()

void mfrc522_picc_dump_details_to_serial ( mfrc522_uid_t * uid )

Dump card info (UID, SAK, Type) about the selected PICC to stdout.

Parameters

[in] uid PICC's UID

◆ mfrc522_picc_dump_mifare_classic_sector_to_serial()

void mfrc522_picc_dump_mifare_classic_sector_to_serial	(	mfrc522_t *	dev,
		mfrc522_uid_t *	uid,
		mfrc522_mifare_key_t *	key,
		uint8_t	sector
	)

Dump memory contents of a sector of a MIFARE Classic PICC to stdout.

Uses mfrc522_pcd_authenticate(), mfrc522_mifare_read() and mfrc522_pcd_stop_crypto1(). Always uses MFRC522_PICC_CMD_MF_AUTH_KEY_A because only Key A can always read the sector trailer access bits.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	uid	PICC's UID
[in]	key	Key A for the sector.
[in]	sector	The sector to dump, 0..39

◆ mfrc522_picc_dump_mifare_classic_to_serial()

void mfrc522_picc_dump_mifare_classic_to_serial	(	mfrc522_t *	dev,
		mfrc522_uid_t *	uid,
		mfrc522_picc_type_t	picc_type,
		mfrc522_mifare_key_t *	key
	)

Dump memory contents of a MIFARE Classic PICC to stdout.

Note: On success the PICC is halted after dumping the data.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	uid	PICC's UID
[in]	picc_type	PICC type enum
[in]	key	Key A used for all sectors.

◆ mfrc522_picc_dump_mifare_ultralight_to_serial()

void mfrc522_picc_dump_mifare_ultralight_to_serial ( mfrc522_t * dev )

Dump memory contents of a MIFARE Ultralight PICC to stdout.

Parameters

[in] dev Device descriptor of the MFRC522

◆ mfrc522_picc_dump_to_serial()

void mfrc522_picc_dump_to_serial	(	mfrc522_t *	dev,
		mfrc522_uid_t *	uid
	)

Dump debug info about the selected PICC to stdout.

Note: On success the PICC is halted after dumping the data. For MIFARE Classic the factory default key of 0xFFFFFFFFFFFF is tried.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	uid	PICC's UID

◆ mfrc522_picc_get_type()

mfrc522_picc_type_t mfrc522_picc_get_type ( uint8_t sak )

Translates the SAK (Select Acknowledge) to a PICC type.

Parameters

[in] sak The SAK byte returned from mfrc522_picc_select()

Returns: PICC type

◆ mfrc522_picc_get_type_string()

const char * mfrc522_picc_get_type_string ( mfrc522_picc_type_t picc_type )

Returns the name for the PICC type.

Parameters

[in] picc_type PICC type enum

Returns: PICC type name

◆ mfrc522_picc_halt_a()

int mfrc522_picc_halt_a ( mfrc522_t * dev )

Instructs a PICC in state ACTIVE(*) to go to state HALT.

Parameters

[in] dev Device descriptor of the MFRC522

Return values

0	on success
-EIO	on communication error
-ETIMEDOUT	on timeout

◆ mfrc522_picc_is_new_card_present()

bool mfrc522_picc_is_new_card_present ( mfrc522_t * dev )

Checks whether a new card could be detected.

Note: Only "new" cards in state IDLE are invited. Sleeping cards in state HALT are ignored.

Parameters

[in] dev Device descriptor of the MFRC522

Returns: true if new card was detected, false otherwise

◆ mfrc522_picc_read_card_serial()

int mfrc522_picc_read_card_serial	(	mfrc522_t *	dev,
		mfrc522_uid_t *	uid
	)

Simple wrapper around mfrc522_picc_select()

Note: Remember to call mfrc522_picc_is_new_card_present(), mfrc522_picc_request_a() or mfrc522_picc_wakeup_a() first.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	uid	PICC's UID

Return values

0	on success
-ECANCELED	on internal error
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_picc_reqa_or_wupa()

int mfrc522_picc_reqa_or_wupa	(	mfrc522_t *	dev,
		mfrc522_picc_command_t	command,
		uint8_t *	buffer_atqa,
		uint8_t *	buffer_size
	)

Transmits REQA (Type A) or WUPA (Type A) commands.

Note: When two PICCs are in the field at the same time we often get -ETIMEDOUT - probably due do bad antenna design.

Parameters

[in]	dev	Device descriptor of the MFRC522
[in]	command	Command to send - MFRC522_PICC_CMD_ISO_14443_REQA or MFRC522_PICC_CMD_ISO_14443_WUPA
[out]	buffer_atqa	Buffer to store the ATQA in
[in,out]	buffer_size	Buffer size, at least two bytes. Also number of bytes returned on success.

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	if command was neither MFRC522_PICC_CMD_ISO_14443_REQA nor MFRC522_PICC_CMD_ISO_14443_WUPA
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_picc_request_a()

int mfrc522_picc_request_a	(	mfrc522_t *	dev,
		uint8_t *	buffer_atqa,
		uint8_t *	buffer_size
	)

Transmits REQA, Type A.

Invites PICCs in state IDLE to go to READY and prepare for anti-collision or selection. 7 bit frame.

Note: When two PICCs are in the field at the same time we often get -ETIMEDOUT - probably due do bad antenna design.

Parameters

[in]	dev	Device descriptor of the MFRC522
[out]	buffer_atqa	Buffer to store the ATQA in
[in,out]	buffer_size	Buffer size, at least two bytes. Also number of bytes returned on success.

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_picc_select()

int mfrc522_picc_select	(	mfrc522_t *	dev,
		mfrc522_uid_t *	uid,
		uint8_t	valid_bits
	)

Transmits SELECT/ANTICOLLISION commands to select a single PICC.

Note

Before calling this function the PICCs must be placed in the READY(*) state by calling mfrc522_picc_request_a() or mfrc522_picc_wakeup_a(). On success:

The chosen PICC is in state ACTIVE(*) and all other PICCs have returned to state IDLE/HALT. (Figure 7 of the ISO/IEC 14443-3 draft.)
The UID size and value of the chosen PICC is returned in *uid along with the SAK.

A PICC UID consists of 4, 7 or 10 bytes. Only 4 bytes can be specified in a SELECT command, so for the longer UIDs two or three iterations are used:

UID size Number of UID bytes Cascade levels Example of PICC ======== =================== ============== =============== single 4 1 MIFARE Classic double 7 2 MIFARE Ultralight triple 10 3 Not currently in use?

Parameters

[in]	dev	Device descriptor of the MFRC522
[in,out]	uid	Normally output, but can also be used to supply a known UID
[in]	valid_bits	Number of known UID bits supplied in *uid. Normally 0. If set you must also supply uid->size.

Return values

0	on success
-ECANCELED	on internal error
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

◆ mfrc522_picc_wakeup_a()

int mfrc522_picc_wakeup_a	(	mfrc522_t *	dev,
		uint8_t *	buffer_atqa,
		uint8_t *	buffer_size
	)

Transmits WUPA, Type A.

Invites PICCs in state IDLE and HALT to go to READY(*) and prepare for anti-collision or selection. 7 bit frame.

Note: When two PICCs are in the field at the same time we often get -ETIMEDOUT - probably due do bad antenna design.

Parameters

[in]	dev	Device descriptor of the MFRC522
[out]	buffer_atqa	Buffer to store the ATQA in
[in,out]	buffer_size	Buffer size, at least two bytes. Also number of bytes returned on success.

Return values

0	on success
-ECONNABORTED	when a collision occurred
-EINVAL	on invalid argument
-EIO	on communication error
-ENOBUFS	when a buffer is too small to receive data
-ETIMEDOUT	on timeout

Detailed Description

Files

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ MFRC522_MF_ACK

◆ MFRC522_MF_KEY_SIZE

◆ MFRC522_UID_MAX_SIZE

Enumeration Type Documentation

◆ mfrc522_picc_type_t

Function Documentation

◆ mfrc522_mifare_decrement()

◆ mfrc522_mifare_get_value()

◆ mfrc522_mifare_increment()

◆ mfrc522_mifare_open_uid_backdoor()

◆ mfrc522_mifare_read()

◆ mfrc522_mifare_restore()

◆ mfrc522_mifare_set_access_bits()

◆ mfrc522_mifare_set_uid()

◆ mfrc522_mifare_set_value()

◆ mfrc522_mifare_transfer()

◆ mfrc522_mifare_ultralight_write()

◆ mfrc522_mifare_unbrick_uid_sector()

◆ mfrc522_mifare_write()

◆ mfrc522_pcd_antenna_off()

◆ mfrc522_pcd_antenna_on()

◆ mfrc522_pcd_authenticate()

◆ mfrc522_pcd_calculate_crc()

◆ mfrc522_pcd_clear_register_bitmask()

◆ mfrc522_pcd_communicate_with_picc()

◆ mfrc522_pcd_dump_version_to_serial()

◆ mfrc522_pcd_get_antenna_gain()

◆ mfrc522_pcd_init()

◆ mfrc522_pcd_mifare_transceive()

◆ mfrc522_pcd_ntag216_auth()

◆ mfrc522_pcd_perform_self_test()

◆ mfrc522_pcd_reset()

◆ mfrc522_pcd_set_antenna_gain()

◆ mfrc522_pcd_set_register_bitmask()

◆ mfrc522_pcd_soft_power_down()

◆ mfrc522_pcd_soft_power_up()

◆ mfrc522_pcd_stop_crypto1()

◆ mfrc522_pcd_transceive_data()

◆ mfrc522_picc_dump_details_to_serial()

◆ mfrc522_picc_dump_mifare_classic_sector_to_serial()

◆ mfrc522_picc_dump_mifare_classic_to_serial()

◆ mfrc522_picc_dump_mifare_ultralight_to_serial()

◆ mfrc522_picc_dump_to_serial()

◆ mfrc522_picc_get_type()

◆ mfrc522_picc_get_type_string()

◆ mfrc522_picc_halt_a()

◆ mfrc522_picc_is_new_card_present()

◆ mfrc522_picc_read_card_serial()

◆ mfrc522_picc_reqa_or_wupa()

◆ mfrc522_picc_request_a()

◆ mfrc522_picc_select()

◆ mfrc522_picc_wakeup_a()