:mod:`rfid_utils` -- the main helper module
============================================

.. module:: rfid_utils

This module provides pre-configured instances of the board LEDs, input and output pins, and the buzzer.
It also provides a simplified wrapper for the ``mfrc522`` class.

Pre-defined objects
===================

* ``RGB`` - an instance of the ``SmartLED`` class.
* ``GLED``, ``RLED`` - instances of the ``SignalLED`` class.
	The name ``GLED`` (shorthand for the ``Green LED``) is kept for compatibility reasons. The default color of this led is ``0x1FFFFF``.
	The name ``RLED`` (shorthand for the ``Red LED``) is kept for compatibility reasons. The default color of this led is ``0xFF1FFF``.
* ``OUT`` - an instance of the pin, controlling the ``OUT+ - OUT-`` pair on the board. ``OUT(1)`` pulls the ``OUT-`` to the ground, ``OUT(0)`` leaves it floating. The ``OUT+`` is always connected to the positive power input.
* ``IN`` - an instance of the pin, corresponding to the ``IN`` contact on the board. ``IN.value()`` returns ``1`` when the ``IN`` contact is floating, ``0`` when the ``IN`` contact is short-circuited to the ground.
* ``BUZZ`` - an instance of the :class:`~buzzer.Buzzer`.


Classes
-------

.. class:: CardFilter(lifetime)

	``lifetime`` is the life time of an entry in seconds.

	The class inherits a dictionary, but it's intended use is more like a ``set``::

		c_filter = CardFilter(2)
		while 1:
			c_filter.clean(time())
			uid = rfid.read()
			if uid not in c_filter:
				# Process the new uid
				c_filter.append(uid)

	.. method:: append(value)

		Puts the value and the current time in the dict.
		This can also be used to refresh the value (for example, update the "last seen" time).

	.. method:: clean(now=None)
	
		Remove all entries with expired lifetime.

.. class:: RFID(gain=rfid.G_33dB, key=None, type=None, ul=None)


	- ``gain`` - the RFID receiver gain
	- ``key`` - Mifare Classic tag access key (``None`` or a byte-like object)
	- ``typ`` - the key type (``b'A'``, or ``b'B'``, or ``rfid.KEY_A``, or ``rfid.KEY_B``). If provided, the ``key`` should be 6 bytes long. If ``None``, and the ``key`` is not ``None``, the ``key`` should be 6 bytes long (will be interpreted as the Mifare Classic A key).
	- ``ul`` - the Mifare Ultralight password (and integer or a 4 byes long byte-like object).

	.. method:: read(fmt='hU*', key=None, type=None, ul=None)

		- ``fmt`` - the format of the output (ref. (RFID format string)[https://open-dev.ru/rfid-format])
		- ``key``, ``typ``, ``ul`` - if not ``None``, override the corresponding constructor parameter.

	.. method:: scan():

		Resets the rfid IC and scans for a tag. Refer to the ``scan()`` method of the ``mfrc522`` class.

	.. method:: write(block, data, key=None, typ=None, ul=None)

		- ``block`` - the number of the block to be written. Starts at zero (**NB**: most tags have a read-only first block).
		- ``data`` - a bytes-like object. Must be 4 or 16 bytes long, depending on the type of the tag.
		- ``key``, ``typ``, ``ul`` - if not ``None``, override the corresponding constructor parameter.
		- the ``typ`` parameter accepts only the ``rfid.KEY_A`` or ``rfid.KEY_B`` constants.