March 12, 2011 – An App for Periodically Vibrating A Phone with Java Micro Edition
Nowadays, people probably program for Android or iOS, but I don’t have a high-tech phone that runs Android or iOS or anything. I needed an app that would make my phone vibrate every few minutes. I often find myself falling into a food coma, so I’m hoping that a phone that vibrates periodically will help keep me awake. I figured this would be a good learning opportunity for me, so I didn’t bother looking very hard to see if an app for this already exists. I went through setting up my development environment, coding the MIDlet (what they call Java apps on phones) using the J2ME libraries, testing using the emulator and packaging the app for deployment. My code is also available for download.
Setting Up the Development Environment
To develop this app, I used Eclipse combined with a plugin called EclipseME. To test the app, I used the Sun Java Wireless Toolkit for CLDC. Also, in order to program anything in Java, one must also have the JDK.
Download and install the programs below to set up the development environment. There are quite a few things to install here, but most of it is just download and double-click, except for the stuff that has to do with EclipseME.
The JDK can downloaded here
- Eclipse IDE
Eclipse is a free IDE for different programming languages such as Java, C++ and PHP. It can be downloaded here
- Sun Java Wireless Toolkit
This program provides all the tools for debugging the program such as the phone emulator and also allows the programmer to package the app into a usable jar file for the phone. At the time of this writing, the version for this program is 2.5.2_01. The program can be downloaded here
This is a plugin for Eclipse that adds functionality for programming apps for mobile phones. For example, it allows the programmer to code, debug, and deploy with one piece of software rather than coding elsewhere and compiling with the Wireless Toolkit. The method to install it is to use the update manager within Eclipse. Detailed instructions here
After installation, I had to configure the virtual devices the program would use for debugging. Initially, there are no devices listed in the preferences and when I went to create a new Eclipse project, picking a device was required. The link below has instructions how to do this configuration. However, I made one slight change to it, which is the search directory. The Wireless Toolkit installed itself in “C:WTK2.5.2_01” rather than “C:Softwaretoolkitswtk22”.
Follow the link here for instructions how to set up the virtual devices.
Once all this is done, the actual programming can begin. The next thing to do is to create a new project.
Creating A New Project
To create a new project:
- Go to File > New > Project (not Java Project)
- Expand the heading J2ME
- Choose J2ME MIDlet Suite
- Click Next
- Type in a name and choose the directory that it will go in
- Choose the Sun Java Wireless Toolkit at where it says Group, in the Devices section
- Choose a device under where it says Device, but it doesn’t matter which one is picked unless the phone app depends on the different phone interface
This is where the device management step came in. Hopefully, the configuration was done earlier. If not, click here for instructions.
- Click Finish
The project is now created and we are not ready to begin writing code. But as an aside, below is a brief explanation of what MIDlets are.
What Is A MIDlet?
In short, a MIDlet is basically the app that runs on the phone. So when I’m talking about writing an app, I’m also talking about writing a MIDlet. The word app just sounds less technical.
All Java MIDlets use a class that extends the MIDlet class. So I made a class called WakeUpMIDlet that extended the MIDlet class. Also, the extended class, must define/override some of the methods that exist in the super class (MIDlet). These methods are:
These methods assist the MIDlet in transitioning to one of its three states, which are active, paused, and destroyed. The startApp method brings the MIDlet to the active state, while destroyApp takes the MIDlet to the destroyed state, and the pauseApp method will take the MIDlet to the paused state. When the MIDlet is created, the constructor for the class and startApp are called respectively. Click here for more information about MIDlets and J2ME in general.
Building the MIDlet
Here is where the actual coding for the vibrator app begins. I am also assuming that anybody reading this already knows the basics of programming Java. I will discuss the code I used to develop the MIDlet, but for those interested in the MIDlet equivalent of a “Hello World” program, click here.
About the App
Since I don’t want to slip into a food coma, I made this app to make the phone vibrate in regular intervals. These intervals can be set by the user. In terms of the GUI, there will be a text field for the user to input the interval time, and text to show the time until the next vibration. See the picture at the top of the post to see what the app will look like.
I used these imports in my program:
The first import is so that I can use the timer object in the program, which is for doing the countdown. The second is to be able to extend the MIDlet class since we must subclass it (see the section “What Is A MIDlet” for more information). The third import contains the GUI functionality for the MIDlets, which includes the text fields, buttons, etc.
Extending the MIDlet Class
In addition to extending the MIDlet class, the CommandListener interface must be implemented as well in order for buttons to work.
public class WakeUpMIDlet extends MIDlet implements CommandListener
The code could have been inferred from the description, but I put it up for completeness.
Class Variables and Constants
Below are the variables and constants that I defined in my class. What the variables are for is in the comments but a more detailed explanation will follow.
private static final int DEFAULT_INTERVAL = 5;
private static final int VIBRATE_DURATION = 800;
Form GUI = null;
Command cmdStart = null;
Command cmdExit = null;
TextField tfVibrateInterval = null;
StringItem strTimeToNext = null;
StringItem strTime = null;
Timer timer = null;
TimerTask timerTask = null;
int count = 0;
The first two constants are just there for me to control what the default value for the vibration interval should be and how many milliseconds to vibrate for. The rest are all GUI elements and the objects/variables for managing the countdown.
Form – acts as a container for all the GUI elements such as the buttons and text fields. Later on, I will add each GUI element to this object of the Form class.
Command – used for buttons that appear at the bottom of the window.
TextField – GUI element for the screen that displays text and has a box for users to type in
StringItem – GUI element for displaying text in the Form
Timer – provides a way to run code at fixed intervals
TimerTask – defines what code the timer will run
With these objects set to null, we can now define them in the constructor. For more information about the classes involved in building the GUI, click here or see the references for more information.
I use the constructor to create all the GUI elements I need and to set up the form
GUI = new Form("Wake Up!");
cmdStart = new Command("Start", Command.OK, 0);
cmdExit = new Command("Exit", Command.EXIT, 0);
timer = new Timer();
timerTask = new TimerCountdown();
tfVibrateInterval = new TextField("Vibrate Interval (min): ", String.valueOf(DEFAULT_INTERVAL), 5, TextField.NUMERIC);
strTimeToNext = new StringItem("Time Until Next Vibration ", null);
strTime = new StringItem("n0:00", null);
strTime.setFont(Font.getFont(Font.FACE_SYSTEM, Font.STYLE_BOLD, Font.SIZE_LARGE));
The constructor for the Form class takes one parameter, which is the name. This name gets displayed on the phone when the app is open on some phones.
The constructor for the Command class is the label that appears on the button, and what the purpose of the button is. There are a list of constants that go with this. Refer to the reference on the Command class for more information. The 0 at the end represents the priority of the button. The documentation has a really good explanation on what the priority represents.
The Timer and TimerTask objects are very straightforward as they don’t require any parameters in the constructor. However, the TimerTask object gets an object of its subclass. Subclassing the TimerTask class is required because that is where we put the code that runs at every timer interval.
The addCommand method adds the buttons to the form. In order to get button press events, we need to add a CommandListener (which is why we implemented the interface in the first place).
The next few lines are for defining what kind of text to display on the screen. The parameters there are quite straight forward except for the parameters for TextField. The first parameter for it is the text label, the second one is what appears in the input box, and the third one says what kind of data the input box accepts. By default, I set the timer to 5 minutes. Also, by setting the third parameter to TextField.NUMERIC, the program will check the input for me and make sure that the input was in fact all numbers. The documentation told me that the constant to use was TextField.NUMBER, but I think that is deprecated. The setLayout method is for just setting the GUI elements to the center of the screen.
The last three lines just tells the program to add these GUI elements to the screen. The elements will appear in the order that they’re written.
The startApp(), pauseApp(), and destroyApp() Methods
When the program starts and the constructor code finishes running, the startApp method is invoked. The code here is very easy. All it does is that tells the MIDlet what Form to use for the display.
public void startApp()
public void destroyApp(boolean unconditional)
public void pauseApp()
Each MIDlet contains its own “Display”, which is defined by the Display class. This object contains information on what form to display to the user. Although I never tried, it should be possible to switch between different Forms. For more information about the Display class, see the references.
The other two methods are empty because there is no code that I needed to have run while the program is in the paused and destroyed states. They appear because these methods must be overridden.
The commandAction() Method
This method is run when a button is pressed. This is where the commandListener comes in. When a command is invoked by the user, the commandListener will know what happened and call the commandAction method.
public void commandAction(Command c, Displayable s)
if (c == cmdExit)
else if (c == cmdStart)
if (Integer.parseInt(tfVibrateInterval.getString()) > 0)
count = Integer.parseInt(tfVibrateInterval.getString()) * 60;
timer.schedule(timerTask, 0, 1000);
When the method is invoked, the command object involved is passed to this method and we can use this to determine what to do for each button. Here I set up if statements to check that if the exit button is pressed, the program will terminate, and that if the start button is pressed, I should start the timer. More information about the timer code is below.
Once the program starts, the timer will activate. The value to countdown from is taken from the input box (see above code). In order to get the Timer to do its work, the schedule method must be called with three parameters. One is what task to perform at each interval, how many iterations of the timer to do, and how often to run the code. To set up the task, the TimerTask class must be extended.
private class TimerCountdown extends TimerTask
public final void run()
String minutes = "";
String seconds = "";
minutes = String.valueOf(count / 60);
if (count % 60 >= 10)
seconds = String.valueOf(count % 60);
seconds = "0" + String.valueOf(count % 60);
strTime.setLabel("n" + minutes + ":" + seconds);
if (count == 0)
count = Integer.parseInt(tfVibrateInterval.getString()) * 60;
I put this code inside the class I was working with, so I ended up with a class within a class. The extended class must override the run method. This method is what defines the code that runs at every timer interval. Here, I just put code to count down the time and to write on the screen how long until the next vibration will occur. Once the count reaches zero, the vibratePhone method will be called, the timer is reset. See the references for an example program that uses a timer.
Vibrating the Phone
The actual vibrate method is included in the Display class, I couldn’t put that code with the run method. I solved that problem by putting the code in a different method and calling it.
public void vibratePhone()
The vibrate duration is in milliseconds. By default, I have mine set to 800 ms and I did not set up a way for the user to change this while running the program. The reference discussing the Display class includes information about the vibrate method.
Once all the code is in place, press the run button. If the Wireless Toolkit and the devices were set up properly, the emulator should turn on. Play around with it. Once the countdown goes to zero, a buzzing sound will play to signal that the phone vibrated.
Packaging the App
Once everything works, we need to package the program so that it can be used on the phone and not just on the computer.
Editing the JAD file
When I first tried to install the program on my phone, my phone kept complaining about how it couldn’t read the files properly. It turns out I was missing a line in my JAD file. Open the JAD file for the app with a text editor. It is located in the root directory for the project. Add a new line somewhere in the file like below:
The this line provides a description on the program’s name, icon, and name of the class. I was missing this before, so the program refused to work. It also helps to modify the content of the other lines to show the author and what not. For more information see Reference 18.
This is the last step in the development of the application.
- Go to the Project Explorer
- Right click the project
- Expand the menu for J2ME
- Create Package
Once that is done, a JAR and JAD file will appear in the folder called “deployed” in the project directory. Copy these files to the phone and then execute them on the phone. The app should install and be runnable. There are lots of options for packaging the app like using Antenna, obfuscation, and signing, but I’m not cover those topics here. The references will have more information. This concludes the application development process for the Java Mobile Platform.
For this app, I registered a project on SourceForge.
Project Information: https://sourceforge.net/projects/periodicvibrate/
Here are a bunch of links that I used to gather information on how to do everything I talked about here.
 JDK Download Page
This is for those who don’t already have the JDK installed. People who already program Java should already have this installed.
 Eclipse Download Page
The site to download the free IDE for Java development
 Sun Java Wireless Toolkit Download Page
The site to download the Sun Java Wireless Toolkit
 EclipseME Installation Instructions
Has information on how to obtain, install, and set up EclipseME
 EclipseME Device Management
Provides instructions how to set up the emulation devices for the IDE so that the programmer can perform software testing
 Explanation of the J2ME and MIDlets
Provides an explanation of what MIDlets and J2ME are all about. The site is also a tutorial on programming using the J2ME.
 Wireless Development Tutorial
A tutorial on wireless development on the Java Mobile platform. It also includes instructions on setting up a development environment (different than mine), and a sample “Hello World” program.
 The CommandListener Interface
The documentation for the CommandListener Interface.
 MIDP GUI Programming
Has a good explanation of the classes involved in programming a GUI. It also explains a lot of other GUI elements that I didn’t use in my program.
 The Form Class
The documentation for the Form class.
 The Command Class
The documentation for the Command class.
 The TextField Class
The documentation for the TextField class.
 The StringItem Class
The documentation for the StringItem class.
 The Timer Class
The documentation for the Timer class.
 The TimerTask Class
The documentation for the TimerTask class.
 The Display Class
The documentation for the Display class.
 J2ME Timer MIDlet Example
Contains an example program for how to use timers in a MIDlet
 Wireless Application Programming: MIDP Programming and Packaging Basics
Contains information on how to package the application and how to edit the JAD file so that the program will work on the phone.
 Packaging Your MIDlet Suite
Contains information on how to package the MIDlet with various methods such as using Antenna, obfuscation, and how to sign the app.