--- a/doc/User-oriented-commands	Mon Feb 15 05:40:10 2021 +0000
+++ b/doc/User-oriented-commands	Mon Feb 15 10:00:17 2021 +0000
@@ -281,7 +281,7 @@
 
 This command erases the specified range of records in the named phonebook.  The
 starting record must be identified by number (SIM record numbers are 1-based);
-the ending record argument may be either as a number or the "end" keyword.
+the ending record argument may be either a number or the "end" keyword.
 
 Last Number Dialed (LND)
 ========================
@@ -354,10 +354,113 @@
 
 This command erases the specified range of records in EF_SMS.  The starting
 record must be identified by number (SIM record numbers are 1-based); the
-ending record argument may be either as a number or the "end" keyword.
+ending record argument may be either a number or the "end" keyword.
+
+Manipulating SMS parameters
+===========================
+
+SIM cards have an SMS parameter store in the form of record-based file EF_SMSP.
+Its most essential function is to specify the Service Centre Address for
+outgoing SMS, but it can also be put to a few other uses:
+
+* The primary SMSP record that gives the SC address also typically includes PID
+  and DCS parameters.  The only sensible settings that can function as a
+  general-purpose default are PID=0x00 and DCS=0x00, but some SIMs have been
+  seen in the field that set bogus PID and DCS via their SMSP.  It appears that
+  most end user phones ignore these settings, and they have no effect when
+  outgoing SMS are submitted to an AT command modem in PDU mode, but these
+  settings do affect our TI-based AT command modem in text mode - if they are
+  bogus on the SIM, they need to be fixed, either with fc-simtool or in the
+  actual AT modem session with AT+CSMP.
+
+* The same primary SMSP record can also specify a default validity period in
+  one-byte relative VP format.
+
+* Just like the situation with MSISDN, even though only the first record of
+  EF_SMSP is used in practice, most SIM issuers allocate room for a few records.
+  These extra SMSP records are almost always blank,
+
+fc-simtool provides the following commands for working with EF_SMSP:
+
+smsp-dump
+
+This command dumps the full content of EF_SMSP (all records) on the terminal,
+using a lossless text-based format similar to the one we use for phonebooks.
+To illustrate our smsp format by way of examples, here is the output of
+smsp-dump from old T-Mobile USA SIMs that have classic GSM 11.11 SIM
+functionality:
+
+#1: SC=12063130004,0x91 PID=0x00 DCS=0x00 "T-Mobile"
+#2: ""
+#3: ""
+#4: ""
+
+Here is the output from an Austrian S-Budget Mobile SIM from circa-2017:
+
+#1: SC=4365009000000,0x91 PID=0xFF DCS=0xFF VP=173 ""
+#2: ""
 
-Manipulating SMS profiles
-=========================
+As one can see from these examples, T-Mobile allocated 4 records for their
+EF_SMSP, whereas S-Budget Mobile allocated only 2 records for theirs.
+(Sysmocom webshop SIMs sysmoUSIM-SJS1 and sysmoISIM-SJA2 also have 2 records in
+their EF_SMSP.)  Yet only the first record is actually used, and the remaining
+ones are blank.  Note that unlike pb-dump, smsp-dump does not skip blank
+records: it displays every record (the design rationale is that the total number
+of EF_SMSP records is expected to be small), and a blank record is simply one
+that has no parameters present and has an empty alpha tag.
+
+The following parameters may be present in each SMSP record, appearing in the
+smsp-dump output in the same order in which they appear in the SIM binary
+record:
+
+DA=	TP-Destination_Address
+SC=	TS-Service_Centre_Address
+PID=	TP-Protocol_Identifier
+DCS=	TP-Data_Coding_Scheme
+VP=	TP-Validity_Period
+
+The phone numbers in DA= and SC= parameters are emitted in the same format as
+in pb-dump, PID= and DCS= are emitted in hexadecimal with a 0x prefix, and VP=
+is emitted in decimal.  The alpha tag is always emitted at the end of the ASCII
+line, just like in pb-dump.
+
+smsp-dump outfile
+
+This form of the smsp-dump command produces the same dump of EF_SMSP, but saves
+it in the named file instead of sending it to the terminal.
+
+smsp-restore filename
+
+This command reads a file written by smsp-dump and writes it back to the SIM.
+Both decimal and 0x-prefixed hexadecimal forms are accepted for all 3 of PID=,
+DCS= and VP= parameters.
+
+smsp-set rec params
+
+This command writes a single record into SMSP directly from the command line,
+without going through a data file.  The record index to write to must be given,
+followed by one or more parameters as in DA=, SC=, PID=, DCS= or VP=.  DA= and
+SC= phone numbers can be entered in the same relaxed form as in the
+pb-update-imm command, and the remaining 3 parameters can be either decimal or
+0x-prefixed hexadecimal.  This command leaves the alpha tag field blank.
+
+smsp-set-tag rec alpha-tag params
+
+This command is just like smsp-set, but adds an alpha tag argument.
+
+smsp-erase-all
+
+This command erases every record entry in EF_SMSP.
+
+smsp-erase-one rec
+
+This command erases the specified individual record in EF_SMSP.
+
+smsp-erase-range start-rec end-rec
+
+This command erases the specified range of records in EF_SMSP.  The starting
+record must be identified by number (SIM record numbers are 1-based); the
+ending record argument may be either a number or the "end" keyword.
 
 Identifying MVNO SIMs
 =====================