Zurück zu den Anleitungen

NDEF-Records mit Python und ndeflib schreiben

ndeflib baut und liest NDEF-Nachrichten in purem Python. So erstellst du Text-, URI- und Smartposter-Records, kodierst sie zu Bytes und prüfst sie, bevor überhaupt ein Tag im Spiel ist.

Veröffentlicht

Mit ndeflib kannst du in einem Python-Skript genau die Bytes erzeugen, die ein NFC-Tag enthalten soll, und sie prüfen, bevor du je ein Tag anhältst. Die Bibliothek erstellt und liest NDEF-Nachrichten. Mit einem Tag kommuniziert sie nicht, und genau das erwarten viele von ihr.

Was in einer NDEF-Nachricht steckt

Eine NDEF-Nachricht besteht aus einem oder mehreren Records. Jeder Record hat einen Header mit einem 3-Bit-TNF (Type Name Format), dann einen Typ, eine optionale ID und eine Payload, wie die Android-NdefRecord-Referenz beschreibt. Der Well-known-TNF ist 1, und zu seinen Typnamen gehören T für Text, U für URI und Sp für Smart Poster.

ndeflib bildet diesen Aufbau nach. Du erstellst Record-Objekte, und die Bibliothek macht aus einer Liste davon Bytes.

ndeflib installieren

pip install ndeflib

Importiert wird es als ndef. Laut der PyPI-Seite ist ndeflib pures Python mit ISC-Lizenz. Die neueste Version ist 0.3.3 vom Mai 2019, und die Classifier nennen Python 2.7 und 3.4/3.5. Das ist alt. Pures Python altert meist gut, aber teste es mit deiner eigenen Python-Version, bevor du einen Workflow darauf aufbaust.

Text-Record und URI-Record erstellen

Ein Text-Record erwartet den Text, einen Sprachcode und eine Kodierung:

import ndef

text = ndef.TextRecord("Hallo Welt", "de")

Als Sprache gilt standardmäßig en, als Kodierung UTF-8. UTF-16 ist die andere Option. Wann das eine Rolle spielt, erfährst du unter UTF-8 oder UTF-16 in Text-Records.

Ein URI-Record erwartet die Adresse:

link = ndef.UriRecord("http://www.example.com")

Kodiert ergibt dieser Record d1 01 0c 55 01, gefolgt von example.com. Die 01 nach dem U ist ein Präfixcode, der für http://www. steht und auf einem kleinen Tag Bytes spart. Laut der ndeflib-URI-Seite löst die Bibliothek diese Präfixcodes beim Dekodieren für dich auf. Das Attribut uri liefert eine reine ASCII-Form, iri behält die ursprünglichen Zeichen.

Nachricht zu Bytes kodieren und wieder dekodieren

ndef.message_encoder nimmt eine Liste von Records und liefert Bytes, ein Stück pro Record. Füge die Stücke zur vollständigen Nachricht zusammen:

message = [ndef.TextRecord("Hello"), ndef.TextRecord("World")]
payload = b"".join(ndef.message_encoder(message))
print(payload.hex())

Das gibt 9101085402656e48656c6c6f5101085402656e576f726c64 aus, das Beispiel von der ndeflib-Startseite. In die Gegenrichtung geht es so:

for record in ndef.message_decoder(bytearray.fromhex(payload.hex())):
    print(record)

Du erhältst NDEF Text Record ID '' Text 'Hello' Language 'en' Encoding 'UTF-8' und dasselbe für World.

Der Decoder kennt über das Argument errors drei Modi, laut den Encode- und Decode-Docs:

  • strict ist der Standard. Er verlangt eine gültige Nachricht, mit dem Message-Begin-Flag beim ersten und Message End beim letzten Record.
  • relax akzeptiert kleinere Formatfehler.
  • ignore hört bei einem nicht behebbaren Fehler stillschweigend auf.

Ungültige Eingaben im Encoder lösen ndef.EncodeError aus, ein Formatfehler im Decoder ndef.DecodeError. Nutze strict, solange du entwickelst, damit Fehler jetzt auffallen und nicht erst auf einem Tag in der Schublade.

Smartposter und generische Records

Ein Smartposter bündelt einen Link mit einem Titel und einer empfohlenen Aktion. Nur die Ressource ist Pflicht:

poster = ndef.SmartposterRecord("https://github.com/nfcpy/ndeflib")
poster.set_title("Python package for parsing and generating NDEF", "en")
poster.resource_type = "text/html"
poster.action = "exec"

Die Aktion kann exec, save oder edit sein. In den Docs kommt ein ähnliches Poster, bei dem zusätzlich eine Größe gesetzt ist, auf 115 Bytes. Behalte das im Hinterkopf: Auf einem kleinen Tag ist dafür vielleicht kein Platz.

Für alles andere gibt es den generischen ndef.Record(type, name, data). Er deckt alle TNF-Formen ab, und name ist die Record-ID mit bis zu 255 Zeichen. Payloads sind standardmäßig über Record.MAX_PAYLOAD_SIZE auf 1 MB begrenzt. Die Bibliothek führt außerdem Record-Typen für Wi-Fi Simple Configuration und Bluetooth-Pairing auf; in unserem Beitrag zum Wi-Fi-WSC-Record siehst du, was diese Payload enthält.

Die Bytes auf ein Tag bringen

ndeflib hört bei den Bytes auf. Zum Schreiben brauchst du ein Lese-/Schreibgerät und eine Bibliothek oder App, die sie zum Tag schickt. Vergleiche vorher die Nachrichtenlänge mit der Kapazität des Tags und prüfe, ob das Tag gesperrt ist. Ein gesperrtes Tag verweigert das Schreiben, und ein Tag nach dem Beschreiben noch zu ändern geht nur, wenn es nicht gesperrt ist.

Wenn du für ein einzelnes Tag lieber auf Skripte verzichtest, schreiben NFCore im App Store und bei Google Play NDEF-Records direkt von deinem Smartphone.

Kurz zusammengefasst

Nutze ndeflib, um NDEF-Bytes offline zu erstellen und zu prüfen: Records bauen, mit message_encoder kodieren, mit message_decoder im Modus strict dekodieren und die Länge mit der Kapazität deines Tags vergleichen. Das Veröffentlichungsdatum 2019 ist ein Grund zum Testen, kein Grund, die Bibliothek zu meiden.

Häufig gestellte Fragen

Schreibt ndeflib von selbst auf ein Tag?

Nein. ndeflib baut und liest nur NDEF-Bytes. Du brauchst ein Lese-/Schreibgerät und ein separates Tool oder eine Bibliothek, die diese Bytes an ein Tag sendet.

Wird ndeflib noch gepflegt?

PyPI zeigt 0.3.3 als neueste Version, datiert auf Mai 2019, und die Classifier nennen Python 2.7 und 3.4/3.5. Die Bibliothek ist pures Python, also teste sie mit deiner eigenen Python-Version, bevor du dich darauf verlässt.

Wie erstelle ich einen WLAN- oder Bluetooth-Record?

Die Docs führen Record-Typen für Wi-Fi Simple Configuration und Bluetooth Secure Simple Pairing auf, jeweils auf einer eigenen Seite. Für alles Private nimmt die generische Klasse Record einen Typ, eine ID und rohe Payload-Bytes.

Was passiert bei einem ungültigen Wert?

Der Encoder löst bei ungültigen Record-Werten ndef.EncodeError aus, und der Decoder löst bei einem Formatfehler ndef.DecodeError aus, es sei denn, du übergibst errors='ignore'.