PythonでNDEFレコードを作成する方法(ndeflib)
ndeflibは、NDEFメッセージの作成と解析をPythonだけで行えるライブラリです。Text、URI、Smartposterレコードを作ってバイト列にエンコードし、NFCタグに触れる前に内容を確認する方法を紹介します。
ndeflibを使えば、NFCタグに書き込むべきバイト列をPythonスクリプトで正確に作成し、タグにかざす前に確認できます。このライブラリはNDEFメッセージの作成と読み取りを行うもので、タグとの通信は行いません。ここは多くの人が誤解しやすい点です。
NDEFメッセージの中身
NDEFメッセージは1つ以上のレコードで構成されます。各レコードのヘッダーには3ビットのTNF(Type Name Format)があり、その後ろにタイプ、任意のID、ペイロードが続きます。詳しくはAndroidのNdefRecordリファレンスを参照してください。Well-knownのTNFは1で、タイプ名にはテキスト用の T、URI用の U、Smart Poster用の Sp があります。
ndeflibはこの構造をそのまま反映しています。レコードオブジェクトを作成し、そのリストをライブラリがバイト列に変換します。
ndeflibをインストールする
pip install ndeflib
インポートする際は ndef という名前を使います。PyPIのページによると、ndeflibは純粋なPythonで書かれており、ライセンスはISCです。最新リリースは2019年5月の0.3.3で、対応バージョンの分類にはPython 2.7と3.4/3.5が挙げられています。かなり古いものです。純粋なPythonのライブラリは古くても動くことが多いですが、これを使った運用を組む前に、お使いのPythonバージョンで動作を確認してください。
TextレコードとURIレコードを作る
Textレコードには、テキスト、言語コード、エンコーディングを指定します。
import ndef
text = ndef.TextRecord("Hallo Welt", "de")
言語のデフォルトは en、エンコーディングのデフォルトはUTF-8で、もう1つの選択肢はUTF-16です。どんなときに違いが問題になるかは、テキストレコードのUTF-8とUTF-16の違いをご覧ください。
URIレコードにはアドレスを指定します。
link = ndef.UriRecord("http://www.example.com")
エンコードすると、このレコードは d1 01 0c 55 01 の後ろに example.com が続く形になります。U の後ろの 01 は http://www. を表すプレフィックスコードで、容量の小さいタグでバイト数を節約できます。ndeflibのURIのページによると、デコード時にはこのプレフィックスコードをライブラリが展開してくれます。uri 属性はASCIIのみの形式を返し、iri 属性は元の文字をそのまま保持します。
メッセージをバイト列にエンコードし、デコードして戻す
ndef.message_encoder はレコードのリストを受け取り、レコードごとにバイト列を1つずつ生成します。これらを連結すればメッセージ全体になります。
message = [ndef.TextRecord("Hello"), ndef.TextRecord("World")]
payload = b"".join(ndef.message_encoder(message))
print(payload.hex())
出力は 9101085402656e48656c6c6f5101085402656e576f726c64 で、これはndeflibのトップページに載っている例と同じです。逆方向の変換は次のとおりです。
for record in ndef.message_decoder(bytearray.fromhex(payload.hex())):
print(record)
NDEF Text Record ID '' Text 'Hello' Language 'en' Encoding 'UTF-8' と、World についての同様の出力が得られます。
エンコードとデコードのドキュメントによると、デコーダーは errors 引数で3つのモードを使えます。
strictがデフォルトです。最初のレコードにMessage Beginフラグ、最後のレコードにMessage Endフラグが付いた、正しいメッセージが必要です。relaxは軽微なフォーマットエラーを許容します。ignoreは修復できないエラーに遭遇すると、何も言わずに処理を止めます。
エンコーダーに不正な入力を渡すと ndef.EncodeError が発生し、デコーダーでフォーマットエラーがあると ndef.DecodeError が発生します。開発中は strict を使いましょう。そうすれば、引き出しの中に眠っているタグではなく、今この場でミスに気づけます。
Smartposterと汎用レコード
Smartposterは、リンクにタイトルと推奨アクションをまとめたものです。必須なのはリソースだけです。
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"
アクションには exec、save、edit を指定できます。ドキュメントには、サイズも設定した同様のポスターの例があり、115バイトになると示されています。容量の小さいタグには収まらない場合があることを覚えておいてください。
それ以外のレコードには、汎用の ndef.Record(type, name, data) を使います。すべてのTNF形式に対応しており、name はレコードIDで、255文字までです。ペイロードは、Record.MAX_PAYLOAD_SIZE によってデフォルトで1 MBまでに制限されています。このライブラリには、Wi-Fi Simple ConfigurationやBluetoothペアリングのレコードタイプも用意されています。そのペイロードの中身については、Wi-Fi WSCレコードの解説をご覧ください。
バイト列をタグに書き込む
ndeflibが扱うのはバイト列までです。書き込むにはリーダー/ライターと、そのバイト列をタグに送るライブラリまたはアプリが必要です。書き込む前に、メッセージの長さをタグの容量と比べ、タグがロックされていないか確認してください。ロックされたタグへの書き込みは拒否されます。また、書き込み後にタグの内容を変更することができるのは、ロックされていない場合だけです。
1枚だけのタグのためにスクリプトを書くのが面倒な場合は、App StoreのNFCoreやGoogle PlayのNFCoreを使えば、スマートフォンからNDEFレコードを書き込めます。
まとめ
ndeflibを使えば、オフラインでNDEFのバイト列を作成して確認できます。レコードを作り、message_encoder でエンコードし、strict モードの message_decoder でデコードして、長さをタグの容量と比べましょう。2019年というリリース時期は、避ける理由ではなく、動作確認をする理由として受け止めてください。
よくある質問
ndeflibだけでタグに書き込めますか?
いいえ。ndeflibはNDEFのバイト列を作成して解析するだけです。そのバイト列をタグに送るには、リーダー/ライターと、別のツールまたはライブラリが必要です。
ndeflibは今もメンテナンスされていますか?
PyPIでは、最新リリースは2019年5月の0.3.3で、対応バージョンの分類にはPython 2.7と3.4/3.5が挙げられています。純粋なPythonで書かれていますが、使う前にお使いのPythonバージョンで動作を確認してください。
Wi-FiやBluetoothのレコードはどう作りますか?
ドキュメントには、Wi-Fi Simple ConfigurationとBluetooth Secure Simple Pairingのレコードタイプが、それぞれ別のページで紹介されています。独自の用途には、汎用のRecordクラスにタイプ、ID、生のペイロードのバイト列を渡します。
無効な値を渡すとどうなりますか?
無効なレコードの値に対してエンコーダーは ndef.EncodeError を発生させ、デコーダーはフォーマットエラーがあると ndef.DecodeError を発生させます。ただし errors='ignore' を指定した場合は発生しません。