RC522 NFC/RFID

../../_images/rc522-full.jpg

The rc522 component allows you to use RC522 NFC/RFID controllers (datasheet, Ali Express) with ESPHome. ESPHome can read the UID from the tag. Every NFC/RFID tag has a unique “UID” value assigned at the time of manufacture. Tags can be associated with binary sensors, making it easy to determine when a specific tag is present. You can also use the tag information directly within ESPHome automations/lambdas. See Setting Up Tags for information on how to setup individual binary sensors using this component.

The RC522 IC supports SPI, I²C and UART communication protocols; ESPHome can use either SPI or I²C.

Component/Hub

  • If you have a module as shown in the image above, it can only be used in SPI mode (unless hacked) and you must define a SPI bus in your configuration with both the miso_pin and mosi_pin set.

  • If you have a RC522 which communicates via I²C (as on the M5 Stack), you need to have an I²C bus configured.

Over SPI

The rc522_spi component allows you to use RC522 NFC/RFID controllers with ESPHome. This component is a global hub that establishes the connection to the RC522 via SPI. Using RC522 binary sensors, you can then create individual binary sensors that track if an NFC/RFID tag is currently detected by the RC522.

spi:

rc522_spi:
  cs_pin: GPIOXX

binary_sensor:
  - platform: rc522
    uid: 74-10-37-94
    name: "RC522 RFID Tag"

Configuration variables:

  • cs_pin (Required, Pin Schema): The pin on the ESP that the chip select line is connected to.

  • reset_pin (Optional, Pin Schema): The pin connected to the RST line. Some tests shows the RC522 working okay without this.

  • update_interval (Optional, 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.

  • spi_id (Optional, ID): Manually specify the ID of the SPI Component if you want to use multiple SPI buses.

  • id (Optional, ID): Manually specify the ID for this component.

  • on_tag (Optional, Automation): An automation to perform when a tag is read. See on_tag Trigger.

  • on_tag_removed (Optional, Automation): An automation to perform after a tag is removed. See on_tag_removed Trigger.

Over I²C

The rc522_i2c component allows you to use RC522 NFC/RFID controllers with ESPHome. This component is a global hub that establishes the connection to the RC522 via I²C (also available over SPI). Using the RC522 binary sensors you can then create individual binary sensors that track if an NFC/RFID tag is currently detected by the RC522.

i2c:

rc522_i2c:

binary_sensor:
  - platform: rc522
    uid: 74-10-37-94
    name: "RC522 RFID Tag"

Configuration variables:

  • address (Optional, int): Manually specify the I²C address of the sensor. Defaults to 0x28.

  • reset_pin (Optional, Pin Schema): The pin connected to the RST line. Some tests shows the RC522 working okay without this.

  • update_interval (Optional, 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.

  • i2c_id (Optional, ID): Manually specify the ID of the I²C Component if you want to use multiple I²C buses.

  • id (Optional, ID): Manually specify the ID for this component.

  • on_tag (Optional, Automation): An automation to perform when a tag is read. See on_tag Trigger.

  • on_tag_removed (Optional, Automation): An automation to perform after a tag is removed. See on_tag_removed Trigger.

Triggers

on_tag Trigger

This automation will be triggered immediately after the RC522 identifies a tag.

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.

rc522_spi: # or rc522_i2c
  # ...
  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 homeassistant.tag_scanned Action.

rc522_spi: # or rc522_i2c
  # ...
  on_tag:
    then:
      - homeassistant.tag_scanned: !lambda 'return x;'

on_tag_removed Trigger

This automation will be triggered when the RC522 no longer “sees” a previously scanned tag.

The parameter x this trigger provides is of type std::string and is the removed tag UID in the format 74-10-37-94. The example configuration below will publish the removed tag ID on the MQTT topic pn7160/tag_removed.

rc522_spi: # or rc522_i2c
  # ...
  on_tag_removed:
    then:
      - mqtt.publish:
          topic: rc522/tag_removed
          payload: !lambda 'return x;'

rc522 Binary Sensor

The rc522 binary sensor platform lets you track if an NFC/RFID tag with a given unique id (uid) is currently being detected by the RC522 or not.

# Example configuration entry
spi:
  clk_pin: D0
  miso_pin: D1
  mosi_pin: D2

rc522_spi: # or rc522_i2c
  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 NFC/RFID tag. This is a hyphen-separated list of hexadecimal values. For example 74-10-37-94.

  • All other options from Binary Sensor.

Setting Up Tags

To set up binary sensors for specific NFC/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 NFC/RFID Tag, you should see a message like this:

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