Our fc-simtool and fc-uicc-tool operate as interactive shells.  When you run
either program, it selects (based on -d or -p options) the card access back end
it will use, and if the card connection is successful (ATR will be displayed),
the program 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 clean up: in the case of PC/SC readers, we tell
pcsc-lite to power down the card; if you are using the Calypso back end
(fc-simint), the Calypso device will be commanded into soft power-off.

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 {-d /dev/ttyXXX | -p N} [batch-command]
fc-uicc-tool {-d /dev/ttyXXX | -p N} [batch-command]

The target selection option (-d or -p, see Back-end-selection article) is
mandatory - there is no default.  If you run fc-simtool or fc-uicc-tool with
just the required -d or -p target selection option and no other arguments, the
program will enter the interactive command shell.

Aside from target selection and other back end options, 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 -p0 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.