--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Low-level-commands	Tue Feb 16 15:35:05 2021 +0000
@@ -0,0 +1,72 @@
+fc-simtool is a tool built from the bottom up: at the foundation there is a set
+of low-level commands that provide raw access to the actual SIM protocol APDU
+commands, these low-level commands can be used to do everything that the SIM
+protocol allows, and all higher-level commands merely provide user-friendly
+utilities for the most common particular use cases.  This document describes
+these low-level commands.  Readers of this document are expected to know the
+SIM interface protocol as defined in GSM TS 11.11 and its successor 3GPP TS
+51.011.
+
+Exploring and reading commands
+==============================
+
+atr
+
+This command displays the ATR (Answer To Reset) byte string which the SIM sent
+to the reader when it powered up.
+
+select File_ID
+
+This fc-simtool command sends a SELECT command to the SIM, follows up with a
+GET RESPONSE command as expected in the T=0 protocol, and provides some human-
+readable parsing of the most important fields in the SIM response structure.
+If a correctly formed response was received from the SIM and this response
+structure indicates that a record-based EF has been selected, the indicated
+record length is saved in an internal variable used by readrec and update-rec
+commands.
+
+The file ID can be specified either in hexadecimal (exactly 4 hex digits, *no*
+0x prefix) or as a symbolic name.  fc-simtool knows the following symbolic
+names:
+
+* MF
+* DF_GSM, DF_DCS1800 and DF_TELECOM
+* "gsm" and "telecom" as shorthand names for DF_GSM and DF_TELECOM
+* Some of the most classic EFs, but not all
+
+Important note: regardless of whether you specify the file ID in raw hex or
+symbolically, this low-level select command will send only one SELECT command
+to the SIM.  Per the SIM protocol, in order to successfully select an EF, you
+have to be in the right directory first, i.e., select MF, DF_GSM or DF_TELECOM
+as appropriate before the EF of interest.  Our low-level select command does
+NOT do this extra step on its own, you have to do it explicitly, even if you
+use symbolic names for EFs.
+
+sim-resp
+
+This command displays in raw hex the content of the internal buffer that holds
+the last response received from the SIM.  This internal buffer is filled by the
+GET RESPONSE command that follows up after SELECT or RUN GSM ALGORITHM, and by
+the READ BINARY or READ RECORD commands, whether they are invoked directly as
+low-level commands (select, readbin, readrec or a38) or internally as part of
+higher-level fc-simtool commands.
+
+readbin offset len
+readrec record-index [len]
+
+readef
+savebin
+
+Writing commands
+================
+
+update-bin
+update-bin-imm
+update-rec
+
+restore-file
+
+GSM authentication testing
+==========================
+
+a38