# HG changeset patch # User Mychaela Falconia # Date 1613865325 0 # Node ID 13dea9b95afccf5da306425bea6b585704bfbae7 # Parent ede661d78730ccc49d708b2c8385e51cdf42ff52 doc/Simtool-command-shell article written diff -r ede661d78730 -r 13dea9b95afc doc/Simtool-command-shell --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Simtool-command-shell Sat Feb 20 23:55:25 2021 +0000 @@ -0,0 +1,124 @@ +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.