class MFRC522 — read/write RFID tags via mfrc522 chip

The MFRC522 class provides an interface to the mfrc522 IC, i.e. methods to query, read and write RFID tags (Mifare Classic/Plus, Mifare Ultralight/NTAGs).

Usage example:

import rfid

#create a mfrc522 object (not configured - pass a gain value to the constructor to init in place)
mfrc = rfid.mfrc522(1, cs=pyb.Pin.cpu.C13, rst=pyb.Pin.cpu.C14)
#init the IC and power it on with 43dB gain value
mfrc.init(gain=rfid.G_43dB)
#just as an example - called by `init` internally
mfrc.poweron(rfid.G_48dB)
#list all cards
cards=[uid for uid in mfrc]

Constructors

class rfid.mfrc522(id='default', cs='cs pin', rst='rst pin', gain='off', hw='default', key=None, ul=None, plus=None)

Construct an MFRC522 object. The parameters are:

  • id is an SPI bus number or an UART bus number. Default for the board is used if not provided.

  • cs is the mfrc522 chip select pin

  • rst is the mfrc522 chip reset pin

  • gain is the antenna gain value. If provided - the IC is initialized and powered on immediately

  • hw (rfid.SPI or rfid.UART). Default for the board is used if not provided.

  • key - set the Mifare Classic key (6 bytes) [default: b'\xFF\xFF\xFF\xFF\xFF\xFF']

  • typ - set the Mifare Classic key type (rfid.KEY_A/rfid.KEY_B or b’A’/b’B’) [default: A]

  • ul - set the current Ultralight password (integer (32le) or 4 bytes) [default: 0xFFFFFFFF]

  • plus - set the current Mifare Plus key (16 bytes) - not all boards support this [default: all FF-s]

All parameters are optional. At this point the class object is created, but the IC is not functional (unless the gain parameter has been passed) - call init() to init and power on the IC.

Setup commands

mfrc522.init(gain=G_33dB)

Chip is initialized and poweron() with the provided gain (or the default 33dB) is called (see poweron() description for the valid values).

mfrc522.reinit()

Re-initialize the IC with the currently used gain value. (includes hard-resetting the IC and switching the RF field off/on)

mfrc522.poweron([gain])

Power on the mfrc522 chip. Set the antenna gain to gain, which must be one of:

mfrc522.shutdown()

Power off the mfrc522 IC.

mfrc522.on()

Switch the RFID antenna on (i.e the RF field).

mfrc522.off()

Switch the RFID antenna off (i.e the RF field).

mfrc522.version()

Get the IC hardware revision.

mfrc522.key([key, type])

Request (without args) or set the Mifare Classic key and type. Returns a tuple (key, type) for the getter function, none for the setter function.

mfrc522.pwd([value])

Request (without args) or set the Mifare Ultralight/NTAG password. Setter function accepts an integer or a 4-byte long buffer. Returs the current password as a 32LE integer for the getter function, none for the setter function.

Example (getting the current password as a bytes object):

from ustruct import pack
pack('<I', mfrc.pwd())
mfrc522.plus()

(*) not all boards support this feature.

Request (without args) or set the Mifare Plus authentication key. Returns the current key for the getter function, none for the setter function.

Working with tags

mfrc522.scan(uid=None, next=False)

  • default: If no current tag is selected, select the first one. If a tag is selected, check its presence.

  • next=True: Halt the current tag (if any) and select the next one.

If uid is provided, try to select the tag with this uid instead of the first one. Returns a tuple (the tag UID and the scan result code) or None.

Errata: (all firmwares built before 2021-06-20) using the uid argument will produce erroneous results. The uid argument must always be None.

mfrc522.sak()

Return the SAK code of the currently selected tag or None.

mfrc522.halt()

Halt the selected tag (for example, to start working with another one). The tag will remain halted until the radio field is switched off and then on, or the tag is removed from the RF field and brought back.

mfrc522.info()

Provides information about the currently selected tag. Returns a tuple (type code, block size, block count) or None (if not tag selected).

Types:

  • 0 - Classic 1K

  • 1 - Classic 4K

  • 2 - Classic Mini

  • 3 - Ultralight

  • 4 - Ultralight C (not supported, UID only)

  • 5 - Ultralight C EV1 (640 bits)

  • 6 - Ultralight C EV1 (1312 bits)

  • 7 - Plus S 2K (SL1)

  • 8 - Plus S 4K (SL1)

  • 9 - DesFire (not supported, UID only)

  • 10 - DesFire (same as 9, kept for compatibility)

  • 11 - DesFire (same as 11, kept for compatibility)

  • 12 - Classic 2K

  • 13 - Plus X 2K (SL1)

  • 14 - Plus X 4K (SL1)

  • 15 - Plus X (SL0)

  • 16 - Plus X 2K (SL2)

  • 17 - Plus X 4K (SL2)

  • 18 - Plus X (SL3)

  • 19 - Plus S (SL0)

  • 20-21 - RFU

  • 22 - Plus S (SL3)

  • 23 - NTAG213

  • 24 - NTAG215

  • 25 - NTAG216

  • 26 - Ultralight Nano

  • 27-254 - RFU

  • 255 - Unknown

mfrc522.read(n[, key=None, typ=b'A', ul=None])

Reads the block n of the selected tag (for Mifare Classic/Plus SL1, Ultralight, NTAG). If needed, an authentication will be performed. key, typ, and ul arguments override the respective internal variables, previously set during the initialization phase.

  • n - block number (valid range depends on the card connected).

  • key - 6byte long authentication key for Mifare Classic / Plus SL1 tags.

  • typ - key type ( b'A' or b'B').

  • ul - password (for Ultralight / NTAGs).

Returns the block data (block size bytes). May raise an exception (TypeError, ValueError, RuntimeError).

mfrc522.write(n, data[, key=None, typ=b'A', ul=None])

Writes data to the card block n. The required data size depends on the card type (16 bytes is always accepted, 4 - only for Ultralight cards). If needed, an authentication will be performed. key, typ, and ul arguments override the respective internal variables, previously set during the initialization phase.

Returns the result code.

mfrc522.value(n[, delta])

Reads the value stored in the block n or increment (if delta>0) or decrement (if delta<0) the stored value.

Returns a tuple (value, address) for the getter function, Тone for the setter function. Raises an exception is the block is not a value block.

mfrc522.pack([pwd])

Authenticates an Ultralight EV1 / NTAG tag with the previously set password (if pwd is not passed), or sets the password and then authenticates the tag.

Returns the PACK value as an 16LE integer.

mfrc522.sprintf(fmt[, key=None, typ=b'A'])

Returns ASCII string with the tag data using the format specified in fmt:

  • a - switch to ascii mode: output data as ascii symbols. Skips data outside the range 8(backspace), 9(tab), 10(return) and 32(space)-126(~).

  • d - switch to decimal mode: output data as a decimal (0-255). No zero padding.

  • h - switch to hexadecimal mode (lower-case).

  • H - switch to hexadecimal mode (upper-case).

  • U - output the tag’s UID. The U switch must be followed by one of the modifiers:

    • * - output the whole UID

    • ~ - output the whole UID in reversed order (the last byte first)

    • n:m - output bytes n, n+1, … m (incl.) of the UID. If m<n, output bytes m, m-1, …, n(incl.). The indices outside the current data range are silently skipped.

    • n: - output bytes n, n+1, … of the UID (till the last byte)

    • n - output byte n. (Attention: n,m indices start at zero!)

  • BN - output block N(0-255) from the tag memory. The block numbers range depends on the tag type. If the block does not exist or cannot be read (for example due to the authentication failure), it is silently skipped. The B switch must be followed by the block number N, then the ‘%’ symbol and one of the modifiers:

    • * - output the whole block (4 or 16 bytes depending on the tag type)

    • ~ - output the whole block in reversed order

    • n:m - output the block range (same format as the U modifier)

    • n: - output part of the block (same format as the U modifier)

    • n - output the block byte (same format as the U modifier)

  • S - output the SAK of the tag

  • t sequence is converted to TAB, n to RETURN.

  • any other symbol is printed as is (no check whether is is a printable character or not is performed). In order to print reserved symbol (‘a’, ‘d’, ‘h’, etc) escape it with a backslash (\)

Mifare Plus tags

(*) not all boards support these features

mfrc522.plus_auth(n)

Authenticates with key number n. Returns the error code.

mfrc522.read_ext(n)

Reads a block from the Mifare Plus tag. Returns the block data as bytes object

mfrc522.write_ext(n, data)

Writes a block to the Mifare Plus tag. Returns the error code.

mfrc522.plus_lev(target)

Switch a Mifare Plus tag to the target security level. Returns the error code.