Volver a las guías

Escribe registros NDEF desde Python con ndeflib

ndeflib crea y lee mensajes NDEF en Python puro. Así haces registros de texto, URI y Smartposter, los codificas a bytes y los compruebas antes de tocar ninguna etiqueta.

Publicado

Con ndeflib puedes construir desde un script de Python los bytes exactos que debe contener una etiqueta NFC y revisarlos antes de acercar ninguna etiqueta. La librería crea y lee mensajes NDEF. No habla con la etiqueta, que es justo lo que mucha gente espera que haga.

Qué hay dentro de un mensaje NDEF

Un mensaje NDEF son uno o más registros. Cada registro tiene una cabecera con un TNF (Type Name Format) de 3 bits, y después un tipo, un ID opcional y una carga útil, tal como describe la referencia de NdefRecord de Android. El TNF well-known vale 1, y sus nombres de tipo incluyen T para texto, U para URI y Sp para Smart Poster.

ndeflib refleja esa estructura. Creas objetos de registro y la librería convierte una lista de ellos en bytes.

Instala ndeflib

pip install ndeflib

Se importa como ndef. Según su página de PyPI, ndeflib es Python puro con licencia ISC. La última versión es la 0.3.3, de mayo de 2019, y los clasificadores listan Python 2.7 y 3.4/3.5. Es antigua. El Python puro suele envejecer bien, pero pruébala en tu versión de Python antes de montar un flujo de trabajo sobre ella.

Crea un registro de texto y uno de URI

Un registro de texto recibe el texto, un código de idioma y una codificación:

import ndef

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

El idioma por defecto es en y la codificación, UTF-8. UTF-16 es la otra opción. Si quieres saber cuándo importa, mira UTF-8 frente a UTF-16 en los registros de texto.

Un registro URI recibe la dirección:

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

Codificado, ese registro es d1 01 0c 55 01 seguido de example.com. El 01 tras la U es un código de prefijo que sustituye a http://www., y así ahorra bytes en una etiqueta pequeña. La página de URI de ndeflib indica que la librería expande esos códigos por ti al decodificar. Su atributo uri da una forma solo ASCII, mientras que iri conserva los caracteres originales.

Codifica un mensaje a bytes y decodifícalo

ndef.message_encoder recibe una lista de registros y devuelve bytes, un fragmento por registro. Únelos para obtener el mensaje completo:

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

Esto imprime 9101085402656e48656c6c6f5101085402656e576f726c64, el ejemplo de la página principal de ndeflib. En sentido contrario:

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

Obtienes NDEF Text Record ID '' Text 'Hello' Language 'en' Encoding 'UTF-8' y lo mismo para World.

El decodificador tiene tres modos mediante su argumento errors, según la documentación de codificación y decodificación:

  • strict es el modo por defecto. Exige un mensaje válido, con el indicador Message Begin en el primer registro y Message End en el último.
  • relax acepta errores de formato menores.
  • ignore se detiene sin avisar ante un error que no puede corregir.

Una entrada incorrecta en el codificador lanza ndef.EncodeError, y un error de formato en el decodificador lanza ndef.DecodeError. Usa strict mientras construyes, para que los fallos salgan ahora y no en una etiqueta olvidada en un cajón.

Smartposter y registros genéricos

Un Smartposter agrupa un enlace con un título y una acción sugerida. Solo el recurso es obligatorio:

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"

La acción puede ser exec, save o edit. La documentación muestra un póster parecido, con un tamaño definido además, que ocupa 115 bytes. Tenlo presente: una etiqueta pequeña puede no tener espacio para él.

Para cualquier otro caso existe el genérico ndef.Record(type, name, data). Cubre todas las formas de TNF, y name es el ID del registro, de hasta 255 caracteres. Las cargas útiles están limitadas a 1 MB por defecto mediante Record.MAX_PAYLOAD_SIZE. La librería también lista tipos de registro Wi-Fi Simple Configuration y de emparejamiento Bluetooth; nuestro análisis del registro WSC de Wi-Fi muestra qué contiene esa carga.

Lleva los bytes a una etiqueta

ndeflib se queda en los bytes. Para escribirlos necesitas un lector/escritor y una librería o app que los envíe a la etiqueta. Antes, compara la longitud del mensaje con la capacidad de la etiqueta y comprueba si la etiqueta está bloqueada. Una etiqueta bloqueada rechazará la escritura, y cambiar una etiqueta después de escribirla solo es posible si no lo está.

Si prefieres evitar el script para una etiqueta suelta, NFCore en la App Store y en Google Play escriben registros NDEF desde tu móvil.

Resumen rápido

Usa ndeflib para crear y revisar bytes NDEF sin conexión: construye los registros, codifica con message_encoder, decodifica con message_decoder en modo strict y compara la longitud con la capacidad de tu etiqueta. Que la última versión sea de 2019 es un motivo para probar, no para descartarla.

Preguntas frecuentes

¿ndeflib escribe en una etiqueta por sí sola?

No. ndeflib solo crea y lee bytes NDEF. Necesitas un lector/escritor y otra herramienta o librería que envíe esos bytes a la etiqueta.

¿ndeflib sigue manteniéndose?

PyPI muestra la 0.3.3 como última versión, de mayo de 2019, y sus clasificadores listan Python 2.7 y 3.4/3.5. Es Python puro, así que pruébala en tu versión de Python antes de depender de ella.

¿Cómo hago un registro de Wi-Fi o de Bluetooth?

La documentación lista los tipos de registro Wi-Fi Simple Configuration y Bluetooth Secure Simple Pairing, cada uno en su propia página. Para algo privado, la clase genérica Record recibe un tipo, un ID y bytes de carga útil sin procesar.

¿Qué pasa con un valor no válido?

El codificador lanza ndef.EncodeError ante valores de registro no válidos, y el decodificador lanza ndef.DecodeError ante un error de formato, salvo que pases errors='ignore'.