Ady Wicaksono Daily Activities

Display Text using javacard on SIM card

with 13 comments

TS 31.111 define USIM Application Toolkit for SIMCard, one feature defined there
is proactive command. What’s is proactive command? Proactive command is
a mechanism whereby the UICC/SIM Card can initiate actions to be taken by the ME
(mobile equipment). These actions include:

– displaying text from the UICC to the ME;
– sending a short message;
– setting up a voice call to a number held by the UICC;
– setting up a data call to a number and bearer capabilities held by the UICC;
– sending a SS control or USSD string;
– playing tone in earpiece;
– initiating a dialogue with the user;
– USIM initialization request and notification of changes to EF(s);
– providing local information from the ME to the UICC;
– providing information about the additional card reader(s) (if class “a” is supported);
– managing timers running physically in the ME;
– running an AT command received from the UICC, and returning the result to the UICC
(if class “b” is supported);
– sending DTMF;
– requesting the ME to launch the browser corresponding to a URL. (if class “c” is supported);
– establishing and managing a bearer independent protocol (if class “e” is supported).

OK, I will start sharing some javacard application that do a display text proactive command
it will be our helloworld smartcard application🙂. Details of proactive command for
displaying text is defined like this:

This command instructs the ME to display a text message, and/or an icon. It allows the UICC to
define the priority of that message, and the text string format.

Two types of priority are defined:
– display normal priority text and/or icon on screen;
– display high priority text and/or icon on screen.

The text string can be in one of three formats:
– packed format in SMS default alphabet
– unpacked format in SMS default alphabet
– UCS2 alphabet format

NOTE: The text string may contain up to 240 bytes.

TLV (Type Length Value) format of Display Text is defined like this:

display-text-proactive-command.png

So how to implement it? Here it is:

package proactive_cmd;

/*
 * Imported packages
 */
import sim.toolkit.*;
import sim.access.*;
import javacard.framework.*;

public class display_text extends javacard.framework.Applet implements
		ToolkitInterface, ToolkitConstants {
	// Mandatory variables
	private SIMView gsmFile;
	private ToolkitRegistry reg;

	// Main Menu
	private byte idMenu1;
	private byte[] Menu1;

	/**
	 * Constructor of the applet
	 */
	public display_text() {
		// Get the GSM application reference
		gsmFile = SIMSystem.getTheSIMView();

		// Get the reference of the applet ToolkitRegistry object
		reg = ToolkitRegistry.getEntry();

		Menu1 = new byte[] {
				(byte) 'D', (byte) 'i', (byte) 's', (byte) 'p',
				(byte) 'l', (byte) 'a', (byte) 'y', (byte) ' ',
				(byte) 'T', (byte) 'e', (byte) 'x', (byte) 't' };
		// Define the applet Menu Entry
		idMenu1 = reg.initMenuEntry(Menu1, (short) 0, (short) Menu1.length,
				PRO_CMD_SELECT_ITEM, false, (byte) 0, (short) 0);
	}

	/**
	 * Method called by the JCRE at the installation of the applet
	 * @param bArray the byte array containing the AID bytes
	 * @param bOffset the start of AID bytes in bArray
	 * @param bLength the length of the AID bytes in bArray
	 */
	public static void install(byte[] bArray, short bOffset, byte bLength) {
		// Create the Java SIM toolkit applet
		display_text StkCommandsExampleApplet = new display_text();
		// Register this applet
		StkCommandsExampleApplet.register(bArray, (short) (bOffset + 1),
				(byte) bArray[bOffset]);
	}

	/**
	 * Method called by the SIM Toolkit Framework
	 * @param event the byte representation of the event triggered
	 */
	public void processToolkit(byte event) {
		EnvelopeHandler envHdlr = EnvelopeHandler.getTheHandler();

		// Manage the request following the MENU SELECTION event type
		if (event == EVENT_MENU_SELECTION) {
			// Get the selected item
			byte selectedItemId = envHdlr.getItemIdentifier();

			// Perform the required service following the Menu1 selected item
			if (selectedItemId == idMenu1) {
				menu1Action();
			}
		}
	}

	/**
	 * Method called by the JCRE, once selected
	 * @param apdu the incoming APDU object
	 */
	public void process(APDU apdu) {
		// ignore the applet select command dispached to the process
		if (selectingApplet()) {
			return;
		}
	}

	/**
	 * Manage the Menu1 selection
	 */
	private void menu1Action() {
		// Get the received envelope
		ProactiveHandler proHdlr = ProactiveHandler.getTheHandler();

		// Display the "Menu1" message text
		// Initialize the display text command
		proHdlr.initDisplayText((byte) 0x00, DCS_8_BIT_DATA, Menu1, (short) 0,
					(short) (Menu1.length));
		proHdlr.send();
		return;
	}
}

The bold font is the code to display text using proactive command. The result on my Nokia 3660 is like this:

display-text-proactive-command.jpg

If we try to trace the APDU, it will be like this

D0 18 81 03 01 21 00 82 02 81 02 8D 0D 04 44 69 73 70 6C 61 79 20 54 65 78 74

Details:

0xD0: this is proactive command tag
0x18 : length of these bytes “81 03 01 21 00 82 02 81 02 8D 0D 04 44 69 73 70 6C 61 79 20 54 65 78 74” which is 24 bytes
0x81: Command details tag, see picture below

command-details.png

0x03: length of value of command details tag “01 21 00”
0x01: command number
0x21 0x00: Display text (normal priority, clear message after a delay)
0x82: Device identities tag, see below

device-identities.png

0x02: Length of device identities values which is “81 02”
0x81: means source is UICC or SIMCard
0x02: means destination is display which is on mobile phone
0x8D: Text string tag, see picture below

text-string-tag.png

0x0D: length of text string tag value, which is “04 44 69 73 70 6C 61 79 20 54 65 78 74”
0x04: DCS or data coding scheme (defined in TS 23.038)
44 69 73 70 6C 61 79 20 54 65 78 74: hex representation of string “Display text”, use hex2string tools to convert from string to hex vice versa

Uh.. complicated.. yes telco stuff is complicated, that’s why it’s expensive hehehehe

Written by adywicaksono

February 9, 2008 at 3:20 pm

13 Responses

Subscribe to comments with RSS.

  1. I want to congratulate you for nice article you post; I interested in java card development and sms sending, I read a lot of specification but I’m very confused.
    I want to send some proactive command to the sim card via SMS message using smpp though a real SMSC, So How can I do that?
    CLIENT->smpp  SMSC -> ME -> SIM
    First I’m sending smpp packet SUBMIT_SM to the SMSC, UDH contains some text message to be displayed to the mobile. “44 69 73 70 6C 61 79 20 54 65 78 74” =Display text

    How and where I should create APDU?

    APDU: [CLASS][INS][P1][P2] [DATA]
    DATA: D0 18 81 03 01 21 00 82 02 81 02 8D 0D 04 [44 69 73 70 6C 61 79 20 54 65 78 74]

    Could you gave me at least some advices?

    Thanks in advance,
    Mihai

    Sebi

    March 20, 2008 at 8:07 am

  2. Hi,

    I came to your site by looking of ways to have the user communicate with the Javacard. The java process recommends using J2ME that communicates with the Javacrd via the SATSA API.

    The only problem is that this API is not widely supported by mobile phones manufacturers.

    I’m trying to make sense of what you are saying in this article. Your help will be very much appreciated.

    First you say this is USIM (USAT) specific. But why is this not possible with the good old STK?

    In your code, you use classes from sim.toolkit and sim.access. Where can i find these classes?

    Finally, do you think this should work with all GSM phones?

    Looking forward to hearing from you.

    Klaus.

    Klaus

    February 24, 2009 at 5:28 pm

  3. mas.. kalo accesing simcard menu gimana commandnya ?
    apa pake AT^SSTK ? penggunaanya bisa dikasih contoh ga ?

    terima kasih.

    herux

    March 23, 2009 at 7:52 am

  4. maksud saya yang bukan pake javacard !

    herux

    March 23, 2009 at 9:40 am

  5. Awesome….

    Girish Mahajan

    November 17, 2009 at 8:32 am

  6. Hi,
    I have problem related to my project. I have to write programe that will make it possible for my phone to get information about cellId(nokia 6300). I have to make usage of at commands as well as SAT(cause it is not possible to run at commands from j2me in my phone). Does anybody tell me how can I do this? I would be so thankfull…

    robert

    December 14, 2009 at 7:27 pm

  7. Another stupid question – I’m so poor at this topic…in which environment can I compile Java card application??

    robert

    December 14, 2009 at 8:01 pm

    • You are NOT, ‘poor’ in this topic. You know NOTHING in this topic. Buy a book.

      Idd Salim

      February 14, 2011 at 2:26 pm

  8. hi……….
    I have problem with my project(secure m-payment protocol simulation). I want sim card with java card support. Please tell me where to get such sim card AND what hardware is reqiured for developing sim card application?

    shruti

    September 11, 2010 at 2:24 pm

  9. mas .. gimana “Get IMEI” dan langsung IMEI tersebut send ke nomor hp mengunakan javacard.
    apakah display text ke dalam SIM Card,semudah kita insert phone book dalam Sim Card

    thnk’s

    hidayat

    October 8, 2010 at 10:04 am

  10. Hello there, is it possible to post a direct download link for sim package?

    Thank

    bunkdeath

    May 24, 2011 at 2:16 am

  11. Hello there,
    I have few question, hope I get answer for it.

    Which IDE are you using? Is it for free or we need to buy?
    I tried this same program in eclipse, I downloaded sim api form http://www.3gpp.org/ftp/Specs/archive/43_series/43.019
    while compiling I get error “error: export file toolkit.exp of package sim.toolkit not found.”
    But in the api, this export file is inside sim.toolkit.javacard package. Is that location correct? What should I do?

    Next question,

    the result you are displaying, is that from emulator? If so, where to get that? (If using specific IDE, does that come with the IDE?).

    bunkdeath

    May 27, 2011 at 5:46 pm

    • it’s not free tool. it’s from Gemalto

      adywicaksono

      May 28, 2011 at 5:52 am


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: