FreeCalypso > hg > freecalypso-tools

annotate doc/SIM-manipulation @ 921:74d284add54d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fc-fsio: guard against bogus readdir results from the target If the FFS being operated on contains SE K2x0 extended filenames, readdir will return strings that are bad for printing. We need to guard against this possibility, and also against possible other bogosity that could be sent by other alien firmwares.
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 31 Dec 2022 22:55:23 +0000
parents ccaa1319740c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
798
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Using fc-simint and fc-simtool to manipulate SIM cards inside Calypso devices
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 =============================================================================
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 Starting with fc-host-tools-r15, our FreeCalypso host tools package includes a
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 new utility called fc-simint that works together with fc-simtool and other SIM
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 card manipulation tools maintained in the separate FC SIM tools package.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 fc-simint is not a standalone program - instead it is a front end to the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 hardware-agnostic fc-simtool main program. Therefore, fc-simint cannot be used
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 unless you install FC SIM tools (fc-simtool and its accessories) on the same
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 host machine where you are going to run fc-simint. As of this writing, our FC
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 SIM tools package has not yet reached the stage of first tarball release, hence
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 you will need to get it from the Hg repository:
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 https://www.freecalypso.org/hg/fc-sim-tools/
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 FC SIM tools can be used by themselves (without FC host tools) if the objective
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 is to operate on a SIM card using a dedicated smart card reader/programmer
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 device. However, if the SIM card to be operated on sits inside a Calypso phone
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 or development board and you would like to poke at it without physically moving
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 it back and forth between that Calypso device and another card reader, then
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 fc-simint from the present package and fc-simtool from FC SIM tools work
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 together to accomplish this feat.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 Once you have both FC host tools and FC SIM tools fully and properly installed,
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 you are ready to run fc-simint. fc-simint works in exactly the same manner as
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 fc-loadtool (operates on the Calypso device, in this case the SIM interface
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 rather than the flash, while the regular firmware is shut down), and it needs
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 to be invoked in exactly the same way: simply change fc-loadtool to fc-simint.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 Some examples:
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 SIM card in a Mot C139/140 phone: fc-simint -h compal -c 1004 /dev/ttyUSBx
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 SIM card in a Pirelli DP-L10 phone: fc-simint -h pirelli /dev/ttyUSBx
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 SIM card in a FreeCalypso board: fc-simint -h fcfam /dev/ttyUSBx
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 If your USB-serial chip and the associated Linux kernel driver support
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 non-standard high baud rates, you can add a -B812500 option to the above command
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 lines to speed up the UART communication between fc-simint/fc-simtool on your
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 host machine and simagent on the Calypso. This speed-up option should always be
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 safe with Pirelli DP-L10 and with FreeCalypso hardware (official FT2232x adapter
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 boards), but the headset jack serial cables used with Mot C1xx phones are more
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 iffy.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 The phone's regular firmware needs to be shut down, and you need to execute the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 Calypso device's boot path. (For very advanced users, target boot control
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 options work exactly the same way as in fc-loadtool.) fc-simint will feed
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 simagent.srec to the Calypso boot ROM, simagent will run on the Calypso device,
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 and then fc-simint will command simagent to bring up the SIM interface.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 fc-simint will retrieve the SIM card's ATR from simagent, it will turn on speed
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 enhancement if the SIM supports it, and then all further control is passed to
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 fc-simtool.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 Once the control is passed to fc-simtool, you will see a simtool> prompt -
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 please refer to fc-simtool documentation in the FC SIM tools package for the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 available commands such as manipulating SIM PINs and phonebooks. Once you are
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 done poking at the SIM card, type "exit" at the simtool> prompt - when operating
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 in Calypso target mode, fc-simtool will issue a poweroff command to simagent
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 just like fc-loadtool, causing most Calypso devices to power off cleanly, or
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 causing the Pirelli DP-L10 phone to boot back into its regular firmware.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 Using fc-simtool batch mode via fc-simint
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 =========================================
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 If your fc-simint invokation line has any additional arguments after the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 /dev/ttyXXX Calypso target pathname, these arguments are passed to fc-simtool,
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 causing it to operate in its batch mode instead of the default interactive
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 shell. However, given the logistics of operating on a Calypso device with its
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 regular firmware shut down, this batch mode of operation is expected to be
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 useful only in very unusual scenarios.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 Using fc-uicc-tool
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 ==================
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 There are two main tools in the FC SIM tools package: fc-simtool speaks the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 classic GSM 11.11 SIM protocol to the card, whereas fc-uicc-tool speaks the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 "enemy" UICC protocol. All currently existing Calypso phone and modem firmwares
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 (both our own FreeCalypso and historical proprietary ones) speak only the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 classic GSM 11.11 SIM protocol, hence if you are using a given SIM in a Calypso
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 phone or modem board, the expectation is that the card needs to support the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 classic GSM SIM application. For this reason, fc-simtool is the tool of primary
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 interest in this mode of usage, and it is the tool which fc-simint invokes by
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 default. In contrast, fc-uicc-tool is meant to be used primarily in lab
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 exploration settings, with the card under investigation inserted into a
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 dedicated smart card reader/programmer, not involving Calypso GSM devices or
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 fc-simint.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 However, if you have a special contrived use case where you would like to run
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 fc-uicc-tool on a SIM card that sits in a Calypso phone or other GSM device, you
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 can do so by adding a -T uicc option to your fc-simint invokation line. This
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 option will make fc-simint pass the control to fc-uicc-tool instead of
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 fc-simtool.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 Other fc-simint options
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 =======================
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 fc-simint supports all command line options documented in the Loadtools-usage
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 article that are relevant to its operation. There are just two more options
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 that haven't been documented already:
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 -n
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 This option suppresses SIM speed enhancement. By default fc-simint
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 looks at the ATR TA1 byte to see if the SIM supports F=512 D=8 speed
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 enhancement (the only speed enhancement mode endorsed by the original
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 GSM SIM specs and supported by Calypso hardware), and requests this
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 speed enhancement mode if it is supported. -n option suppresses the
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 latter action, forcing the default slow speed mode (F=372 D=1)
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 regardless of ATR-indicated SIM capabilities.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 -v volt
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 The volt argument needs to be "1.8" or "3.0" ("3" is also accepted as an
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 alias for 3.0), selecting the voltage mode in which the SIM should be
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 powered up. 3.0 V mode (not 3.3 V!) is class B per the specs, 1.8 V
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 mode is class C. Class A is 5.0 V, but the Iota ABB chip in our Calypso
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 target devices (the chip responsible for SIM voltage supply and level
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 shifting) is new enough to not support that original class any more.
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 In the absence of a -v option, fc-simint currently uses 3.0 V mode by
ccaa1319740c doc/SIM-manipulation article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 default.