# miguelbalboa/rfid: the frozen Arduino MFRC522 library, and what it still does well

> The miguelbalboa/rfid library is the long-standing Arduino driver for RC522-based RFID readers. Development is frozen by the owner, so the useful question is not whether it is modern, but which cards and boards it actually handles.

**miguelbalboa/rfid** — Arduino RFID Library for MFRC522

- Repository: https://github.com/miguelbalboa/rfid
- Stars: 3,037 · Forks: 1,491
- Language: C++
- License: Unlicense
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/miguelbalboa-rfid

## What miguelbalboa/rfid solves, and who it is written for

An RC522 breakout is cheap and speaks SPI, but SPI alone does not give you a card protocol. The reader chip handles the radio side; something has to drive the register sequence, run the Crypto1 authentication for MIFARE Classic, and expose the result as a UID or a block read. That something is this library. It targets Arduino boards, and the README is explicit that the main target and support remain Arduino even though Teensy and ESP8266 work through the Arduino IDE board plugin. The examples directory shows the intended shape of use: ReadNUID, DumpInfo, ReadAndWrite, MifareClassicValueBlock, rfid_default_keys, FixBrickedUID, ChangeUID, Ntag216_AUTH, firmware_check, MinimalInterrupt, ReadUidMultiReader, RFID-Cloner, and the personal data read and write sketches. A beginner can open ReadNUID, wire the reader, and get a UID on the serial monitor. That low floor is the point of the project, and it is also why the owner froze it: the README says the library has a long history and is used in projects that do not document which version they use, so committing changes risks breaking them.

## How the SPI driver and the Crypto1 path actually work

The library sits on top of Arduino SPI. The reader's SPI SS pin, labelled SDA on the RC522 board, is driven as a chip select, and the README lists managing that pin as one of the things that works. The RST pin is wired separately so the library can reset the reader. Above that layer the library performs a firmware self check of the MFRC522 and then runs the card protocol. For MIFARE Classic 1k, 4k and Mini, and for Classic-compatible PICCs, it does Crypto1 authentication against the sector keys, which is why rfid_default_keys exists as an example: it tries known default keys against a card. Once authenticated, block reads and writes become possible, and MifareClassicValueBlock shows the value-block arithmetic that Classic cards support. Sector 0 is special because it holds the UID and the manufacturer block, and the ChangeUID and FixBrickedUID examples exist for the Chinese UID-changeable cards the README mentions. Everything is compiled as C++11, and the code style section asks contributors to use fixed-width integers from stdint.h, because the same source runs on 16-bit and 32-bit architectures and a plain int would change size between them.

## Installing miguelbalboa/rfid and reading a first UID

The README states the library works with Arduino IDE 1.6 and that older versions are not supported and will cause compiler errors. The built-in library manager is supported, so the shortest install path is through the IDE. If you compile outside the IDE, c++11 support has to be enabled yourself.

```bash
# In the Arduino IDE: Sketch > Include Library > Manage Libraries
# Search for MFRC522 and install the miguelbalboa/rfid entry.
```

Wiring comes before code. The pin table in the README gives per-board values, and they differ: on an Uno the RST pin is 9 and SPI SS is 10, on a Mega RST is 5 and SPI SS is 53, on a Nano v3 they are D9 and D10, on a Leonardo or Micro RST is RESET or ICSP-5 and SS is 10, on a Pro Micro RST is RST and SS is 10, on a Yun they are Pin9 and Pin10, and on a Due RST is 22 and SS is 23. MOSI, MISO and SCK follow the board's SPI pins. The README warns that the RC522's SDA label is the SPI SS signal, not I2C data.

Once wired, open the ReadNUID example from the examples directory and upload it. The sketch initialises the reader, waits for a card, and prints the UID to the serial monitor; if the reader is not detected, the firmware self check in the example is what reports it. From there, DumpInfo is the natural second sketch, because it walks the card's sectors rather than stopping at the UID.

## Where miguelbalboa/rfid stops: cards, buses and boards it cannot touch

The README's what works and not section is unusually blunt, and it is the most useful page in the repository. MIFARE DESFire, DESFire EV1 and EV2 are not supported by software. So are 3DES and AES communication. Peer-to-peer ISO/IEC 18092, communication with a smartphone, and card emulation are listed as not supported by hardware, which means no amount of library work fixes them on an RC522. IRQ pin use is not supported, though a proof-of-concept example exists. Power reduction modes are not supported. I2C and UART readers are not supported, only SPI. Intel Galileo Gen2 is not supported. Even the partial column matters: MIFARE Ultralight and other PICCs such as Ntag216 work only partially, and running more than two modules requires a multiplexer, with the README pointing at issue #191. If your project needs any of the unsupported items, this is the wrong library and the README says so before you write a line of code.

## The freeze is deliberate, and it changes how you should treat the project

The owner has ended development. The README describes a feature status of complete freeze with no function or API change, a code status of partial freeze limited to fixes, typos and documentation, and a maintenance status of sporadically. It also states plainly that there will be no extensions for other boards and no new examples, while typo, documentation and bug fixes are still accepted. The last push to the default branch was on 2026-07-02, and the most recent release listed is 1.4.12 from 2025-02-17. That combination means a stable API and a slow-moving dependency, which is a reasonable trade for a course project or a fixed installation, and a poor one if you are building a product that needs a feature the freeze excludes. The README itself redirects advanced work to RFID_MFRC522v2, which is the clearest signal that this repository is a compatibility surface rather than a place to grow.

## RFID_MFRC522v2 and PN532: two different exits

The README names RFID_MFRC522v2 for advanced and further development, and that is the in-family alternative: same reader chip, a codebase that is still being worked on. Choosing it means accepting a different API and less accumulated example code, in exchange for somewhere to send fixes. The other exit is hardware. The README's need more section suggests buying a more expensive reader such as the PN532, which supports NFC and many more card types, costs about $15, and is not usable with this library. That is the real fork in the road: stay on RC522 and accept the frozen feature set, or change the reader and rewrite the driver layer. Neither is a drop-in for the other, and the README does not pretend otherwise.

## Hardware quality, licence and what upgrading costs you

The before buy section is worth reading before ordering anything. The README states that many sellers on eBay and AliExpress sell RC522 boards, that the quality of these boards is extremely different, and that some are soldered with wrong or low quality capacitors or contain fake or defective MFRC522 chips. Its advice is to buy several devices from different suppliers so the chance of getting a working one is higher, and it invites users who can identify bad boards by silkscreen or chip markings to share that knowledge. On licensing, the repository ships an UNLICENSE file and the project is listed as Unlicense, which is a public-domain-style dedication rather than a copyleft licence; anyone embedding the library should read the UNLICENSE text themselves and confirm it fits their distribution, since this is not legal advice. Upgrade cost is low in one direction and high in the other: because the README states the API is frozen, moving from 1.4.10 to 1.4.12 should not require sketch changes, but moving to RFID_MFRC522v2 or to a PN532 reader is a rewrite of the code that talks to the reader.

## Conclusion

Adopt miguelbalboa/rfid if you have an RC522 board, an Arduino Uno, Mega, Nano, Leonardo, Micro, Pro Micro, Yun or Due, and MIFARE Classic cards to read or write. Do not adopt it for DESFire, AES or 3DES, card emulation, phone communication, or I2C and UART readers; the README lists all of those as unsupported, and the owner has ended development, so no extension is coming. Before wiring anything, check the pin table for your exact board, since RST and SPI SS move between models, and buy two or three RC522 boards from different suppliers because the README states board quality varies widely and some ship with wrong capacitors or fake chips. If you need a supported path forward, the README points to RFID_MFRC522v2.

## FAQ

### Can I use the miguelbalboa/rfid library with an Arduino?

Yes. Arduino is the main target and support of the library, and the README states it works with Arduino IDE 1.6 or newer, with older versions unsupported and likely to cause compiler errors. It also lists compatibility with Teensy and ESP8266 through the Arduino IDE board plugin, with pin changes.

### How do I identify the RFID number of a card with miguelbalboa/rfid?

Use the ReadNUID example from the examples directory, which reads the card and prints its UID. For a fuller picture, DumpInfo walks the card's sectors instead of stopping at the UID.

### What is the maximum read distance for an RC522 module used with miguelbalboa/rfid?

The README does not state a read distance for RC522 boards. What it does discuss is board quality, noting that sellers ship boards with wrong or low quality capacitors or fake MFRC522 chips, which is a more common source of unreliable reads than range itself.

## Sources

- [Issues](https://github.com/miguelbalboa/rfid/issues)
- [License: Unlicense](https://github.com/miguelbalboa/rfid/blob/master/LICENSE)
- [miguelbalboa/rfid on GitHub](https://github.com/miguelbalboa/rfid)
- [README](https://github.com/miguelbalboa/rfid/blob/master/README.md)
- [Releases](https://github.com/miguelbalboa/rfid/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/miguelbalboa-rfid