FreeCalypso > hg > freecalypso-tools

comparison doc/SIM-manipulation @ 798:ccaa1319740c

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