Difference between revisions of "Manual:Tools/Sms"

From MikroTik Wiki
Jump to: navigation, search
(Sending)
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Send SMS using GSM AT commands. ==
+
{{Versions|v5 +}}
  
It is possible to connect GSM modem to RouterOS device and use it to send SMS messages. RouterOS lists such modem as serial port that appears in '/port print' listing. GSM standard defines AT commands for sending SMS messages, and defines how messages should be encoded in these commands.
+
__TOC__
  
'advanced-tools' package provides command '/tool sms send' that uses standard GSM AT commands to send SMS.
+
== Summary ==
 +
 
 +
<p  id="shbox"><b>Sub-menu:</b> <code>/tool sms</code>
 +
<br />
 +
<b>Package:</b> <code>advanced-tools</code>
 +
<br />
 +
<b>Standards:</b> <code></code>
 +
</p>
 +
<br />
 +
 
 +
 
 +
It is possible to connect GSM modem to RouterOS device and use it to send and receive SMS messages. RouterOS lists such modem as serial port that appears in '/port print' listing. GSM standard defines AT commands for sending SMS messages, and defines how messages should be encoded in these commands.
 +
 
 +
'advanced-tools' package provides command <code>'/tool sms send'</code> that uses standard GSM AT commands to send SMS.
  
 
== Sending ==
 
== Sending ==
/tool sms '''port''' '''dst''' smsc='''smsc''' message='''message''' type='''type''
 
  
Since V3.23 there is one port per modem, and modem has channels used for commands and data. Channels have numbers 0,1,2, etc. Some modems may have just two channels, some have more. The SMS tool has channel support since v3.28
+
<p  id="shbox"><b>Command:</b> <code>/tool sms send</code>
 +
</p>
 +
 
 +
 
 +
''' Example '''
 +
 
 +
Sending command for ppp interface:
 +
 
 +
<pre>
 +
/tool sms send usb3 "20000000" \
 +
  message="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#\$%^&*(){}[]\"'~"
 +
</pre>
 +
 
 +
For lte interface use lte interface name in port field:
 +
 
 +
<pre>
 +
/tool sms send lte1 "20000000" \
 +
  message="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#\$%^&*(){}[]\"'~"
 +
</pre>
 +
 
 +
Send command takes following parameters:
 +
{{Mr-arg-table-h
 +
|prop=Parameter
 +
|desc=Description
 +
}}
 +
 
 +
{{Mr-arg-ro-table
 +
|arg=port
 +
|type=string
 +
|desc=Name of port from ''/port'' list that GSM modem is attached to.
 +
}}
 +
 
 +
{{Mr-arg-ro-table
 +
|arg=phone-number
 +
|type=string
 +
|desc=Recepient phone number. Allowed characters are "0123456789*#abc". If first character is "+" then phone number type is set to ''international'', otherwise it is set to ''unknown''.
 +
}}
 +
 
 +
{{Mr-arg-ro-table
 +
|arg=channel
 +
|type=integer
 +
|desc=Which modem channel to use for sending.
 +
}}
 +
 
 +
{{Mr-arg-ro-table
 +
|arg=message
 +
|type=string
 +
|desc=Message contents. It is encoded using GSM 7 encoding (UCS2 currently is not supported), so message length is limited to 160 characters (characters ^{}\[]~| are counted as two characters each). Concatenated messages and non-ASCII characters are currently not supported.
 +
}}
 +
 
 +
{{Mr-arg-ro-table
 +
|arg=smsc
 +
|type=string
 +
|desc=
 +
}}
 +
 
 +
{{Mr-arg-ro-table-end
 +
|arg=type
 +
|type=string
 +
|desc=If set to ''class-0'', then send class 0 SMS message. It is displayed immedeately and not stored in phone.
 +
}}
 +
 
  
* '''port''' - Name of port from '/port' list that GSM modem is attached to.
+
{{ Note | Since V3.23 there is one port per modem, and modem has channels used for commands and data. Channels have numbers 0,1,2, etc. Some modems may have just two channels, some have more. The SMS tool has channel support since v3.28 }}
* '''dst''' - Recepient phone number. Allowed characters are "0123456789*#abc". If first character is "+" then phone number type is set to 'international', otherwise it is set to 'unknown'.
 
* '''message''' - Message contents. It is encoded using GSM 7 encoding (UCS2 currently is not supported), so message length is limited to 160 characters (characters ^{}\[]~| are counted as two characters each). Concatenated messages and non-ASCII characters are currently not supported.
 
* '''type''' - If set to 'class-0', then send class 0 SMS message. It is displayed immedeately and not stored in phone.
 
* '''channel''' - Which modem channel to use for sending
 
  
==== Example ====
+
== USSD messages ==
  /tool sms send usb3 "20000000" message="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#\$%^&*(){}[]\"'~"
+
 
 +
USSD (Unstructured Supplementary Service Data) messages can be used to communicate with mobile network provider to receive additional information, enabling additional services or adding funds to prepaid cards.
 +
USSD messages can be processed by using AT commands (commands can differ or even may be blocked on some modems).
 +
 
 +
'''3G or GSM network modes must be activated to use this functionality''', as it's not supported under LTE only mode ('''R11e-LTE''' modem auto switches to 3G mode to send out USSD message).
 +
 
 +
PDU (Protocol Data Unit) message and its decrypted version is printed under LTE debug logging.
 +
 
 +
'''Example'''
 +
 
 +
Check if LTE debug logging is active:
 +
<pre>
 +
/system logging print
 +
Flags: X - disabled, I - invalid, * - default
 +
#    TOPICS                                  ACTION                                  PREFIX   
 +
0  * info                                    memory                                           
 +
1  * error                                  memory                                           
 +
2  * warning                                memory                                           
 +
3  * critical                                echo                                             
 +
</pre>
 +
If there is no logging entry add it by running this command:
 +
<pre>
 +
/system logging add topics=lte,!raw
 +
 
 +
/system logging print
 +
Flags: X - disabled, I - invalid, * - default
 +
#    TOPICS                                  ACTION                                  PREFIX   
 +
0  * info                                    memory                                           
 +
1  * error                                  memory                                           
 +
2  * warning                                memory                                           
 +
3  * critical                                echo   
 +
  4    lte,!raw                                memory                                                   
 +
         
 +
</pre>
 +
To recieve account status from '''*245#'''
 +
<pre>
 +
/interface lte at-chat lte1 input="AT+CUSD=1,\"*245#\",15"
 +
  output: OK
 +
/log print
 +
11:51:20 lte,async lte1: sent AT+CUSD=1,"*245#",15
 +
11:51:20 lte,async lte1: rcvd OK
 +
11:51:23 lte,async,event +CUSD: 0,"EBB79B1E0685E9ECF4BADE9E03", 0
 +
11:51:23 gsm,info USSD: konta atlikums
 +
</pre>
  
 
== Receiving ==
 
== Receiving ==
  
Since v3.24 RouterOS also supports receiving of SMS messages, and can exectue scripts, and even respond to the sender.  
+
Since v3.24 RouterOS also supports receiving of SMS messages, and can execute scripts, and even respond to the sender.  
 +
 
 +
Before router can receive SMS, relevant configuration is required in general '''/tool sms''' menu.
 +
Following parameters are configurable:
 +
 
 +
{{Mr-arg-table-h
 +
|prop=Parameter
 +
|desc=Description
 +
}}
 +
 
 +
{{Mr-arg-table
 +
|arg=allowed-number
 +
|type=string
 +
|default=""
 +
|desc=Sender number that will be allowed to run commands, must specify country code ie. +371XXXXXXX
 +
}}
  
tool sms> print
+
{{Mr-arg-table
  reader-running: no ''- must turn this on to allow receiving of messages''
+
|arg=channel
  port: (unknown)  ''- modema port (modemu can be used only by one process "/port> print" )''
+
|type=integer
  secret: ""        ''- the secret password, mandatory''
+
|default=0
  allowed-number: "" ''- sender number that will be allowed to run commands, must specify with country code ie. +371XXXXXXX''
+
|desc=Which modem channel to use for receiving.
  keep-max-sms: 0 ''- maximum number of keepable messages. if you set this bigger than SIM supports, new messages will not be received!''
+
}}
  
If you have enabled the reader, in '''/tool sms inbox> print''' you will see incoming messages.
+
{{Mr-arg-table
 +
|arg=keep-max-sms
 +
|type=integer
 +
|default=0
 +
|desc=Maximum number of messages that will be saved. If you set this bigger than SIM supports, new messages will not be received!
 +
Replaced with <var>auto-erase</var> parameter starting from RouterOS v6.44.6
 +
}}
  
==== Syntax ====
+
{{Mr-arg-table
 +
|arg=auto-erase
 +
|type=yes {{!}} no
 +
|default=no
 +
|desc=SIM storage size is read automatically. When <var>auto-erase=no</var> new SMS will not be received if storage is full. Set <var>auto-erase=yes</var> to delete the oldest received SMS to free space for new ones automatically. Available starting from v6.44.6
 +
}}
  
 +
{{Mr-arg-table
 +
|arg=port
 +
|type=string
 +
|default=(unknown)
 +
|desc=Modem port (modem can be used only by one process "/port> print" )''
 +
}}
 +
 +
{{Mr-arg-table
 +
|arg=receive-enabled
 +
|type=yes {{!}} no
 +
|default=no
 +
|desc=Must be turned on to receive messages
 +
}}
 +
 +
{{Mr-arg-table-end
 +
|arg=secret
 +
|type=string
 +
|default=""
 +
|desc=the secret password, mandatory
 +
}}
 +
 +
===Inbox===
 +
<p  id="shbox"><b>Sub-menu:</b> <code>/tool sms inbox</code>
 +
</p>
 +
 +
 +
If you have enabled the reader, you will see incoming messages in this submenu.
 +
 +
 +
Read-only properties:
 +
{{Mr-arg-table-h
 +
|prop=Property
 +
|desc=Description
 +
}}
 +
 +
{{Mr-arg-ro-table
 +
|arg=phone
 +
|type=string
 +
|desc=Senders phone number.
 +
}}
 +
 +
{{Mr-arg-ro-table
 +
|arg=message
 +
|type=string
 +
|desc=Message body
 +
}}
 +
 +
{{Mr-arg-ro-table
 +
|arg=timestamp
 +
|type=time
 +
|desc=Time when message was received. It is the time sent by operator, not the router's local time.
 +
}}
 +
 +
{{Mr-arg-ro-table-end
 +
|arg=type
 +
|type=string
 +
|desc=Message type
 +
}}
 +
 +
=== Syntax ===
 +
 +
<pre>
 
  :cmd SECRET script NAME [[ VAR[=VAL] ] ... ]
 
  :cmd SECRET script NAME [[ VAR[=VAL] ] ... ]
 +
</pre>
 +
 +
<ul class="bullets">
 +
<li>'''SECRET''' - the password
 +
<li>'''NAME''' - name of the script that's available in "/system script"
 +
<li>'''VAR''' - variables that will be passed to the script (can be passed as VAR or as VAR=value), separated by spaces.
 +
</ul>
  
*'''SECRET''' - the password
 
*'''NAME''' - name of the script that's available in "/system script"
 
*'''VAR''' - variables that will be passed to the script (can be passed as VAR or as VAR=value), separated by spaces.
 
  
 
Other things to remember:
 
Other things to remember:
 
+
<ul class="bullets">
*Parameters can be put into quotes "VAR"="VAL" if necessary.  
+
<li>*Parameters can be put into quotes "VAR"="VAL" if necessary.  
*Escaping of values is not supported (VAR="\"").  
+
<li>*Escaping of values is not supported (VAR="\"").  
*Combined SMS are not supported, every SMS will be treated separately
+
<li>*Combined SMS are not supported, every SMS will be treated separately
* 16Bit unicode messages are not supported
+
<li>* 16Bit unicode messages are not supported
* SMS are decoded with the standard GSM7 alphabet, so you can't send in other encodings, otherwise it will be decoded incorrectly
+
<li>* SMS are decoded with the standard GSM7 alphabet, so you can't send in other encodings, otherwise it will be decoded incorrectly
 +
</ul>
  
 
==== Examples ====
 
==== Examples ====
Line 69: Line 274:
 
:cmd slepens script mans_skripts var="a a"  
 
:cmd slepens script mans_skripts var="a a"  
 
</pre>
 
</pre>
 
  
 
== Debugging ==
 
== Debugging ==
  
'''/tool sms send''' command logs data it writes and reads. It is logged with tags gsm,debug,write and gsm,debug,read
+
'''/tool sms send''' command is logging data that is written and read. It is logged with tags ''gsm,debug,write'' and ''gsm,debug,read''
 +
For more information see [[M:System/Log | system logging]].
  
 
== Implementation details ==
 
== Implementation details ==
  
This command uses "AT+CMGS" and "AT+CMGF" commands. Port is acquired for the duration of this command, and cannot be used concurently by another RouterOS component. Sending message can take a long time, this command timeouts after a minute while sending message data, and after two seconds during initial AT command exchange.
+
''AT+CMGS'' and ''AT+CMGF'' commands are used. Port is acquired for the duration of the command and cannot be used concurently by another RouterOS component. Message sending process can take a long time, it times out after a minute and after two seconds during initial AT command exchange.
  
 
== See also ==
 
== See also ==
 +
 
* http://www.3gpp.org/ftp/Specs/html-info/27-series.htm
 
* http://www.3gpp.org/ftp/Specs/html-info/27-series.htm
 
* http://www.3gpp.org/ftp/Specs/html-info/23-series.htm
 
* http://www.3gpp.org/ftp/Specs/html-info/23-series.htm
 +
 +
 +
{{cont}}
 +
 +
[[Category:Manual|S]]
 +
[[Category:Tools|S]]

Latest revision as of 15:15, 31 October 2019

Version.png

Applies to RouterOS: v5 +

Summary

Sub-menu: /tool sms
Package: advanced-tools
Standards:



It is possible to connect GSM modem to RouterOS device and use it to send and receive SMS messages. RouterOS lists such modem as serial port that appears in '/port print' listing. GSM standard defines AT commands for sending SMS messages, and defines how messages should be encoded in these commands.

'advanced-tools' package provides command '/tool sms send' that uses standard GSM AT commands to send SMS.

Sending

Command: /tool sms send


Example

Sending command for ppp interface:

/tool sms send usb3 "20000000" \
   message="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#\$%^&*(){}[]\"'~"

For lte interface use lte interface name in port field:

/tool sms send lte1 "20000000" \
   message="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#\$%^&*(){}[]\"'~"

Send command takes following parameters:

Parameter Description
port (string) Name of port from /port list that GSM modem is attached to.
phone-number (string) Recepient phone number. Allowed characters are "0123456789*#abc". If first character is "+" then phone number type is set to international, otherwise it is set to unknown.
channel (integer) Which modem channel to use for sending.
message (string) Message contents. It is encoded using GSM 7 encoding (UCS2 currently is not supported), so message length is limited to 160 characters (characters ^{}\[]~
smsc (string)
type (string) If set to class-0, then send class 0 SMS message. It is displayed immedeately and not stored in phone.


Icon-note.png

Note: Since V3.23 there is one port per modem, and modem has channels used for commands and data. Channels have numbers 0,1,2, etc. Some modems may have just two channels, some have more. The SMS tool has channel support since v3.28


USSD messages

USSD (Unstructured Supplementary Service Data) messages can be used to communicate with mobile network provider to receive additional information, enabling additional services or adding funds to prepaid cards. USSD messages can be processed by using AT commands (commands can differ or even may be blocked on some modems).

3G or GSM network modes must be activated to use this functionality, as it's not supported under LTE only mode (R11e-LTE modem auto switches to 3G mode to send out USSD message).

PDU (Protocol Data Unit) message and its decrypted version is printed under LTE debug logging.

Example

Check if LTE debug logging is active:

/system logging print
Flags: X - disabled, I - invalid, * - default 
 #    TOPICS                                  ACTION                                  PREFIX    
 0  * info                                    memory                                            
 1  * error                                   memory                                            
 2  * warning                                 memory                                            
 3  * critical                                echo                                              

If there is no logging entry add it by running this command:

/system logging add topics=lte,!raw

/system logging print
Flags: X - disabled, I - invalid, * - default 
 #    TOPICS                                  ACTION                                  PREFIX    
 0  * info                                    memory                                            
 1  * error                                   memory                                            
 2  * warning                                 memory                                            
 3  * critical                                echo     
 4    lte,!raw                                memory                                                     
          

To recieve account status from *245#

/interface lte at-chat lte1 input="AT+CUSD=1,\"*245#\",15"
  output: OK
/log print
11:51:20 lte,async lte1: sent AT+CUSD=1,"*245#",15 
11:51:20 lte,async lte1: rcvd OK 
11:51:23 lte,async,event +CUSD: 0,"EBB79B1E0685E9ECF4BADE9E03", 0 
11:51:23 gsm,info USSD: konta atlikums

Receiving

Since v3.24 RouterOS also supports receiving of SMS messages, and can execute scripts, and even respond to the sender.

Before router can receive SMS, relevant configuration is required in general /tool sms menu. Following parameters are configurable:

Parameter Description
allowed-number (string; Default: "") Sender number that will be allowed to run commands, must specify country code ie. +371XXXXXXX
channel (integer; Default: 0) Which modem channel to use for receiving.
keep-max-sms (integer; Default: 0) Maximum number of messages that will be saved. If you set this bigger than SIM supports, new messages will not be received! Replaced with auto-erase parameter starting from RouterOS v6.44.6
auto-erase (yes | no; Default: no) SIM storage size is read automatically. When auto-erase=no new SMS will not be received if storage is full. Set auto-erase=yes to delete the oldest received SMS to free space for new ones automatically. Available starting from v6.44.6
port (string; Default: (unknown)) Modem port (modem can be used only by one process "/port> print" )
receive-enabled (yes | no; Default: no) Must be turned on to receive messages
secret (string; Default: "") the secret password, mandatory

Inbox

Sub-menu: /tool sms inbox


If you have enabled the reader, you will see incoming messages in this submenu.


Read-only properties:

Property Description
phone (string) Senders phone number.
message (string) Message body
timestamp (time) Time when message was received. It is the time sent by operator, not the router's local time.
type (string) Message type

Syntax

 :cmd SECRET script NAME [[ VAR[=VAL] ] ... ]
  • SECRET - the password
  • NAME - name of the script that's available in "/system script"
  • VAR - variables that will be passed to the script (can be passed as VAR or as VAR=value), separated by spaces.


Other things to remember:

  • *Parameters can be put into quotes "VAR"="VAL" if necessary.
  • *Escaping of values is not supported (VAR="\"").
  • *Combined SMS are not supported, every SMS will be treated separately
  • * 16Bit unicode messages are not supported
  • * SMS are decoded with the standard GSM7 alphabet, so you can't send in other encodings, otherwise it will be decoded incorrectly

Examples

Wrong:

:cmd script mans_skripts
:cmd slepens script mans skripts
:cmd slepens script mans_skripts var=
:cmd slepens script mans_skripts var= a
:cmd slepens script mans_skripts var=a a

Right:

:cmd slepens script mans_skripts
:cmd slepens script "mans skripts"
:cmd slepens script mans_skripts var
:cmd slepens script mans_skripts var=a
:cmd slepens script mans_skripts var="a a" 

Debugging

/tool sms send command is logging data that is written and read. It is logged with tags gsm,debug,write and gsm,debug,read For more information see system logging.

Implementation details

AT+CMGS and AT+CMGF commands are used. Port is acquired for the duration of the command and cannot be used concurently by another RouterOS component. Message sending process can take a long time, it times out after a minute and after two seconds during initial AT command exchange.

See also


[ Top | Back to Content ]