MIDP on Danger's hiptop Device

The hiptop is a very network-friendly device. In some respects it operates as a thin client, off-loading certain processing and data storage tasks to a server hosted by the mobile operator. For example, the hiptop's implementation of the Record Management System (RMS) stores data on the device and automatically synchronizes it with a backup copy on the server. Because each hiptop is in constant communication with its server, most mobile operators that support the device do so with a flat-rate data plan. A reasonable inference is that the networking facilities available to you through the MIDP connector framework will be robust.

Despite this network-centric design, the hiptop is not capable of conventional over-the-air software installation from a public web server. Hiptop users install applications and ringtones exclusively from a carrier-operated catalog of content, available directly on the device, shown in Figure 3.

At the core of the hiptop software environment is Danger's Java runtime and custom frameworks. All applications and some portions of the operating system and UI toolkit are completely written in Java. A complete hiptop-specific application framework with supporting utility frameworks affords easy subclassing to create software that conforms to users' expectations of the hiptop environment. On top of this framework, Danger has implemented the Connected Limited Device Configuration (CLDC) 1.1 and MIDP 2.0. This architecture gives developers tremendous flexibility in building their applications, using either the familiar and generic MIDP APIs, or the more powerful but hiptop-specific APIs.

If you have the Java Development Kit 1.3 or later and the Ant build utility 1.6 or later, all you need to add to start building applications for the hiptop platform is the SDK. While most of the tools, libraries, and, importantly, the hiptop simulator are written in Java and thus portable to virtually any development platform you’d use, a few important utilities exist only as native binaries. For this reason, development is supported only on Windows, Linux, and Mac OS X.

The build environment is completely driven by Ant. You may use the text editor and IDE of your choice, so long as it can drive an Ant build script. You may find the Sun Java Wireless Toolkit (formerly the J2ME Wireless Toolkit) very useful. The SDK’s examples directory contains a diverse collection of sample projects that build and run out-of-the-box with a single call to Ant.

You'll find a set of MIDP-oriented sample projects in the examples/MIDlets subdirectory. Most of these have dependencies on sample projects provided with the wireless toolkit (make sure the WTK_HOME environment variable is defined and points to the root of the WTK installation). The Helloworld projects can run as they are, however. Just change to the Helloworld_src directory, type ant, and the application will build, the hiptop simulator will launch, and the application will run. You'll see it at the bottom the hiptop's "Jump" menu, with a default icon and splash screen, as in Figure 4.

As I noted earlier, the hiptop is in some respects a thin-client device, deferring some tasks like web-page rendering, network proxy, and data storage to a server hosted by the mobile operator. In hiptop parlance, the functionality offered by this server is called the Service. Danger maintains a separate instance of the Service for developers working with the SDK, although access to it is permitted only on request. Danger's developer web site has a simple form you fill in to request permission to use the Service.

For deployment to a hiptop device, the SDK includes a utility called htconsole. This command-line program opens a terminal-style serial connection to the hiptop over a USB cable, and displays the contents of System.out and System.err messages, and helpful logging info as well.

htconsole includes a number of essential commands, including one to move a compiled application bundle from your development environment to the device. Figure 5 shows htconsole in action, installing an application bundle with the command upload bundle. To make sure that the application stays installed after a reboot, be sure to call loader save. Issuing the help command produces a listing of available commands.

At this writing, MIDP support is not available on any hiptop device currently in production. Version 2.3 of the hiptop operating system includes MIDP and is expected to be deployed as an over-the-air update for T-Mobile USA subscribers in late 2005. Until then, developers can write and test MIDlets on the simulator, but won’t be able to test them on the device.

The first step is to duplicate the Helloworld_jar project directory from the SDK’s examples/MIDlets directory, so you can use it as a template for your project. For my project, I ported the JBenchmark2 tool, which exercises the MIDP 2.0 APIs and measures the performance of a device's Java implementation, available as a free download from Kishonti LP. I named my project directory JBenchmark2.

Next, modify your project's build.xml file, replacing references to HelloWorld with references to your project. The fields to update are the project name, the APP_CLASS_NAME property, and the APP_PACKAGE_NAME property. Here's the build.xml for JBenchmark2:

<project name="JBenchmark2" default="run">
    <property environment="env"/>
    <property name="DANGER_HOME" value="${env.DANGER_HOME}"/>

    <!-- NOTE: the fully qualified class name is actually
         JBenchmark2.JBenchmark2, so in this case the class
         and package name happen to be identical.
         Don't be confused. -->
    <property name="APP_CLASS_NAME"  value="JBenchmark2"/>
    <property name="APP_PACKAGE_NAME" value="JBenchmark2"/>

    <property name="APP_MIDLET_FROM_JAR" value="true"/>

    <import file="${DANGER_HOME}/tools/build_common.xml"/>
</project>

Now, in your project's bin directory, replace the existing HelloWorld.jar with your JAR file. It's important that the name of your JAR file match exactly the value of APP_CLASS_NAME in the manifest. In my JBenchmark2 project, the JAR's name must be JBenchmark2.jar.

Last, in your project's locale/en_US directory, rename the existing HelloWorld.rsrc file to match the name of your MIDlet's APP_CLASS_NAME from the build file. For JBenchmark2, the file's name is JBenchmark2.rsrc. This file is Danger's proprietary resource format used for localizing applications for different regions and languages. In this case, the default file is for the en_US locale, and you should change the entry for ID_APP_NAME to the American English name for your application.

This resource file is also where you specify custom icons and splash screens. Because the defaults are reasonable for now, don't make any other changes.

Here are the contents of JBenchmark2.rsrc:

string ID_APP_NAME    "JBenchmark2"
string ID_APP_CLASS   "danger.midlet.Launcher"

string ID_LOCALE      "en_US"

javaResources         "{resources}"

That's all you need to do. Launch the build script from your project directory with the ant command and the JAR will be repackaged as a hiptop bundle and launched in the simulator. Figure 6 shows JBenchmark2 running on the hiptop.

This time, the first step is to duplicate the Helloworld_src directory and give it a different name. For this example, I’m going to use the source code for the venerable MicroTank MIDlet. You can download the MicroTank project from http://developers.sun.com/mobility/midp/articles/game.

Next, replace the contents of your project’s bin and src directories with the contents of the MicroTank project's bin and src directories. Add a res directory to your project and copy the files from MicroTank's res directory. Now the bin directory should contain the files MANIFEST.MF and muTank.jad, and the src directory should contain MicroTankCanvas.java, MicroTankMIDlet.java, and MicroTankSprite.java. The res directory should contain board.png and tank.png.

Update the build.xml file to reflect the project name, the application's main class, and the package that class is in. Because MicroTank’s classes have no declared package, just remove the APP_PACKAGE_NAME property. Here is MicroTank's build.xml:

<?xml version="1.0"?>

<project name="MicroTank" default="run">
    <property environment="env"/>
    <property name="DANGER_HOME" value="${env.DANGER_HOME}"/>

    <property name="APP_CLASS_NAME" value="MicroTankMIDlet"/>

    <property name="APP_MIDLET_FROM_SRC" value="true"/>

    <import file="${DANGER_HOME}/tools/build_common.xml"/>
</project>

It's important that you now rename the JAD file to match your APP_CLASS_NAME – not your project name. For MicroTank, rename the JAD file in the bin directory from muTank.jad to MicroTankMIDlet.jad.

Likewise, you must change the name of the resource file in the locale/en_US directory to match your APP_CLASS_NAME value. For MicroTank, this is MicroTankMIDlet.rsrc. Then, update the file's ID_APP_NAME entry to reflect the American English name of the application. Here is MicroTank's MicroTankMIDlet.rsrc file:

string ID_APP_NAME    "MicroTank"
string ID_APP_CLASS   "danger.midlet.Launcher"

string ID_LOCALE      "en_US"

javaResources         "{resources}"

Because absolutely no code changes are required, you're now ready to compile and run. Execute the build with the ant command from your project directory. The source code will compile, the resources, JAD file, and classes will be packaged into a hiptop application bundle, and the simulator will launch. Figure 7 shows MicroTank playing on the hiptop. (The prerelease build of the SDK seems to have some problems with transparency.)

While the life-cycle of a MIDlet on the hiptop conforms to the MIDP specification, it may be different from what some developers would expect. The first time the user launches the application, the hiptop runtime instantiates the MIDlet and calls startApp(). After that, the runtime calls pauseApp() when the user switches to another application, and startApp() again when the MIDlet returns to the foreground.

Because hiptop users are incessant multitaskers, MIDlets must be sure to pause their threads and generally minimize their resource consumption when pauseApp() is called, or they can severely degrade the performance of the device. The hiptop runtime calls destroyApp() only if the MIDlet explicitly requests it or when the MIDlet is deleted by htconsole, but not when the device shuts down. Developers must furnish clean-up routines in pauseApp(), not only in destroyApp().

The hiptop screen has a completely different aspect ratio from most other MIDP devices. While form-based MIDlets won’t have a problem, games and other canvas-based applications should scale their user interface to take better advantage of the full screen, based on the dimensions the Canvas class’s getWidth() and getHeight() methods return.

To make this transition easier, Danger has provided some compatibility modes, configurable from the resource file, that force Canvas to return the dimensions of many other popular MIDP devices.

User input is handled through the Canvas class’s keyPressed() and keyReleased() methods. The keyboard buttons generate their corresponding ASCII key codes, and Canvas.getGameAction() correctly interprets the hiptop’s direction pad and fire button. All other buttons produce negative key codes as permitted by the MIDP specification. These values map to their equivalents documented in the hiptop API.

For ease of transition, Danger supports a compatibility mode, where certain buttons on the keyboard (see Figure 2) map to the 12-key pad found on most phones. You enable this mode through a property in the application’s resource file.

The Audio Building Block implementation required by the MIDP 2.0 specification allows applications to produce sounds and music. The hiptop supports MIDI through its embedded high-quality Beatnik audio engine. Neither MMAPI nor video capture through the built-in camera is yet available.

A final word of caution: You might want some MIDlets to take full advantage of the platform-specific APIs available on the hiptop platform. Be aware that the hiptop doesn’t support mixing its own UI toolkit with MIDP’s lcdui packages. After you choose how to implement the user interface, the other, non-UI libraries are fair game.

Editor's Note: MIDP support for the hiptop is supposed to be out "Real Soon Now" but Danger has not published a specific date. MIDP support gets sent out to all current subscribers as an OTA update.