FreeCalypso > hg > freecalypso-tools
annotate doc/SIM-manipulation @ 1014:961efadd530a default tip
fc-shell TCH DL handler: add support for CSD modes
TCH DL capture mechanism in FC Tourmaline firmware has been extended
to support CSD modes in addition to speech - add the necessary support
on the host tools side.
It needs to be noted that this mechanism in its present state does NOT
provide the debug utility value that was sought: as we learned only
after the code was implemented, TI's DSP has a misfeature in that the
buffer we are reading (a_dd_0[]) is zeroed out when the IDS block
is enabled, i.e., we are reading all zeros and not the real DL bits
we were after. But since the code has already been written, we are
keeping it - perhaps we can do some tests with IDS disabled.
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Tue, 26 Nov 2024 06:27:43 +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. |