FreeCalypso > hg > fc-pcsc-tools

comparison doc/Simtool-command-shell @ 134:13dea9b95afc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Simtool-command-shell article written
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 20 Feb 2021 23:55:25 +0000
parents
children
comparison
equal deleted inserted replaced
133:ede661d78730 134:13dea9b95afc
1 Our fc-simtool and fc-uicc-tool operate as interactive shells. When you run
2 either program, it selects the "card reader" device it will use and connects to
3 the card via pcsc-lite facilities, and then it gives you an interactive command
4 shell. The communication session with the card (including vital volatile state
5 like PIN authentication and currently selected directory and EF) remains
6 unbroken until you exit the shell, at which point our tools tell pcsc-lite to
7 power down the card.
8
9 The actual useful commands available in fc-simtool and fc-uicc-tool are
10 described in other documents; this document describes program invokation and
11 the command shell itself.
12
13 Program invokation
14 ==================
15
16 Both tools share the same command line structure:
17
18 fc-simtool [-p num] [batch-command]
19 fc-uicc-tool [-p num] [batch-command]
20
21 If you run either tool without any options or arguments, it will select the
22 first reader supported by pcsc-lite (reader number 0, same as if -p0 was
23 specified), and if the card connection is successful, it will enter the
24 interactive command shell. Use the -p num option to select a different reader
25 number; to tell which reader number is which, use fc-pcsc-list to list all
26 available readers.
27
28 Aside from the -p num option, any arguments given on the command line suppress
29 the default interactive shell and select the tool's batch mode instead - the
30 arguments specify the command to be executed. For example, the following
31 invokation will read and display the inserted card's ICCID, and immediately
32 exit:
33
34 fc-simtool iccid
35
36 This batch mode is particularly useful with the exec command described further
37 in this document.
38
39 Command shell basic features
40 ============================
41
42 The interactive command shell prompt is "simtool> " in fc-simtool and "uicc> "
43 in fc-uicc-tool. In this interactive command shell mode commands are entered
44 naturally, with white space separating the command keyword and any arguments.
45 Arguments containing spaces need to be enclosed in double-quotes as in
46 "quoted string"; our tools have two main instances where such complex arguments
47 are used:
48
49 * Many of our commands, particularly low-level ones, take hexadecimal byte
50 strings as arguments. In such hex byte strings each byte must be given as
51 exactly two hex digits (no 0x and no single-digit bytes for small values),
52 but spaces between bytes for human readability are optional. If these
53 optional spaces are included, the whole argument needs to be included in
54 double-quotes.
55
56 * Some of our commands take arguments that represent GSM 03.38 text strings,
57 using our ASCII representation format for such strings that is defined in the
58 SIM-data-formats document in the freecalypso-docs repository. If these
59 arguments contain spaces, they need to be enclosed in double-quotes, and any
60 embedded '"' characters need to be entered as \".
61
62 Output redirection
63 ==================
64
65 Most of our information retrieval and dumping commands support output
66 redirection at the tool-internal command shell level. For example, the
67 following command will list the SIM Service Table (SST) on the terminal and
68 redisplay the "simtool> " prompt:
69
70 simtool> sst
71
72 The following form of the same command will write the output to the named file
73 and not send anything to the terminal:
74
75 simtool> sst > sst-list-file
76
77 If you try the '>' output redirection construct on a command that does not
78 support it, you will get an error message.
79
80 Working with the local host file system
81 =======================================
82
83 Because our tools provide a lot of commands for saving SIM data into host files
84 (the above output redirection mechanism and some binary file writes) as well as
85 reading data and command scripts from host files, having a sensible interaction
86 with the local host file system is important. Users should have a convenient
87 way to see what directory they are in, change their current directory, and
88 invoke other local host commands like mkdir from inside their fc-simtool session
89 - hence the following features are provided:
90
91 * Any command beginning with '!' is passed to the system shell /bin/sh - the
92 primary use of this feature is to be able to run !pwd to see what directory
93 you are in, and more rarely do other things like !mkdir mysimdata.
94
95 * The built-in cd command changes the current directory of the running
96 fc-simtool process - because of the way UNIX works, cd is one command that
97 cannot be usefully executed via the '!' shell invokation mechanism.
98
99 Command script facility
100 =======================
101
102 Both fc-simtool and fc-uicc-tool implement an exec command:
103
104 exec script-file
105
106 This command opens the named file, reads it line by line, and executes each
107 read line as a command. Whitespace-only lines are skipped, and any lines
108 beginning with '#' are treated as comments. exec scripts can be nested. If
109 the execution of any command encounters an error, all nested scripts are
110 stopped: we implement the "stop on first error" policy.
111
112 If the given script file name contains any slashes, it is used as-is. If there
113 are no slashes in the requested script file name, the file is sought first in
114 the script installation directory /opt/freecalypso/sim-scripts, and if it is
115 not found there, then in the current directory.
116
117 Data file sourcing
118 ==================
119
120 All fc-simtool and fc-uicc-tool commands that read from ASCII-based data files
121 named as arguments implement the same search logic as the exec command. This
122 design allows complex SIM programming scripts to be installed in
123 /opt/freecalypso/sim-scripts along with their data files, ready to be invoked
124 as needed.