Skip to main content

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 to Winnie 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 dialout group

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)

Source distribution for winnie-nfc 1.1.0
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)

Table of built distributions (wheels) for winnie-nfc 1.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page