Initial documentation and planning

4 files changed, 95 insertions, 0 deletions

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 <data-len> <data>`
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 <command> <bytes-static> <static> [<bytes-dynamic> <dynamic>]
+```
+
+### 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