Emulator

Overview

The HP webOS Emulator simulates a webOS device on a Linux, Mac, or Windows computer. It is built on VirtualBox, virtual machine software that is free from Oracle. If you installed the SDK, you already have the Emulator on your computer.

image
Figure: HP webOS Platform Developer Toolset 1 (Emulator or device support)

The Emulator includes a radio simulator that lets you simulate phone calls and GPS fixes. For more info, see Radio Simulator.

Currently, the Emulator does not support the following:

  • Accelerometer live data (does support orientation and shaking events)
  • Audio
  • Bluetooth (UI and any interface-specific APIs do not work in the Emulator)
  • Camera
  • Gesture area
  • Multi-touch
  • Sound
  • Video
  • Wi-Fi (UI and any interface-specific APIs do not work in the Emulator, but network connectivity works by using the desktop connection)

Note: When invoked at the command-line, the Emulator has a number of options. For a reference on this, see Command-Line Usage (at end).

Starting the Emulator

Follow the instructions for your system:

  • Linux: At the command prompt, type palm-emulator.

  • Mac: In the Applications folder, double-click the Emulator icon.

  • Windows: Select Start > All Programs > Palm > SDK > Emulator.

Running Applications on the Emulator

If you are using Eclipse with the HP webOS plug-in, you can run an application on the Emulator by selecting Run > Run Configurations..., then selecting "Palm Emulator" for the target of your application name. On subsequent activations, select Run > Run As... > Mojo Application. Eclipse automatically packages, installs, and launches the application. With Eclipse, there is no need to uninstall the application before re-running it.

If you are using the command line tools, run the application at the command prompt by using the webOS tools included with the SDK.

Notes:

  • These instructions use the "Hello, World!" example. Remember to make changes as needed for actual applications.
  • The "workspace directory" contains all of the application directories.
  • Changes made during development and debugging may not appear unless you first delete the previous version, and then repackage and reinstall the updated application.
  • Installing a new version of an application does not remove any source files that are not present in the new version. Therefore, during testing, it is useful to delete the old version of an application before installing a new version.

Package and install the application on the Emulator

  1. Start the Emulator.

  2. Open a Command Prompt window, and then navigate to the workspace directory.

  3. Use the palm-package command as follows to package the directory containing the application: 

    palm-package HelloWorld

  4. Use the palm-install command as follows to install the resulting .ipk file on the emulator. (Note that if you do not have the Emulator running, but do have a webOS device plugged into your computer's USB port, this will install the package to the device if you have enabled Developer Mode. You will find your app's icon at the bottom of the first launcher menu. When plugging the device into the computer to load an app, select the "Just Charge" option on the device.) 

    palm-install com.mystuff.hello_1.0.0_all.ipk

Launch the application at the command prompt

  1. Start the Emulator, if it is not already started.

  2. Open a Command Prompt window, and then navigate to the workspace directory.

  3. Use the palm-launch command as follows: 

    palm-launch com.mystuff.hello

Close the application at the command prompt

  1. Start the Emulator, if it is not already started.

  2. Open a Command Prompt window, and then navigate to the workspace directory.

  3. Use the palm-launch command as follows: 

    palm-launch -c com.mystuff.hello

Delete the application from the Emulator

  1. Start the Emulator, if it is not already started.

  2. Open a Command Prompt window, and then navigate to the workspace directory.

  3. Use the palm-install command as follows: 

    palm-install -r com.mystuff.hello

Debugging an Application

There are two ways to debug an application in the Emulator:

  • Use the Debugger.
  • Use the console output of the Emulator.

Set up the console output on Windows

  1. Open PuTTY from the HP webOS > PDK program group.

  2. Enter localhost as the Host Name and 5522 as the port.

  3. If a security alert dialog box appears, press Yes.

  4. For the login name, enter root, and then press Enter.

  5. For the password, press Enter (the password is blank).

  6. At the Emulator command prompt root@qemux86:/var/home/root#, enter the following command: 

    log com.yourdomain.your-app

Set up the console output on Mac or Linux

  1. Open a terminal.

  2. Run the following command: novaterm.

  3. At the Emulator command prompt root@qemux86:/#, enter the following command: 

    log com.yourdomain.your-app

For more info about generating logs from your application, see Logging and palm-log.

Keyboard Shortcuts for the Emulator

The following table lists the keyboard shortcuts supported in the Emulator.

Key Description
Alt (Windows and Linux) or Option (Mac) Option key
End Opens and closes the launcher
Esc Performs the back gesture (or swipe back)
Home Minimizes and maximizes the card
Left/Right Arrow Switches the application left or right in the Card view
Control Sym (symbol) key

Exiting the Emulator

To exit the Emulator, select Machine > Close > Power off the machine > OK.

Note:

If you choose a different option, you cannot install applications on the Emulator the next time you start it.

Performing a Hard Reset

Follow the instructions for your system:

  • Linux: At the command prompt, type the following: 

    palm-emulator --reset

  • Mac: Open a terminal, and type the following: 

    /Applications/Palm\ Emulator.app/Contents/MacOS/palm-emulator --reset

  • Windows: At the command prompt, type the following: 

    \\Program Files\HP webOS\SDK\bin\palm-emulator.bat --reset

Running VirtualBox

Follow the instructions for your system:

  • Linux: At the command prompt, type VirtualBox.

  • Mac: In the Applications folder, double-click the VirtualBox icon.

  • Windows: Select Start > All Programs > Oracle VM VirtualBox > VirtualBox.

Keyboard Capture

By default, VirtualBox captures the keyboard into a virtual machine. On the Mac, this can interfere with using the left command key to switch among applications with command-tab. If you run into this problem, try the following:

  1. Exit the Emulator.
  2. Open VirtualBox.
  3. On the VirtualBox menu, select Preferences.
  4. Switch to the Input section.
  5. Press the right command key to switch the Host Key, and then turn off Auto Capture Keyboard.
  6. Press OK, and then close VirtualBox.

Accelerometer Events

The Emulator supports certain accelerometer events through the use of function keys.

Key Description
F5 Simulate shaking
F6 Simulate "up" (12:00 or normal) orientation
F7 Simulate "down" (6:00) orientation
F8 Simulate "right" (3:00) orientation
F9 Simulate "left" (9:00) orientation

Note that the orientation keys will only be active if Window Orientation has been set to "free".

Emulator Host Mode

The webOS SDK Emulator (version 1.4.1 and later) includes a feature called Emulator Host Mode. This mode allows you to inspect your application using a desktop browser (Chrome or Safari). To accomplish this, the Emulator now contains its own web server that renders your application on port 8080, which is automatically mapped by the "palm-emulator" tool to port 5580 on your desktop.

After the Emulator is started, you can launch a browser on your desktop and render any applications in your browser directly! (Note that if using Chrome, you'll need to disable the popup blocker.)

Using Emulator Host Mode

Open your web browser, and enter the following URL: 

http://localhost:5580/

Command-Line Usage

Command-line usage for the HP webOS Emulator.

Syntax 

palm-emulator [OPTION...]

Options 

      Option                     Description
    --list                   List the available Emulator images
    --start=IMAGE            Start an Emulator image
    --stop=IMAGE             Stop an Emulator image
    --reset=IMAGE            Reset an Emulator image
    --install=IMAGE_FILE     Install an Emulator image
    --remove=IMAGE           Remove a user-installed Emulator image
    --remove-all             Remove all user-installed Emulator images
    --version                Display version info and exit
    --help                   Display this help and exit

Usage Notes

IMAGE is the name of an Emulator image, including the resolution.

IMAGE_FILE is the file path of the Emulator image file to install.

Note that SDK-installed Emulator images cannot be removed.

If no options are specified, an image selection window will be displayed.

Examples

  • Start the Emulator and choose an image 
 palm-emulator
  • List the available Emulator images 
 palm-emulator --list
  • Start the Emulator image named "SDK-1.4 (320x480)" 
 palm-emulator --start "SDK-1.4 (320x480)"
  • Stop the Emulator image named "SDK-1.4 (320x480)" 
 palm-emulator --stop "SDK-1.4 (320x480)"
  • Install a new Emulator image 
 palm-emulator --install "~/Downloads/SDK 1.4.5.452.vmdk.zip"
  • Remove a user-installed Emulator image 
 palm-emulator --remove "SDK 1.4.5.452"
  • Remove all user-installed Emulator images 
 palm-emulator --remove-all