MOBITEK SMS Engine — Enterprise Edition version 7.x and 8.x Manual

REVISION HISTORY

RELEASE NOTES

COPYRIGHT

© 2019 MOBITEK System Sdn. Bhd.  All rights reserved.

No part of this document may be reproduced, distributed, stored in a retrieval system or translated into any language, in any form or by any means, electronic, mechanical, magnetic, optical, photocopying, manual or otherwise, without the prior written permission of MOBITEK System Sdn. Bhd.

TRADEMARKS

MOBITEK^® is a registered trademark owns by MOBITEK System Sdn. Bhd.
Product names, logos, brands and other trademarks referred in this document are the property of their respective trademark holders and are used only to directly describe the products being provided.

DISCLAIMER

MOBITEK makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose.

Furthermore, MOBITEK reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to notify any person of such revision or changes.

INTRODUCTION

MOBITEK^® SMS Engine – Enterprise Edition is a Windows Service that sends and receives SMS. It is the engine that powers MOBITEK^® MobiGATE™ SMS Gateway.

The MOBITEK^® SMS Engine – Enterprise Edition uses SQL Server database to store incoming SMS, and to check if there is any pending SMS to be send out.

System integrator and software developer do not need to write any code to build a SMS Gateway.

To send out SMS, insert record into “outbox” table.

To read incoming SMS, retrieve record from “inbox” table. to read SMS.

FEATURES

1. Running as Windows Service.
2. Supports both SMS and USSD.
3. Send and receive Chinsese SMS (unicode).
4. Concatenate multiple SMS, i.e. support sending SMS longer than 160 characters and joining them into 1 SMS.
5. MOBITEK^® SMS Engine – Enterprise Edition will always try to initialise connection with MOBITEK^® MobiGATE™ SMS Gateway e.g. If PC/server is rebooted, the engine service will automatically establish connection with SMS gateway .
6. Auto-reconnection with modem – if modem is disconnected from PC/server (for whatever reasons), and then re-connected at later stage, service will automatically establish connection with modem.
7. Uses Microsoft SQL Server, MySQL Server or Oracle Database to store incoming SMS, and to process outgoing SMS in database. Support both Windows and SQL authentication mode.
   • support for Oracle 11g requires separate license
8. Prevention of any lost of SMS:–
   1. During initialisation, if there are any database error, it will not send nor read SMS, therefore no message will be lost.
   2. Auto-reconnection with database server.
9. Sending of SMS in alphanumeric character (text) and in Chinese character (Unicode).
10. Intelligent SMS Sending Logic:-
    1. Scheduling of outgoing SMS – based on the date and time set in “datetime_schedule”
    2. Prioritisation of outgoing SMS – earliest “datetime_schedule” will be send out, and all “datetime_schedule = null” will be last to send out
    3. FIFO – if there is neither scheduling nor prioritization, then “FIFO” rule will be applied – SMS Engine will process the 1st record in the “outbox” table until the last record.
11. Configure the direction of individual modem:-
    1. 2 way send and read SMS;
    2. 1 way read SMS; or
    3. 1 way send SMS.
12. Scalable – support 1 or more MOBITEK^® MobiGATE™ SMS Gateway without any need to reinstall Engine.
13. Concurrency and Load balancing – all modems in MOBITEK^® MobiGATE™ SMS Gateway work together to broadcast message. It is NOT on “round-robin” basis.
14. Fail-over – if modem no.1 cannot send out the SMS, modem no. 2 will take over, and so on until modem no. 4.
15. Dynamic queue size – the Engine will dynamically allocate queue size, if more modems are successfully initialised then queue size will be increased.
16. Configurable maximum queue size – the maximum queue size can be changed, default minimum size is 64 SMS/records per modem.
17. Routing – sophisticated and intelligent routing logic that defines:-
    1. automatic routing;
    2. prefix routing – which modem to use for sending out SMS to designated prefix mobile number. Good for cost saving as SMS sent within the intra-network is cheaper than inter-network;
    3. manual routing – specify which modem to send out SMS manually.
18. Number of retries – can be configured. If SMS fails to be send, it will retry until the specified time.

LIMITATION

1. Sending of SMS in Chinese character with maximum of 70 characters length.
2. Does not support receiving concatenate or long SMS. Receiving of SMS is limited to 160 characters (ASCII) or 70 characters (Unicode) per record in the “inbox” table; if the total is exceeded then the incoming SMS will be stored in multiple records in the “inbox” table.

REQUIREMENT

1. MOBITEK^® MobiGATE™ SMS Gateway
2. System integrators and software developers must posses knowledge of:-
   1. SQL Database Administration for:-
      • Microsoft SQL Server, Microsoft SQL Server Enterprise Manager, Microsoft SQL Server Query Analyzer;
      • MySQL Database Server; or
      • Oracle Database Server
   2. Database programming:-
      • ODBC, ADO, ADO.net; and
      • SQL statement
   3. Windows Service Administration
3. SIM card(s)
4. Supported operating system:-
   1. Windows Server 2003 / 2008 / 2012 / 2016 Server 32-bit and 64-bit;
   2. Windows XP / Vista / 7 / 8 / 10 32-bit and 64-bit.
5. Microsoft .NET Framework Version 2.0
6. Microsoft .NET Framework Version 4.0 if using Oracle 11g
7. Supported SQL Database Server:-
   1. Microsoft SQL Server 2000 / 2003 / 2008 / 2012 / 2014 / 2016 / 2017 Enterprise Edition;
   2. Microsoft SQL Server Express Edition;
   3. MySQL version 4.1 and above with MySQL ODBC driver version 5.1 in Windows OS;
   4. MySQL version 4.1 and above with MySQL ODBC driver version 5.1 in Linux OS; or
   5. Oracle 11g (separate license required)

 SYSTEM ARCHITECTURE

INSTALLATION of SMS ENGINE ENTERPRISE EDITION

1. Optional, install Microsoft .NET Framework Version 2.0 (install it from the USB thumb drive)
2. Add a new database or use existing database.
3. Execute SQL script (in USB thumb drive) to add new tables to a new database or existing database.
4. The SQL script will generate 4 tables:
   1. inbox
   2. outbox
   3. modem_state
   4. retry_send

      Note:  please make sure you have back-up your database before executing SQL script. 

5. Install MOBITEK® SMS Engine — Enterprise Edition.
6. Go to the SMS Engine installation folder located at C:\Program Files (x86)\SMS Engine Enterprise Edition right-click on the folder and select “Properties”. Click on “Security” tab -> “Edit”.
   
7. Select “Users” and check for “Full Control”. Click “Apply”.
8. Copy the configuration file “config.xml” from USB thumb drive to the location (path) where the engine is installed, e.g. C:\Program Files (x86)\SMS Engine Enterprise Edition
9. Install Control Panel for SMS Engine from USB thumb drive and edit the “config.xml” with Control Panel (refer to the user guide).
10. The contents of config.xml is as follows:
    

    <SMSConfig> <RETRY_SEND>3</RETRY_SEND> <QUEUE_SIZE>16</QUEUE_SIZE> <ROUTING>P</ROUTING> <MODEM_LIST> <MODEM> <ID>1</ID> <PORT>41</PORT> <ENABLED>true</ENABLED> <MODE>B</MODE> <TARGET_PREFIX>*</TARGET_PREFIX> </MODEM> <MODEM> <ID>2</ID> <PORT>42</PORT> <ENABLED>true</ENABLED> <MODE>B</MODE> <TARGET_PREFIX>*</TARGET_PREFIX> </MODEM> <MODEM> <ID>3</ID> <PORT>43</PORT> <ENABLED>true</ENABLED> <MODE>B</MODE> <TARGET_PREFIX>*</TARGET_PREFIX> </MODEM> <MODEM> <ID>4</ID> <PORT>44</PORT> <ENABLED>true</ENABLED> <MODE>B</MODE> <TARGET_PREFIX>*</TARGET_PREFIX> </MODEM> </MODEM_LIST> <DATASOURCE> <DBTYPE>MySQL</DBTYPE> <SERVER>localhost</SERVER> <USERNAME>root</USERNAME> <PASSWORD>root</PASSWORD> <DATABASENAME>smseee6</DATABASENAME> <AUTHMODE>SQL</AUTHMODE> </DATASOURCE> </SMSConfig>

    This table explains the node in the “config.xml” file:

    NODE	VALUE	DESCRIPTION
    <RETRY_SEND>	A number, starting from 0 <RETRY_SEND>0</RETRY_SEND> = no retry <RETRY_SEND>3</RETRY_SEND> = retry 3 times	Enter the number of retry in the event if SMS cannot be sent. The total number of sending is 1 + number of retry. This is a global setting that will affect all modems.
    <QUEUE_SIZE> Note: this function has been deprecated will be removed in future version.	A number, default is 16. <QUEUE_SIZE>16</QUEUE_SIZE> = Engine will select 16 records from “outbox” table Minimum is 16. Maximum is unlimited	Maximum number of records that the Engine will select from the “outbox” table. The larger the queue size, the lesser connection/query is made to the SQL Database.
    <ROUTING>	Value can be “A”, “P” or “M”. <ROUTING>A</ROUTING> = automatic routing and load balancing <ROUTING>P</ROUTING> = routing by pre-fix based on value in <TARGET_PREFIX> <ROUTING>M</ROUTING> = manual routing based on value in the outbox.target_modem	To set the routing mode. This is a global setting that will affect all modems.
    <MODEM>	N/A	Setting for each modem. If there are 8 modems in MobiGATE, then there must be 8 <MODEM> nodes. If there are 4 modems, then there must be 4 <MODEM> nodes.
    <ID>	A number starting from 1. <ID>1</ID> = this modem’s ID or number is 1 <ID>2</ID> = this modem’s ID or number is 2	ID of modem or modem number. Depending on the model of MobiGATE, the range of ID can be from 1 to 4 or 1 to 8.
    <PORT>	A number, starting from 1 <PORT>9</PORT> = this modem is connected to COM port number 9	COM port of which the modem is connected. Please refer to “Device Manager > Ports” to find out the COM port numbers.
    <ENABLED>	Value is either “True” or “False”. <ENABLED>True</ENABLED> = modem is enabled <ENABLED>False</ENABLED> = modem is disabled, neither SMS will be send nor read on this modem	To enable or disable a modem. Engine will need to be restarted to take effect.
    <MODE>	Value can be “B”, “R” or “S”. <MODE>B</MODE> = bi-directional, modem will read and send SMS <MODE>R</MODE> = one way read SMS only <MODE>S</MODE> = one way send SMS only	To set the direction mode of modem.
    <TARGET_PREFIX>	A number List of numbers, separated by comma blank “*” wild card <TARGET_PREFIX>016</TARGET_PREFIX> = this modem will only send out SMS to mobile numbers with 016 prefix <TARGET_PREFIX>017,012</TARGET_PREFIX> = this modem will only send out SMS to numbers with 017 and 012 prefix <TARGET_PREFIX></TARGET_PREFIX> = this modem will NOT send out any SMS <TARGET_PREFIX>*</TARGET_PREFIX> = this modem will send SMS to any mobile numbers	To configure the prefix rule, modem will only send out SMS if prefix rule is matched. The routing must be set to <ROUTING>P</ROUTING> in order for the target prefix to work, else it will be ignored
    <MODEM> <ID>1</ID> <PORT>41</PORT> <ENABLED>true</ENABLED> <MODE>B</MODE> <TARGET_PREFIX>17,012</TARGET_PREFIX> </MODEM>	N/A	Modem ID 1 is connected to COM port number 41. It is enabled, and the mode is send and read SMS. It will only send SMS to numbers with 017 and 012 prefix.
    <DATASOURCE>	N/A	Settings for SQL Database Server
    <DBTYPE>	“MYSQL” or “MSSQL” <DBTYPE>MYSQL</DBTYPE> = Database server is MySQL <DBTYPE>MSSQL</DBTYPE> = Database server is MS SQL	To set which type of database server is used.
    <SERVER>	“IP address” or “name of server” <SERVER>192.168.1.66</SERVER> = IP address of the database server <SERVER>localhost</SERVER> = database server is on local server <SERVER>127.0.0.1SQLEXPRESS </SERVER> = IP address of MS SQL Express database server Note: for MS SQL Express Edition, add a suffix – “SQLEXPRESS” , e.g. 127.0.0.1SQLEXPRESS	To set the IP address or name of database server.
    <USERNAME>	<USERNAME>root</USERNAME> = user name is “root”; default for MySQL <USERNAME>sa</USERNAME> = user name is “sa”; default for MS SQL	To set the user name of the login account of the database server
    <PASSWORD>	<PASSWORD>root</PASSWORD> = password is “root”; default for MySQL <PASSWORD>sa</PASSWORD> = password is “sa”; default for MS SQL	To set the password of the login account of the database server
    <DATABASENAME>	Alpanumeric. <DATABASENAME>smseee6</DATABASENAME> = name of the database used is “smseee6”	To set the database name used.
    <AUTHMODE>	Value can be “SQL”, “WIN” or blank <AUTHMODE>SQL</AUTHMODE> = MS SQL Server will use SQL authentication mode <AUTHMODE>WIN</AUTHMODE> = MS SQL Server will use Windows authentication mode <AUTHMODE></AUTHMODE> = leave blank if using MySQL Database Server	To set the authentication mode, only applies for MS SQL Database Server. For MySQL, leave it blank.

11. Make sure MOBITEK® MobiGATE^TM is powered on and each modem’s blue LED is blinking:-
    
12. Make sure VCOM is running:-
    
13. Start the Engine (Windows service) via Control Panel:-
    
14. In Control Panel for SMS Engine, open log file to see if service is successfully started:-
    

OUTBOX TABLE – SEND SMS & USSD COMMAND

By default, SMS Engine send out SMS based on the ascending order of the “msg_id”. That is “msg_id = 1” will be send out first then “msg_id = 2”.

1. To send USSD command, the SQL statement is:-
   Insert into Outbox (message, destination, msg_type, target_modem) values ('*122#', '', 'D', '2');
   Note: for USSD to work, the routing must be set to “M” <ROUTING>M</ROUTING>
2. To send out SMS in text mode, the SQL statement is:-
   Insert into Outbox (message, destination) values ('Hello!', '+60172233111');
3. To send out SMS having Chinese character, the SQL statement is:-
   Insert into Outbox (message, destination, msg_type) values ('你好', '+60172233111', 'U');
4. To send out SMS by manual routing via modem ID 4 (provided that <ROUTING>M</ROUTING> is set), the SQL statement is:-
   Insert into Outbox (message, destination, target_modem) values ('Hello!', '+60172233111', '4');
5. To schedule a SMS to be send out at a predetermined date, the SQL statement is:-
   Insert into Outbox (message, destination, datetime_schedule) VALUES ('Happy New Year!', '+60176096718', '2020-01-01 00:01:00');

INBOX TABLE – READ SMS & USSD REPLY

SQL Statement:

• To read all new SMS

Select * from Inbox where read_status = 'N'

• To change the status of new SMS to “read”

Update Inbox Set read_status = 'Read' Where Status = 'N'

or

Update Inbox Set read_status = 'Read' Where msg_id = 'ID of the message that SI/SD is processing'

RETRY SEND TABLE

This table is used for logging number of retries for a message.

For example, if a record with ID “118” has this value:-

It means – modem with ID number 1 had retried 3 times to send out the message having ID “A3210”.

CHECK LIST

These are import factors to ensure SMS Engine operates smoothly:

1. VCOM has started and running
2. SMS Engine Windows Service has started and running

FREQUENTLY ASKED QUESTIONS

Please refer to https://mobitek-system.com/blog/category/sms/sms-gateway/

REQUEST FOR SUPPORT

Please write to support@mobitek.my with:

1. company name
2. invoice number (located at back of modem)
3. description of problem
4. attach screen capture of VCOM showing all COM ports and its IP address
5. attach log file (located at C:Program Files (x86)SMS Engine Enterprise Editionlog)
6. attach “config.xml” file

APPENDIX 1: HOW TO SET-UP MS SQL SERVER EXPRESS

1. Install Microsoft SQL Server 2008 R2, you can get it from Microsoft official site.
2. Run Microsoft SQL Server Management Studio.
3. On the first run, “Connect to Server” will pop-up
   

   1. Choose:-

      • Server type : Database Engine
        
      • Server name: <browse for more → local server → database engine →your pc name >
        
      • Authentication : Windows Authentication
        

      • Press connect.

4. On “object explorer” → right click on databases → create new database.
   
   
   
5. Give it a name “smseee” and press OK
6. On “object explorer” → right click on your new created database → New Query
   
   
7. <plang=”en-US”>Copy and paste the sql command from “mssql.sql”

• Execute the command

9. The database is set up, in case you want to know about the detail of you database for further use in MOBITEK^® SMS Engine (Enterprise Edition), right click on your database → properties
   
   
10. In “config.xml” file, edit as follows:-
    <DATASOURCE>
    <DBTYPE>MSSQL</DBTYPE>
    <SERVER>DELL-D630SQLEXPRESS</SERVER>
    <USERNAME>abc</USERNAME>
    <PASSWORD>abc</PASSWORD>
    <DATABASENAME>smseee5</DATABASENAME>
    <AUTHMODE>WIN</AUTHMODE>
    </DATASOURCE>

APPENDIX 2: HOW TO SET-UP MySQL DATABASE

1. Run the “WampServer64” to install Apache, MySQL Database and PHP.

2. After successful installation, at the taskbar, click “Start All Services”.

3. Click “Localhost”.

4. Your localhost should be opened at the browser like below. Click at the “phpmyadmin”.
   

5. You will be directed to “localhost/phpmyadmin”. Click “New” on the left side.
   

6. Enter the nameas “smseee6” then click “Create”.
   

7. Click the “smsee6”.
   

8. Click at the ‘SQL’ one you are directed like below.
   

9. Go to your folder and open up your mysql-smsee6. Right click and click edit with “Notepad++” or “Notepad”.
   

10. Select all and copy the SQL script.
    

11. Go back to your “phpmyadmin” page. Right click and paste it at “Run SQL query/queries on database smseee6”. Then click “Go” button.
    

12. If successful, it will display the following result.:
    

13. There you can see 4 tables inside your database which are “inbox”, “modem_state”, “outbox” and “retry_send”.