FreeCalypso > hg > fc-pcsc-tools

annotate doc/User-oriented-commands @ 72:54800d2f5752

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/User-oriented-commands: SMS manipulation documented
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 15 Feb 2021 05:40:10 +0000
parents a008f7a4bddf
children a56bbd6b0277
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
64
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 This document describes those commands and functions of fc-simtool which can be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 exercised by end users on any regular operator-issued SIM, without requiring a
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 special programmable SIM with admin privileges. The Mother's plans for future
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 development include a companion fc-simint utility that will operate on SIM cards
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 inside Calypso phones; the intent is that all of the end-user-oriented commands
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 of fc-simtool described in this document will also be replicated in fc-simint.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 Understanding SIM PIN1
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 ======================
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 Every standard SIM card has a secret code called PIN1; this secret code can be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 anywhere between 4 and 8 digits in length, with 4-digit PINs being most common.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 In terms of persistent non-volatile state, SIM PIN1 can be enabled or disabled.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 When SIM PIN1 is disabled, all regular functions of the card are enabled, as in
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 being able to power up the phone with the SIM in it and connect to the GSM
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 network with your subscriber identity, and being able to read and write SIM user
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 data content like phonebooks and stored messages - all of these functions are
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 enabled from the moment you turn on the phone with the SIM in it (or power the
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 SIM up by itself in a smart card "reader" driven by fc-simtool), without the
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 user ever being asked for a PIN, such that you can forget that the PIN even
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 exists - this situation in very common nowadays. But when SIM PIN1 is enabled,
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 the smart chip in the SIM will not allow you access to any of the data stored
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 on the card and will not allow any GSM authentication operations until and
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 unless you send the correct PIN to the SIM in the VERIFY CHV command.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 If you forgot your PIN1, the only way to reset it is to enter another secret
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 code (always 8 digits in length) called PUK1. If the SIM is made according to
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 standards, then its PUK1 is set to a random number during either physical
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 manufacturing or administrative programming of the card and then remains
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 unchangeable afterward. Therefore, in an ideal world if someone forgot their
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 PIN1 and don't have their PUK1 either, they should be able to obtain PUK1 from
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 the cellular operator who issued the SIM - but whether or not today's operators
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 will actually help such hapless users (without forcing them to get a new SIM)
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 is another question altogether. PUK1 is often printed on the big (credit-card-
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 sized) plastic piece on which SIM cards are initially delivered - but it doesn't
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 help if you originally got your SIM many ages ago and no longer have that
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 souvenir plastic piece.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 The standard protocol for communicating with SIM cards provides 5 special
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 commands that are dedicated to working with PIN1, and so does fc-simtool:
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 verify-pin1 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 This command tells the SIM that you are attempting to prove knowledge
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 of PIN1, presenting a string of digits. If the PIN digits you specify match
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 the PIN1 secret code stored inside the SIM, the card unlocks access to its
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 primary functions. If the digits you send are wrong, the SIM decrements its
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 non-volatile attempt counter, giving you a total of 3 attempts (irrespective of
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 card power-downs between attempts) to enter the correct PIN. If PIN1 is entered
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 incorrectly 3 times in a row, this PIN is blocked, and the only way to unblock
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 it is via PUK1.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 enable-pin1 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 This command changes the non-volatile state of the PIN1 enable/disable flag,
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 such that from now on the SIM will require PIN1 to be provided on every card
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 power-up before it will allow GSM authentication and access to user data. The
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 enable-pin1 operation itself requires correct PIN1 digits to be provided.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 disable-pin1 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 This command changes the non-volatile state of the PIN1 enable/disable flag,
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 such that from now on the SIM will NOT require PIN1 to be provided on every
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 card power-up, and will instead be live immediately without needing proof of
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 card owner's identity. The disable-pin1 operation itself requires correct PIN1
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 digits to be provided.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 change-pin1 old-PIN new-PIN
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 This command tells the SIM that you wish to change PIN1 secret code to some new
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 digits. Knowledge of the old PIN1 is required for this operation to succeed.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 unblock-pin1 PUK1-secret-code new-PIN1
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 This command tells the SIM that you are attempting to prove knowledge
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 of PUK1 and to set new PIN1. If PUK1 is given correctly, the new PIN1 will be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 set. If you enter wrong PUK1, the SIM decrements its non-volatile attempt
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 counter, giving you a total of 10 attempts (irrespective of card power-downs
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 between attempts) to enter the correct code. If PUK1 is entered incorrectly 10
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 times in a row, it is blocked and the card should be considered bricked beyond
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 recovery.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 Understanding SIM PIN2
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 ======================
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 GSM standards provide support for a very rarely used feature that works in the
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 spirit of "parental controls": if you authenticate to the SIM with PIN2 secret
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 code (which has to be different from PIN1 for meaningful security), you can
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 edit a SIM-resident list of so-called Fixed Dialing Numbers (FDN), and then all
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 standard phones that implement this feature per the spec will refuse to allow
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 ordinary users (authenticated with PIN1 or with no PIN at all) to call any
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 numbers other than those programmed in FDN.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 This whole "parental control" feature is totally silly and is not expected to be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 of any practical use, but the whole purpose of fc-simtool is to allow every
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 feature of SIM cards to be exercised, hence we provide the necessary support.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 The following commands work just like their PIN1 counterparts:
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 verify-pin2 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 change-pin2 old-PIN new-PIN
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 unblock-pin2 PUK2-secret-code new-PIN2
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 Unlike PIN1, PIN2 cannot be disabled per traditional SIM card standards.
65
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
104
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
105 Getting basic info from the SIM
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
106 ===============================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
107
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
108 The following commands are available for retrieving basic info from the SIM:
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
109
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
110 iccid
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
111
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
112 This command retrieves the ICCID (Integrated Circuit Card ID) record from the
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
113 SIM - it is a number of up to 20 digits (although 19-digit ICCIDs are most
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
114 common) that identifies the SIM card as a physical artifact. If your SIM is of
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
115 the traditional operator-issued kind, as opposed to a developer-oriented
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
116 programmable SIM from vendors like Sysmocom who have different ideas, this ICCID
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
117 will usually be the SIM card ID number printed on the physical plastic, along
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
118 with a barcode representation of the same number.
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
119
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
120 imsi
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
121
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
122 This command retrieves the IMSI (International Mobile Subscriber Identity) from
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
123 the SIM - it is the most fundamental ID token by which GSM phones present
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
124 themselves to networks, and they even use the first 5 or 6 digits of the IMSI
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
125 to decide which network they should try connecting to first.
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
126
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
127 sst
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
128
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
129 Every SIM card is required to have an essential data record (an EF in technical
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
130 terms) called the SIM Service Table, or SST. This SST indicates which services
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
131 are allocated and activated on the given SIM. Our sst command lists all
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
132 allocated service numbers, listing just a plain number if the service is both
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
133 allocated and activated (the usual case), or a number with a '^' suffix if the
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
134 service is allocated but not activated. You will need to look in the 3GPP TS
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
135 51.011 spec to make sense of these service numbers.
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
136
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
137 user-sum
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
138
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
139 This command displays a user-friendly summary of user-oriented services present
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
140 on the SIM. It reads SST to get the list of available and activated services,
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
141 but it considers only user-oriented ones (as opposed to SIM services dealing
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
142 with GSM network functions or serving operators' interests rather than users'),
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
143 and it displays them in a user-friendly manner. For each present SIM phonebook
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
144 (ADN, FDN, SDN) and for the SMS store, user-sum displays the storage capacity
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
145 provided by the SIM (number of phonebook entries or messages), and for each of
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
146 the various phonebooks, the allocated number of alpha tag bytes is also
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
147 displayed.
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
148
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
149 The number of bytes allocated for the alpha tag in SIM phonebooks determines
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
150 the maximum length of the name field in each phonebook entry. These name fields
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
151 can be written either in GSM7 encoding (GSM 03.38 aka 3GPP 23.038) or in UCS-2;
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
152 when GSM7 encoding is used, no SMS-style septet packing is applied - instead the
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
153 high bit of each byte is simply cleared. Therefore, the maximum number of
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
154 characters in a phonebook entry name field usually equals the number of bytes
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
155 allocated for the alpha tag on the SIM, except for names containing ASCII
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
156 characters [\]^ and {|}~ which get expanded to 2-character escape sequences in
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
157 GSM7 encoding.
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
158
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
159 uicc-dir
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
160
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
161 If your SIM card functions not only as a classic GSM 11.11 SIM, but also as a
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
162 UICC with USIM/ISIM or other UICC-based applications, it will have a file named
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
163 EF_DIR in its file system, listing those applications. fc-simtool uicc-dir
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
164 command dumps the content of this file in a human-readable form - but please
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
165 note that fc-simtool only speaks the classic GSM 11.11 protocol to the SIM, and
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
166 not the UICC protocol. EF_DIR does not officially exist in the classic GSM SIM
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
167 spec, hence the dir command in fc-uicc-tool (speaking the UICC protocol) is the
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
168 official way to read and dump the content of EF_DIR.
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
169
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
170 Manipulating SIM phonebooks
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
171 ===========================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
172
69
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
173 GSM SIM specs allow for several different phonebooks to be present on the card:
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
174
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
175 * ADN (Abbreviated Dialing Numbers) is the main SIM phonebook. Each SIM card
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
176 issuer decides how much storage space they allocate to ADN (how many records);
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
177 the SIM spec maximum is 254 records, and many issuers' SIMs do provide this
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
178 many records or close to this limit.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
179
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
180 * FDN (Fixed Dialing Numbers) is the "parental control" phonebook. The FDN
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
181 phonebook can only be written to after authenticating with PIN2, and when it
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
182 is enabled (enabling FDN is done by "invalidating" ADN, an operation which
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
183 also requires PIN2), spec-compliant phones allow only numbers in FDN to be
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
184 called.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
185
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
186 * SDN (Service Dialing Numbers) is a service-provider-controlled phonebook: it
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
187 can only be written if you have special admin privileges (ADM authentication
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
188 method is card-vendor-dependent), and it is read-only to ordinary users.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
189
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
190 * MBDN (Mailbox Dialing Numbers) is a late addition to GSM SIM specs - it is a
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
191 special phonebook that stores the number for Voice Mail and other related
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
192 esoteric services.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
193
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
194 * MSISDN is a phonebook-like file that stores the subscriber's own phone
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
195 number(s). Most classic GSM phones have a menu command for showing your own
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
196 number, usually called "My number" or something like that; this menu command
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
197 displays the first record stored in the MSISDN phonebook. Most network
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
198 operators update this MSISDN record over the air (using special SMS-encoded
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
199 commands) when you activate service or get a new phone number without changing
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
200 your SIM, but this MSISDN store in the SIM also has some interesting
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
201 properties:
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
202
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
203 + Per the spec the MSISDN phonebook is writable by ordinary users, not just
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
204 admins, and the Mother's experience with real T-Mobile SIMs is that they do
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
205 indeed allow the user to write anything into MSISDN.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
206
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
207 + Most SIM card issuers allocate multiple records for MSISDN, not just one.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
208 It is not clear if ordinary end user phones would do anything useful with
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
209 the extra records if one were to write something there.
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
210
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
211 fc-simtool provides a unified set of commands and data formats for working with
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
212 all SIM phonebooks: all pb-* commands take the name of the phonebook to be
70
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
213 operated on as their first argument. The following commands are available:
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
214
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
215 pb-dump PBNAME
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
216
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
217 This command dumps the full content of the selected phonebook on the terminal.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
218 The data format for representing SIM phonebook content in UNIX-based text files
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
219 and dumps is described in the SIM-data-formats document in the freecalypso-docs
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
220 repository.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
221
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
222 pb-dump PBNAME outfile
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
223
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
224 This form of the pb-dump command dumps the full content of the selected
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
225 phonebook, but saves it in the named file instead of sending it to the terminal.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
226 This form is ideal for making backups of large SIM phonebooks.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
227
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
228 pb-dump-rec PBNAME rec
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
229
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
230 This command dumps a single record from a potentially large phonebook.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
231
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
232 pb-dump-rec PBNAME start-rec end-rec
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
233
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
234 This command dumps the specified range of records from a potentially large
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
235 phonebook.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
236
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
237 pb-update PBNAME filename
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
238
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
239 This command reads a phonebook data file in the format described in the
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
240 SIM-data-formats document and uploads it into the named SIM phonebook, writing
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
241 each record from the data file into the SIM with an UPDATE RECORD command.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
242
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
243 Please note that this command does NOT include a built-in erase of those SIM
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
244 phonebook record positions which are not covered by the data file being uploaded
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
245 - any non-blank records in those positions will retain their previous content.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
246
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
247 pb-update-imm PBNAME rec phone-number [alpha-tag]
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
248
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
249 This command writes a single phonebook entry directly from the command line,
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
250 without going through a data file. The specific record index to write into must
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
251 always be specified (there is no built-in "find first empty record" function),
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
252 and the entry format for both the phone number and the alpha tag is more relaxed
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
253 compared to the very strict format required in data files:
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
254
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
255 * The phone number can begin with a '+' character for international format;
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
256
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
257 * The comma-separated TON/NPI byte is optional and will usually be omitted in
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
258 ordinary usage - this byte will default to 0x91 if the number begins with '+'
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
259 or to 0x81 otherwise;
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
260
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
261 * Double-quotes around the alpha tag argument are required only if it contains
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
262 spaces or other problematic characters, and can be omitted otherwise;
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
263
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
264 * If the alpha tag is empty, the last argument can be omitted altogether.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
265
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
266 pb-update-imm-hex PBNAME rec phone-number alpha-tag-hex
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
267
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
268 This command is like pb-update-imm, but the alpha tag argument (required for
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
269 this command) is given in hex - intended for creating phonebook entries with
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
270 UCS-2 alpha tags.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
271
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
272 pb-erase PBNAME
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
273
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
274 This command fully erases the named phonebook.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
275
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
276 pb-erase-one PBNAME rec
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
277
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
278 This command erases the specified individual record in the named phonebook.
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
279
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
280 pb-erase-range PBNAME start-rec end-rec
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
281
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
282 This command erases the specified range of records in the named phonebook. The
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
283 starting record must be identified by number (SIM record numbers are 1-based);
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 69
diff changeset
284 the ending record argument may be either as a number or the "end" keyword.
69
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
285
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
286 Last Number Dialed (LND)
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
287 ========================
d4058ae94749 doc/User-oriented-commands: started phonebook description
Mychaela Falconia <falcon@freecalypso.org>
parents: 65
diff changeset
288
71
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
289 Traditional SIMs include a cyclic file that is intended to be updated whenever
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
290 an outgoing call is dialed - but it is up to individual phone designs whether
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
291 they actually update this LND cyclic store or not. This SIM LND store has the
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
292 same record format as phonebooks, carrying only phone numbers and optional alpha
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
293 tags - there are no fields for date & time, call duration or status as in call
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
294 answered or not. Because of the limitations of this SIM LND store, most phone
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
295 designs do not use it, and instead go with their own implementation of call
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
296 history lists.
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
297
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
298 Because this LND store is a cyclic file, not linear fixed like phonebooks, it
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
299 can only be dumped - it cannot be freely edited. (The only update operation
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
300 allowed on cyclic files is writing a new record that becomes the new #1,
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
301 shifting all previous records down and losing the oldest one - but it is an
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
302 operation to be performed by phones if they support this LND as envisioned by
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
303 ancient spec writers, not something we are in the business of with fc-simtool.)
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
304
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
305 The command to dump the LND cyclic store is just 'dump-lnd'. If you have had
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
306 your SIM for a very long time, having used it in different phones with different
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
307 firmwares, it may be interesting to look at the output of dump-lnd - you may
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
308 have LND records that were generated ages ago by other phones if your current
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
309 one does not write into SIM LND.
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 70
diff changeset
310
65
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
311 Manipulating stored SMS
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
312 =======================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
313
72
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
314 The fundamental operating model of all message stores for SMS (whether SIM or
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
315 phone-based) is that received messages accumulate (and possibly sent ones too,
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
316 if they are stored in this manner), the limited available memory fills up, and
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
317 then the user needs to clean out the accumulated messages, preferably also
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
318 archiving them by transferring to a larger computer for longer-term storage.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
319 Given this fundamental operating model, we only need to provide commands for
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
320 dumping the content of the message store and for cleaning it out - there is no
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
321 real need to implement commands for writing messages into the store.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
322
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
323 The extent of special support for the SIM SMS store in fc-simtool is rather
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
324 minimal because it just so happened that we already have external tools that do
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
325 a major part of the work. Some phone firmwares, particularly that of the
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
326 Pirelli DP-L10 phone currently used by the Mother, implement their on-the-phone
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
327 SMS storage by a way of a file in their local flash file system whose binary
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
328 format just happens to be exactly the same as the binary format of SIM-based
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
329 EF_SMS if all 176-byte records are simply abutted together in the host-based
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
330 binary representation. A few release cycles ago we added a new utility named
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
331 pcm-sms-decode to our FreeCalypso host tools suite; this utility reads a binary
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
332 file in this "EF_SMS records concat" format and performs the quite involved job
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
333 of fully decoding all messages into human-readable form. Given that we have
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
334 this external pcm-sms-decode utility, all we need to do in fc-simtool is save
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
335 all records of EF_SMS into a single concatenated binary file, and let
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
336 pcm-sms-decode do the rest.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
337
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
338 Our dedicated commands for working with the SIM SMS store are as follows:
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
339
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
340 save-sms-bin host-filename
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
341
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
342 This command saves the full content of EF_SMS in the named file in the host file
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
343 system in binary format, suitable for further decoding with pcm-sms-decode.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
344
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
345 sms-erase-all
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
346
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
347 This command erases every record entry in EF_SMS.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
348
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
349 sms-erase-one rec
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
350
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
351 This command erases the specified individual record in EF_SMS.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
352
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
353 sms-erase-range start-rec end-rec
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
354
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
355 This command erases the specified range of records in EF_SMS. The starting
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
356 record must be identified by number (SIM record numbers are 1-based); the
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
357 ending record argument may be either as a number or the "end" keyword.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 71
diff changeset
358
65
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
359 Manipulating SMS profiles
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
360 =========================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
361
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
362 Identifying MVNO SIMs
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
363 =====================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 64
diff changeset
364