FreeCalypso > hg > sms-coding-utils

comparison doc/Generator-tool-workflow @ 30:d7571dc2fecc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: encoder/generator portion is now just one part
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 13 Jun 2024 23:16:04 +0000
parents doc/Tool-workflow@f0139d74d3aa
children
comparison
equal deleted inserted replaced
29:aae078d9eaa6 30:d7571dc2fecc
1 The encoder/generator part of the present sms-coding-utils suite consists of
2 two principal programs: sms-encode-text and sms-gen-tpdu. There is also a
3 shell script named gen-sms-deliver-pdu that serves as a wrapper around
4 sms-gen-tpdu for one important use case of network-side testing of MT SMS.
5
6 sms-encode-text encodes only the user text body of SMS (either single or
7 concatenated) and does not deal with any of the headers. The output from
8 sms-encode-text is designed to be fed into sms-gen-tpdu with some additional
9 prepended lines, either by way of a wrapper shell script like
10 gen-sms-deliver-pdu or by way of an intermediate file: redirect the output of
11 sms-encode-text into a file, manually edit that file to add user-addr and
12 possibly other header lines, and then feed it to sms-gen-tpdu.
13
14 The intermediate format in which SMS user data payload is passed from
15 sms-encode-text to sms-gen-tpdu is long hex strings, with the following
16 peculiarities:
17
18 * In the most common case of GSM7 encoding, the conversion from ASCII to
19 GSM 03.38 has already been done (for example, character '@' will be encoded
20 as 00 rather than 40 in these hex strings, and '[' will be escape-encoded as
21 1B3C), but the packing of septets into octets has NOT been done yet - instead
22 a string of binary septets is emitted, with the high bit clear in each hex
23 byte.
24
25 * In the case of GSM7-encoded message segments that begin with UDH (used for
26 concatenated SMS), the UDH part is encoded as octets, followed by septets for
27 the text part. The recipient of this intermediate format will need to extract
28 UDHL from the first octet of the hex string and use this length to locate the
29 boundary between octet-encoded UDH and septet-encoded text.
30
31 This peculiar format was chosen because it is the representation format used in
32 SMPP transport, and in any case it is a necessary intermediate step between
33 ASCII input and the final GSM 03.40 TPDU form. The Mother had to write another
34 test program for SMPP (smpp-send in themwi-system-sw repository), and that
35 program is front-fed with the same sms-encode-text preliminary.
36
37 sms-encode-text usage
38 =====================
39
40 The basic usage synopsis is:
41
42 sms-encode-text [options] [message-text]
43
44 If the message text to be encoded is given on the command line, it must be a
45 single argument, i.e., quotes will need to be used at the shell level. If no
46 message text is given on the command line, it will be read from stdin instead.
47 The operation of this program generally mirrors fcup-smsend from FreeCalypso
48 host tools - please read User-phone-tools document in freecalypso-tools
49 repository. Allowed options are -c, -C, -e, -u and -U, and they work exactly
50 the same as in fcup-smsend.
51
52 Just like fcup-smsend, sms-encode-text can generate either single SMS (if the
53 message text fits within 160 characters for GSM7 or 70 characters for UCS-2) or
54 concatenated SMS. To enable the possibility of concatenated SMS, you have to
55 invoke the program with either -c or -C option; the difference between these
56 two options is in how the reference number for concatenated SMS is obtained.
57 With -C you specify this reference number explicitly; with -c the program
58 implements the same $HOME/.concat_sms_refno logic as fcup-smsend.
59
60 In the case of single SMS, the output from sms-encode-text consists of two
61 lines: a mode-setting line that reads either 'dcs 0 septet' or 'dcs 8 octet',
62 followed by a message line. The single message line consists of 'msg' keyword
63 followed by a long hex string as explained in the previous section.
64
65 In the case of concatenated SMS, the output from sms-encode-text consists of 3
66 or more lines: a dcs line that is the same as for single SMS, followed by 2 or
67 more msg-udh lines. Each msg-udh line carries a TP-UD field that consists of
68 UDH followed by text, and the msg-udh keyword (as distinct from plain 'msg')
69 conveys the UDHI bit.
70
71 sms-gen-tpdu usage
72 ==================
73
74 sms-gen-tpdu takes only one command argument: a mode keyword selecting which
75 type of PDU needs to be generated. The 4 choices are:
76
77 mo Generate a pure GSM 03.40 SMS-SUBMIT TPDU
78 mt Generate a pure GSM 03.40 SMS-DELIVER TPDU
79 sc-mo Generate SMS-SUBMIT with a prepended SC-address
80 sc-mt Generate SMS-DELIVER with a prepended SC-address
81
82 sc-mo and sc-mt forms are intended for the mobile side of GSM, as this format
83 is written into EF_SMS on SIMs and exchanged in GSM 07.05 PDU mode. Plain mt
84 format is intended for generating SMS-DELIVER TPDUs for MT SMS testing from the
85 network side (SMSC development), and plain mo format exists for completeness.
86
87 All other bits beyond the above mode selection are read from stdin. The input
88 is line-based and is expected to consist of setting lines followed by message
89 lines. Each msg or msg-udh line in the input results in a TPDU being generated,
90 but in order to produce valid message PDUs for anything other than an MO draft
91 that hasn't had its To address set yet, these message lines need to be preceded
92 by some setting lines. Usually only user-addr setting needs to be given before
93 sms-encode-text output; other settings may be given as part of more advanced
94 experiments.
95
96 The following settings are supported:
97
98 dcs INTEGER (septet|octet)
99
100 Set TP-DCS. The first argument is the value to be put into the TP-DCS octet in
101 the TPDU; the second argument is a mode keyword that tells sms-gen-tpdu whether
102 it should operate in septet or octet mode when encoding TP-UDL and TP-UD.
103
104 lp
105
106 Set TP-LP; valid only in MT mode.
107
108 mms
109
110 Set TP-MMS; valid only in MT mode. Note that the bit encoding this Boolean flag
111 is inverted: when no TP-MMS is set, the bit is 1, and when 'mms' setting is
112 given, the bit becomes 0.
113
114 mr INTEGER
115
116 Set TP-MR; valid only in MO mode. The default in the absence of this setting
117 is 0xFF.
118
119 pid INTEGER
120
121 Set TP-PID. The default in the absence of this setting is 0.
122
123 rd
124
125 Set TP-RD; valid only in MO mode.
126
127 rp
128
129 Set TP-RP.
130
131 sc-addr NUMBER[,INTEGER]
132
133 Valid only in sc-mo and sc-mt modes: set the SC-address to be prepended before
134 the GSM 03.40 TPDU. If this setting is omitted, a null SC-address (a single
135 length octet of 0) is emitted. The latter approach works with GSM 07.05 at
136 least with FreeCalypso firmware - the MS firmware replaces this null SC-address
137 with the one programmed on the SIM.
138
139 sc-ts YY/MM/DD,HH:MM:SS[+-]TZ
140
141 Set TP-SCTS; valid only in MT mode. If this setting is not given, the current
142 local time is used to generate TP-SCTS.
143
144 sr
145
146 Set TP-SRI or TP-SRR (different names for the same bit).
147
148 user-addr NUMBER[,INTEGER]
149
150 Set TP-DA in SMS-SUBMIT or TP-OA in SMS-DELIVER.
151
152 user-addr alpha:STRING
153
154 This special form of user-addr sets TP-OA (or TP-DA - we provide mechanism, not
155 policy) in the special alphanumeric address format (TON=5, NPI=0). The alpha
156 address can be up to 11 GSM7 characters; the GSM7 string is given in standard
157 FreeCalypso representation defined in the SIM-data-formats specification in
158 freecalypso-docs.
159
160 vp-abs YY/MM/DD,HH:MM:SS[+-]TZ
161
162 Set TP-VP in absolute format; valid only in MO mode.
163
164 vp-rel INTEGER
165
166 Set TP-VP in relative format; valid only in MO mode.
167
168 INTEGER format: decimal by default, hexadecimal if prefixed with 0x.
169
170 NUMBER[,INTEGER] phone number entry format for user-addr and sc-addr
171 --------------------------------------------------------------------
172
173 The same convention is used as elsewhere in FreeCalypso queendom, e.g., in
174 fcup-smsend and fc-simtool:
175
176 * If no comma-separated TON/NPI byte is given, it defaults to 0x91 if the number
177 begins with '+' or 0x81 otherwise.
178
179 * If the number is suffixed with a comma and a byte-sized integer (decimal by
180 default or 0x prefix for hex), the TON/NPI byte is set explicitly.