fc-pcsc-tools: doc/User-oriented-commands annotate

annotate doc/User-oriented-commands @ 97:d924e4b1387f

doc/User-oriented-commands: grammar fix

author	Mychaela Falconia <falcon@freecalypso.org>
date	Wed, 17 Feb 2021 21:03:39 +0000
parents	8a714fe98aa9
children	6ba14a9247d2

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
89 629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	237 pb-restore PBNAME filename
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	238
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	239 This command reads a phonebook data file in the format described in the
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	240 SIM-data-formats document and uploads it into the named SIM phonebook. Every
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	241 record in the SIM phonebook is overwritten with an UPDATE RECORD command; those
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	242 record indices which do not appear in the data file being restored get blank
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	243 records (0xFF in every byte) written into them.
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	244
70 8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	245 pb-update PBNAME filename
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 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	248 SIM-data-formats document and uploads it into the named SIM phonebook, writing
89 629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	249 only those record indices which appear in the data file - each record from the
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	250 data file gets written into the SIM with an UPDATE RECORD command, while all
629be330f92b doc/User-oriented-commands: pb-restore documented Mychaela Falconia <falcon@freecalypso.org> parents: 77 diff changeset	251 other record locations remain untouched.
70 8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	252
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	253 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	254
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	255 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	256 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	257 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	258 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	259 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	260
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	261 * 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	262
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	263 * 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	264 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	265 or to 0x81 otherwise;
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	266
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	267 * 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	268 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	269
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	270 * 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	271
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	272 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	273
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	274 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	275 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	276 UCS-2 alpha tags.
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 pb-erase PBNAME
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 This command fully erases the named phonebook.
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 pb-erase-one PBNAME rec
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	283
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	284 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	285
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	286 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	287
8dee7aa9ec58 doc/User-oriented-commands: phonebook commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 69 diff changeset	288 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	289 starting record must be identified by number (SIM record numbers are 1-based);
73 a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	290 the ending record argument may be either a number or the "end" keyword.
69 d4058ae94749 doc/User-oriented-commands: started phonebook description Mychaela Falconia <falcon@freecalypso.org> parents: 65 diff changeset	291
d4058ae94749 doc/User-oriented-commands: started phonebook description Mychaela Falconia <falcon@freecalypso.org> parents: 65 diff changeset	292 Last Number Dialed (LND)
d4058ae94749 doc/User-oriented-commands: started phonebook description Mychaela Falconia <falcon@freecalypso.org> parents: 65 diff changeset	293 ========================
d4058ae94749 doc/User-oriented-commands: started phonebook description Mychaela Falconia <falcon@freecalypso.org> parents: 65 diff changeset	294
71 a008f7a4bddf doc/User-oriented-commands: dump-lnd documented Mychaela Falconia <falcon@freecalypso.org> parents: 70 diff changeset	295 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	296 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	297 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	298 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	299 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	300 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	301 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	302 history lists.
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented Mychaela Falconia <falcon@freecalypso.org> parents: 70 diff changeset	303
a008f7a4bddf doc/User-oriented-commands: dump-lnd documented Mychaela Falconia <falcon@freecalypso.org> parents: 70 diff changeset	304 Because this LND store is a cyclic file, not linear fixed like phonebooks, it
90 8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	305 does not allow random access writes: it allows random access reads like all
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	306 regular record-based files, but the only write operation allowed by the SIM
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	307 interface protocol and the SIM file system architecture is writing a new record
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	308 that becomes the new #1, shifting all previous records down and losing the
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	309 oldest one. Because of this write access limitation, we do not provide the same
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	310 set of operations on LND as for regular phonebooks - but we still provide good
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	311 tinkering ability. The following commands are available:
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	312
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	313 lnd-dump
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	314
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	315 This command dumps the content of the LND store on the terminal, in the same
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	316 format as pb-dump for regular phonebooks.
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	317
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	318 If you have had your SIM for a very long time, having used it in different
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	319 phones with different firmwares, it may be interesting to look at the output of
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	320 lnd-dump - you may have LND records that were generated ages ago by other
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	321 phones if your current one does not write into SIM LND.
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	322
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	323 lnd-dump outfile
71 a008f7a4bddf doc/User-oriented-commands: dump-lnd documented Mychaela Falconia <falcon@freecalypso.org> parents: 70 diff changeset	324
90 8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	325 This form of the lnd-dump command produces the same dump format, but saves it
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	326 in the named file instead of sending it to the terminal.
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	327
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	328 lnd-restore filename
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	329
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	330 This command reads the named phonebook data file (presumably written previously
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	331 with lnd-dump) and writes it into EF_LND on the SIM. This command works by
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	332 first constructing a full binary image of the desired EF_LND content, then
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	333 writing every record in the reverse order from the last index to the first.
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	334
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	335 lnd-write phone-number [alpha-tag]
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	336
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	337 This command writes a new record into the LND cyclic store just like a standard
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	338 phone would do when making a record of a new outgoing call. The two arguments
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	339 (one required and one optional) are the same as for pb-update-imm.
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	340
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	341 lnd-erase
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	342
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	343 This command erases the EF_LND cyclic store, making it appear as if no outgoing
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	344 calls have ever been recorded. It works by writing a blank record (0xFF in
8a714fe98aa9 doc/User-oriented-commands: new lnd-* commands Mychaela Falconia <falcon@freecalypso.org> parents: 89 diff changeset	345 every byte) N times, where N is the size of the cyclic store in records.
71 a008f7a4bddf doc/User-oriented-commands: dump-lnd documented Mychaela Falconia <falcon@freecalypso.org> parents: 70 diff changeset	346
65 cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	347 Manipulating stored SMS
cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	348 =======================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	349
72 54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	350 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	351 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	352 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	353 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	354 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	355 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	356 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	357 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	358
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	359 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	360 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	361 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	362 Pirelli DP-L10 phone currently used by the Mother, implement their on-the-phone
97 d924e4b1387f doc/User-oriented-commands: grammar fix Mychaela Falconia <falcon@freecalypso.org> parents: 90 diff changeset	363 SMS storage by way of a file in their local flash file system whose binary
72 54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	364 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	365 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	366 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	367 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	368 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	369 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	370 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	371 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	372 pcm-sms-decode do the rest.
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	373
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	374 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	375
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	376 save-sms-bin host-filename
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	377
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	378 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	379 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	380
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	381 sms-erase-all
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	382
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	383 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	384
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	385 sms-erase-one rec
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	386
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	387 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	388
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	389 sms-erase-range start-rec end-rec
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	390
54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	391 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	392 record must be identified by number (SIM record numbers are 1-based); the
73 a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	393 ending record argument may be either a number or the "end" keyword.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	394
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	395 Manipulating SMS parameters
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	396 ===========================
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	397
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	398 SIM cards have an SMS parameter store in the form of record-based file EF_SMSP.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	399 Its most essential function is to specify the Service Centre Address for
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	400 outgoing SMS, but it can also be put to a few other uses:
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	401
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	402 * The primary SMSP record that gives the SC address also typically includes PID
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	403 and DCS parameters. The only sensible settings that can function as a
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	404 general-purpose default are PID=0x00 and DCS=0x00, but some SIMs have been
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	405 seen in the field that set bogus PID and DCS via their SMSP. It appears that
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	406 most end user phones ignore these settings, and they have no effect when
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	407 outgoing SMS are submitted to an AT command modem in PDU mode, but these
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	408 settings do affect our TI-based AT command modem in text mode - if they are
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	409 bogus on the SIM, they need to be fixed, either with fc-simtool or in the
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	410 actual AT modem session with AT+CSMP.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	411
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	412 * The same primary SMSP record can also specify a default validity period in
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	413 one-byte relative VP format.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	414
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	415 * Just like the situation with MSISDN, even though only the first record of
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	416 EF_SMSP is used in practice, most SIM issuers allocate room for a few records.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	417 These extra SMSP records are almost always blank,
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	418
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	419 fc-simtool provides the following commands for working with EF_SMSP:
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	420
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	421 smsp-dump
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	422
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	423 This command dumps the full content of EF_SMSP (all records) on the terminal,
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	424 using a lossless text-based format similar to the one we use for phonebooks.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	425 To illustrate our smsp format by way of examples, here is the output of
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	426 smsp-dump from old T-Mobile USA SIMs that have classic GSM 11.11 SIM
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	427 functionality:
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	428
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	429 #1: SC=12063130004,0x91 PID=0x00 DCS=0x00 "T-Mobile"
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	430 #2: ""
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	431 #3: ""
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	432 #4: ""
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	433
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	434 Here is the output from an Austrian S-Budget Mobile SIM from circa-2017:
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	435
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	436 #1: SC=4365009000000,0x91 PID=0xFF DCS=0xFF VP=173 ""
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	437 #2: ""
72 54800d2f5752 doc/User-oriented-commands: SMS manipulation documented Mychaela Falconia <falcon@freecalypso.org> parents: 71 diff changeset	438
73 a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	439 As one can see from these examples, T-Mobile allocated 4 records for their
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	440 EF_SMSP, whereas S-Budget Mobile allocated only 2 records for theirs.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	441 (Sysmocom webshop SIMs sysmoUSIM-SJS1 and sysmoISIM-SJA2 also have 2 records in
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	442 their EF_SMSP.) Yet only the first record is actually used, and the remaining
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	443 ones are blank. Note that unlike pb-dump, smsp-dump does not skip blank
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	444 records: it displays every record (the design rationale is that the total number
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	445 of EF_SMSP records is expected to be small), and a blank record is simply one
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	446 that has no parameters present and has an empty alpha tag.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	447
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	448 The following parameters may be present in each SMSP record, appearing in the
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	449 smsp-dump output in the same order in which they appear in the SIM binary
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	450 record:
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	451
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	452 DA= TP-Destination_Address
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	453 SC= TS-Service_Centre_Address
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	454 PID= TP-Protocol_Identifier
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	455 DCS= TP-Data_Coding_Scheme
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	456 VP= TP-Validity_Period
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	457
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	458 The phone numbers in DA= and SC= parameters are emitted in the same format as
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	459 in pb-dump, PID= and DCS= are emitted in hexadecimal with a 0x prefix, and VP=
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	460 is emitted in decimal. The alpha tag is always emitted at the end of the ASCII
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	461 line, just like in pb-dump.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	462
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	463 smsp-dump outfile
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	464
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	465 This form of the smsp-dump command produces the same dump of EF_SMSP, but saves
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	466 it in the named file instead of sending it to the terminal.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	467
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	468 smsp-restore filename
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	469
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	470 This command reads a file written by smsp-dump and writes it back to the SIM.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	471 Both decimal and 0x-prefixed hexadecimal forms are accepted for all 3 of PID=,
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	472 DCS= and VP= parameters.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	473
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	474 smsp-set rec params
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	475
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	476 This command writes a single record into SMSP directly from the command line,
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	477 without going through a data file. The record index to write to must be given,
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	478 followed by one or more parameters as in DA=, SC=, PID=, DCS= or VP=. DA= and
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	479 SC= phone numbers can be entered in the same relaxed form as in the
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	480 pb-update-imm command, and the remaining 3 parameters can be either decimal or
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	481 0x-prefixed hexadecimal. This command leaves the alpha tag field blank.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	482
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	483 smsp-set-tag rec alpha-tag params
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	484
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	485 This command is just like smsp-set, but adds an alpha tag argument.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	486
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	487 smsp-erase-all
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	488
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	489 This command erases every record entry in EF_SMSP.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	490
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	491 smsp-erase-one rec
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	492
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	493 This command erases the specified individual record in EF_SMSP.
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	494
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	495 smsp-erase-range start-rec end-rec
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	496
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	497 This command erases the specified range of records in EF_SMSP. The starting
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	498 record must be identified by number (SIM record numbers are 1-based); the
a56bbd6b0277 doc/User-oriented-commands: smsp-* commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 72 diff changeset	499 ending record argument may be either a number or the "end" keyword.
65 cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	500
cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	501 Identifying MVNO SIMs
cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	502 =====================
cc48ac3b151c doc/User-oriented-commands: basic info commands documented Mychaela Falconia <falcon@freecalypso.org> parents: 64 diff changeset	503

FreeCalypso > hg > fc-pcsc-tools

annotate doc/User-oriented-commands @ 97:d924e4b1387f