winnie_nfc
Python driver for the Pollen Robotics Winnie NFC board. It reads and writes NFC Type 2 tags (NTAG213/215/216, MIFARE Ultralight EV1) from the host, over USB.
It handles NDEF text and URI records, and comes with a winnie-nfc
command-line tool.
Requirements
- Linux or Windows, Python ≥ 3.9
- The Winnie NFC board (
ASE01209), revisions A1 to A3, plugged in over USB, with its USB product string flashed toWinnie NFC <version>: that is how the driver finds it (see USB identity) - On Linux, read/write access to the serial port: add your user to the
dialoutgroup
Installation
From PyPI
pip install winnie-nfc
This installs the winnie_nfc package and the winnie-nfc command. The only
dependency is pyserial.
From the repository
To work on the driver, run the tests or use the scripts in tools/:
git clone https://github.com/pollen-robotics/winnie_nfc.git
cd winnie_nfc
python3 -m venv .venv
.venv/bin/pip install -e . pytest
The editable install (-e) makes changes to the source take effect without
reinstalling. The test procedure and the tools
assume this .venv at the root of the repository.
Command line
winnie-nfc doctor # check the stack layer by layer
winnie-nfc read # print the NDEF records
winnie-nfc write --url "https://pollen-robotics.com"
winnie-nfc write --text "hello" --lang en
winnie-nfc erase # empty NDEF message (--full: zero all user memory)
winnie-nfc dump # hex dump of the user memory
All commands find the board by its USB product string, or take --port,
given before the command: winnie-nfc --port COM3 read.
Python API
from winnie_nfc import NTagReader, NoTagError
with NTagReader() as reader: # or NTagReader("/dev/ttyACM1")
try:
print(reader.uid().hex(" "))
print(reader.read_ndef()) # [{'type': 'uri', ...}]
reader.write_text("hello winnie")
except NoTagError:
print("no tag on the antenna")
NTagReader also provides info(), read_tag() (UID, model, records and raw
data in a single selection), write_uri(), erase() and dump(). All
exceptions are exported from winnie_nfc.
A service that keeps the reader open and polls the antenna should call
field_off() after each poll: otherwise the RF field stays on for as long as
the reader is open. The port is opened exclusively, so a second driver cannot
take the board from under the first.
Safety
The driver cannot damage a tag. It only writes to the area that holds the tag's content, and never to the parts that would make a tag unusable for good: its identifier, its NDEF formatting, its locks, configuration or password. A tag written or erased by this driver can always be rewritten, and stays readable by a phone.
A tag partly locked by another tool is the exception: the driver detects a tag declared read-only, but not lock bits or a password set on some pages only. A write that reaches such a page fails and leaves the tag blank.
It also refuses to write a message longer than the tag can hold, or to a tag whose size it cannot determine, rather than risk overflowing into those parts. Tests enforce these rules; the memory layout is in Type 2 tags.
Tests
.venv/bin/python -m pytest tests/
No hardware needed. To test with the hardware, see the test procedure.
The tools/ directory holds scripts for continuous reading,
batch writing and comparing hosts.
Documentation
- Test procedure: hardware validation step by step, known pitfalls
- Hardware notes: the reader chip and the serial link, soft reset, FIFO, performance
- Architecture: modules, design decisions, error families, scope
- Type 2 tags: memory map, commands, write ordering and safety guarantees
License
Apache License 2.0, see LICENSE.
Metadata
Release files for winnie-nfc 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| winnie_nfc-1.1.0.tar.gz | 53.9 kB | With provenance | Details for winnie_nfc-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| winnie_nfc-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for winnie_nfc-1.1.0-py3-none-any.whl |
Total release size: 96.1 kB
Release files / winnie_nfc-1.1.0.tar.gz
| Download URL | winnie_nfc-1.1.0.tar.gz |
|---|---|
| Size | 53.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49a270f1dfe84bba5efdaeb2e444ee6653daf433ceee186aa5fa6070f152a3f1
|
|
BLAKE2b-256 checksum How to use checksums |
160fcf48f42ac25dc94382bc43b4018776c6c4bf5439e858d61aee69b7aa1e4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / winnie_nfc-1.1.0-py3-none-any.whl
| Download URL | winnie_nfc-1.1.0-py3-none-any.whl |
|---|---|
| Size | 42.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9dfb1c4d2e0052265beb2d44f2722bfbeac3216aa9a7e505d525d4ce67d4c50e
|
|
BLAKE2b-256 checksum How to use checksums |
d6a32ae79a7746ba50ccb407c6dd6bb8171f46ec6cdbcb8b268a6e7111fc967d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for winnie-nfc 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for winnie_nfc-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.