MojoScale Studio Docs
API Reference

mfrc522

MFRC522 RFID/NFC reader module.

All modules Open Studio
Studio Docs Sensors & I/O

import mfrc522

The mfrc522 module talks to common RC522/MFRC522 RFID reader boards over SPI. Use it to detect 13.56 MHz cards and tags, read their UID, and perform simple MIFARE Classic block authentication/read/write operations.

Quick example

import mfrc522
import system

reader = mfrc522.MFRC522(mosi=23, miso=19, sclk=18, cs=5, rst=22)

def check_card():
    card = reader.read_uid()
    if card["present"]:
        print(card["uid"])
        reader.halt()

system.schedule("rfid", 500, 500, -1, check_card)

import mfrc522

reader = mfrc522.MFRC522(mosi=23, miso=19, sclk=18, cs=5)
card = reader.read_uid()

if card["present"] and reader.auth(4):
    block = reader.read_block(4)
    print(block["data_hex"])
    reader.stop_crypto()
    reader.halt()

importmfrc522

MFRC522 RFID/NFC reader module.

The mfrc522 module talks to common RC522/MFRC522 RFID reader boards over SPI. Use it to detect 13.56 MHz cards and tags, read their UID, and perform simple MIFARE Classic block authentication/read/write operations.

API 31 available

mfrc522.MFRC522(mosi: int, miso: int, sclk: int, cs: int, rst: int = None, frequency: int = None, mode: int = None, timeout_ms: int = None) -> mfrc522_reader

Create an MFRC522 RFID/NFC reader object.

The returned object owns the active SPI-backed MFRC522 reader. If a newer MFRC522 object is created, older reader objects fail clearly instead of talking to the wrong chip-select configuration.

Parameters
Name Type Pass as Required Description
mosi int positional or keyword Yes GPIO connected to reader MOSI.
miso int positional or keyword Yes GPIO connected to reader MISO.
sclk int positional or keyword Yes GPIO connected to reader SCK/SCLK.
cs int positional or keyword Yes GPIO connected to reader SDA/SS/chip-select.
rst int positional or keyword No Optional GPIO connected to reader RST. Defaults to -1, which skips the hardware reset pin and uses a soft reset.
frequency int positional or keyword No Optional SPI clock in hertz. Defaults to 4000000.
mode int positional or keyword No Optional SPI mode. Defaults to 0.
timeout_ms int positional or keyword No Optional command timeout in milliseconds. Defaults to 40.
Returns

mfrc522_reader mfrc522_reader object.

mfrc522.MFRC522().reset() -> bool

Soft-reset and reconfigure the reader.

mfrc522.MFRC522().version() -> int

Read the MFRC522 version register.

mfrc522.MFRC522().present(wakeup=False) -> bool

Check whether a card is in the RF field.

Parameters
Name Type Pass as Required Description
wakeup bool positional or keyword No Optional value. Defaults to False.

mfrc522.MFRC522().read_uid(wakeup=False) -> dict

Read and select the UID of the nearest card.

Parameters
Name Type Pass as Required Description
wakeup bool positional or keyword No Optional value. Defaults to False.

mfrc522.MFRC522().uid(wakeup=False) -> dict

Alias for read_uid().

Parameters
Name Type Pass as Required Description
wakeup bool positional or keyword No Optional value. Defaults to False.

mfrc522.MFRC522().halt() -> bool

Put the selected card into the HALT state.

mfrc522.MFRC522().auth(block, key=None, key_type="A", uid=None) -> bool

Authenticate a MIFARE Classic block.

Parameters
Name Type Pass as Required Description
block any positional or keyword Yes Required value.
key any positional or keyword No Optional value. Defaults to None.
key_type str positional or keyword No Optional value. Defaults to "A".
uid any positional or keyword No Optional value. Defaults to None.

mfrc522.MFRC522().read_block(block) -> dict

Read a 16-byte MIFARE Classic block.

Parameters
Name Type Pass as Required Description
block any positional or keyword Yes Required value.

mfrc522.MFRC522().write_block(block, data) -> bool

Write a 16-byte MIFARE Classic block.

Parameters
Name Type Pass as Required Description
block any positional or keyword Yes Required value.
data any positional or keyword Yes Required value.

mfrc522.MFRC522().stop_crypto() -> bool

Stop MIFARE Crypto1 encryption.

mfrc522.MFRC522().antenna(enabled=True) -> bool

Turn the RF antenna driver on or off.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword No Optional value. Defaults to True.

mfrc522.MFRC522().read_register(reg) -> int

Read a raw MFRC522 register.

Parameters
Name Type Pass as Required Description
reg any positional or keyword Yes Required value.

mfrc522.MFRC522().write_register(reg, value) -> bool

Write a raw MFRC522 register.

Parameters
Name Type Pass as Required Description
reg any positional or keyword Yes Required value.
value any positional or keyword Yes Required value.

mfrc522.MFRC522().info() -> dict

Return reader configuration and last-card state.

mfrc522.MFRC522().close() -> bool

Release SPI resources and close this object.

mfrc522.begin(mosi: int, miso: int, sclk: int, cs: int, rst: int = None, frequency: int = None, mode: int = None, timeout_ms: int = None) -> bool

Initialize an MFRC522 reader over SPI.

Parameters
Name Type Pass as Required Description
mosi int positional or keyword Yes GPIO connected to reader MOSI.
miso int positional or keyword Yes GPIO connected to reader MISO.
sclk int positional or keyword Yes GPIO connected to reader SCK/SCLK.
cs int positional or keyword Yes GPIO connected to reader SDA/SS/chip-select.
rst int positional or keyword No Optional GPIO connected to reader RST. Defaults to -1, which skips the hardware reset pin and uses a soft reset.
frequency int positional or keyword No Optional SPI clock in hertz. Defaults to 4000000.
mode int positional or keyword No Optional SPI mode. Defaults to 0.
timeout_ms int positional or keyword No Optional command timeout in milliseconds. Defaults to 40.
Returns

bool True when SPI and the reader are initialized.

mfrc522.reset() -> bool

Soft-reset and reconfigure the reader.

Returns

bool True when reset commands were sent.

mfrc522.version() -> int

Read the MFRC522 version register.

Returns

int Integer version register value, commonly 0x91 or 0x92.

mfrc522.present(wakeup: bool = None) -> bool

Check whether a card is in the RF field.

Parameters
Name Type Pass as Required Description
wakeup bool positional or keyword No Optional boolean. False sends REQA. True sends WUPA to also wake halted cards.
Returns

bool True when a card responds.

mfrc522.read_uid(wakeup: bool = None) -> dict

Read and select the UID of the nearest card.

Parameters
Name Type Pass as Required Description
wakeup bool positional or keyword No Optional boolean. False sends REQA. True sends WUPA.
Returns

dict Dict with ok, present, status, uid, uid_bytes, uid_size, sak, and atqa. When no card is present, present is False and status is "no_card".

mfrc522.halt() -> bool

Put the selected card into the HALT state.

Returns

bool True when the halt command was accepted or the card stopped replying.

mfrc522.auth(block: any, key: list = None, key_type: str = None, uid: any = None) -> bool

Authenticate a MIFARE Classic block.

Parameters
Name Type Pass as Required Description
block any positional or keyword Yes Block number to authenticate.
key list positional or keyword No Optional 6-byte key as a list, bytes value, or 12-character hex string. Defaults to "FFFFFFFFFFFF".
key_type str positional or keyword No Optional key type, "A" or "B". Defaults to "A".
uid any positional or keyword No Optional UID bytes or UID hex string. Defaults to the last UID returned by read_uid().
Returns

bool True when MIFARE Crypto1 authentication is active for the block.

mfrc522.read_block(block: any) -> dict

Read a 16-byte MIFARE Classic block.

Parameters
Name Type Pass as Required Description
block any positional or keyword Yes Authenticated block number to read.
Returns

dict Dict with ok, status, block, data, and data_hex. The data field is a list of 16 byte values.

mfrc522.write_block(block: any, data: list) -> bool

Write a 16-byte MIFARE Classic block.

Parameters
Name Type Pass as Required Description
block any positional or keyword Yes Authenticated block number to write.
data list positional or keyword Yes Block payload as 16 bytes, a list of byte values, a 32-character hex string, or text up to 16 characters. Short text is padded with zero bytes.
Returns

bool True when the card acknowledged the write.

mfrc522.stop_crypto() -> bool

Stop MIFARE Crypto1 encryption after authenticated operations.

Returns

bool True when the reader crypto state was cleared.

mfrc522.antenna(enabled: bool = None) -> bool

Turn the reader RF antenna driver on or off.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword No Optional boolean. Defaults to True.
Returns

bool True when the antenna control register was updated.

mfrc522.read_register(reg: any) -> int

Read a raw MFRC522 register.

Parameters
Name Type Pass as Required Description
reg any positional or keyword Yes Register address.
Returns

int Integer register value.

mfrc522.write_register(reg: any, value: int) -> bool

Write a raw MFRC522 register.

Parameters
Name Type Pass as Required Description
reg any positional or keyword Yes Register address.
value int positional or keyword Yes Byte value to write.
Returns

bool True when the SPI write completed.

mfrc522.info() -> dict

Return reader configuration and last-card state.

Returns

dict Dict with initialized, pins, frequency, version, antenna, last_uid, and timeout fields.

mfrc522.deinit() -> bool

Release the SPI device and bus used by the reader.

Returns

bool True when resources were released.