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

annotate doc/User-oriented-commands @ 74:8562d8508cf2

grcard2-set-{adm,super}-hex commands implemented It appears that GrcardSIM2 cards allow arbitrary 64-bit keys for ADM and SUPER ADM, not necessarily consisting of ASCII digits like the specs require for standard PIN and PUK, and pySim-prog.py in fact sets the ADM key to 4444444444444444 in hex by default, which is not an ASCII digit string. If the cards allow such keys, we need to support them too.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Tue, 16 Feb 2021 04:10:36 +0000
parents	a56bbd6b0277
children	4558048fce10

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

FreeCalypso > hg > fc-pcsc-tools

annotate doc/User-oriented-commands @ 74:8562d8508cf2