ESP-IDF library for managing NFC cards using MFRC522 module

Introduction

RFID (Radio-Frequency Identification) is a widely used technology for contactless identification, access control, and short-range data transfer. The MFRC522 is a popular RFID reader/writer that supports ISO/IEC 14443 Type A cards such as MIFARE Classic and NTAG families.

MFRC522 Read Write example output shown in Terminal

The esp-idf-rc522 library is a lightweight and efficient ESP-IDF component, written in C, designed to simplify integration of MFRC522 modules with ESP32-based projects. It handles card polling, lifecycle events, and read/write operations, providing developers with a stable and extensible interface for RFID communication.

Features

Card polling with lifecycle management
Event callbacks for detection, removal, and status change
Authentication support for MIFARE cards
Read/write access to card memory blocks
SPI and I2C communication support
Unit testing framework for Linux
Practical examples for real-world use cases

Installation

To add this component to your project, simply run:

idf.py add-dependency "abobija/rc522"

This will fetch the latest compatible version using the ESP-IDF component manager.

Supported Cards

MIFARE Classic 1K / 4K
MIFARE Mini
NTAG and Ultralight card families

MFRC522 reader wired to the ESP32 device. Ready for new RFID cards.

The component supports a wide range of commands, making it suitable for reading, writing, and authenticating various card types used in everyday RFID applications.

Communication Interfaces

The MFRC522 module can be connected using:

SPI (default)
I²C

You can configure the GPIOs according to your needs. See the basic.c file in the example project for a working SPI setup.

Usage Examples

Run the Basic Example

To try the basic example:

idf.py create-project-from-example "abobija/rc522:basic"
cd basic
idf.py build flash monitor

This example shows how to:

Initialize the RC522 module
Detect cards and log UIDs
Authenticate and read memory blocks

More examples, such as memory_dump, are available in the examples/ folder.

Security Notes

MIFARE Classic cards should not be used for security-sensitive applications.

MIFARE Classic uses the Crypto-1 cipher, which is considered insecure.
Some cards on the market allow changing the UID, which makes them unsuitable as unique identifiers.
For secure authentication, consider using more modern card types like MIFARE DESFire or Plus (with AES encryption).

Terminology

Term	Description
PCD	Proximity Coupling Device (e.g. RC522 reader)
PICC	Proximity Integrated Circuit Card (e.g. RFID tag or card)

References

Conclusion

The esp-idf-rc522 component is a robust and easy-to-use RFID library tailored for the ESP32 platform. With support for common card types, flexible communication options, and an event-driven design, it enables developers to build interactive and secure RFID-enabled applications with minimal effort.

Whether you’re building an access control system, an attendance tracker, or simply experimenting with contactless technology, this component provides a solid foundation for working with RFID cards on ESP32.

License

This project is licensed under the Apache 2.0 License.
See the LICENSE file for details.