tagreader is an ESP8266 and PN532 NFC reader whose whole config is one YAML file
Simple to build/use NFC tag reader, specially created for Home Assistant
At a glance
- What is it?
- tagreader is a Home Assistant NFC tag reader built from a D1 mini ESP8266 and a PN532 module, configured through a single ESPHome YAML file rather than custom firmware. What you give up for that simplicity is control: there is one hardware recipe, one firmware configuration file, and no documented way to add behaviour of your own.
- Who is it for?
- Home Assistant users who want NFC tag control with no soldering beyond a fixed four wire module and no firmware work should build tagreader, since the entire device definition lives in tagreader.yaml and the reader appears in Home Assistant on its own.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 179 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The bill of materials is four parts and two switches
tagreader is a Home Assistant NFC tag reader built around a D1 mini ESP8266 and a PN532 NFC module, with the firmware built using ESPHome. The documented component list contains the ESP8266 D1 Mini, the PN532 NFC Reader, a WS2812 and a buzzer.
The critical detail is the PN532 configuration, and it is stated twice because getting it wrong is the most common failure. The switches on the PN532 must be set to Switch 1 On (up) and Switch 2 Off (down). The README explains that this enables the PN532 to communicate with the D1 over I2C and says it is required for the modules to work together. Both are cheap parts with a physical switch, so this is a check to make before soldering rather than a configuration to discover later.
There is also a documented hardware compatibility note. The README originally carried a warning that AZdelivery D1 boards were not recommended and would not be supported, struck through and replaced with a note that recent reports suggest more clones of the D1 are now working as expected, verified on an AZdelivery D1. So clone boards that used to be excluded have been re-tested, but the history tells you that D1 clone quality was the source of early support requests.
Assembly requires soldering, an iron with a fairly thin tip, and about 40cm of thin wire in at least five colours. The schematic is in the repository as `Schematics/tag_reader_schematics_v3.2.png`, and the enclosure is provided as 3D models under `STLs/`.
One YAML file is the entire firmware configuration
This is the design decision that makes the project simple and also its limit. There is no firmware to write. You point ESPHome at `tagreader.yaml` in the repository root and that file is the device definition, so the reader's behaviour is whatever the author decided it should be.
The version requirement is pinned in the README as a warning: the tag reader requires ESPHome `1.16.0`. If you are new to ESPHome the project recommends the ESPHome Home Assistant add-on rather than a manual install, which keeps the tool and the firmware compiler on one version.
The `blueprints/` directory at the repository root holds ESPHome blueprints, and `scripts/` holds helper scripts, but the README does not describe what either contains or how they extend the base configuration. `static/`, `docs/` and `AUTHORS.md` sit alongside them.
So the honest characterisation is that tagreader is a device recipe rather than a framework. You get a reader that works with Home Assistant's tag system, and you get the YAML so you can see exactly how it was configured rather than reverse engineering a binary.
What happens on first boot and inside Home Assistant
The setup path on the Home Assistant side is short. The reader requires Home Assistant 0.115 or later, and once it is connected to the same network it will be automatically discovered by Home Assistant, after which you follow the in-UI instructions to set it up.
The documented setup relies on automatic discovery once the reader is connected to the same network.
There is a fallback for the case where the reader cannot join your network. If it is unable to connect to a WiFi network it will start a WiFi access point with a captive portal so you can enter your credentials. That is a provisioning path rather than a failure, and it means a device mounted somewhere awkward does not need a serial cable to configure.
Once running, scanned tags are managed from the tags interface in Home Assistant, found under config and then tags. The README does not explain how scanned identifiers are handled beyond their management through this interface.
Where tagreader is the wrong build
The clearest case is anyone who needs behaviour the YAML does not provide. Custom tag filtering, a different tag standard, an OLED display showing the tag identifier, or a relay triggered directly by the reader instead of through Home Assistant all mean editing `tagreader.yaml` substantially, and at that point you are writing an ESPHome configuration rather than using tagreader. The repository offers a starting point, not a component with documented extension points.
The hardware assumption is equally narrow. A D1 mini and a PN532 is one design, and the enclosure models under `STLs/` are printed for that build. Someone wanting a weatherproof outdoor reader or a panel-mount reader is out of scope.
The version requirement is explicit. The README requires Home Assistant 0.115 or later and ESPHome `1.16.0`. If you run a current ESPHome version, the README does not say whether this configuration still compiles, and the released tags v3.0.0, v3.0.1 and v4.0.0 all date from 2020.
The last push to the repository was on 2026-04-27. It is not archived, so the work has continued since the last release, but the released configuration on the tags page is nearly six years old, and it is the released tag rather than the branch that most users will flash.
Editorial conclusion
Home Assistant users who want NFC tag control with no soldering beyond a fixed four wire module and no firmware work should build tagreader, since the entire device definition lives in tagreader.yaml and the reader appears in Home Assistant on its own. Anyone who needs custom tag handling, a different display, or a reader that also works outside Home Assistant should write their own ESPHome config instead, because this repository ships one configuration rather than a component you extend. Before you buy parts, set the PN532 switches as the README requires and confirm your Home Assistant version is 0.115 or later, since that is the stated floor.
Frequently asked questions
What hardware do I need to build a tagreader?
An ESP8266 D1 Mini, a PN532 NFC Reader, a WS2812 and a buzzer, plus a soldering iron and about 40cm of thin wire in at least five colours. The enclosure is provided as 3D models in the STLs directory.
How do I set the switches on the PN532 module?
Switch 1 On (up) and Switch 2 Off (down). That enables the PN532 to talk to the D1 mini over I2C, and the README says it is required for the modules to work together.
Which ESPHome version does tagreader need?
The README warns that the tag reader requires ESPHome 1.16.0, and suggests the ESPHome Home Assistant add-on if you are new to ESPHome.
What happens if the tag reader cannot join my WiFi?
It starts a WiFi access point with a captive portal so you can enter your credentials. Once it is on the network, Home Assistant discovers it automatically.
Where do scanned tags show up in Home Assistant?
In the tags interface under config and then tags. What a tag does is defined by Home Assistant automations rather than by the reader.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/adonno-tagreader)Was this useful?