ST25R NFC Reader

Component/Hub

The st25r_spi component allows you to use STMicroelectronics ST25R3916 family NFC readers (datasheet) with ESPHome. This SPI hub component establishes the connection to the ST25R3916 via SPI and detects ISO 14443A (NFC-A) tags with multi-tag anticollision support for 4-byte, 7-byte, and 10-byte UIDs.

Over SPI

spi:
  clk_pin: GPIO18
  miso_pin: GPIO19
  mosi_pin: GPIO23

st25r_spi:
  cs_pin: GPIO5
  irq_pin: GPIO4
  update_interval: 1s
  on_tag:
    then:
      - logger.log:
          format: "Tag: %s"
          args: ['x.c_str()']
  on_tag_removed:
    then:
      - logger.log:
          format: "Removed: %s"
          args: ['x.c_str()']

Configuration variables

cs_pin (Required, Pin Schema): The SPI chip select pin.
irq_pin (Optional, Pin Schema): The IRQ GPIO pin. Recommended for fastest tag detection response.
reset_pin (Optional, Pin Schema): Hardware reset GPIO pin. Optional but recommended for reliable recovery.
rf_power (Optional, int): TX driver strength 0-15 (15 = maximum range). Defaults to 15.
update_interval (Optional, Time): Tag polling interval. Defaults to 1s.
on_tag (Optional, Automation): An automation to perform when a tag is first detected. See on_tag Trigger.
on_tag_removed (Optional, Automation): An automation to perform when a tag is removed (no longer detected after 3 consecutive missed scans). See on_tag_removed Trigger.
id (Optional, ID): Manually specify the ID for this component.

`on_tag` Trigger

This automation is triggered when a new tag is detected. The tag UID is available as x (a std::string in the format 0410A7675F6180).

st25r_spi:
  # ...
  on_tag:
    then:
      - homeassistant.tag_scanned: !lambda 'return x;'

`on_tag_removed` Trigger

This automation is triggered when a previously detected tag is no longer present. The removed tag’s UID is available as x (a std::string).

st25r_spi:
  # ...
  on_tag_removed:
    then:
      - logger.log:
          format: "Tag removed: %s"
          args: ['x.c_str()']

Setting Up Tags

To find your tags’ UIDs, set up the component with the logger at INFO level (or lower). When you hold a tag near the reader, you will see a log message like:

[st25r:INFO] Tag selected: 0410A7675F6180 (SAK=0x00)

Copy this UID for use in your automations.

Supported Hardware

Chip	Interface	Status
ST25R3916	SPI	Verified (Elechouse module)
ST25R3916B	SPI	Verified (STEVAL-MB17149B)