Ady Wicaksono Daily Activities

Archive for February 9th, 2008

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:


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) {

	 * 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()) {

	 * 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));

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


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


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


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


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


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