diff --git a/components/binary_sensor/images/rc522-full.jpg b/components/binary_sensor/images/rc522-full.jpg new file mode 100644 index 000000000..b1563499f Binary files /dev/null and b/components/binary_sensor/images/rc522-full.jpg differ diff --git a/components/binary_sensor/rc522.rst b/components/binary_sensor/rc522.rst new file mode 100644 index 000000000..0fb6438af --- /dev/null +++ b/components/binary_sensor/rc522.rst @@ -0,0 +1,153 @@ +RC522 RFID +========== + +.. seo:: + :description: Instructions for setting up RC522 RFID tag readers and tags in ESPHome + :image: rc522.jpg + :keywords: RC522, RFID + +.. _rc522-component: + +Component/Hub +------------- + +The ``rc522`` component allows you to use RC522 RFID controllers +(`datasheet `__, `Ali Express `__) +with ESPHome. This component is a global hub that establishes the connection to the RC522 via :ref:`SPI ` and +outputs its data. Using the :ref:`RC522 binary sensors ` you can then +create individual binary sensors that track if an RFID tag is currently detected by the RC522. + +.. figure:: images/rc522-full.jpg + :align: center + :width: 60.0% + +See :ref:`rc522-setting_up_tags` for information on how to setup individual binary sensors for this component. + +As the communication with the RC522 is done using SPI you need to have an :ref:`SPI bus ` in your configuration with both +the **miso_pin** and **mosi_pin** set. + +.. code-block:: yaml + + # Example configuration entry + spi: + clk_pin: D0 + miso_pin: D1 + mosi_pin: D2 + + rc522_spi: + cs_pin: D3 + update_interval: 1s + + binary_sensor: + - platform: rc522 + uid: 74-10-37-94 + name: "RC522 RFID Tag" + +Configuration variables: +************************ + +- **cs_pin** (**Required**, :ref:`Pin Schema `): The pin on the ESP that the chip select line + is connected to. +- **reset_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the RST line. Some tests + shows the RC522 working okay without this. +- **update_interval** (*Optional*, :ref:`config-time`): The duration of each scan on the RC522. This affects the + duration that the individual binary sensors stay active when they're found. + If a device is not found within this time window, it will be marked as not present. Defaults to 1s. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform + when a tag is read. See :ref:`rc522-on_tag`. +- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component ` if you want + to use multiple SPI buses. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. + +.. _rc522-on_tag: + +``on_tag`` +---------- + +This automation will be triggered when the RC522 module responds with a tag. Please note that this +can be called quite often (with an interval of ``update_interval``) as it's triggered repeatedly +if the tag is re-read many times. + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format +``74-10-37-94``. The configuration below will for example publish the tag ID on the MQTT topic ``rc522/tag``. + +.. code-block:: yaml + + rc522: + # ... + on_tag: + then: + - mqtt.publish: + topic: rc522/tag + payload: !lambda 'return x;' + +A tag scanned event can also be sent to the Home Assistant tag component +using :ref:`api-homeassistant_tag_scanned_action`. + +.. code-block:: yaml + + rc522: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda 'return x;' + +.. _rc522-tag: + +RFID Tag +-------- + +The ``rc522`` binary sensor platform lets you track if an RFID tag with a given +unique id (``uid``) is currently being detected by the RC522 or not. + +.. code-block:: yaml + + # Example configuration entry + spi: + clk_pin: D0 + miso_pin: D1 + mosi_pin: D2 + + rc522_spi: + cs_pin: D3 + update_interval: 1s + + binary_sensor: + - platform: rc522 + uid: 74-10-37-94 + name: "RC522 RFID Tag" + +Configuration variables: +************************ + +- **uid** (**Required**, string): The unique ID of the RFID tag. This is a hyphen-separated list + of hexadecimal values. For example ``74-10-37-94``. +- **name** (**Required**, string): The name of the binary sensor. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Binary Sensor `. + +.. _rc522-setting_up_tags: + +Setting Up Tags +--------------- + +To set up binary sensors for specific RFID tags you first have to know their unique IDs. To obtain this +id, first set up a simple RC522 configuration without any binary sensors like above. + +When your code is running and you approach the RC522 with an RFID Tag, you should see a message like this: + +.. code:: + + Found new tag '74-10-37-94' + +Then copy this id and create a ``binary_sensor`` entry as in the configuration example. Repeat this process for +each tag. + +See Also +-------- + +- :doc:`index` +- :doc:`rdm6300` +- :doc:`pn532` +- :apiref:`rc522_spi/rc522_spi.h` +- :ghedit:`Edit` diff --git a/images/rc522.jpg b/images/rc522.jpg new file mode 100644 index 000000000..addd2ea51 Binary files /dev/null and b/images/rc522.jpg differ diff --git a/index.rst b/index.rst index 51ff28995..c147be2fe 100644 --- a/index.rst +++ b/index.rst @@ -189,6 +189,7 @@ Binary Sensor Components Nextion Touch, components/binary_sensor/nextion, nextion.jpg Template Binary Sensor, components/binary_sensor/template, description.svg PN532, components/binary_sensor/pn532, pn532.jpg + RC522, components/binary_sensor/rc522, rc522.jpg RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg TTP229, components/binary_sensor/ttp229, ttp229.jpg Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png