RC522 RFID

The rc522 component allows you to use RC522 RFID controllers (datasheet, Ali Express) with ESPHome. ESPHome can read the tag UID from it, every RFID tag comes with a unique UID value. Each known tag can be associated to a binary sensor, or you can use the tag information directly. See Setting Up Tags for information on how to setup individual binary sensors for this component. The RC522 supports SPI, I²C and UART communication protocols, ESPHome can use either SPI or I²C.

Component/Hub

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

  • If you have a RC522 which communicates via I²C like in the M5 Stack then you need to have an I²C bus configured.

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

Over SPI

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

spi:

rc522_spi:
  cs_pin: GPIO15

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.

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

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

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

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

Over I²C

The rc522_i2c component allows you to use RC522 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 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.

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

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

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

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

on_tag Action

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.

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

rc522 Binary Sensor

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.

# 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 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, ID): Manually specify the ID used for code generation.

  • All other options from Binary Sensor.

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:

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