FreeCalypso > hg > freecalypso-tools
annotate doc/SIM-manipulation @ 840:25a182bc031b
rvinterf/include/audio.h: create interface definitions
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 31 Jul 2021 07:33:58 +0000 |
parents | ccaa1319740c |
children |
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. |