esp-idf-rc522

This repository contains ESP-IDF library (component) for communication with RFID cards using MFRC522 reader.

Library takes care of polling the cards and managing the card lifecycle. It also fires events when a card is detected, removed, or when the card changes to any state described in ISO-14443. Additionally, it provides an API for reading and writing to card memory blocks.

Installation

To install latest version of this component to your project, run:

idf.py add-dependency "abobija/rc522"

Read more about esp-idf component manager in official documentation.

Support

• Cards: MIFARE 1K, MIFARE 4K and MIFARE Mini
• Card operations:
  • Read and write to memory blocks (example)
• Communication protocols: SPI and I2C
• ESP-IDF version: ^5

Create project from example

Tip

To find more interesting examples (like memory_dump), go to examples folder.

To run basic example, create it as follows:

idf.py create-project-from-example "abobija/rc522:basic"

Then build and flash it as usual:

cd basic
idf.py build flash monitor

Note

basic example uses SPI communication. Find defined GPIO configuration in basic.c file.

Pin Layout

Pin layout is configurable by the user. To configure the GPIOs, check the #define statements in the basic example. If you are not using the RST pin, you can connect it to the 3.3V.

Unit testing

To run unit tests, go to test directory and set target to linux:

cd test
idf.py --preview set-target linux

Then build the project and run tests:

idf.py build && ./build/test.elf

Security

• Mifare Classic cards use the Crypto-1 cipher for authentication and encryption, which has been broken for a long time. As a result, it is not advisable to use Mifare Classic cards for security-sensitive applications. Instead, consider using Mifare Plus or Desfire cards, which utilize AES encryption.
• Even though block zero, which contains the UID, is typically considered as read-only, there are certain cards known as "magic" or "Chinese magic" cards that can be used to modify the UID. As a result, relying on the UID of a card as a secure identifier is not recommended.

Terms

Term	Description
PCD	Proximity Coupling Device (the card reader). In our case this is MFRC522 module
PICC	Proximity Integrated Circuit Card (e.g: rfid card, tag, ...)

References

• ISO/IEC 14443 Identification cards - Contactless integrated circuit cards
• ISO/IEC 14443-2 Radio frequency power and signal interface
• ISO/IEC 14443-3 Initialization and anticollision
• ISO/IEC 14443-4 Transmission protocol
• MFRC522 MFRC522 - Standard performance MIFARE and NTAG frontend
• AN10833 MIFARE type identification procedure
• AN10834 MIFARE ISO/IEC 14443 PICC selection
• MF1S50YYX_V1 MIFARE Classic EV1 1K
• MF1S70YYX_V1 MIFARE Classic EV1 4K

License

This component is provided under Apache 2.0 license, see LICENSE file for details.