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.

Installation

It is fairly simple. You just need to unzip Skin800x480.zip bundle into JMESDK 3.0 installation directory. (C:\\Program Files\\Java ME SDK 3.0 on windows or /Applications/Java_ME_SDK_3.0.app/Contents/Resources 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" 
pressedSkin="skin-test-pressed.png" 
highlightedSkin="skin-test-highlighted.png" 
networkIndicator="NetworkIndicator">

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 ...

Comments:

This is a good introduction to the new skin format. I am interested in further customization of the skin, such as running my own device firmware/classes and controlling cpu/memory. Do you have any more detailed guides on customizing skins for SDK 3.0?

Thanks,
J Marsh

Posted by J Marsh on February 11, 2010 at 06:30 AM PST #

There is possibility to create a new skin + device adapter + runtime. I need to prepare a tutorial since this is more advanced thing.
To get a feeling how it works look at our autoupdate server and install an example of PhoneME device. It contains skin + device adapter for cldc/midp opensource runtime http://phoneme.dev.java.net But you have to compile your runtime first!

Posted by Tomas Brandalik on February 15, 2010 at 05:02 AM PST #

That sounds exactly like what I want to do. If have time to create a tutorial, I would really appreciate it. In the mean time, I will look through the example you pointed to.

Thank you,
J Marsh

Posted by J Marsh on February 15, 2010 at 05:10 AM PST #

Also, do you know of a way to include a text box in the emulator window? This would be to simulate an input from device specific hardware. A button is pressed and the emulator reads the data in the text box and sends it to the runtime as if it came from hardware. Or is there another similar way to simulate custom hardware input?

Thanks for helping me,
J Marsh

Posted by J Marsh on February 16, 2010 at 07:20 AM PST #

One more question, I promise. Could you point me to the license document for the emulator? In other words, if I were to make a skin following this example and using your sample code above, would I be allowed to redistribute my skin or would that skin have to be for my internal use only?

Thank you,
J Marsh

Posted by J Marsh on February 22, 2010 at 08:41 AM PST #

Please, look at legal folder for license details. I suppose you may create your own custom skin and redistribute it.

Posted by Tomas Brandalik on February 23, 2010 at 04:07 PM PST #

Can you point me to the location of the documentation for doing this.

For example a document that explains all the files and the possible properties and range of values each property can take?

Posted by Jim on March 23, 2010 at 11:53 PM PDT #

I have tried modifying this so that it is a cdc pbp1.0 device, and it doesn't work. Really need more information on setting a skin up.

Posted by Jim on March 24, 2010 at 08:04 PM PDT #

When I run "emulator -Xquery -Xdevice:Skin800x480", I got:

\*\*\* Error \*\*\*
Device "Skin800x480" not registered!

Please help.

Thanks!

Jeffrey

Posted by Jeffrey on March 28, 2010 at 10:32 PM PDT #

Your example as well as a skin I created are both giving errors on execution of the emulator (however the regular skins work properly):

\*\*\* Error \*\*\*
Failed to connect to device 7!
Reason:
Emulator 7 terminated while waiting for it to register!

after poking around, I found the device.log under $HOME/Library/Application Support/javame-sdk/3.0/work/7 which provides the following information:

[ 1007] ERROR - oolkit.bootstrap.MainNamespace - java.lang.NullPointerException
java.lang.NullPointerException
at javax.swing.ImageIcon.<init>(ImageIcon.java:167)
at com.sun.jme.toolkit.propertyeditors.BufferedImageEditor.setAsText(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Batch.setValue(Unknown Source)
at com.sun.jme.toolkit.bootstrap.BasicObjectConfiguration.initializeField(Unknown Source)
at com.sun.jme.toolkit.bootstrap.BasicObjectConfiguration.initializeFields(Unknown Source)
at com.sun.jme.toolkit.bootstrap.ObjectConfiguration.initializeObject(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Batch.initializeObject(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Batch.initializeObjects(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Namespace.startBatch(Unknown Source)
at com.sun.jme.toolkit.bootstrap.MainNamespace.runModules(Unknown Source)
at com.sun.jme.toolkit.bootstrap.MainNamespace.run(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Container.run(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Container.main(Unknown Source)
[ 1009] INFO - un.jme.toolkit.bootstrap.Batch - Calling stop() methods...
[ 1009] INFO - un.jme.toolkit.bootstrap.Batch - Calling destroy() methods...
[ 1010] INFO - un.jme.toolkit.bootstrap.Batch - Objects stopped
[ 1010] FATAL - me.toolkit.bootstrap.Container - java.lang.NullPointerException
java.lang.NullPointerException
at com.sun.jme.toolkit.bootstrap.MainNamespace.runModules(Unknown Source)
at com.sun.jme.toolkit.bootstrap.MainNamespace.run(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Container.run(Unknown Source)
at com.sun.jme.toolkit.bootstrap.Container.main(Unknown Source)

Any ideas as to what might be wrong and how to fix it?

Thanks,
Marcus

Posted by Marcus on March 31, 2010 at 09:12 AM PDT #

ok that's interesting but I found it a little weird that there is no downloadable devices around the web do you know of any? I just need a device with a screen with with 480 px to work within eclipse pulsar to emulate a midlet. thanks

Posted by guest on May 23, 2011 at 07:02 PM PDT #

Can you create a emulator like Kemulator?

Posted by Nolookpass on February 21, 2012 at 05:49 PM PST #

Post a Comment:
  • HTML Syntax: NOT allowed
About

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

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today