Voltar aos guias

Como escrever registros NDEF em Python com a ndeflib

A ndeflib cria e lê mensagens NDEF em Python puro. Veja como montar registros Text, URI e Smartposter, codificá-los em bytes e conferi-los antes de encostar em qualquer tag.

Publicado

Com a ndeflib, você consegue montar em um script Python os bytes exatos que uma tag NFC deve guardar e conferi-los antes de encostar em uma tag. A biblioteca cria e lê mensagens NDEF. Ela não se comunica com a tag, que é justamente o que muita gente espera que ela faça.

O que existe dentro de uma mensagem NDEF

Uma mensagem NDEF é formada por um ou mais registros. Cada registro tem um cabeçalho com um TNF (Type Name Format) de 3 bits, depois um tipo, um ID opcional e um payload, como descreve a referência NdefRecord do Android. O TNF well-known é 1, e entre os nomes de tipo dele estão T para texto, U para URI e Sp para Smart Poster.

A ndeflib segue esse mesmo formato. Você cria objetos de registro, e a biblioteca transforma uma lista deles em bytes.

Instale a ndeflib

pip install ndeflib

Você a importa como ndef. Segundo a página dela no PyPI, a ndeflib é Python puro, com licença ISC. A versão mais recente é a 0.3.3, de maio de 2019, e os classificadores listam Python 2.7 e 3.4/3.5. Isso é antigo. Python puro costuma envelhecer bem, mas teste na sua versão do Python antes de montar um fluxo de trabalho em cima dela.

Crie um registro Text e um registro URI

Um registro de texto recebe o texto, um código de idioma e uma codificação:

import ndef

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

O idioma padrão é en e a codificação padrão é UTF-8. UTF-16 é a outra opção. Se quiser saber quando isso importa, veja UTF-8 versus UTF-16 em registros de texto.

Um registro URI recebe o endereço:

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

Codificado, esse registro fica d1 01 0c 55 01 seguido de example.com. O 01 depois do U é um código de prefixo que representa http://www., o que economiza bytes em uma tag pequena. A página de URI da ndeflib diz que a biblioteca expande esses códigos de prefixo para você ao decodificar. O atributo uri dá uma forma só com ASCII, enquanto iri mantém os caracteres originais.

Codifique uma mensagem em bytes e decodifique de volta

ndef.message_encoder recebe uma lista de registros e gera bytes, um bloco por registro. Junte os blocos para obter a mensagem completa:

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

Isso imprime 9101085402656e48656c6c6f5101085402656e576f726c64, que é o exemplo da página inicial da ndeflib. No caminho inverso:

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

Você obtém NDEF Text Record ID '' Text 'Hello' Language 'en' Encoding 'UTF-8' e o equivalente para World.

O decodificador tem três modos, por meio do argumento errors, de acordo com a documentação de codificação e decodificação:

  • strict é o padrão. Exige uma mensagem válida, com o flag Message Begin no primeiro registro e Message End no último.
  • relax aceita pequenos erros de formato.
  • ignore para em silêncio diante de um erro que não consegue corrigir.

Uma entrada inválida no codificador gera ndef.EncodeError, e um erro de formato no decodificador gera ndef.DecodeError. Use strict enquanto desenvolve, para que os erros apareçam agora e não em uma tag esquecida na gaveta.

Smartposter e registros genéricos

Um Smartposter reúne um link com um título e uma ação sugerida. Só o recurso (resource) é obrigatório:

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"

A ação pode ser exec, save ou edit. A documentação mostra um poster parecido, com um tamanho definido também, que resulta em 115 bytes. Tenha isso em mente: uma tag pequena pode não ter espaço para ele.

Para qualquer outro caso, existe o genérico ndef.Record(type, name, data). Ele cobre todas as formas de TNF, e name é o ID do registro, com até 255 caracteres. Os payloads são limitados a 1 MB por padrão por meio de Record.MAX_PAYLOAD_SIZE. A biblioteca também lista os tipos de registro Wi-Fi Simple Configuration e de pareamento Bluetooth; nossa explicação sobre o registro WSC de Wi-Fi mostra o que esse payload contém.

Coloque os bytes em uma tag

A ndeflib termina nos bytes. Para gravá-los, você precisa de um leitor/gravador e de uma biblioteca ou app que envie os dados para a tag. Antes disso, compare o tamanho da mensagem com a capacidade da tag e verifique se a tag está bloqueada. Uma tag bloqueada recusa a gravação, e alterar uma tag depois de gravada só é possível quando ela não está bloqueada.

Se preferir dispensar o script para uma tag avulsa, o NFCore na App Store e no Google Play grava registros NDEF direto do seu celular.

Resumo rápido

Use a ndeflib para criar e conferir bytes NDEF offline: monte os registros, codifique com message_encoder, decodifique com message_decoder no modo strict e compare o tamanho com a capacidade da sua tag. Encare a data de lançamento de 2019 como um motivo para testar, não para evitar a biblioteca.

Perguntas frequentes

A ndeflib grava em uma tag sozinha?

Não. A ndeflib só cria e interpreta bytes NDEF. Você precisa de um leitor/gravador e de uma ferramenta ou biblioteca separada para enviar esses bytes à tag.

A ndeflib ainda recebe manutenção?

O PyPI mostra a 0.3.3 como a versão mais recente, de maio de 2019, e os classificadores listam Python 2.7 e 3.4/3.5. Ela é Python puro, então teste na sua versão do Python antes de depender dela.

Como faço um registro de Wi-Fi ou Bluetooth?

A documentação lista os tipos de registro Wi-Fi Simple Configuration e Bluetooth Secure Simple Pairing, cada um em sua própria página. Para qualquer formato privado, a classe genérica Record recebe um tipo, um ID e os bytes brutos do payload.

O que acontece com um valor inválido?

O codificador gera ndef.EncodeError para valores de registro inválidos, e o decodificador gera ndef.DecodeError em caso de erro de formato, a menos que você passe errors='ignore'.