Retour aux guides

Écrire des enregistrements NDEF en Python avec ndeflib

ndeflib crée et analyse des messages NDEF en Python pur. Voici comment fabriquer des enregistrements Text, URI et Smartposter, les encoder en octets et les vérifier avant même de toucher un tag.

Publié

Avec ndeflib, vous pouvez construire depuis un script Python les octets exacts que doit contenir un tag NFC, et les vérifier avant d'avoir approché le moindre tag. La bibliothèque crée et lit des messages NDEF. Elle ne communique pas avec un tag, alors que c'est justement ce que beaucoup de gens attendent d'elle.

Que contient un message NDEF

Un message NDEF est composé d'un ou plusieurs enregistrements. Chaque enregistrement possède un en-tête avec un TNF (Type Name Format) sur 3 bits, puis un type, un ID facultatif et une charge utile, comme le décrit la référence Android NdefRecord. Le TNF « well-known » vaut 1, et ses noms de type incluent T pour le texte, U pour l'URI et Sp pour le Smart Poster.

ndeflib reprend cette structure. Vous créez des objets enregistrement, et la bibliothèque transforme une liste de ces objets en octets.

Installer ndeflib

pip install ndeflib

On l'importe sous le nom ndef. D'après sa page PyPI, ndeflib est en Python pur, sous licence ISC. La dernière version est la 0.3.3, publiée en mai 2019, et les classifieurs indiquent Python 2.7 et 3.4/3.5. C'est ancien. Le Python pur vieillit en général plutôt bien, mais testez-la sur votre propre version de Python avant de bâtir un flux de travail dessus.

Créer un enregistrement Text et un enregistrement URI

Un enregistrement texte prend le texte, un code de langue et un encodage :

import ndef

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

La langue vaut en par défaut et l'encodage UTF-8. UTF-16 est l'autre option. Pour savoir quand cela compte, consultez UTF-8 ou UTF-16 dans les enregistrements texte.

Un enregistrement URI prend l'adresse :

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

Une fois encodé, cet enregistrement donne d1 01 0c 55 01 suivi de example.com. Le 01 après le U est un code de préfixe qui remplace http://www., ce qui économise des octets sur un petit tag. La page URI de ndeflib précise que la bibliothèque développe ces codes de préfixe pour vous au décodage. Son attribut uri donne une forme en ASCII uniquement, tandis que iri conserve les caractères d'origine.

Encoder un message en octets et le décoder

ndef.message_encoder prend une liste d'enregistrements et produit des octets, un bloc par enregistrement. Assemblez les blocs pour obtenir le message complet :

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

Cela affiche 9101085402656e48656c6c6f5101085402656e576f726c64, qui est l'exemple de la page d'accueil de ndeflib. Pour faire le chemin inverse :

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

Vous obtenez NDEF Text Record ID '' Text 'Hello' Language 'en' Encoding 'UTF-8' et la même chose pour World.

Le décodeur propose trois modes via son argument errors, selon la documentation d'encodage et de décodage :

  • strict est le mode par défaut. Il exige un message valide, avec l'indicateur Message Begin sur le premier enregistrement et Message End sur le dernier.
  • relax accepte les erreurs de format mineures.
  • ignore s'arrête silencieusement devant une erreur qu'il ne peut pas corriger.

Une entrée incorrecte dans l'encodeur déclenche ndef.EncodeError, et une erreur de format dans le décodeur déclenche ndef.DecodeError. Utilisez strict pendant le développement, pour que les erreurs apparaissent tout de suite et pas sur un tag oublié au fond d'un tiroir.

Smartposter et enregistrements génériques

Un Smartposter regroupe un lien, un titre et une action suggérée. Seule la ressource est obligatoire :

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"

L'action peut être exec, save ou edit. La documentation montre un poster similaire, avec une taille en plus, qui atteint 115 octets. Gardez cela en tête : un petit tag peut ne pas avoir assez de place.

Pour tout le reste, il existe l'enregistrement générique ndef.Record(type, name, data). Il couvre toutes les formes de TNF, et name est l'ID de l'enregistrement, jusqu'à 255 caractères. Les charges utiles sont plafonnées à 1 Mo par défaut via Record.MAX_PAYLOAD_SIZE. La bibliothèque liste aussi des types d'enregistrement Wi-Fi Simple Configuration et d'appairage Bluetooth ; notre article sur l'enregistrement Wi-Fi WSC montre ce que contient cette charge utile.

Écrire les octets sur un tag

ndeflib s'arrête aux octets. Pour les écrire, il vous faut un lecteur/enregistreur et une bibliothèque ou une application qui les envoie au tag. Avant cela, comparez la longueur du message avec la capacité du tag et vérifiez si le tag est verrouillé. Un tag verrouillé refusera l'écriture, et modifier un tag après l'avoir écrit n'est possible que s'il ne l'est pas.

Si vous préférez vous passer de script pour un tag isolé, NFCore sur l'App Store et sur Google Play écrivent des enregistrements NDEF depuis votre téléphone.

En résumé

Utilisez ndeflib pour créer et vérifier des octets NDEF hors ligne : construisez les enregistrements, encodez avec message_encoder, décodez avec message_decoder en mode strict, puis comparez la longueur à la capacité de votre tag. Voyez la date de 2019 comme une raison de tester, pas de renoncer.

Foire aux questions

ndeflib écrit-il sur un tag à lui seul ?

Non. ndeflib se contente de créer et d'analyser des octets NDEF. Il vous faut un lecteur/enregistreur et un outil ou une bibliothèque à part pour envoyer ces octets à un tag.

ndeflib est-il toujours maintenu ?

PyPI indique la 0.3.3 comme dernière version, datée de mai 2019, et ses classifieurs mentionnent Python 2.7 et 3.4/3.5. Elle est en Python pur, donc testez-la sur votre propre version de Python avant de vous y fier.

Comment créer un enregistrement Wi-Fi ou Bluetooth ?

La documentation liste des types d'enregistrement Wi-Fi Simple Configuration et Bluetooth Secure Simple Pairing, chacun sur sa propre page. Pour tout format privé, la classe générique Record accepte un type, un ID et des octets de charge utile bruts.

Que se passe-t-il avec une valeur invalide ?

L'encodeur déclenche ndef.EncodeError pour les valeurs d'enregistrement invalides, et le décodeur déclenche ndef.DecodeError en cas d'erreur de format, sauf si vous passez errors='ignore'.