Friday Jan 15, 2010

How to create a custom device

I've got a question how to create custom emulator skins several times. It can't be answered in a few words, a short tutorial with an example will be the best way of explanation. Skin800x480The zip bundle here contains an example of standard CLDC/MIDP device with a display of 800 x 480 pixels and a few buttons. Due to lack of creativity I call the device "Skin800x480" and I have to admit it looks quite ugly.  I will use it as a reference throughout this tutorial. You can use it as a base for your further customization. Before we get to a details I need to say a few words about the installation of the device.


It is fairly simple. You just need to unzip bundle into JMESDK 3.0 installation directory. (C:\\Program Files\\Java ME SDK 3.0 on windows or /Applications/ on MacOS) Restart of the device-manager is required.

Device definition and device instances

Files which you've just unzipped into JMESDK is a definition of a device. JMESDK installation directory contains only device definitions. Device definitions are during launch of the device-manager used to create device instances. After you have restarted the device-manager you can check that an instance of "Skin800x480" device has been really initialized. Have a look into your user home Library/Application Support/javame-sdk/3.0/work (MacOS) or Application Data/javame-sdk/3.0/work (windows). Device instances are identified by numbers from 1 to 6 (MacOS) or 1 to 11 (Windows). One more instance No. 7 or No.12 has been initialized by the device-manager after the "Skin800x480" installation. It's more less obvious what all files inside instance directories mean. I will let it up to you inspecting them and finding it out.

Test it

 Let's check that the installation has been successful now. Open command line and and call emulator to list properties of the new device. Usually you don't have to use -Xdevice switch but because the default device is "DefaultCldcPhone1" and not our "Skin800x480" you will have to specify always device name for every emulator command. Write:

emulator -Xquery -Xdevice:Skin800x480

Command will list profile and configuration of the device along with other properties like bootclasspath, screen width and height etc. It's time to start the device now, this time star it without an application. Write:

emulator -Xjam -Xdevice:Skin800x480

or with an application

emulator -Xdescriptor:../apps/Demos/dist/Demos.jad -Xdevice:Skin800x480

Use the device and you will see how buttons behave when pressed or when mouse goes over the button.

The device

JMESDK is highly customizable and lets you define new devices without touching a code. Flexibility is necessary since there is a big number of handsets out on the marked and they differ in many aspects. A display size or a color depth, controls, number and type of keyboards (midp, qwerty, sliding keyboard), number of displays (2 displays in case of clamshell phones),  hardware modules (GPS, battery level sensor, motion sensor), external memory card just to name a few of them. JMESDK can literally assemble a device from particular components to match as close as possible desired handset. Here is what we can use as a building blocks of our device:

  1. skin (a picture of the handset)
  2. display (number of displays, size, color depth)
  3. device states (open, closed)
  4. keyboards (keyboard layout and key codes mapping)
  5. JVM (runtime associated with a device)
  6. device properties (fonts, default locale, BT address, phone number, heap size, security domain and many more)
  7. hardware modules (GPS, accelerometer, sensors, memory card etc.) 

Making a device

Look into a zip file into devices/Skin800x480/conf. You need 3 skins (png bitmaps) of the device. 1st one displays device in "normal" state, 2nd in "highlighted" (how the button should look like when mouse goes over it) and 3rd one in "pressed" state (how button should change when it is pressed). In our case we have 4 buttons A,B,C,D and "joystick" in the middle with buttons Left, Right, Up, Down and Select.  Important part is the display. You have to ensure that the size of display fits perfectly 800x480 pixels. You will need to write down boundaries of each button and of the display as well.  We will use them later on in mapping of buttons and in dislpay setup.

Besides of 3 skin bitmaps mentioned above the folder contains a few other files:

  1. index.html, bg.jpg, skin-test-small.png - these files compose a device information page which appear in our small IDE when you double click a device in device selector.
  2. networkIndicatorOn.png - you need this if the device has a small light (network indicator) which blinks when there is a network traffic.
  3. modules file - devices are sharing some functionality across them. This file describes what support should be loaded for this device. Each row is a path to particular module. For example modules/emulator-cldc is generic cldc-hi runtime, skin/single-state-shared is a module common to all devices which have only single state, emulator/generic/ui/touch-screen-support is a module which enables touch screen support etc.
Display setup

We have bitmaps with a space for display ready. What we have to do now is just to place a screen buffer properly on the bitmap and set screen buffer size. We will do this in .bean files. These files are being read when device and its runtime starts. Each .bean file represents an object with given setters.

  • ScreenGraphics.bean::dimension is a setter for a width and height of a screen buffer. Proper value for our device is 800, 480
  • Screen.bean::position sets x,y location of screen buffer on a skin bitmap. In our case 21,21
  • NetworkIndicator.bean::bounds location and width of network inicator
  • NetworkIndicator.bean::image a name of network indicator png bitmap
Button mapping

Our simplified device has four-way joystick, select button in the middle and four soft buttons A, B, C, D. ButtonsMapping file is called default-state.xml. It defines one single state of the device. For example Clamshell phone has 2 states opened and closed and need 2 mapping files.

Here are parts of the file:

<device-state name="Default" defaultSkin="skin-test-normal.png" 

device-state references 3 skin bitmaps -- normal, highlighted, pressed and a network indicator object. You need to put correct bitmap names here.

<button activators="VK_F1" vmKeyCode="-6" 
x="259" y="509" width="88" height="22"/> 

Each button is defined by its bounds (x, y, width, height) a vmKeyCode (integer sent to the runtime when button was pressed) and activator (keyboard activator for this button are VK_\* constants, as defined in java KeyEvent class)

vmKeyCodes are defined as follows:

    UP           = -1,
    DOWN         = -2,
    LEFT         = -3,
    RIGHT        = -4,
    SELECT       = -5,
    SOFT1        = -6,
    SOFT2        = -7,
    CLEAR        = -8,
    SEND         = -10
    END          = -11
    POWER        = -12
    KEY_0 .. KEY_9, #, \*, etc = ASCII code of the character. 
                               (vmKeyCode for printable character
                                is its ASCII code)

We don't have a button with printable character on our device but here is an example for number '1'.

 <button activators="VK_1 VK_NUMPAD1" 
vmKeyCode="0x31" keyChar="1" 
x="36" y="493" width="76" height="31"/>

Device adapter

Here I will talk about files related to the device manager. Device manager recognizes any device when its corresponding device adapter is installed. For every device adapter, there is a corresponding .bean file in process/device-manager/device-adapter.  Among other things adapter references runtime which should be used with this device. In our case it is cldc-hi-fx runtime (cldc/midp runtime with built-in JavaFX extension).  Since there is no other option for a runtime, I won't go deeper into settings of runtime in the adapter. You will better leave adapter files untouched. Just copy all files to use them for your own device, do the search through all files and replace Skin800x480 with a name of your own device. Although one thing has left to be mentioned here. You can add as many device instances as you wish. We have 1instance for Skin800x480. Instance .bean file is in process/device-manager/device-adapter/Skin800x480/1.bean. But can be copied to 2.bean, just change the setter deviceName to for example Skin800x480_1.

The end

I think we are done with simple customization. Definitely there's much more options to setup like device states etc. I've mentioned them all above. We can get back to them later if somebody needs them. I hope this entry will help to everyone who wants to create his own skin. Don't forget to share with us any skin you would create ...

Saturday Dec 26, 2009

Use Mac AirPort to work with WinMobile handsets

As you probably know we ship Java ME SDK with cldc java runtime for Windows Mobile. You can deploy MIDlets onto Windows Mobile handset as easy as it was an emulator. Connecting a WinMobile handset from Java ME SDK is very straightforward using activesync on windows. It's really just a matter of plugging device and runing jvm on it.

Situation is different on Mac since there's no free activesync support. Fortunately most of WinMobile handsets come equipped with Wi-Fi and we can take advantage of Mac's AirPort networking. What we need is to create computer-to-computer network and let WinMobile handsets connect to the network. Only trick is to find out IP address of the handset. When you have the IP and you have started jvm let Java ME SDK look up the handset. Since it's recognized you can deploy MIDlet on it an also debug your applications right on the handset using Netbeans Mobility Pack. 

Before you start with this tutorial copy .cab file from Java ME SDK installation folder named "on-device" to your WinMobile handset and install it.

Create computer-to-computer network and give a name to it (in our example "MyNetwork").

On handset look into Settings->Conections->Wi-Fi and search for computer-to-computer networks and connect to network. After your handset is successfully connected to "MyNetwork" look at details of Wi-Fi adapter where you find assigned IP address. Just to be sure open terminal and try to ping the handset


if your handset is reachable you can continue in Java ME SDK. Launch JMESDK and look at Device Selector window where 2 new buttons have been added in version 3.0 for Mac. Look at the image below where the buttons are highlighted

The first one  opens a wizard which helps you to connect to handset. All you need is to specify IP address. When the jvm on handset responds to look up from JMESDK it is added under the device node "Other" as you can see on the image above. Second button  refreshes connection to handset. My htc diamond falls asleep after some time and when it is awake I need to refresh connection. Device registration can be made also from command line

device-address add ip

or on device-manager. Click on device manager icon  in status bar and choose manage device addresses.

Now with the handset connected you can deploy MIDlet on it. Just open one of the sample projects right click on CldcWinceEmu1 node and choose "Run Project".

Of course all of this you can do also without Mac AirPort simply over the Wi-Fi router if you have one available. About debugging on-device using Netbeans Mobility Pack I will write soon. I suppose after you're successfull with this setup you will figure out how to make it work for Netbeans MP as well.

Monday Dec 21, 2009

A Christmas present to all Mac users

Merry Christmas to everyone and especially to all Mac users. There's still few days remaining to Christmas but we are giving presents already. Thanks to great effort of software and quality engineering during last weeks we have managed to wrap up our Mac release before end of this year and make it public today. You can download Java ME SDK 3.0 for Mac OS and try out Java ME cldc/midp mobile development on Mac OS for the first time.

Java ME SDK 3.0 for Mac OS contains these key features:

CLDC/MIDP emulator supporting multitasking built upon CLDC 1.1 and MIDP 2.1.
  • Contains complete Mobile Service Architecture (MSA 1.1) stack except JSR234 - Advanced Multimedia Supplements
  • Mobile Sensor API (JSR 256)
  • XML API for Java ME (JSR 280)
  • Payment API (JSR 229)

On device deployment and debugging support

  • SDK comes with one-click solution for easy testing your apps right on the device.
  • Windows Mobile JVM is included in SDK

Integrated Lightweight UI Toolkit

  • LWUIT version 1.2 library and resources manager integrated into SDK makes development of rich UI easy

CPU profiling support

  • A built-in profiler lets you easily profile CLDC/MIDP applications. The profiler is based on the successful Netbeans profiler used in VisualVM, which is bundled with Java SE 6

New development environment based on Netbeans 6.7 platform

  • SDK leverages the successful Netbeans platform. A shared project system allows easy transition of your project to the rich, full-featured CLDC/MIDP development tool Netbeans Mobility Pack

JDK 1.5 and JDK 1.6 support

  • Both JDK are now supported although upgrade to 1.6 is recommended

Device search database

  • Technical specifications of thousands of mobile devices are now available through the database search tool.

Java FX Mobile emulator

  • The SDK includes the JavaFX Runtime version 1.2.1 and two default phone skins for JavaFX Mobile.
An important note for users of Early Access how to uninstall:
  1. stop all emulators and Java ME SDK IDE
  2. stop device-manager. If running on jdk 1.6 click on the icon   in status bar and chose Exit. If running on jdk 1.5 use ps aux | grep and kill the process
  3. remove Early Access rm -rf /Applications/
  4. remove working directory rm -rf /Users/<username>/Library/Application Support/javame-sdk

Merry Christmas and happy New Year

- Your Java ME SDK Team

Sunday Apr 26, 2009

Future Directions


Just a day after Java ME SDK 3.0 release we decided to have the first meeting about features for next Java ME SDK version. It was a nice sunny day in Prague and we were sitting on the grass in front of our building to get fresh ideas on the fresh air. We put together long list of enhancements and new features but we would also like to know your opinion. Do you miss some feature? Do you think something should be improved? Share your mind with us, we will very appreciate it.

From left to right: Radko, Martin, Tomas, Ondra, Lubo, Igor and Pavel behind the photo camera.

Wednesday Apr 08, 2009

Released: Java ME Platform SDK 3.0 now available

Java ME SDK team is happy to announce availability of Java ME Platform SDK 3.0.

Java ME SDK 3.0 is the successor to the popular Java Wireless Toolkit 2.5.2 and Java Toolkit 1.0 for CDC. It provides device emulation, a standalone development environment and a set of utilities for rapid development of Java ME applications.Users will get all-in-one for cldc/midp, cdc and BD-J development.

Among new features are:

  • on-device deployment and on-device debugging
  • CLDC runtime based on PhoneME Feature
  • optimized MSA 1.1
  • new development environment based on Netbeans platform
  • integrated profiler and network monitor
  • lightweight UI Toolkit (LWUIT) support
  • device database WURFL search tool
  • BD-J support
  • Windows Mobile Java VM included

Read more details on Java ME Platform SDK 3.0 page.

Submitt questions to other users in Java ME SDK forum.  


Java ME Platform SDK is a toolbox for developing mobile applications. Java ME SDK Download


« July 2016