FreeCalypso > hg > freecalypso-tools

annotate doc/SIM-manipulation @ 911:7077d02ed3b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Host-tools-overview: document fc-efr2tch
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 29 Dec 2022 21:15:36 +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.