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.
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.relaxaceita pequenos erros de formato.ignorepara 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'.