FreeCalypso > hg > fc-sim-tools
view doc/Simtool-command-shell @ 47:b0cf75d0bb2d
doc/Serial-SIM-readers article written
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 21 Mar 2021 04:32:18 +0000 |
parents | da6e9d0b2ee6 |
children | d73fddc64485 |
line wrap: on
line source
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.