FreeCalypso > hg > fc-pcsc-tools

annotate doc/Simtool-command-shell @ 141:a1aa8ee2da85

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