FreeCalypso > hg > fc-sim-tools

annotate doc/Serial-SIM-readers @ 93:6041c601304d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fcsim1-mkprov: revert OTA key addition It appears that GrcardSIM2 cards (which is what we got for FCSIM1) do not support OTA after all, contrary to what we were previously led to believe by some tech support emails from Grcard - apparently those support emails and OTA descriptions referred to some other card model(s).
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 21 Apr 2021 05:38:39 +0000
parents b0cf75d0bb2d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
47
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 A serial SIM reader is a very simple hardware gadget consisting of just the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 following:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 * An always-on power supply (voltage determined by hw design) connected to SIM
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 VCC contact;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 * An always-on fixed-frequency clock fed to SIM CLK contact;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 * SIM I/O line connected to both TxD and RxD of a general-purpose UART, with
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 UART TxD driving SIM I/O by way of an open collector or open drain buffer;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 * SIM RST line controlled by one of the modem control lines, either DTR or RTS.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 In order to successfully communicate with the SIM, the UART baud rate needs to
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 be set to clock_freq/372, where clock_freq is the clock frequency fed to SIM CLK
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 contact, determined by the crystal oscillator used in the design of the serial
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 SIM reader gadget. This baud rate must be used initially for receiving ATR and
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 performing PTS, and it can also be used for the entire card session if the user
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 is content with the default slow speed - however, if the SIM card supports speed
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 enhancement (almost all cards do), this speed enhancement feature can be
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 supported with serial SIM readers if the UART baud rate can be switched under
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 software control from clock_freq/372 to clock_freq/64.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 I (Mother Mychaela) am a very late comer to this game, thus I am not able to
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 speak with authority regarding the history of how serial SIM readers came about.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 However, my understanding of this history is that early serial SIM readers were
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 RS-232 serial rather than USB-serial, thus they were constrained to use only
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 standard RS-232 baud rates like 9600 bps. And even when "serial" SIM readers
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 are really USB-serial, with a USB UART chip built directly into the custom
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 gadget, most people are still used to standard RS-232 baud rates (and the most
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 important OSes still make it unreasonably difficult to use non-standard baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 rates on USB-serial and other ports that are capable of such), thus the classic
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 baud rate of 9600 bps has stuck.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 When a serial SIM reader gadget is designed to operate at 9600 baud, the crystal
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 oscillator frequency should ideally be 3.571200 MHz: 9600 * 372 = 3571200.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 However, most real-life serial SIM readers out there have been built in a "race
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 to the bottom" fashion in terms of cost, and they typically feature crystals of
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 some frequency that is close to the ideal one, but not exactly - apparently
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 crystals of other nearby frequencies are cheaper than getting one for the ideal
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 frequency of 3.571200 MHz. (As a practical example, the USB-serial SIM reader
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 I bought on ebay in 2021-03 features a 3.579545 MHz crystal.) These serial SIM
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 readers with slightly-off crystals exploit the baud rate error tolerance that is
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 inherent in all UART interfaces.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 The use of 3.571200 MHz (or close to this frequency) clocks in USB-serial SIM
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 reader designs is a case of conservative thinking, as opposed to maximizing
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 speed. The highest clock frequency allowed by SIM card specs is 5 MHz for
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 class A (5.0 V) or 4 MHz for classes B and C (3.0 V and 1.8 V), thus if someone
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 sought maximum SIM communication speed, they could use a higher frequency clock
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 (for example, the same 4.8 MHz clock that is used in the USB CCID reader on
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 which I measured it with an oscilloscope, HID Omnikey 3121), use a high-quality
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 USB-serial chip with good support for non-standard baud rates, and design the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 software around the resulting non-standard baud rates, including baud rate
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 switching for SIM speed enhancement. If anyone has ever made such a USB-serial
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 SIM reader, our tools are ready to support it - but I don't know if anyone has
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 ever built such a gadget.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 In case of serial SIM readers with 3.571200 MHz (or nearby) clocks, it is my
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 (Mychaela's) guess that their designers probably never considered the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 possibility of using SIM speed enhancement, and that most programmers who write
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 software tools for such readers don't consider it either, resigning themselves
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 to just the default slow speed mode of F=372 D=1. However, if the SIM card
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 supports F=512 D=8 speed enhancement (almost all cards do) and this mode is
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 activated via PTS procedure, the baud rate becomes 55800 bps. This baud rate
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 is non-standard - however, the USB-serial chip in the SIM reader gadget I got
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 from ebay supports it just fine. (The USB-serial chip in this particular reader
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 is a PL2303, so I initially thought that it wouldn't support non-standard baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 rates - however, a closer investigation revealed that the popular notion of
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 these chips not supporting non-standard baud rates is actually a myth: PL2303
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 chips support non-standard baud rates just fine, instead this support was
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 lacking in earlier versions of the Linux kernel pl2303 driver.)
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 Our FC SIM tools back end for serial SIM readers supports 55800 baud speed
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 enhancement mode whenever the UART and its Linux kernel driver support it, and
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 we also support even higher speed enhancement modes: if the UART can handle
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 111600 baud, we can use F=512 D=16 mode, and if the UART can handle 223200 baud,
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 we can use F=512 D=32 mode which most newer SIM cards support. And yes, the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 PL2303 USB-serial chip in the SIM reader I got from ebay supports this fastest
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 223200 baud mode just fine.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 Using fc-simtool with serial SIM readers
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 ========================================
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 The most basic usage is as follows:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 fc-simtool -d /dev/ttyXXX
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 If the serial SIM reader uses a 3.571200 MHz (or nearby frequency) crystal and
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 you are not going for speed enhancement (i.e., if you are sticking with 9600
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 baud for the entire card session), then no further options are needed.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 If the clock frequency stays at 3.571200 MHz (or nearby) but you do wish to use
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 speed enhancement, add one of the following options:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 -e1 if your UART can handle 55800 bps;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 -e2 if your UART can handle 55800 and 111600 bps;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 -e4 if your UART can handle 55800, 111600 and 223200 bps.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 The actual selected mode will be based both on the UART capabilities declared
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 with the -e option and on the SIM card capabilities indicated in the ATR TA1
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 byte.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 If your serial SIM reader uses a different clock frequency such that you need to
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 use baud rates other than 9600 and 55800 bps for standard and speed-enhanced
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 modes, respectively, then you need to use the more general -b option instead of
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 -e, taking one of the following forms:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 -b base_baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 -b base_baud,spenh_baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 -b base_baud,spenh_baud,spenh_max
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 base_baud is the initial baud rate to use for receiving ATR; if no further
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 comma-separated parameters are specified, then this initial baud rate persists
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 for the entire card session without any speed enhancement modes. spenh_baud is
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 the baud rate to use for F=512 D=8 speed enhancement mode. spenh_max must be
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 1, 2, 4 or 8 (the default is 1); it is the maximum further multiplier that can
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 be applied to spenh_baud, if any.