[st25r] Add ST25R3916 NFC reader documentation#6428
[st25r] Add ST25R3916 NFC reader documentation#6428JohnMcLear wants to merge 1 commit intoesphome:currentfrom
Conversation
Documentation for the new ST25R3916 NFC reader component (SPI, ISO14443A). Matches esphome/esphome#15608. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
esphome
bot
added
component: st25r
component: st25r_spi
current
has-parent
wrong-base-branch
labels
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
ImgTable blocks are not in alphabetical order
Found 1 ImgTable block(s) with incorrect ordering below Network Protocols.
Each table has at most one Core item (matching the section name, e.g. "Sensor Core" for the Sensor section), pinned first, followed by Template items (names starting with "Template "), then all remaining items sorted alphabetically.
You can fix this automatically by running:
node script/check_component_index.mjs --fix
The unsorted blocks are outside this PR's diff. Try merging the latest base branch first, or run the fix command above.
![esphome[bot]](https://avatars.githubusercontent.com/in/247347?s=60&v=4){kind=small}
There was a problem hiding this comment.
As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughAdded documentation for the ESPHome ST25R NFC reader component, a global hub supporting ISO 14443A detection via SPI interface. Includes configuration examples, variable definitions, tag detection automations, and hardware compatibility guidance. Updated the components index to reference the new documentation page. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Suggested labels
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/components/binary_sensor/st25r.mdx`:
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dbe43103-03e0-45c4-8ee4-2f65b39053f4
📒 Files selected for processing (2)
src/content/docs/components/binary_sensor/st25r.mdxsrc/content/docs/components/index.mdx
| 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) | ||
| ``` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Pull request overview
Adds documentation for the new ST25R3916-based NFC reader so users can configure it in ESPHome and discover tags, plus exposes it in the component index under the NFC/RFID category.
Changes:
- Added a new documentation page for the ST25R NFC reader (SPI setup, configuration options, and tag triggers).
- Added ST25R to the NFC/RFID list in the components index.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| src/content/docs/components/index.mdx | Adds the ST25R entry to the NFC/RFID ImgTable for discoverability. |
| src/content/docs/components/binary_sensor/st25r.mdx | New ST25R NFC reader documentation including example config and triggers. |
| 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. |
There was a problem hiding this comment.
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).
| 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. |
| clk_pin: GPIO19 | ||
| miso_pin: GPIO10 | ||
| mosi_pin: GPIO18 | ||
|
|
||
| st25r_spi: | ||
| cs_pin: GPIO6 | ||
| irq_pin: GPIO7 |
There was a problem hiding this comment.
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.
| 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 |
| cs_pin: GPIO6 | ||
| irq_pin: GPIO7 |
There was a problem hiding this comment.
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.
| cs_pin: GPIO6 | |
| irq_pin: GPIO7 | |
| cs_pin: GPIOXX | |
| irq_pin: GPIOYY |
| - **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`. |
There was a problem hiding this comment.
rf_power range is written as 0--15, which reads like a typo. Consider changing to 0-15 (or 0..15) to avoid confusion.
| - **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`. |
| 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) | ||
| ``` |
There was a problem hiding this comment.
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.
Summary
Matches component PR: esphome/esphome#15608
Test plan
🤖 Generated with Claude Code