ST25R3916 NFC

Component/Hub

The st25r component allows you to use STMicroelectronics ST25R3916 and ST25R3916B NFC readers (datasheet) with ESPHome. The reader is a global hub that polls for ISO 14443A (NFC-A) tags, reads the UID of the tag on the antenna and runs the on_tag and on_tag_removed automations. It is connected over SPI through the st25r_spi platform.

The NFC binary sensor can be used with this reader to react to a specific tag.

Over SPI

# Example configuration entry
spi:
  clk_pin: GPIOXX
  miso_pin: GPIOXX
  mosi_pin: GPIOXX

st25r_spi:
  cs_pin: GPIOXX
  irq_pin: GPIOXX
  on_tag:
    then:
      - homeassistant.tag_scanned: !lambda 'return x;'

Configuration Variables

cs_pin (Required, Pin Schema): The pin connected to the reader’s chip select line.
irq_pin (Optional, Pin Schema): The pin connected to the reader’s IRQ line. With it set, the reader only talks to the chip once it has signalled a response during a scan, and that response wakes the main loop at once instead of waiting for its next pass. Tags are still looked for on every update_interval.
reset_pin (Optional, Pin Schema): The pin connected to the reader’s reset line. The chip is reset through it at startup.
rf_power (Optional, int): Transmitter driver strength from 0 to 15, where 15 is the strongest field. Defaults to 15.
update_interval (Optional, Time): How often to poll for a tag. Defaults to 1s.
on_tag (Optional, Automation): An automation to perform when a tag is first read. See on_tag Trigger.
on_tag_removed (Optional, Automation): An automation to perform after a tag has not been seen for three polls. See on_tag_removed Trigger.
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` Trigger

This automation is triggered when a tag is read. The UID is available as x, a std::string in the format 74-10-37-94, and the tag as tag, an nfc::NfcTag.

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

`on_tag_removed` Trigger

This automation is triggered after a tag has been absent for three polls. The same x and tag are available.

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

Setting Up Tags

To find the UID of a tag, hold it to the reader with the logger at INFO level or lower and look for a line like:

[I][st25r]: Tag detected: 74-10-37-94

That UID can then be used in an NFC binary sensor:

st25r_spi:
  id: nfc_reader
  cs_pin: GPIOXX

binary_sensor:
  - platform: nfc
    nfcc_id: nfc_reader
    name: "Blue Tag"
    uid: 74-10-37-94

Supported Hardware

Chip	Bus	Notes
ST25R3916	SPI	Tested with an Elechouse breakout
ST25R3916B	SPI	Tested with the STEVAL-MB17149B board

The reader currently finds one ISO 14443A tag per poll; NFC-B, NFC-V and NDEF reading are not supported yet.