Skip to content

[st25r] Add ST25R3916 NFC reader documentation #6428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
JohnMcLear wants to merge 2 commits into
base: current
Choose a base branch
from
Draft

[st25r] Add ST25R3916 NFC reader documentation #6428

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
edaf51c
[st25r] Add ST25R3916 NFC reader documentation
JohnMcLear Apr 9, 2026
2e4739b
fix: address CodeRabbit review feedback
JohnMcLear Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 120 additions & 0 deletions src/content/docs/components/binary_sensor/st25r.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
description: "Instructions for setting up ST25R NFC reader components in ESPHome"
title: "ST25R NFC Reader"
---

import APIRef from '@components/APIRef.astro';

<span id="st25r-component"></span>

## Component/Hub

The `st25r` component allows you to use STMicroelectronics ST25R3916 family NFC readers
([datasheet](https://www.st.com/resource/en/datasheet/st25r3916.pdf))
with ESPHome. This component is a global hub that establishes the connection to the ST25R3916 via
[SPI](/components/spi) and detects ISO 14443A (NFC-A) tags with multi-tag anticollision support
for 4-byte, 7-byte, and 10-byte UIDs.
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intro describes this as the st25r component, but the configuration examples use st25r_spi:. To avoid confusing users, please align the wording and examples (similar to PN532/RC522 docs, which explicitly describe the *_spi hub component name used in YAML).

Suggested change
The `st25r` component allows you to use STMicroelectronics ST25R3916 family NFC readers
([datasheet](https://www.st.com/resource/en/datasheet/st25r3916.pdf))
with ESPHome. This component is a global hub that establishes the connection to the ST25R3916 via
[SPI](/components/spi) and detects ISO 14443A (NFC-A) tags with multi-tag anticollision support
for 4-byte, 7-byte, and 10-byte UIDs.
The `st25r_spi` component allows you to use STMicroelectronics ST25R3916 family NFC readers
([datasheet](https://www.st.com/resource/en/datasheet/st25r3916.pdf))
with ESPHome. This SPI hub component is configured in YAML under `st25r_spi:` and establishes the
connection to the ST25R3916 via [SPI](/components/spi). It detects ISO 14443A (NFC-A) tags with
multi-tag anticollision support for 4-byte, 7-byte, and 10-byte UIDs.

Copilot uses AI. Check for mistakes.

## Over SPI

```yaml
spi:
clk_pin: GPIO19
miso_pin: GPIO10
mosi_pin: GPIO18

st25r_spi:
cs_pin: GPIO6
irq_pin: GPIO7
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The SPI example uses ESP32 flash/PSRAM pins (e.g., GPIO10 for MISO). These pins are not generally usable on common ESP32 dev boards and can cause boot failures; consider using GPIOXX placeholders or example pins that are safe/commonly available.

Suggested change
clk_pin: GPIO19
miso_pin: GPIO10
mosi_pin: GPIO18
st25r_spi:
cs_pin: GPIO6
irq_pin: GPIO7
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
st25r_spi:
cs_pin: GPIO5
irq_pin: GPIO4

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example uses GPIO6/GPIO7 for cs_pin/irq_pin, which are typically reserved for SPI flash on many ESP32 boards. Consider switching to GPIOXX placeholders or known-safe pins to prevent users copy/pasting a non-working configuration.

Suggested change
cs_pin: GPIO6
irq_pin: GPIO7
cs_pin: GPIOXX
irq_pin: GPIOYY

Copilot uses AI. Check for mistakes.
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](/guides/configuration-types#pin-schema)): The SPI chip select pin.

- **irq_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The IRQ GPIO pin.
Recommended for fastest tag detection response.

- **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#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`.
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rf_power range is written as 0--15, which reads like a typo. Consider changing to 0-15 (or 0..15) to avoid confusion.

Suggested change
- **rf_power** (*Optional*, int): TX driver strength 0--15 (15 = maximum range). Defaults to `15`.
- **rf_power** (*Optional*, int): TX driver strength 0-15 (15 = maximum range). Defaults to `15`.

Copilot uses AI. Check for mistakes.

- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): Tag polling interval.
Defaults to `1s`.

- **on_tag** (*Optional*, [Automation](/automations)): An automation to perform when a tag is first
detected. See [`on_tag` Trigger](#on_tag-trigger).

- **on_tag_removed** (*Optional*, [Automation](/automations)): An automation to perform when a tag is
removed (no longer detected after 3 consecutive missed scans). See [`on_tag_removed` Trigger](#on_tag_removed-trigger).

- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID for this component.

<span id="on_tag-trigger"></span>

## `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`).

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

<span id="on_tag_removed-trigger"></span>

## `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`).

```yaml
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 DEBUG level. When you hold a tag
near the reader, you will see a log message like:

```log
[st25r:INFO] Tag selected: 0410A7675F6180 (SAK=0x00)
```
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Logger level guidance conflicts with the sample output

Line 99 asks for DEBUG, but the sample shown is an INFO log. Please align the instruction and sample level so users know what to expect.

Suggested doc tweak 
-To find your tags' UIDs, set up the component with the logger at DEBUG level. When you hold a tag
+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:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/components/binary_sensor/st25r.mdx` around lines 99 - 104,
The doc currently tells users to set the logger to DEBUG but shows an example
log with an INFO level; update the doc so the levels match by either changing
the instruction from "DEBUG" to "INFO" or changing the sample log prefix from
"[st25r:INFO]" to "[st25r:DEBUG]"; ensure the text around the "Tag selected:
0410A7675F6180 (SAK=0x00)" sample and the instruction mentioning logger level
use the same level term so users know what to expect.

Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says to set the logger to DEBUG to find UIDs, but the example log line shown is at INFO level ([st25r:INFO] ...). Please reconcile these (either adjust the recommended logger level or update the example) so readers know which level is actually required.

Copilot uses AI. Check for mistakes.

Copy this UID for use in your automations.

## Supported Hardware

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

## See Also

- [PN532 NFC/RFID](/components/binary_sensor/pn532/)
- [RC522 NFC/RFID](/components/binary_sensor/rc522/)
- [Binary Sensor Component](/components/binary_sensor/)
- <APIRef text="st25r.h" path="st25r/st25r.h" />
1 change: 1 addition & 0 deletions src/content/docs/components/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -602,6 +602,7 @@ Often known as "tag" or "card" readers within the community.
["PN716X", "/components/pn7160/", "pn716x.jpg"],
["RC522", "/components/binary_sensor/rc522/", "rc522.jpg"],
["RDM6300", "/components/binary_sensor/rdm6300/", "rdm6300.jpg"],
["ST25R", "/components/binary_sensor/st25r/", "nfc.png", "dark-invert"],
["Wiegand Reader", "/components/wiegand/", "wiegand.jpg"],
]} />

Expand Down
Loading