Remote debugging of a Microsoft Windows Mobile 5.0 device or emulator with IBM Lotus Expeditor V6.1.1

Launch and debug managed client applications from a Microsoft Windows desktop to a Microsoft Windows Mobile 5.0 device or a Windows Mobile 5.0 emulator using IBM Lotus Expeditor V6.1.1.

Sridhar Pakanati (srid@us.ibm.com), Developer, IBM

Sridhar Pakanati is a developer for IBM Lotus Expeditor Toolkit. He has worked on the design of Lotus Expeditor Toolkit device debugging. Previously, he was a member of the IBM WebSphere Device Developer development team, where he worked on functions for application creation and deployment to devices such as PDAs and cellular phones. He holds a Bachelor's degree in Electrical Engineering from India and a Master's degree in Computer Science from the State University of New York. Sridhar can be reached at srid@us.ibm.com.



13 November 2007

Also available in Chinese Russian

IBM Lotus Expeditor provides an end-to-end environment that includes a server, a client that provides support for desktops, laptops, and mobile devices, and a toolkit that provides a complete, integrated set of tools you can use to develop, debug, test, package, and deploy client applications. The toolkit is built using Eclipse technology and leverages the Eclipse plug-in framework. This article describes how to use Lotus Expeditor Toolkit to debug and deploy an application to a Windows Mobile 5.0 device and a Windows Mobile 5.0 emulator.

To keep the focus on demonstrating the launch and debug methods, instead of writing new code the article makes use of the existing device sample eRCP email application that is provided with Lotus Expeditor Toolkit.

Prerequisites

This article assumes that you are an experienced developer familiar with using the Eclipse IDE. You must have Lotus Expeditor Toolkit installed in a supported development tool, such as Eclipse 3.2.2. You also need the Lotus Expeditor Client for Devices to use the debug tools. To communicate with the Windows Mobile 5.0 device or emulator, you need to install Microsoft ActiveSync 4.x (this article uses ActiveSync version 4.5). If you prefer to launch and debug on a Windows Mobile 5.0 device you should have the device set up properly to communicate through ActiveSync. If you use a Windows Mobile 5.0 emulator instead of a physical device, the Microsoft Windows Mobile 5.0 emulator needs to be installed (this article uses the standalone version of the Micosoft Device Emulator 1.0).


Overview

In this article, the steps you need to launch and debug on both a physical Windows Mobile 5.0 device and on an emulator are provided. You can skip the Windows Mobile 5.0 emulator setup portion of the article if your target is a physical device and not an emulator. This article describes the following tasks:

  • Configuring the IDE using the toolkit's configuration wizard for device-targeted applications
  • Importing the sample eRCP application into the workspace
  • Setting up a Windows Mobile 5.0 emulator or device
  • Installing Lotus Expeditor Client for Devices on the device or emulator
  • Copying debugging tools to the device or emulator
  • Creating an Expeditor on Device debug configuration and launch

Configuring the IDE using the configuration wizard in Lotus Expeditor Toolkit

After you have installed Lotus Expeditor Toolkit in your Eclipse-based development environment and restarted the IDE, a Lotus Expeditor Toolkit Configuration dialog box opens. The Configuration dialog box shows the configurable test environments in a drop-down list. From the test environment list, do the following:

  1. Select "Lotus Expeditor for Device." The other fields in the dialog box change to match the selected test environment.
  2. Click OK.

The IDE is configured with the appropriate JRE, compliance levels, and target platform from the values displayed in the Configuration dialog box (see figure 1).

Figure 1. Configuration dialog box with Lotus Expeditor for Device selected
Configuration dialog box with Lotus Expeditor for Device selected

You can also access this Lotus Expeditor Toolkit Configuration dialog box from within IDE by choosing Window - Preferences - Client Services - Configure.


Importing the sample eRCP email application into the workspace

Your next step is to import the eRCP email sample. The sample is an embedded Rich Client Platform (eRCP) application and is shipped with Lotus Expeditor Toolkit. To import the sample into your workspace, do the following:

  1. Choose File - Import.
  2. From the Import wizard, select General, and then select "Existing Projects into Workspace." Click Next.
  3. Select the Select Archive file option.
  4. Use the Browse button to browse to the plug-in directory; under the plug-in directory com.ibm.rcp.tools.device.samplegallery, select the ercpapp.jar file from the archive directory.
  5. The Import wizard shows the projects present in the archive JAR file in the Projects list. Click Finish to complete.

The project is now imported and built. You can set up break points in the code. For example, set up a break point on the first line in the method enableLaunchCommand in class org.eclipse.ercp.app.views.NormalView.


Setting up a Windows Mobile 5.0 emulator or device

If your target is a Windows Mobile 5.0 physical device, then you need to cradle the device to your PC and have ActiveSync recognize and communicate properly with the device. If you use a Windows Mobile 5.0 emulator, then you need to configure ActiveSync to connect to the emulator, and then use Microsoft Device Emulator Manager to launch the emulator and cradle so that ActiveSync can communicate with the emulator just as it would with a device.

ActiveSync needs to use the DMA transport feature to connect to an emulator, so ActiveSync needs to be set to DMA. Follow these steps:

  1. In ActiveSync, choose File - Connection Settings.
  2. In the Connection Settings dialog box, select the "Allow connections to one of the following" option, and then select DMA from the list in the drop-down box as shown in figure 2.
  3. Click OK.
Figure 2. ActiveSync Connection Settings dialog box with DMA selected
ActiveSync Connection Settings dialog box with DMA selected

ActiveSync is now ready to communicate with the emulator. You need to use Microsoft Device Emulator Manager to start and cradle the emulator. Follow these steps:

  1. Start Microsoft Device Emulator Manager.
  2. Select the Windows Mobile 5.0 Pocket PC Emulator from the list of emulators displayed in the dialog box.
  3. Right-click, and then choose Connect from the menu that appears.

A separate Windows Mobile 5.0 emulator is launched as shown in figure 3. Alternately, you can launch the Windows Mobile 5.0 emulator separately. If you launch the emulator separately outside of Microsoft Device Emulator Manager, then click the Refresh button in Microsoft Device Emulator Manager.

Figure 3. Windows Mobile 5.0 emulator
Windows Mobile 5.0 emulator

A green arrow displays in front of the name of the currently running emulator in the emulator list in the Device Emulator Manager window The green arrow indicates that the emulator is running, but not cradled yet.

To cradle the emulator, follow these steps:

  1. Select the emulator with the green arrow from the list in the Device Emulator Manager window.
  2. Right-click, and in the context menu that appears, choose Cradle.

ActiveSync now indicates that it is connected to the emulator as shown in figure 4. The Windows Mobile 5.0 emulator is now cradled and is seen by ActiveSync.

Figure 4. Device Emulator Manager after it is cradled
Device Emulator Manager after it is cradled

Installing the Lotus Expeditor client on the device or emulator

Whether you use a Windows Mobile 5.0 device or an emulator, you need to install the Lotus Expeditor client to the device or emulator through ActiveSync. You can run the Expeditor-wm-setup.exe installation program found in the device\install\wm directory of the Lotus Expeditor client CD. The installation copies and installs to the device or emulator. Follow any additional on-screen instructions on the device or emulator to complete the Lotus Expeditor client installation.


Copying debugging tools to the device or emulator

The Lotus Expeditor client installed on the device or emulator needs to have a debug version of the JRE to debug. You can find the debug version of the JRE on the Lotus Expeditor client CD; you need to copy this to the device. Do the following:

  1. In ActiveSync, open the Explorer and browse to \eclipse\plugins\com.ibm.pvc.wece.device.win32.arm_6.1.2.0-(date}\jre\bin.
  2. Rename the existing j9.exe to j9.bak.
  3. Copy the j9dbg_wm.exe from the directory utils\jclDevice\wm of the Lotus Expeditor client CD to the \eclipse\plugins\com.ibm.pvc.wece.device.win32.arm_6.1.2.0-{date}\jre\bin directory on the device.
  4. Rename the j9dbg_wm.exe to j9.exe on the device.

Creating an Expeditor on Device configuration and launch

You can now launch the eRCP email sample application in the workspace through an Expeditor on Device configuration. To create this configuration and launch, follow these steps:

  1. Choose Run - Debug to open the Debug Configuration wizard shown in figure 5.
  2. Double-click Expeditor on Device.
  3. Change the new configuration's name to ERCP_Sample.
  4. In the Java Application tab, click the Browse button in the Project field and select org.eclipse.ercp.app.
  5. In the Device field, select PocketPC from the drop-down list. The Debug connection properties are already set by default and need not be changed.
  6. Click Debug.
Figure 5. Expeditor on Device debug configuration with complete settings
Expeditor on Device debug configuration with complete settings

The eWorkbench is launched with the eRCP email sample on the device or emulator as shown in figure 6.

Figure 6. Sample application running on the emulator Windows Mobile 5.0
Sample application running on the emulator Windows Mobile 5.0

The application displays a list of emails. Select the first row, and from the Command menu choose View the message. The IDE prompts you to switch to the Debug perspective; after you switch to that perspective, execution stops at the break point that was set (see figure 7).

Figure 7. Execution halts at the break point in the sample code
Execution halts at the break point in the sample code

You should be able to inspect the variables as you would while debugging any application. Click the Resume button to continue execution, and the application displays a simple test message for the email you selected.


Conclusion

Lotus Expeditor gives you the tools you need to develop managed client applications that can run on devices such as PocketPC (Windows Mobile 5.0 and Windows Mobile 2003 platforms) and Nokia E90. In this article, you learned the steps ito set up the environment and debug an application that is targeted for a Windows Mobile 5.0 platform using a sample application that is provided with Lotus Expeditor Toolkit.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, WebSphere
ArticleID=268295
ArticleTitle=Remote debugging of a Microsoft Windows Mobile 5.0 device or emulator with IBM Lotus Expeditor V6.1.1
publish-date=11132007