MOBITEK STK API version 6 — Manual for Software Developer


RELEASE NOTE

VERSION 6.6

  • Released on 15-Dec-2020.
  • New function USSD.Cancel() added.

 

VERSION 6.5

  • To debug “OK” in SMS class.
  • To remove unnecessary logging.

 

VERSION 6.4

To debug “OK” in STK.InputSubmit()

  • The menu is not submitting when it get to the end of the flow. On Android, the menus shows a message saying “sending…”, which stays on for few seconds, before presenting a confirmation box with “Ok” and “Cancel” buttons.
  • The menu fails to submit any value which starts with “Ok”. Some customers have names (first name, last name) starting with “Ok”. Example “Okie”.

 

VERSION 6.3

Bug: consecutively calling SendSMSText() will result failure, “False” value is returned due to “Response: none due to time out”. But in fact, SMS has been actually send out, therefore may result duplicate SMS sent out.

  • Bug fixed in SendSMSText() by waiting longer for 60 seconds.

Log file “MOBITEK STK API Log” is automatically created in “system32” folder

 

VERSION 6.2

Supports Java (via JACOB) by converting arguments into properties.

  • Replace “Public Function MainMenuDisplay(MainMenuName As String, MainMenuList As String) As Boolean” with “Public Function MainMenuDisplay() As Boolean”
    • the arguments are converted into properties
      • MainMenuName
      • MainMenuList
  • Replace “Public Function SubMenuDisplay(SubMenuName As String, SubMenuList As String) As Boolean” with “Public Function SubMenuDisplay() As Boolean
    • the arguments are converted into properties
      • SubMenuName
      • SubMenuList

 

VERSION 6.1

Supports GL6100

 

VERSION 6.0

USSD class upgraded, based on version 9

  • New function – USSDListen()

 

VERSION 5.0

  • New class “Modem” added
  • Class “SMS” upgraded

 

VERSION 4.0

  • This version only works with STK modem Type Q24-STK4.
  • STK API version 4 is similar to version 2, so you can re-use your process flow from version 2.
  • There are no new methods nor properties, so there is no need to re-write your code when upgrading from version 2.3 and 3.x.

 

VERSION 3.1

  • This version only works with STK modem – Wavecom Fastrack Supreme 10, Type S10-STK3. Other types of STK modem will not work.
  • Method ‘MainMenuSelect()’  improved. Previously all 1st try will get “MainMenuSelect() = False”.

 

VERSION 3.0

  • This version only works with STK modem – Wavecom Fastrack Supreme 10, Type S10-STK3. Other types of STK modem will not work.
  • There are no new method nor property in STK class.
  • Phonebook class added.
  • SMS class has a new method – “GetSignalStrength()”. Refer to the SMS API Manual for more information.
  • Method “MainMenuDisplay()” improved. Auto-reconfiguration of modem is only required when necessary. Wait for STK’s response then only display items in main menu.

 

VERSION 2.3

  • There are no new method nor property.
  • Better handling of Digi Flexi e-load that returns non-standard response.
  • Automatically re-configure the STK modem in order to send and receive SMS.
    • The response time to obtain “True” or “False” for the “MainMenuDisplay()” will be longer in version 2.3 than in 2.1 as the function will automatically re-configure the STK modem. However, the re-configuration process will occur once only.

 

UPGRADING FROM VERSION 4 TO 5

If you are upgrading from version 4 to 5, then you may need to re-write your code. The following table will guide you on methods or properties that has changed:

MOBITEK STK API version 6-06

 

REVISION HISTORY

EDITION ISSUED DATE REMARK

23rd

To restore missing section on “STK API METHODS”

22nd

6th of July 2016 Updated pictures that shows 64 bit OS environment; updated pictures that shows 64 bit OS environment; added “APPENDIX 4: How to set-up JACOB to work in 64 bit OS”; added “APPENDIX 5: Java Sample Code for version 6.5”
21st 13th of October 2015 “RELEASE NOTE” revised; reference to “MobitekSTKAPI5” has been updated to “MobitekSTK6.dll”; added “APPENDIX : How to Install JACOB in 64 bit OS”; Version 6.3 is released; Version 6.4 is released; Version 6.5 is released; added “Java Sample Code for version 6.4” in Appendix 2
20th 8th of August 2014 Version 6.1 is released; Version 6.2.1 is released; “RELEASE NOTE” revised; “APPENDIX 2: How to Use STK API in JAVA” added by Faez; “APPENDIX 3: How to Decode Alpha Field Displayed in STK Menu” added by Faez
19th 19th of December 2013 “STK API FLOW CHART” amended

18th

12th of August 2013 Version 6.0 (beta) is released
17th 5th of April 2010 FAQ updated

16th

4th of December 2009 Version 5.0 released

15th

29th of July 2008 Minor addition to section of “warranty and support”

14th

6th of June 2008 Version 4.0 released

13th

3rd of April 2008 Version 3.1 released

12th

15th of March 2008 Version 3.0 released

11th

27th of February 2008 FAQ section added

10th

20th of December 2007 Version 2.3 released

9th

31st of October 2007 Version 2.1 released

8th

3rd of September 2007 Version 2.0 released

7th

30th of July 2007 Minor modification

6th

26th of November 2006 APPENDIX 1: Using COM Components from Visual Studio .Net Directly added

5th

27th of September 2006 Release version 1.4

4th

24th of July 2006 Remove SMS API from manual

3rd

15th of June 2006 Release version 1.3

2nd

8th of April 2006 Added SMSSentDisplay()

1st

1st of April 2006 Draft release

COPYRIGHT

© 2009-2016 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.

 

TRADEMARK

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 here of 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.

 

ACKNOWLEDGEMENT

We like to extend our appreciation to the following persons for their contribution in revising this manual:-

  1. Mr. Muhamad Faezudin bin Hairuddin, UNIVERSITY SAINS MALAYSIA
  2. Nur Shafiqah binti Muhamad Baharum, UNIVERSITI PERTAHANAN NASIONAL MALAYSIA

 

DEFINITION

  1. STK – SIM Tool Kit
  2. STK MODEM – a GSM modem that is certified to use STK API.
  3. SIM APPLICATION – an application that resides in the SIM card; usually the application is a “menu”. Example of SIM applications are top-up of prepaid account, mobile banking, information on demand, etc.
  4. SOFTWARE APPLICATION – a Windows programme residing in computer.
  5. SOFTWARE PROGRAMME – same meaning as “SOFTWARE APPLICATION”.

 

INTRODUCTION

API TYPE: ActiveX DLL component (Component Object Model) for Windows

ActiveX Name: MobitekSTK6.dll

Version: 6.5

The API contains 5 classes:

  1. Modem
  2. SIMToolKit
  3. SMS
  4. USSD
  5. Phonebook

Scope of Manual: This manual only covers the SIMToolKit class. For information on the Modem, SMS, USSD and Phonebook classes, please refer to the manual, “SMS API v9 Manual”.

Pre-requisite: System integrator, and software developer must posses programming skill, and knowledge in making reference to DLL file.

 

FEATURES

  1. Software developer can develop their own user interface or software application that can access and interact with the SIM application residing in the SIM card.
  2. Software application can obtain menu items from SIM application.
  3. Software application can select menu items.
  4. Software application can obtain response from SIM application.
  5. Software application can submit data to SIM application.
  6. Software application can instruct SIM application to send out a SMS.
  7. Software application can obtain status of SIM application.
  8. Software application can stop a session of SIM application.

 

SYSTEM REQUIREMENTS

Any programming language that can use ActiveX DLL or COM such as:

  1. Visual Basic
  2. Visual Basic .Net
  3. Visual C++
  4. Visual Studio .Net
  5. Cold Fusion
  6. Any programming language that can call MobitekSTK6.dll

Operating System: Windows 98, 2000, XP, Server 2003, Server 2008, Vista, 7, 32 and 64 bit.

 

BENEFITS

  1. To automate a top-up or reload process such as Maxis e-load, and Digi Flexi e-load.
  2. To integrate multi-level marketing system with SIM application.
  3. To integrate customer relationship management system with SIM application.
  4. To integrate e-commerce system with SIM application.

 

LIMITATIONS

  1. STK API cannot load any application into SIM card.
  2. STK API is not a development tool to develop SIM application.
  3. STK API cannot change, modify, edit, or delete the menu in the SIM.

 

OVERVIEW OF SOFTWARE ARCHITECTURE

MOBITEK STK API version 6-01

 

 

FLOW CHART

MOBITEK STK API version 6-02

 

INSTALLATION GUIDE

Run the “Setup.exe” to install “MobitekSTK6.dll” file. The dll file will be installed into “system32” folder”.

Before using the STK API (ActiveX), please go through the following check list:

  1. MOBITEK Q24 STK MODEM is properly set-up.
  2. Identify the COM port where the STK modem is connected.
  3. The IDE (VB6, VB.net, VC++, etc.) is properly configured to use the ActiveX (refer to your programming guide).

Below is a Visual Basic.NET example on how to configure to use the “MobitekSTK6.dll”:

Go to “Project > Add Reference > COM > MobitekSTK6> OK”

MOBITEK STK API version 6-03

MOBITEK STK API version 6-04

STK API METHODS

The 1st important step is to call method Modem.Init() and obtain a return value of “1”. This is to establish connection between server (PC) and STK modem. This method is contained in the “Modem” class.

The “SIMToolKit” class contains 12 methods:

 

CloseSTK() as Boolean

  • To close, cancel or stop a STK transaction. It does not terminate the STK session.
  • Return value is:

= TRUE if successfully ended

= FALSE if not

Tip: use this method when you want to cancel a reload transaction.

 

ActivateSTK() as Boolean

    • To turn on the SIM Tool Kit (STK). This is the 2nd important step after Modem.Init(). If you do not call this method, then all other methods will fail to work.
    • Return value is:

= TRUE if activated

= FALSE if not

Tip: call this method once only. You do not need to call this for every reload/top-up transaction.

 

DeactivateSTK() as Boolean

  • To terminate or exit the STK session. You must call this method before calling SendSMS() or ReadSMS(), otherwise you cannot send nor read SMS.
  • Call this method before using methods and properties in SMS, USSD, Phonebook classes.
  • You must terminate the STK session before you can send SMS, read SMS, issue USSD command, and access Phonebook.
  • Return value is:

= TRUE if successful

= FALSE if not

 

MainMenuDisplay (MainMenuName As String, MainMenuList As String) as Boolean

  • To get main menu from STK. If return value is true, then the following values are retrieved:
    • MainMenuName
    • MainMenuList
  • Call this function only if

    STKStatus = STKMainMenu

    or

    ActivateSTK() = True

 

MainMenuSelect(ByVal ItemSelect As Integer) As Boolean

  • To select an item in main menu of STK.
  • Return value is:

= True if successfully submitted.

= False if not.

 

SubMenuDisplay(SubMenuName As String, SubMenuList As String) As Boolean

  • To get sub menu from STK. If return value is true, then the following values are retrieved:
    • SubMenuName
    • SubMenuList
  • Call this function only if STKStatus = STKSubMenu

 

SubMenuSelect(ByVal ItemSelect As Integer) As Boolean

  • To select an item in sub menu of STK.
  • Return value is:

= True if successfully submitted.

= False if not

 

InputRequestDisplay() As String

  • To display the request by STK for user input.
  • Call this function only if STKStatus = STKRequestInput

 

InputSubmit(ByVal UserInputSubmit As String) As Boolean

  • To submit user input to STK. The input can be alphanumeric or “OK”.
  • Use this only after calling InputRequestDisplay().
  • Return value is:

= TRUE if the submission is successful.

= FALSE if not.

 

ResponseDisplay() As String

  • To display STK response after user has successfully submitted an input.
  • Call this function only if STKStatus = STKResponse

 

SMSSentDisplay() As String

  • To display the outgoing SMS sent by STK.
  • Call this function only if STKStatus = STKSMSSent

 

STKStatusGet() as STKStatus

  • To get the status of STK.
  • Return values is an integer representing status. The description of each status is as per STKStatus describe below:
    • STKMainMenu = 0 (STK has a main menu to show to user)
    • STKResponse = 1 (STK has a response to user’s input)
    • STKInputRequest = 3 (STK has a request to user for input)
    • STKSubMenu = 6 (STK has a sub menu to show to user)
    • STKSMSSent = 9 (STK has sent out a SMS)
    • STKTimeOut = 98 (STK time out)
    • STKSessionEnd = 99 (STK session ends)
    • STKUnknown = 100 (Unknown status)

 

STK API FLOW CHART

MOBITEK STK API version 6-05

 

USSD CLASS

Unstructured Supplementary Service Data (“USSD”) is a feature offered by GSM network. It allows data communication with the Network Operator (“CELCO”) in wireless mode. It is generally associated with real-time or instant messaging type phone services. There is no store-and-forward capability that is typical of ‘normal’ short messages (in other words, an SMSC is not present in the processing path). Response times for interactive USSD based services are generally quicker than those used for SMS.

USSD is typically used as a ‘trigger’ to invoke independent calling services which don’t require the overhead and additional usage costs of an SMSC, such as a callback service (e.g. cheaper phone charges while roaming), or interactive menuing service (e.g. stock quotes, sporting results).

USSD is a standard for transmitting information over GSM signalling channels. It is mostly used as a method to query the available balance and other similar information in pre-paid GSM services.

Example USSD command:

  • “*122#” – to check account balance of Hotlink
  • “*126#” – to check account balance of Digi Prepaid
  • “*124#” – to check account balance of XPax
  • “*111*<14 digit PIN>#” – to reload or top-up Hotlink
  • “*123*<16 digit PIN>#” – to reload or top-up Digi Prepaid

As a comparison, USSD is similar to telnet, while SMS is similar to mail.

USSD is instead session oriented, unlike SMS, which is a store-and-forward, transaction-oriented technology.

Users do not need to access any particular phone menu to access services with USSD- they can enter the Unstructured Supplementary Services Data (USSD) command direct from the initial mobile phone screen.

USSD commands are routed back to the home mobile network’s Home Location Register (HLR), allowing for the virtual home environment concept – the ability for services (based on USSD in this case) to work just as well and in exactly the same way when users are roaming.

In SMS API version 5 you are able to send USSD command to the CELCO, and obtain a response. Before you can use the USSD method, please refer to your IDE guide on setting up the USSD class.

Use USSD Class to develop the following applications or systems:

  1. Check Credit Balance – check the credit balance of prepaid account (Hotlink, Xpax, Digi Prepaid) without the need of removing the SIM card from modem.
  2. Reload Account – to reload or top-up prepaid account without the need of removing the SIM card from modem.

 

USSD

USSD.USSD (Command As String) As String

To submit a command via Unsturctured Supplementary Service Data, and get a response.

Arguments

  1. Command (string type) – the command. For example:
    • USSD(“*122#”) – to check account balance of Hotlink
    • USSD(“*126#”) – to check account balance of Digi Prepaid
    • USSD(“*124#”) – to check account balance of XPax
    • USSD(“*111*12345678901234#”) – to reload or top-up Hotlink
    • USSD(“*111*1234567890123456#”) – to reload or top-up Digi Prepaid

Return Value

  1. Empty string (if there is no response, or an error has occured); or
  2. A response from GSM network operator. For example, “Account Balance: RM45.65, top-up by 31.03.2007 to keep making calls/SMS”.

 

USSDListen

USSD.USSDListen (Optional ByVal iTimeOutSeconds As Integer = 3)

This function call will listen for USSD prompt from the network operator and capture it. While listening, no other functions are allowed to be called, it will stop upon time-out (default is 3 seconds).

If USSDListen() is not called, any USSD prompt is sent by network operator, then it will not be captured.

If USSDListen() is called after USSD prompt is sent by network operator, then it will not be captured.

Arguments

  • iTimeOutSeconds: how long to listen, default is 3 seconds

 

Cancel

USSD.Cancel() As Boolean

This function call will terminate the session of current USSD so that a new session can be established.

 

SAMPLE CODE

Please refer to the CD for VB sample code that uses STK API.

 

DEPLOYMENT

When you want to deploy your STK application on another PC, you need to run the set-up file (setup.exe) for MobitekSTK6.dll which is located in the CD folder.

 

SUPPORT

Support shall be in the form of e-mail support, and response time shall be within 3 working days. All e-mail must contain the following information:

  1. Company name
  2. Invoice number (can also be obtained from the white label located at the back of the modem)
  3. Description of problem and send it to support2010@mobitek.com.my

If the STK modem is not responsive (hang), please provide these information:-

  1. Based on what observation that you conclude the modem is not responsive.
  2. What did you do before it hangs?
  3. What function / method or property did you call before it hangs?
  4. What process was it working before it hangs?
  5. Does your software have log file? If so, please include it.

 

 

FAQ

Last updated on 4th of December, 2009.

Q: In the middle of my process, I want to reset/reboot the STK modem, what is the correct flow?

A: The recommended flow is – half way through your code > SIMToolKit.StopSTK() > SIMToolKit.DeactivateSTK() > Modem.Reboot() > Modem.Init() > SIMToolKit.ActivateSTK()

The wrong flow is – half way through your code > Modem.Init()

If you do so, most likely you will get “Modem.Init() = SIMError”

 

Q: Why do I receive a pop-up message – “Invalid GSM Modem connected!”?

A: You are using a STK modem that is not compatible with STK API. You must use STK modem supplied by MOBITEK System. Other types of modem do not work.

 

Q: Why do I get “SendSMS() = False” and “ReadSMS() = False” even though “Modem.Init() = 1”?

A: The correct flow is – Modem.Init() > code running STK process > SIMToolKit.DeactivateSTK() > SMS.SendSMS() or SMS.ReadSMS() > SIMToolKit.ActivateSTK() > code running STK process

The wrong flow is – Modem.Init() > code running STK process > SMS.SendSMS() or SMS.ReadSMS()

Ie. you must deactivate the STK session before sending or reading SMS, otherwise you will get “SMS.SendSMS() = False” or “SMS.ReadSMS() = False”

 

Q: Why do I always get a “Fail” whenever I call any methods or functions?

A: Because your computer’s processing speed is very, very much faster than SIM card’s processing speed, and also faster than the communication speed between STK modem and server of GSM network operator. Therefore, you software application runs faster than SIM application, and if it is too fast then your software application may jam the SIM application resulting “False” whenever you called a function.

Suggested solutions are:-

  •  Put a delay or wait in between calling of methods

e.g. MainMenuSelect() > Wait > MainMenuSelect() > Wait > STKStatusGet()

avoid – MainMenuSelect() > MainMenuSelect() > STKStatusGet()

  • Put a delay or wait between reload transaction

e.g. after you have completed a top-up for 1st customer > Wait > then process next customer

avoid – after you have completed a top-up for 1st customer > process next customer

 

Q: Why does the STK modem often hang (not responsive)?

A: Your software application may jam the STK modem. It can be caused by any one of these:-

  • 2 or more timers, each timer contains subroutine calling functions at the same time;
  • 2 or more events, each event contains subroutine calling functions at the same time;

  • 2 or more threads (asynchronous), each calling functions at the same time.

Suggested solution is to develop your software application in synchronous mode and in sequential mode.

 

Q: Can the STK API supports multiple STK modems?

A: Yes. Our STK API (ActiveX-COM) is multi-threaded. There are 2 methods:-

 

1st METHOD – multiple applications calling 1 ActiveX-COM

e.g. modem1.exe calls STKAPI.dll to control STK modem no. 1 modem2.exe calls STKAPI.dll to control STK modem no. 2,etc.

The code for modem1.exe is the same as the code in modem2.exe You do not need to rewrite your code. You use back the same code, except on the part where you specify the COM port number.

 

2nd METHOD – 1 application creating 1 thread for each STK modem; you need to use .Net Framework such as VB.Net or C# or C++.Net to develop a multi-threaded application.

e.g. modem.exe creates thread no. 1 that calls STKAPI.dll to control STK modem no. 1

modem.exe creates thread no. 2 that calls STKAPI.dll to control STK modem no. 2, etc.

 

APPENDIX 1: REFERRENCING COM IN .NET

The following article is from http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndotnet/html/callcomcomp.asp.It describes how you can call ActiveX COM from .Net:

As a .NET developer, you also have the option of using COM components directly. At least, that’s what it looks like, although you’re programmatic ally still using a RCW to get to objects in unmanaged code. If you’re working within a Visual Basic .NET project, you can follow these steps to add a reference to a COM component:

  1. Click Project, and then click Add Reference.
  2. In the Add Reference dialogue box, click the COM tab.
  3. Select the type library you wish to use from the list and click Select, or use the Browse button to locate a component that’s not listed. The selected components will be added to the lower listview in the dialogue box.
  4. Click OK to create RCWs for the selected type libraries in your Visual Basic .NET project.

When you do this, you’ll find that Visual Basic .NET actually creates a DLL in your project’s /Bin folder, with a name derived from the original COM component name. For example, if you reference BackEnd.dll version 2.0 in this manner, Visual Basic .NET will create the RCW in the file Interop.BackEnd_2_0.dll.

 

APPENDIX 2: HOW TO USE STK API IN JAVA

System Requirements

Install the following:-

  1. SMS/GSM Modem: follow the instruction in SMS Gateway Development CD to set-up the SMS/GSM modem.
  2. MOBITEKTM STK API version 6.2 : follow the instruction in CD to install.

  3. JRE: install JRE version 1.6 from the CD.
  4. JACOB: unzip the file “jacob-1.14.3.zip” that is in CD, then copy these 2 files to “system32” folder:
    • jacob-1.14.3-x64.dll
    • jacob-1.14.3-x86.dll
  5. ECLIPSE: install from CD; we choose ECLIPSE as the IDE for Java. You may use other IDE.

 

Set-up Eclipse

  1. Add a new project, select “Java Project”
  2. Click “Next”MOBITEK STK API version 6-08
  3. Type “STKAPIv6” in “Project Name:”
  4. Click “Next”MOBITEK STK API version 6-09 - Copy
  5. Go to “Libraries” tab
  6. Click on “Add External JARs” button
  7. Select the file “jacob.jar” (that was unzip from “jacob-1.14.3.zip”)
  8. The final outcome should be similar to figure right
  9. Click on “Finish” buttonMOBITEK STK API version 6-10 - Copy
  10. Add a new package, named it “STKAPIv6”
  11. Add a new class, named it “STKAPIv6Test.java”
  12. And your final outcome should be similar to figure below:MOBITEK STK API version 6-11
  13.  Copy the Java sample code (refer Below; also available in CD) and paste to “STKAPIv6Test.java””
  14. In the sample code, change the COM port to the respective COM port:
    • vMOBITEK = Modem.invoke(“Init”, 1);
  15. In the Java code, we already hardcoded a script just for the sake of testing the STK will function as below in Start() FunctionOpen STK Main MenuCall sub menu, 254 → EasyAccessCall sub menu, 1 → News & SportCall sub menu, 6 → News on DemandCall sub menu, 5 → SportCall sub menu, 1 → TennisSend SMS Out* This STK Menu is using Maxis Telco (Malaysia Telco)* Please change accordingly to your telco or try to only call STK Main Menu First.
  16. Click “Run” buttonMOBITEK STK API version 6-12
  17. And you will see the result in “Console” tab:
    • GSM modem is connected to computer.GSM modem is connected to GSM network.The operator of the GSM network is MY MAXIS.STK Activated : true=====EasyAccess255:My Hotlink254:News&Sports253:Hotlines252:Money251:Downloads250:At Play249:Going Places248:Community247:My Favourites
      >254 Selected!
      News&Sports1:News On Demand

      2:EasyAlerts
      >1 Selected!
      1:Breaking News

      2:General

      3:Business

      4:Technology

      5:Entertainment

      6:Sports
      >6 Selected!
      1:General

      2:F1

      3:Soccer

      4:Golf

      5:Tennis
      >5 Selected!
      1:Send

      2:Back
      >1 Selected!

      User has allowed STK to send out SMS

      =====

      STK Deactivated : true

      Connection between GSM modem and computer is closed.MOBITEK STK API version 6-13

  18. You have successfully used Java with MOBITEKTM STK API version 6.2 to:
    • Initiate Modem
    • Check the GSM operator name
    • Activate the STK
    • open and navigate through STK Menu
    • send out SMS;
    • Deactivate STK
    • Close the modem connection

 

Java Sample Code

 package STKAPIv6;

import com.jacob.activeX.*;

import com.jacob.com.*;

public class STKAPIv6Test {

static Variant vMOBITEK;

static boolean bMOBITEK;

static int iMOBITEK;

static String sMOBITEK;

static ActiveXComponent Modem = new ActiveXComponent (“MobitekSTK6.Modem”);

static ActiveXComponent STKAPI = new ActiveXComponent (“MobitekSTK6.SIMToolKit”);

public static void main(String[] args)

{

ModemInitialize();

ActivateSTK();

Start();

DeactivateSTK();

ModemDeinitialize();

System.exit(0);//<-force close

}

private static void ModemInitialize() {

vMOBITEK = Modem.invoke(“Init”, 1);

iMOBITEK = vMOBITEK.getInt();

switch (iMOBITEK)

{

case 0 : System.out.println(“GSM modem is NOT connected to computer!”); System.exit(0);

case 1 : System.out.println(“GSM modem is connected to computer.”); break;

case 2 : System.out.println(“GSM modem is NOT connected to computer because a PIN is required!”); System.exit(0);

case 3 : System.out.println(“GSM modem is NOT connected to computer because wrong PIN is entered!”); System.exit(0);

case 4 : System.out.println(“GSM modem is NOT connected to computer because SIM card is blocked by network operator!”); System.exit(0);

case 5 : System.out.println(“GSM modem is NOT connected to computer because SIM card has problem!”); System.exit(0);

}

vMOBITEK = Modem.invoke(“IsConnectToGSM”);

bMOBITEK = vMOBITEK.getBoolean();

if (bMOBITEK)

{

System.out.println(“GSM modem is connected to GSM network.”);

vMOBITEK = Modem.invoke(“OperatorName”);

sMOBITEK = vMOBITEK.getString();

System.out.println (“The operator of the GSM network is “ + sMOBITEK + “.”);

}

else

{

System.out.println(“GSM modem is NOT connected to GSM network!”);

System.exit(0);

}

}

private static void ActivateSTK() {

// TODO Auto-generated method stub

vMOBITEK = STKAPI.invoke(“ActivateSTK”);

System.out.println(“STK Activated : “ + vMOBITEK);

}

private static void Start() {

// TODO Auto-generated method stub

//SimToolKit Menu

System.out.println(“=====”);

//open main menu

CallMainMenu();

// Below are script please change accordingly or

// Comment it to call only main menu

MainMenuSel(254); // EasyAccess

CallSubMenu();

SubMenuSel(1); // News&sport

CallSubMenu();

SubMenuSel(6); // News On Demand

CallSubMenu();

SubMenuSel(5); // Sport

CallSubMenu();

SubMenuSel(1); // Tennis

// End of Script

AllowSendSMS();

System.out.println(“=====”);

}

private static void CallMainMenu() {

vMOBITEK = STKAPI.invoke(“MainMenuDisplay”);

bMOBITEK = vMOBITEK.getBoolean();

if(bMOBITEK==true)

{

String MMName = STKAPI.getPropertyAsString(“MainMenuName”);

//property “MSG” is the sender’s message

String MMList = STKAPI.getPropertyAsString(“MainMenuList”);

System.out.println(MMName+“\n”+MMList);

}

}

private static void MainMenuSel( int num) {

STKAPI.invoke(“MainMenuSelect”,num);

System.out.println(“\n>”+num + ” Selected! \n”);

}

private static void CallSubMenu() {

vMOBITEK = STKAPI.invoke(“SubMenuDisplay”);

bMOBITEK = vMOBITEK.getBoolean();

if(bMOBITEK==true)

{

String MMName2 = STKAPI.getPropertyAsString(“SubMenuName”);

//property “MSG” is the sender’s message

String MMList2 = STKAPI.getPropertyAsString(“SubMenuList”);

System.out.println(MMName2+“\n”+MMList2);

MMName2 = null;

MMList2 = null;

}

}

private static void SubMenuSel( int num) {

STKAPI.invoke(“SubMenuSelect”,num);

System.out.println(“\n>”+num + ” Selected! “);

}

private static void AllowSendSMS() {

vMOBITEK = STKAPI.invoke(“SMSSentDisplay”);

sMOBITEK = vMOBITEK.getString();

if( sMOBITEK == null)

System.out.println(sMOBITEK);

else

System.out.println(“User has allowed STK to send out SMS”);

}

private static void DeactivateSTK() {

// TODO Auto-generated method stub

vMOBITEK = STKAPI.invoke(“DeactivateSTK”);

System.out.println(“STK Deactivated : “ + vMOBITEK);

}

private static void ModemDeinitialize() {

// TODO Auto-generated method stub

//call API to close connection between GSM modem and computer, the return value of the API call is assigned to “SMSAPIReturnValue”

vMOBITEK = Modem.invoke(“ShutDown”);

//since the return value of “ModemClose” is a boolean, so extract the return value as a boolean and assign to “bSMS”

bMOBITEK = vMOBITEK.getBoolean();

if (bMOBITEK) System.out.println(“Connection between GSM modem and computer is closed.” );

else System.out.println(“Connection between GSM modem and computer CANNOT be closed!” );

}

}

 

APPENDIX 3: How to Decode Alpha Field Displayed in STK Menu

In countries where English is not the primary language, the STK Menu may display alphanumeric string instead of English text.

We provide VB.Net sample code to decode the alphanumeric string.The VB.Net Sample Code decodes the alphanumeric string into UCS2 and then decode the UCS2 to display the unicode characters.

The sample code is in the MOBITEK Air-Time Reload Development Kit CD.

Example, the alphanumeric string displayed by Orange STK Menu is “810E00C4E5F2EEE9E5F220F4F2E1EEF3AE “, the VB.Net sample code will decode it and convert to “Dernier trans.”. Refer image below.

MOBITEK STK API version 6-14

MOBITEK STK API version 6-15

APPENDIX 4: How to set-up JACOB to work in 64 bit OS

User must have JRE version 1.6 for Windows

SI/SD must know how to use JACOB version 1.14.3;

  1. Installing the JACOB
    • Unzip the file “jacob-1.14.3.zip” that is in CDMOBITEK STK API version 6-16
    • Copy these 2 files (compulsory both of them) to “SysWOW64” folder that is situated in the jacob-1.14.3:
      • jacob-1.14.3-x64.dll
      • jacob-1.14.3-x86.dll
    • It will be display in the “SysWOW64” folder
    • MOBITEK STK API version 6-17
  2. Working out on Eclipse
    • Add a new project, select “Java Project”
    • Make it “JavaSMS” in “Project Name:”
    • DONT USE THE DEFAULT “jre7” because this is not recommended and either the JRE or the compiler compliance level should be (stated on below screen captured) .MOBITEK STK API version 6-18
    • Please make sure to choose the right one in JRE part which is “Use an execution environment JRE”: JavaSE-1.6″ (Third row). Click Next
    • Go to “Libraries” tab
    • Click on “Add External JARs” button MOBITEK STK API version 6-19
    • Select the file “jacob.jar” (that was unzip from “jacob-1.14.3.zip”)MOBITEK STK API version 6-20
    • Click on “Finish” button
    • Add a new package, named it “javaSMS”
    • Add a new class, named it “javaSMSTest.java”
    • And your final outcome should be similar to figure below:MOBITEK STK API version 6-21

APPENDIX 5: Java Sample Code for version 6.5

package STK6point5;

import com.jacob.activeX.*;

import com.jacob.com.*;

public class STK6point5 {
//NKL: to declare variables

static Variant vMOBITEK;

static boolean bMOBITEK;

static int iMOBITEK;

static String sMOBITEK;

 

//NKL: to create objects

static ActiveXComponent Modem = new ActiveXComponent (“MobitekSTK6.Modem”);

static ActiveXComponent STKAPI = new ActiveXComponent (“MobitekSTK6.SIMToolKit”);

 

 

//NKL: main function will call/execute each these functions in sequence

public static void main(String[] args)

{

ModemInitialise();

ActivateSTK();

Start();

DeactivateSTK();

ModemShutDown();

System.exit(0);//NKL: code will stop

}
//NKL: to intialise the STK Modem

private static void ModemInitialise()

{

try

{

vMOBITEK = Modem.invoke(“Init”, 3); //NKL: please change the COM port number accordingly

iMOBITEK = vMOBITEK.getInt(); //NKL: to extract the return value in integer

switch (iMOBITEK)

{

case 0 : System.out.println(“STK Modem is NOT connected to computer!”); System.exit(0);

case 1 : System.out.println(“STK Modem is connected to computer.”); break;

case 2 : System.out.println(“STK Modem is NOT connected to computer because a PIN is required!”); System.exit(0);

case 3 : System.out.println(“STK Modem is NOT connected to computer because wrong PIN is entered!”); System.exit(0);

case 4 : System.out.println(“STK Modem is NOT connected to computer because SIM card is blocked by network operator!”); System.exit(0);

case 5 : System.out.println(“STK Modem is NOT connected to computer because SIM card has problem!”); System.exit(0);

}

}

catch (com.jacob.com.ComFailException e) //NKL: if there is error in calling “Init” then display error message here

{

System.out.println(“Fail to initialise the STK Modem!”);

System.exit(1);//I:(1) is used when some error occurred, can use different values for different kind of errors.

}

 

try

{

vMOBITEK = Modem.invoke(“IsConnectToGSM”); //NKL: to check if STK Modem is connected to GSM network or not

bMOBITEK = vMOBITEK.getBoolean(); //NKL: to extract the boolean value – “True” or “False”
if (bMOBITEK)

{

System.out.println(“STK Modem is connected to GSM network.”);

}

else

{

System.out.println(“STK Modem is NOT connected to GSM network.”);

}

}

catch(com.jacob.com.ComFailException e)//I:this exception is used as try catch method for this program

{

System.out.println(“STK Modem is failed connected to GSM network!”);

System.exit(1);

}

 

try

{

vMOBITEK = Modem.invoke(“OperatorName”);//I: to get the name of GSM network operator; it should display in strings (eg:MY MAXIS, U Mobile)

// print operator name here …

sMOBITEK = vMOBITEK.getString();

 

if (sMOBITEK != “”)

{

System.out.println (“The operator of the GSM network is ” + sMOBITEK + “.”);

}

else

{

System.out.println (“Operator name is unknown”);

}

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“Operator name is unknown”);

System.exit(1);

}

 

try

{

vMOBITEK = Modem.invoke(“GetIMSI”); //NKL: to get the unique ID of SIM card, for more information, refer to http://mobitek-system.com/blog/2015/10/how-do-you- locate-a-sim-card-in-mobitek-q24-stk-modem-hub/

sMOBITEK = vMOBITEK.getString();

System.out.println(“SIM IMSI: ” + vMOBITEK.getString());

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“IMSI is not available”);

System.exit(1);//I:The code will stop here if user use non dealer sim card

}

 

try

{

vMOBITEK = Modem.invoke(“GetMSISDN”); //NKL: to get the mobile number of the SIM card, sometime the infor is not stored inside the SIM

sMOBITEK = vMOBITEK.getString();

System.out.println(“SIM MSISDN: ” + vMOBITEK.getString());

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“MSISDN is not available”);

System.exit(1);

}

}
private static void ActivateSTK()

{

try

{

vMOBITEK = STKAPI.invoke(“ActivateSTK”); //I:This is the 2nd important step after Modem.Init() compulsory otehrwise other methods will fail to work.

System.out.println(“STK Activated : ” + vMOBITEK);

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“STK can’t be activated”);

System.exit(1);

}

}

 

private static void Start()

{

//SimToolKit Menu

System.out.println(“=====”);

//open main menu

CallMainMenu();

MainMenuSel(254); // EasyAccess
CallSubMenu();

SubMenuSel(1); // News&sport
CallSubMenu();

SubMenuSel(6); // News On Demand
CallSubMenu();

SubMenuSel(5); // Sport
CallSubMenu();

SubMenuSel(1); // Tennis
AllowSendSMS();

System.out.println(“=====”);

}
// = = = = = = = = = = = = = = = =
private static void CallMainMenu()

{

try

{

vMOBITEK = STKAPI.invoke(“MainMenuDisplay”); //I:To get main menu from STK

bMOBITEK = vMOBITEK.getBoolean(); //I:if return value is true, then the next values are retrieved

 

if(bMOBITEK==true)

{

String MMName = STKAPI.getPropertyAsString(“MainMenuName”);

//property “MSG” is the sender’s message

String MMList = STKAPI.getPropertyAsString(“MainMenuList”);

System.out.println(MMName+”\n”+MMList);

}

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“Main Menu can’t be called”);

System.exit(1);

}

}
private static void MainMenuSel( int num)

{

STKAPI.invoke(“MainMenuSelect”,num); //I:To select an item in main menu of STK.

System.out.println(“\n>”+num + ” Selected! \n”);

}

 

private static void CallSubMenu()

{

try

{

vMOBITEK = STKAPI.invoke(“SubMenuDisplay”); //I:To get sub menu from STK.

bMOBITEK = vMOBITEK.getBoolean(); //I: If return value is true, then the following values are retrieved

if(bMOBITEK==true)

{

String MMName2 = STKAPI.getPropertyAsString(“SubMenuName”);

//property “MSG” is the sender’s message

String MMList2 = STKAPI.getPropertyAsString(“SubMenuList”);

System.out.println(MMName2+”\n”+MMList2);

MMName2 = null;

MMList2 = null;

}

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“Sub Menu can’t be called”);

System.exit(1);

}

 

}

 

private static void SubMenuSel( int num)

{

try

{

STKAPI.invoke(“SubMenuSelect”,num); //I:To select an item in sub menu of STK.

System.out.println(“\n>”+num + ” Selected! “);

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“Sub Menu can’t be viewed”);

System.exit(1);

}

}

 

private static void AllowSendSMS()

{

try

{
vMOBITEK = STKAPI.invoke(“SMSSentDisplay”); //I:To display the outgoing SMS sent by STK.

sMOBITEK = vMOBITEK.getString();

 

if( sMOBITEK == null)

{

System.out.println(sMOBITEK);

}

else

 

System.out.println(“User has allowed STK to send out SMS”);

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“Sending SMS is not allowed”);

System.exit(1);

}

}

 

// = = = = = = = = = = = = = = = =

 

private static void DeactivateSTK()

{

try

{

vMOBITEK = STKAPI.invoke(“DeactivateSTK”); //I:To terminate or exit the STK session

System.out.println(“STK Deactivated : ” + vMOBITEK);

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“STK deactivation is denied”);

System.exit(1);

}

}

 

private static void ModemShutDown()

{

try

{

vMOBITEK = Modem.invoke(“ShutDown”); //I: to disconnect the GSM Modem

//since the return value of “ModemClose” is a boolean, so extract the return value as a boolean and assign to “bSMS”

bMOBITEK = vMOBITEK.getBoolean();

if (bMOBITEK)

{

System.out.println(“STK Modem is disconnected with PC/Server.” );

}

else

{

System.out.println(“Connection between STK Modem and PC/Server CANNOT be disconnected!” );

}

}

catch (com.jacob.com.ComFailException e)

{

System.out.println(“Status unknown”);

System.exit(1);

}
}

}

 

Output

STK Modem is connected to computer.

STK Modem is connected to GSM network.

The operator of the GSM network is MY MAXIS.

SIM IMSI: 502123335953655

SIM MSISDN: 0176096718

STK Activated : true

=====

EasyAccess

255:My Hotlink

254:News&Sports

253:Hotlines

252:Money

251:Downloads

250:At Play

249:Going Places

248:Community

247:My Favourites
>254 Selected!
News&Sports

1:News On Demand

2:EasyAlerts
>1 Selected!
>6 Selected!
1:Breaking News

2:General

3:Business

4:Technology

5:Entertainment

6:Sports
>5 Selected!
1:Send

2:Back
>1 Selected!

User has allowed STK to send out SMS

=====

STK Deactivated : true

STK Modem is disconnected with PC/Server.