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.

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

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

• MFRC522 Datasheet (NXP)
• ISO/IEC 14443 Overview
• MIFARE Classic 1K Datasheet
• Application Note AN10833 – Card Type Detection
• Application Note AN10834 – PICC Selection

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.