From 1f22af635893d4c3221dffca8f05ea3bb8870028 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 4 Jun 2023 00:14:53 +0200 Subject: Initial documentation and planning --- README.txt | 26 ++++++++++++++++++++++++++ api_command.txt | 42 ++++++++++++++++++++++++++++++++++++++++++ api_control.txt | 23 +++++++++++++++++++++++ api_reader.txt | 4 ++++ 4 files changed, 95 insertions(+) create mode 100644 README.txt create mode 100644 api_command.txt create mode 100644 api_control.txt create mode 100644 api_reader.txt diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..22dabf9 --- /dev/null +++ b/README.txt @@ -0,0 +1,26 @@ +# NFCommander + +This tool serves as an adapter between NFC/ISO14443A Tags and Cards (Mifare Cards, NTAG Tags) +and any other tooling. + +## Tag format + +The data on the NFC tag is split into three parts, the detailed format of which is defined +in the `reader API` document. + +* Tag Command: The command a tag will call. This maps to an executable defined in the NFCommander configuration. +* Static data: Unstructured textual parameters to the command that will stay unchanged for this tag over the lifetime of it's programming. +* Dynamic data: Unstructured textual data that may be changed by the execution of a command to keep state over multiple invocations/presentations. + +## API Surfaces + +This project has three distinct APIs + +* The command API: The commands that can be triggered by and while a tag is present on the reader +* The control API: Tag programming/administration, command testing +* The reader API: Interaction with the active NFC hardware + +## Things that crossed my mind + +* Maybe we should use NDEF on the tag instead of yet another custom format +* It might be useful to implement support for hardware button passthrough to commands diff --git a/api_command.txt b/api_command.txt new file mode 100644 index 0000000..931d224 --- /dev/null +++ b/api_command.txt @@ -0,0 +1,42 @@ +# NFCommander command API + +This interfaces specifies the way NFCommander calls and communicates with the tools actually implementing +the commands specified on tags. + +## Specification + +TBD + +## Execution + +The command executable is spawned when the tag has been detected, read and parsed. +The `stdin` and `stdout` streams are connected to NFCommander and are used to exchange data and commands. + +Once the tag is removed, NFCommander will send a SIGINT signal to the process. +The process is required to handle this signal and appropriately release any resources held. + +Should the process terminate before the tag is removed, it is not respawned until the tag has been +removed and presented to the reader again. + +## Parameters & Environment + +The command process receives as its first argument the static part of the tag command. +The second parameter will be the dynamic part at the time of tag presentation, if present. + +The command process will find in its environment the following variables: + +* `TAG_UID`: UID of the tag that caused the execution of the command + +## Communication + +Commands may receive subsequent instructions (e.g. physical button presses) via their stdin stream. +This feature is not yet specified or implemented, but may become available in subsequent releases. + +Commands may control the dynamic data section of the present tag using commands on their stdout +stream. +This feature can be used to persist a limited amount of state across tag presentations. + +To set the dynamic data of the current tag, a command may send the following newline-terminated (\r\n) +command: + +`DYNAMIC ` diff --git a/api_control.txt b/api_control.txt new file mode 100644 index 0000000..983ab85 --- /dev/null +++ b/api_control.txt @@ -0,0 +1,23 @@ +# NFCommander control API + +This interface provides a means for external applications to program tags compatible +with NFCommander, as well as to run commands for testing purposes. + +## Access + +This API can be accessed via a network/unix socket connection. +Commands are sent as newline-terminated (\r\n) UTF-8 strings. +Replies are prefixed with either `OK` or `FAIL`, optionally contain an explanatory message +and are terminated likewise. + +## Commands + +### Run a command + +``` +RUN [ ] +``` + +### Get current tag info + +### Program tag with command diff --git a/api_reader.txt b/api_reader.txt new file mode 100644 index 0000000..2ddc362 --- /dev/null +++ b/api_reader.txt @@ -0,0 +1,4 @@ +# NFCommander reader API + +This API concerns the communication with the active NFC components used for tag reading / writing. +Implementing this API allows the project to support new NFC hardware -- cgit v1.2.3