Thales' cellular IoT products business is now part of Telit Cinterion, find out more.

You are here

Telit Cinterion IoT Developer Community

Hello World Application

Tutorial, January 14, 2014 - 5:43pm, 29766 views

Experience Level:
Basic

Motivation/Description
Learn how to create your first application on a Cinterion® M2M module.

Covered topics

  • Midlet structure: learn how to structure your Java application
  • Deploying  an application: how to build, install and run your Java application
  • Standard output: what to do if you want to see the output messages

Scenario

  • Create the JavaME project
  • Add new Midlet
  • Implement output messages
  • Build the application
  • Install  and run the application

Prerequisites

  • IDE (this tutorial uses Eclipse as an IDE)
  • Target Platform (EHS5, EHS6,  Concept Board)

 Actual Tutorial

Create JavaME project

Before implementing all the features of your JavaME application you need to prepare your workspace. You can find the basic information on how to install the IDE in the Gemalto Java Users Guide (Chapter 3). If you have already prepared the IDE you can start to deploy your very first application for the Gemalto Java Modules.

First you need to create a JavaME project inside your IDE. It will contain the structure for all the files required in the process of deploying the application. In the Gemalto Java Users Guide you can find  a step-by-step guide explaining in detail how to do this (Chapter 10).

So let’s create our new project. We will name it HelloWorld.

New project named HelloWorld

Now when we have the fundamental structure for the application ready, we can start creating all the code elements for it.

Add new MIDlet

The applications for the JavaME are often called midlets (because they are following the specification of the MIDP configuration). MIDlet is also the class name for the objects containing the entry point and the exit point of each application. We need to create such a class which will extend the MIDlet in our project. Right click the project root folder and select New->Java ME Midlet.

New Java ME MIDlet

Let’s call this midlet Main.java. It will indicate that it contains the main functionality (start & exit) of our application. Press Finish.

Source folder HelloWorld

The created class is automatically added to the application descriptor file, and will be used as an entry point for our demo. You can verify this by editing the project descriptor HelloWorld.jad in the project’s root folder. Just double click it and select the Application Descriptor tab.

It should look like this:

 MIDlet-Version: 1.0.0
MIDlet-Vendor: MIDlet Suite Vendor
MIDlet-Jar-URL: HelloWorld.jar
MicroEdition-Configuration: CLDC-1.1
MicroEdition-Profile: IMP-NG
MIDlet-1: MIDlet-1,,Main
MIDlet-Name: HelloWorld MIDlet Suite
 

Implement output

Now we are able to implement the methods which extend the MIDlet class inside the Main.java class.  They are startApp, destroyApp and pauseApp.

startApp

Is an entry point of the application. All the methods initiating the main activities should be invoked from here

destroyApp

Is an exit point of the application. All the methods which clears/releases the modules global resources should be invoked from here.
At the end, the method should always invoke the notifyDestroy() to confirm that all the final activities are done and the application can be closed.
The boolean parameter unconditional is used to indicate if the application exit may be rejected from inside the destroyApp method or not.

pauseApp

Not used in  GSM modules. It is invoked mainly in cell phones when some event (e.g. a voice call) interrupts the user’s activity. Then the application (e.g. a game) can temporary pause its processes.
 
We will fill the startApp and destroyApp methods with the proper output messages. We can  disregard  pauseApp since it is not used in  GSM modules.

 import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

public class HelloWorld extends MIDlet {

	public HelloWorld() {
		// Default constructor
	}

	protected void destroyApp(boolean unconditional) throws MIDletStateChangeException {
		// this method should always be the exit point of the application
		// if any resources need to be released, the released methods should be
		// invoked here
		System.out.println("destroyApp()");

		// this method informes Java Virtual Machine that all users activities
		// were done, and the app may be closed; this method should be infoked
		// only from this place
		notifyDestroyed();
	}

	protected void pauseApp() {
		// this method is not used in the M2M applications

	}

	protected void startApp() throws MIDletStateChangeException {

		// the system out works like in Java SE, providing access to one of
		// available outputs (ASC0, ASC1 or USB)
		System.out.println("startApp()");

		// custom code should be put here
		// this part may just invoke some actions and quit JVM or start some
		// threads and exit without terminating, so the living threads will
		// still processing

		// this invokation is optional and may be invoked from any place in the
		// code
		// it should be used as an ony exit point of the application
		destroyApp(true);
	}
}
 

Finally we have the main class ready.  With this we can build the application and run it on the module. To do so, we need to deploy it first.

Build the application

To deploy the application just go back to the application descriptor (HelloWorld.java in the root folder of the project & double click). This time select the Overview tab. You will find the Create package button, left-click on it.

Overview tab

Create MIDlet package

Make sure the Use deployment directory option is checked. If you press the Finish button now, it will build the application and put the deployed files inside the project folder in deployed/ IMP_NG_EHS5.

You should see two files created: HelloWorld.jad and HelloWorld.jar.

The jar file is quite the same as in standard Java applications. It contains all the classes and the manifest file. The manifest is a file which stores the information about the Java application (e.g. version number etc.)

The jad file is specific for the JavaME. It does not contain any code. It is simply a text file. The data inside is quite the same as in the project descriptor, e.g. containing the midlet which will be used as a start point of the application. The jad file also contains the cryptographic information when the application is signed.

jad file

Installing  and running it

Now when you have both jar and jad files you may copy them to the Flash File System of the module (we call it FFS). To do this we use MES – the Module Exchange Suite. MES is installed automatically during the installation process of the Gemalto Installation CD. You should see its icon in the MyComputer view. It will allow you to use the module´s FFS like the system drive.

MyComputer view

To use it you need to have the module connected to the PC. Check the COM port number to which it is connected. Also make sure that no other application is using it. In addition you can check if the module responds to the AT commands on this port (just to be sure that the connection is working).

You need to configure the MES now. Just right click on the icon and select Properties. You will see the list of available ports. Select the one, to which the module is connected and press OK.

Now you can double click on the MES icon. You should see the a:/ drive. This is the local drive on the FFS of the module.

Module view

Just double click it. You can copy your jar/jad files here. After that your app will be ready for the installation.

To install your application on the module start the terminal application and send the following AT command:

 AT^SJAM=0,"a:/HelloWorld.jad","" 

‘0’ means that this is an installation. Next is the path to your application on the modules FFS. The last one is the password, used to secure the application from unauthorized start,stop or replace. Like in case of all other commands, the module should respond with the OK if the command was properly executed. You can find the detailed description of each AT command  in the module´s AT command specification.

When the application is installed the module does not need its jar/jad file any more. You can remove them to save the place on the FFS.

Before you start the application one further step is needed. Since the module has three types of  serial interfaces, we need to decide on which the Java standard output will will be executed.

They are ASC0, ASC1 and the USB. You should select the interface which is available on your device and on which you can communicate with the module using the terminal application. To establish which of the interfaces you are currently connected to, you should refer to the hardware documentation of the device on which you are using the module. Below you can see location of serial interfaces on the Cinterion® Concept Board.

Cinterion Concept Board

Let’s assume you want to use the ASC0. To set up the Java output on this terminal you need to send  (via some other serial interface e.g. USB):

 AT^SCFG="Userware/Stdout","ASC0" 

This is a  configuration command. The first parameter of this command is always the name of the feature to configure. In case of this feature, the second parameter is the interface which can be ASC0, ASC1, USB and a few others.

After switching the system out to the ASC0 you should be able to see the following message on this interface.

 SYSTEM.OUT STARTED 

If the command returns with ERROR (or ERROR message) most probably you are trying to set it using the ASC0 interface. Keep in mind that you can’t switch on the system output on the same interface  which you are using to send the AT^SCFG command.

If the system out is redirected you may now start the application. To do so, you need to send the AT^SJAM command, but with the parameter ‘1’ instead of ‘0’.

 AT^SJAM=1,"a:/HelloWorld.jad","" 

The application will start.  You should receive the following output on the ASC0, as the result of your hard work:

 startApp() invoked

HelloWorld!

destroyApp() invoked 

Outlook: Suggested next steps (for further training)

So far you have learnt how to create JavaME applications on Gemalto Java Modules.

Now you can use data transmission, SMS exchange, GPIOs and many more features in your application. You may also try some other Gemalto M2M tutorials:

  • How to send SMSstext messages
  • How to receive text messages
  • How to use LED on the Concept Board
  • How to use buttons on the Concept Board
  • and many others…

Resources

Software:

  • Gemalto M2M Ehs5 Install CD

Documentation:

  • wm02_java_users_guide_v04.pdf
  • ehs5-e_atc_v01441.pdf

Code:

  • Hello World.java

Other:

  • HelloWorldEclipse.zip – Archive with the full eclipse project ready to be imported
  • HelloWorld.jad
  • HelloWorld.jar
Great!)

Only a wireless connection is a good connection!

Any plans on a tutorial on using the cellular modem ? Establishing a connecting to the internet. Performing an HTTP GET/POST, ... ?
Hi, a tutorial for basic usage of Internet Service has been published: https://iot-developer.thalesgroup.com/tutorial/concept-board-internet-se...
Great! Thank you! Though I know this is the very first and easiest application I could develop, for me it was not trivial that I had to connect the board using both the USB and the ASC0 interface. This is because once the terminal is configured as the SYSTEM.OUT, it will no longer accept AT commands. This way I configured the Stdout on the ASC0 terminal, and sent the "AT^SJAM=1,"a:/HelloWorld.jad",""" command through the USB terminal. This is getting so exciting and I hope I can contribute more. I want to share the way I connected the board and managed to run the HelloWorld MIDlet. http://imgur.com/Uwh1QUo

The board claims the support Arduino Shields without mentioning of which shield it supports. Does it support Arduino Ethernet Shield? 

Thanks million ***** in advance. 

xu's picture
xu

Hi,

I have a question about how to uninstall an application, since I have installed a MQTT client to the concept board before, and I don't need it anymore, but every time when I connect the board via ternimal, the message from that application is comeing that is really annoying when I want to test the other application. So any idea about how to remove an installed application or remove all installed application if it's easier? Thank you very much

Hi,

Yo can used the at^sjam command to stop the midlet if it is running and also the same comand to remove the Midlet from the FFS ( installed)

Take a look to the at^sjam command for mode details

Regards

ALopez

Somewhere over the rainbow!!! Looking for the Oz Land!!!

Hello,

I'm trying to use a BGS5 as a MQTT Client using libraries from PAHO, but It has a lot of trouble validating the external libraries, please tell me how did you manage to install the MQTT library on your project.

HI.

Is not possible to use "ASC0" for AT comands and for "stdout" at the same time as we do with TC65i?

Hello, I need to use ASC0 as a data Input, I'm using the Concept Board which would be the proper AT^SCFG to have access in the Java App to ASC0 and still receive System.out messages in another Virtual Serial Port?

I'm getting the following error "java.io.IOException: Opening port COM0 was failed\n"

Thanks in advance

Author

Mani Gemalto Moderator's picture
Mani Gemalto Moderator