sms(s): delete after copy to common directory
[sip-router] / modules_k / sms / README
1 SMS Module
2
3 Bogdan-Andrei Iancu
4
5    voice-system.ro
6
7 Edited by
8
9 Bogdan-Andrei Iancu
10
11    Copyright © 2003 FhG FOKUS
12    Revision History
13    Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
14                               (Mi, 06 Aug 2008) $
15      __________________________________________________________
16
17    Table of Contents
18
19    1. Admin Guide
20
21         1.1. Overview
22
23               1.1.1. Hardware Requirements
24               1.1.2. Numbering Plan
25               1.1.3. Address Mapping
26
27         1.2. Dependencies
28
29               1.2.1. Kamailio Modules
30               1.2.2. External Libraries or Applications
31
32         1.3. Exported Parameters
33
34               1.3.1. modems (string)
35               1.3.2. networks (string)
36               1.3.3. links (string)
37               1.3.4. default_net (string)
38               1.3.5. max_sms_parts (integer)
39               1.3.6. domain (string)
40               1.3.7. use_contact (integer)
41               1.3.8. sms_report_type (integer)
42
43         1.4. Exported Functions
44
45               1.4.1. sms_send_msg_to_net(network_name)
46               1.4.2. sms_send_msg()
47
48    2. Developer Guide
49
50    List of Examples
51
52    1.1. Set modems parameter
53    1.2. Set networks parameter
54    1.3. Set links parameter
55    1.4. Set default_net parameter
56    1.5. Set max_sms_parts parameter
57    1.6. Set domain_str parameter
58    1.7. Set use_contact parameter
59    1.8. Set sms_report_type parameter
60    1.9. sms_send_msg_to_net usage
61    1.10. sms_send_msg usage
62
63 Chapter 1. Admin Guide
64
65 1.1. Overview
66
67    This module provides a way of communication between SIP network
68    (via SIP MESSAGE) and GSM networks (via ShortMessageService).
69    Communication is possible from SIP to SMS and vice versa. The
70    module provides facilities like SMS confirmation--the gateway
71    can confirm to the SIP user if his message really reached its
72    destination as a SMS--or multi-part messages--if a SIP messages
73    is too long it will be split and sent as multiple SMS.
74
75    Errors occurred because of an invalid number or a too long
76    message or because of an internal modem malfunction are
77    reported back to the SIP user via a SIP message containing
78    explanations regarding the error.
79
80 1.1.1. Hardware Requirements
81
82    The SMS module needs a GSM modem to be able to send/receive the
83    SMS messages. Usually, this kind of modems are externals,
84    linked to the machine via serial cable. The modem can be a
85    dedicated one (as the ones provided by FALCOM) or can be a GSM
86    telephone that has an internal modem (as the latest mobile
87    phones from NOKIA and ERICSSON).
88
89 1.1.2. Numbering Plan
90
91    The gateway accepts and advertises phone numbers in
92    international format, more specific like: +(international
93    code)(area code)(number). Ex: Germany, D1 = +49 170 5678181
94    Romania, Connex = +40 722 123456. A number in this format is
95    expected to be placed as username into RURI or in the To
96    header. If RURI misses the username, the To header will be
97    consider. Also, the gateway will advertise in this format the
98    username in Contact headers (in SIP replies and requests) and
99    in From headers (in SIP requests).
100
101 1.1.3. Address Mapping
102
103    To identify the destination number of the SMS, the gateway
104    expects to have a mobile number in username of the SIP
105    destination address (for example
106    sip:+401704678811@sidomain.net). For the reverse direction,
107    because the gateway has only one GSM number, the destination
108    SIP address has to be encapsulated into the SMS body. The
109    gateway expects to find a SIP address at the beginning of the
110    SMS body in "sip:user.host" format. Everything before the SIP
111    address will be discarded, the useful text begins exactly after
112    the address (for example SMS="For sip:user@host hello world!!"
113    -> SIP= "hello world") In order to facilitate replying, the
114    gateway sends all the SMS messages with a header containing the
115    source SIP address in the following format: "From sip:user@host
116    (if you reply DONOT remove it)<new_line>". When an SMS-reply is
117    received having this header (all of it or truncated at the
118    end), the header will be left out (it will not be in the SIP
119    message).
120
121 1.2. Dependencies
122
123 1.2.1. Kamailio Modules
124
125    The following modules must be loaded before this module:
126      * tm - Transaction Manager.
127
128 1.2.2. External Libraries or Applications
129
130    The following libraries or applications must be installed
131    before running Kamailio with this module loaded:
132      * None.
133
134 1.3. Exported Parameters
135
136 1.3.1. modems (string)
137
138    Define and configure one or more GSM modems.
139 modems_value     = modem_definition *( ";" modem_definition )
140 modem_definition = modem_name "[" list_of_params "]"
141 list_of_params   = modem_param *( ";" modem_param )
142 modem_param       = name "=" value
143
144    The following parameters can be used:
145      * d=device (mandatory) - Device associated with modem
146        (/dev/ttyS0, /dev/modem, etc.).
147      * p=pin (optional) - SIM PIN - default is NULL.
148      * m=mode (optional) - Modem working mode
149        ("ASCII","OLD","DIGICOM", "NEW"). Default value is "NEW".
150      * c=SMS_Center (optional) - SMS center number for that modem.
151        Default is the SMS center set on the SIM card.
152      * b=baudrate (optional) - Default is 19600.
153      * r=retry (optional) - How many times to try to re-send a SMS
154        that reported error. Default is twice.
155      * l=looping (optional) - Time for modem to wait before
156        performing a new check for incomimg/outgoing SMS/SIP_MSG.
157        Default is 20.
158
159    No default value, the parameter is mandatory.
160
161    Example 1.1. Set modems parameter
162 ...
163 modparam("sms", "modems", "Nokia [d=/dev/ttyS1;b=9600;m=new;l=30] ")
164 modparam("sms", "modems", "Nokia[d=/dev/ttyS1];Siemens[d=/dev/ttyS2]")
165 ...
166
167 1.3.2. networks (string)
168
169    Define and configure used GSM networks.
170 networks_value = net_definition *( ";" net_definition )
171 net_definition = net_name "[" list_of_params "]"
172 list_of_params = set_param *( ";" set_param )
173 set_param         = name "=" value
174
175    The following parameters can be used:
176      * m=msx_sms_per_call (optional) - Maximum number of SMS send
177        / received from that net in one modem loop. Default is 10.
178        This parameter was introduced to avoid starvation.
179        Example of the starvation--a modem can send SMS for more
180        than 1 networks. If you have a huge number of SMS for the
181        first network and the number of incoming SIP messages is
182        equal to the sent SMS per same unit of time, the modem will
183        never get to send SMS for the next networks.
184
185    No default value, the parameter is mandatory.
186
187    Example 1.2. Set networks parameter
188 ...
189 modparam("sms", "networks", "D1 [m=10] ;d2[ m=20]")
190 ...
191
192 1.3.3. links (string)
193
194    Define from which network each modem should send SMS.
195 links_value = modem_assoc *( ";" modem_assoc )
196 modem_assoc = modem_name "[" list_of_networks "]"
197 list_of_networks = network *( ";" network )
198
199    No default value, the parameter is mandatory.
200
201    Example 1.3. Set links parameter
202 ...
203 modparam("sms", "links", "NOKIA[D1;d2]")
204 ...
205
206    The modem NOKIA will send SMS from D1 and D2 net (in this order
207    !). if in a net queue are more then max_sms_per_call SMS the
208    modem will not sleep before starting the next loop ! Shortly,
209    if messages are waiting to be sent, the modem will not go in
210    sleep.
211
212 1.3.4. default_net (string)
213
214    The default network to use. If no one specified, the first
215    defined network is used. This parameter is useful only if the
216    "sms_send_msg" exported function is used (see Section 1.4,
217    "Exported Functions").
218
219    Example 1.4. Set default_net parameter
220 ...
221 modparam("sms", "default_net", "D1")
222 ...
223
224 1.3.5. max_sms_parts (integer)
225
226    Shows in how many parts (SMS messages) a SIP message can be
227    split. If exceeded, the SIP message will be sent truncated and
228    the SIP user will get back another message containing the
229    unsent part.
230
231    Default value is 4.
232
233    Example 1.5. Set max_sms_parts parameter
234 ...
235 modparam("sms", "max_sms_parts", 10)
236 ...
237
238 1.3.6. domain (string)
239
240    Specify a fake domain name to be used by the gateway. The
241    Contact headers and the From header from request will be
242    construct based on this fake domain name. It's useful when the
243    gateway is transparently hidden behind a proxy/register
244    (located on different machines).
245
246    Default is the name of the machine the gateway is running on.
247
248    Example 1.6. Set domain_str parameter
249 ...
250 modparam("sms", "domain_str", "foo.bar")
251 ...
252
253 1.3.7. use_contact (integer)
254
255    If a contact header should be added to the outgoing SIP
256    messages. Even if the SIP draft forbids this, some UAS require
257    it.
258
259    Default is 0 (no).
260
261    Example 1.7. Set use_contact parameter
262 ...
263 modparam("sms", "use_contact", 1)
264 ...
265
266 1.3.8. sms_report_type (integer)
267
268    If the modem should ask for SMS confirmation from the SMS
269    Center. If the SMSC reply with an error code, the gateway will
270    send back to SIP user a SIP message containing the text (or
271    part of it) that couldn't be send. Two report mechanisms are
272    implemented:
273      * 1 - the reports are delivered by the GSM device as SMS
274        reports (so far supported only by Nokia modems);
275      * 2 - the reports are delivered as async. CDS responses
276        (supported by almost all modems, except Ericsson).
277
278    Default is 0 (no report).
279
280    Example 1.8. Set sms_report_type parameter
281 ...
282 modparam("sms", "sms_report_type", 1)
283 ...
284
285 1.4. Exported Functions
286
287 1.4.1.  sms_send_msg_to_net(network_name)
288
289    Put the SIP msg in the specified network queue. The function
290    return error if the number encapsulated into SIP message is
291    malformed, if the content_type is incorrect or because of some
292    internal failures.
293
294    Meaning of the parameters is as follows:
295      * network_name - Name of network.
296
297    This function can be used from REQUEST_ROUTE.
298
299    Example 1.9. sms_send_msg_to_net usage
300 ...
301 if (sms_send_msg_to_net("D1"))
302 {
303         if (!t_reply("202", "yes sir, SMS sent over"))
304         {
305                 # if replying failed, retry statelessly
306                 sl_reply_error();
307         };
308 } else {
309         if (!t_reply("502", "Bad gateway - SMS error"))
310         {
311                 # if replying failed, retry statelessly
312                 sl_reply_error();
313         };
314         exit;
315 };
316 ...
317
318 1.4.2.  sms_send_msg()
319
320    The same as the previous one, but use the default network
321    queue.
322
323    This function can be used from REQUEST_ROUTE.
324
325    Example 1.10. sms_send_msg usage
326 ...
327 if (sms_send_msg_to_net())
328 {
329         if (!t_reply("202", "yes sir, SMS sent over"))
330         {
331                 # if replying failed, retry statelessly
332                 sl_reply_error();
333         };
334 } else {
335         if (!t_reply("502", "Bad gateway - SMS error"))
336         {
337                 # if replying failed, retry statelessly
338                 sl_reply_error();
339         };
340         exit;
341 };
342 ...
343
344 Chapter 2. Developer Guide
345
346    Each modem forks its own process for sending /fetching SMS.
347    Communication and queuing between Kamailio working processes
348    and modem processes is done with pipes.