.. currentmodule:: rfid
.. _rfid.MFRC522:

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
--------------

.. method:: 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).

.. method:: mfrc522.reinit()

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

.. method:: mfrc522.poweron([gain])

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

    * `rfid.G_18dB` - 18dBm
    * `rfid.G_23dB` - 23dBm
    * `rfid.G_33dB` - 33dBm (\* the default one)
    * `rfid.G_38dB` - 38dBm
    * `rfid.G_43dB` - 43dBm
    * `rfid.G_48dB` - 48dBm

.. method:: mfrc522.shutdown()

   Power off the mfrc522 IC.

.. method:: mfrc522.on()

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

.. method:: mfrc522.off()

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

.. method:: mfrc522.version()

    Get the IC hardware revision.

.. method:: 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.

.. method:: 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())

.. method:: 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
------------------

.. method:: 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``.

.. method:: mfrc522.sak()

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

.. method:: 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.

.. method:: 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

.. method:: 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).

.. method:: 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.

.. method:: 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.

.. method:: 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.

.. method:: 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

.. method:: mfrc522.plus_auth(n)

    Authenticates with key number *n*.
    Returns the error code.

.. method:: mfrc522.read_ext(n)

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

.. method:: mfrc522.write_ext(n, data)

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

.. method:: mfrc522.plus_lev(target)

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