Our fc-simtool and fc-uicc-tool operate as interactive shells.  When you run
either program, it selects the "card reader" device it will use and connects to
the card via pcsc-lite facilities, and then it gives you an interactive command
shell.  The communication session with the card (including vital volatile state
like PIN authentication and currently selected directory and EF) remains
unbroken until you exit the shell, at which point our tools tell pcsc-lite to
power down the card.

The actual useful commands available in fc-simtool and fc-uicc-tool are
described in other documents; this document describes program invokation and
the command shell itself.

Program invokation
==================

Both tools share the same command line structure:

fc-simtool [-p num] [batch-command]
fc-uicc-tool [-p num] [batch-command]

If you run either tool without any options or arguments, it will select the
first reader supported by pcsc-lite (reader number 0, same as if -p0 was
specified), and if the card connection is successful, it will enter the
interactive command shell.  Use the -p num option to select a different reader
number; to tell which reader number is which, use fc-pcsc-list to list all
available readers.

Aside from the -p num option, any arguments given on the command line suppress
the default interactive shell and select the tool's batch mode instead - the
arguments specify the command to be executed.  For example, the following
invokation will read and display the inserted card's ICCID, and immediately
exit:

fc-simtool iccid

This batch mode is particularly useful with the exec command described further
in this document.

Command shell basic features
============================

The interactive command shell prompt is "simtool> " in fc-simtool and "uicc> "
in fc-uicc-tool.  In this interactive command shell mode commands are entered
naturally, with white space separating the command keyword and any arguments.
Arguments containing spaces need to be enclosed in double-quotes as in
"quoted string"; our tools have two main instances where such complex arguments
are used:

* Many of our commands, particularly low-level ones, take hexadecimal byte
  strings as arguments.  In such hex byte strings each byte must be given as
  exactly two hex digits (no 0x and no single-digit bytes for small values),
  but spaces between bytes for human readability are optional.  If these
  optional spaces are included, the whole argument needs to be included in
  double-quotes.

* Some of our commands take arguments that represent GSM 03.38 text strings,
  using our ASCII representation format for such strings that is defined in the
  SIM-data-formats document in the freecalypso-docs repository.  If these
  arguments contain spaces, they need to be enclosed in double-quotes, and any
  embedded '"' characters need to be entered as \".

Output redirection
==================

Most of our information retrieval and dumping commands support output
redirection at the tool-internal command shell level.  For example, the
following command will list the SIM Service Table (SST) on the terminal and
redisplay the "simtool> " prompt:

simtool> sst

The following form of the same command will write the output to the named file
and not send anything to the terminal:

simtool> sst > sst-list-file

If you try the '>' output redirection construct on a command that does not
support it, you will get an error message.

Working with the local host file system
=======================================

Because our tools provide a lot of commands for saving SIM data into host files
(the above output redirection mechanism and some binary file writes) as well as
reading data and command scripts from host files, having a sensible interaction
with the local host file system is important.  Users should have a convenient
way to see what directory they are in, change their current directory, and
invoke other local host commands like mkdir from inside their fc-simtool session
- hence the following features are provided:

* Any command beginning with '!' is passed to the system shell /bin/sh - the
  primary use of this feature is to be able to run !pwd to see what directory
  you are in, and more rarely do other things like !mkdir mysimdata.

* The built-in cd command changes the current directory of the running
  fc-simtool process - because of the way UNIX works, cd is one command that
  cannot be usefully executed via the '!' shell invokation mechanism.

Command script facility
=======================

Both fc-simtool and fc-uicc-tool implement an exec command:

exec script-file

This command opens the named file, reads it line by line, and executes each
read line as a command.  Whitespace-only lines are skipped, and any lines
beginning with '#' are treated as comments.  exec scripts can be nested.  If
the execution of any command encounters an error, all nested scripts are
stopped: we implement the "stop on first error" policy.

If the given script file name contains any slashes, it is used as-is.  If there
are no slashes in the requested script file name, the file is sought first in
the script installation directory /opt/freecalypso/sim-scripts, and if it is
not found there, then in the current directory.

Data file sourcing
==================

All fc-simtool and fc-uicc-tool commands that read from ASCII-based data files
named as arguments implement the same search logic as the exec command.  This
design allows complex SIM programming scripts to be installed in
/opt/freecalypso/sim-scripts along with their data files, ready to be invoked
as needed.