8 About the Java ME Embedded Emulator

Installing and Running IMlet Suites Using the Java ME Embedded Emulator

Java ME Embedded applications are distributed as IMlet suites that consist of a JAR file described by a JAD file. When you run a Java ME Embedded application using Oracle Java ME SDK, the corresponding IMlet suite is automatically installed and started on the emulated device.

When the Java ME Embedded Emulator is running, you can also install and run IMlet suites manually. One device can have several IMlet suites installed and running at the same time. To manage IMlet suites for a device, open the AMS tab.

To install an IMlet suite:

1. On the AMS tab, click Install.

2. Specify the path or URL to the corresponding JAR or JAD file, or click Browse to select it in the file explorer window.

3. Click OK and wait for the IMlet suite to install.

   The installed IMlet appears in the list with the status Not Running.

To reinstall an IMlet suite, select it in the list and click Reload.

To remove an IMlet, select it in the list and click Remove.

To view the manifest file information about the IMlet, select it in the list and click Info.

To run an installed IMlet:

1. Select it in the list and click Run.

2. Select the options for debugging, profiling, and monitoring if necessary.

3. Click OK.

   The IMlet status changes to Running.

To automatically install and run an IMlet suite:

1. Click the Run IMlet Suite button on the Java ME Embedded Emulator window toolbar, or select Run IMlet Suite on the Application menu.

2. Specify the path or URL to the corresponding JAR or JAD file, or click Browse to select it in the file explorer window.

3. Select the options for debugging, profiling, and monitoring if necessary.

4. Click OK and wait for the IMlet suite to install and start.

   The installed IMlet appears in the list with the status Running.

To stop a running IMlet, select it in the list and click Stop.

Viewing Device Output and Logs

The Java ME Embedded Emulator maintains a separate log file for each device to record errors, warnings, and informational events. A running Java ME Embedded application may write data to the standard output stream (stdout) or standard error stream (stderr). This information can be used for troubleshooting and debugging.

To view the device log file, open the View menu and select Device Log. You can select the level of detail that you would like to view among the following:

• Trace: Displays all logged events, including low-level tracing data.

• Debug: Displays all high-level events, including debugging data.

• Info: Displays high-level informational events and more severe ones.

• Warn: Displays high-level warning events that may possibly indicate a problem and more severe ones.

• Error: Displays high-level events that indicate an error, including fatal ones.

• Fatal: Displays only high-level fatal error events.

To save the output to a LOG file, click Save. To clear the log file, click Clear.

To view the device output console, open the View menu and select Output Console. You can select the streams that you would like to view among the following:

• All: Displays all console messages produced by the application.

• Standard Output: Displays messages printed to the stdout stream.

• Standard Error: Displays messages printed to the stderr stream.

To save the output to a LOG file, click Save. To clear the console output produced by the device, click Clear.

Viewing Messages

Some devices support wireless communication through JSR 120: Wireless Messaging API (WMA), which enables Java ME Embedded applications to send and receive messages. Any messages that are not addressed to a specific application on the device are stored in the inbox.

To see the messages in the inbox using the Java ME Embedded Emulator, open the Device menu and select Messages. The Messages window contains a list of messages in the inbox with the type, sender, timestamp, subject, encoding, and contents of each message.

Managing Landmarks

Some devices support location tracking through JSR 179: Location API for J2ME, which enables Java ME Embedded applications to use information about the physical location of the device. Such devices also maintain a database of landmarks that applications may rely on for guidance.

A landmark is identified by a name, and may be placed in a category that groups landmarks by type (for example, shops, restaurants, gas stations, and so on). A landmark can have a description, and it must define the location using the latitude and longitude. You can also define the altitude and accuracy of positioning. A landmark may contain data about the street address, phone number, URL, and so on.

To manage the landmarks that are known to the device in Java ME Embedded Emulator, open the Tools menu and select Manage Landmarks. Landmarks are stored in a landmark store. You can use the default landmark store or add several named stores.

To add a new landmark store, in the Landmark Stores drop-down list, select Add new landmark store. To manage available landmark stores (add new ones or remove existing ones), click Manage Landmark Stores next to the drop-down list.

To add a category to the selected landmark store, click Add Category. To remove a category, select it and click Remove Category.

By default, the list of landmarks contains all available landmarks in the selected landmark store. To show only landmarks from certain categories, select the corresponding check boxes in the categories list.

To add a landmark, click Add. To edit a landmark, select it and click Edit. To remove a landmark, select it and click Remove. To assign a landmark to categories, select it and click Assign Categories.

When you select a landmark, you can preview the defined location information in the pane below the landmarks list.

Managing the File System

Some devices can interact with the file system resources using the FileConnection package which is part of JSR 75: PDA Optional Packages for the J2ME Platform. The FileConnection package gives Java ME Embedded applications access to the file system of the device, including external memory cards.

The Java ME Embedded Emulator enables IMlets to access files stored on your computer's hard disk as if they are in the device's storage or attached memory card. To manage the device's file system, open the Tools menu and select Manage File System. Mounted root directories are displayed in the top list, and unmounted root directories are displayed in the bottom list. Mounted root directories and their subdirectories are available to applications that implement the FileConnection interface.

Mounted root directories are located in the device's configuration folder of the Oracle Java ME SDK user configuration directory. For example, the root directories for EmbeddedDevice1 are located under

JAVAME_SDK_USER\work\EmbeddedDevice1\appdb\filesystem

The default root directory folder is named root1. You cannot unmount the default root directory.

To create a new empty root directory, click Mount Empty, specify a name and click OK. A new folder is created in the device's filesystem folder and it is mounted as another root directory in addition to the default.

To create a root directory by copying an existing folder on your computer, click Mount Copy and select the necessary folder. This folder and its subfolders is copied to the device's filesystem folder and it is mounted as another root directory in addition to the default.

To make a directory inaccessible to the FileConnection API, select it in the list of mounted root directories and click Unmount. The selected root directory is unmounted and moved to the bottom list. To completely remove a mounted directory, select it and click Unmount & Delete.

To remount an unmounted root directory, select it in the list of unmounted root directories and click Remount. The root directory is moved to the top list.

To delete an unmounted root directory, select it in the list of unmounted root directories and click Delete. The selected root directory is removed from the list.

Managing the Connectivity Configuration

Some devices can communicate over a wired, wireless, or cellular network. They can establish and accept connections to other devices, servers, and so on. There are several APIs that are used to provide this functionality to Java ME Embedded applications.

The Java ME Embedded Emulator enables you to set up the connectivity configuration of the running device, which you would like to emulate. To manage the connectivity configuration, open the Tools menu and select Connectivity. The Connectivity window is separated into several tabs.

Managing Access Points

An access point is a network connectivity configuration of a TCP/IP network interface that is defined on a device using the javax.microedition.io.AccessPoint class.

Use the Access Points tab of the Connectivity window to view and manage available access points. This tab contains a table that lists access points with the following columns:

• Id: Numeric identifier of the access point

• Access Point Name: Name of the access point

• Connected: Whether the access point is connected to a network

• Default: Whether this is the default access point

When you select an access point in the table, you can view and configure additional settings for the access point. Additional settings are displayed in the bottom panel of the Access Points tab. For any access point you can specify a name and select a network interface from the drop-down list. Other settings depend on the selected network interface (for example, the SSID for a WiFi access point).

Click Add Access Point below the table of access points to add a new access point. To remove an access point, select it in the table and click Remove Access Point.

Managing Network Interfaces

A network interface represents the network connection spot for an access point. It is defined on a device using the javax.microedition.io.NetworkInterface class.

Use the Network Interfaces tab of the Connectivity window to view and manage available network interfaces. This tab contains a table that lists network interfaces with the following columns:

• Id: Numeric identifier of the network interface

• Network Interface Name: Name of the network interface

• IP Address: Address of the device in the IP network

• Connected: Whether the interface is connected to a network

When you select a network interface in the table, you can view and configure additional settings for the network interface. Additional settings are displayed in the bottom panel of the Network Interfaces tab. For any network interface you can specify a name, select a type from the drop-down list, and map it to any physical network interface on the host machine.

Click Add Network Interface below the table of network interfaces to add a new network interface. To remove a network interface, select it in the table and click Remove Network Interface.

Managing Cellular Networks

A cellular network is a 3GPP or CDMA network that the device is registered on. It is defined on a device using the javax.microedition.cellular.CellularNetwork class.

Use the Cellular Networks tab of the Connectivity window to view and manage available cellular network. This tab contains a table that lists cellular networks with the following columns:

• Id: Numeric identifier of the cellular network

• Cellular Network Name: Name of the cellular network

When you select a cellular network in the table, you can view and configure additional settings for the cellular network. Additional settings are displayed in the bottom panel of the Cellular Networks tab. For any cellular network you can specify a name, select a network interface from the drop-down list, toggle roaming on and off, and so on.

Click Add Cellular Network below the table of cellular networks to add a new cellular network. To remove a cellular network, select it in the table and click Remove Cellular Network.

Managing Subscribers

A subscriber of a cellular network is represented by an identity, such as SIM, R-UIM, CSIM, and so on. Subscribers resides on the device in a physical or virtual slot exposed as a subscriber identifier. The primary subscriber always resides in slot number 1. A subscriber is defined on a device using the javax.microedition.cellular.Subscriber class.

Use the Subscribers tab of the Connectivity window to view and manage available subscribers. This tab contains a table that lists subscribers with the following columns:

• Slot Number: Numeric identifier of the subscriber slot number

• Phone Number: Phone number of the subscriber

• Registered Cellular Network: The cellular network of the subscriber

When you select a subscriber in the table, you can view and configure additional settings for the subscriber. Additional settings are displayed in the bottom panel of the Subscribers tab. For any subscriber you can specify the operator, phone number, and select the type of cellular network from the drop-down list. Other settings depend on the selected cellular network.

Click Add Subscriber below the table of subscribers to add a new subscriber. To remove a subscriber, select it in the table and click Remove Subscriber.

Generating External Events

Java ME Embedded devices are designed to interact with various external events. These events can include power management signals, location information, pulses, and so on. The Java ME Embedded Emulator enables you to simulate such events using the External Events Generator to see how your Java ME Embedded application processes them.

To access the External Events Generator, open the Tools menu and select External Events Generator. Alternatively, you can click the External Events Generator button on the Java ME Embedded Emulator main window toolbar. The External Events Generator window is separated into several tabs, depending on the configuration and capabilities of the device.

Generating Analog Input

Some devices can read analog input signals and convert them to numerical values using the Analog-to-Digital Converter (ADC). An ADC can have several channels, each one sampling a separate continuous input voltage.

Use the ADC tab to specify the input voltage for an ADC channel that is configured on the emulated device. Select the ADC channel from the drop-down list. Each ADC pin is denoted by a pin number and a channel number (for example, ADC1Ch1).

Specify the input voltage for the selected ADC channel by entering the value in the text field or using the slider.

Alternatively, you can set the output of an existing Digital-to-Analog Converter (DAC) channel to be used as the input voltage for the selected ADC channel by selecting DAC Input and using the drop-down list to choose the DAC channel.

Generating Button Events

Some devices have General-Purpose Input/Output (GPIO) pins that may be used as additional digital control lines. They can be controlled and programmed at runtime, and they are generally used for connecting buttons and light-emitting diodes (LEDs).

Use the GPIO tab to generate input events for the GPIO pins that are configured on the emulated device. For each input pin, you can toggle the input value between Low and High by clicking the corresponding button. This corresponds to pressing the hardware analogy of the button connected to the pin, toggling it on and off.

Under Wave Generator, you can set the frequency (in hertz) and duration (in milliseconds) of a more complex signal. To run and stop the wave generator for an individual pin, supply frequency and duration values, and use the corresponding Run and Stop buttons. You can also use the Run All or Stop All buttons to run or stop all pins simultaneously.

Generating Input From Emulated Peripheral Devices

Some devices support Inter-Integrated Circuit (I2C) and Serial Peripheral Interface (SPI) communication with peripheral devices, such as various sensors. To emulate a peripheral slave device on either of these bus links, there are two options: you can add a simple emulated device that echoes back any data that is sent to it, or add an implementation of the device using the embedded support API.

If you implement an I2C or SPI peripheral device, you can use the I2C or SPI tabs to generate events from it to the emulated device. For example, the default Qualcomm_IoE_Device emulator implements three I2C peripherals (an accelerometer, a light sensor, and a temperature sensor) and one SPI peripheral (an accelerometer).

On the I2C tab and SPI tab, at the top of the G-Sensor group, you can see the range and bandwidth of the emulated accelerometer implementation. Below you can use the sliders to specify the acceleration of the device along the three axes (X, Y, and Z).

On the I2C tab, in the Light Sensor group, you can see the type, range, resolution, illuminance limits, and whether the interrupt flag is set for the emulated light sensor implementation. Below you can use the slider to set the current illuminance level in lux.

On the I2C tab, in the Temperature Sensor group, you can see the temperature limits of the emulated temperature sensor implementation. Below you can use the slider to set the current temperature in degrees Celsius.

Generating Location Provider Information

Some devices support location tracking through JSR 179: Location API for J2ME, which enables Java ME Embedded applications to use information about the physical location of the device. A real device receives location information from a location provider.

Use the Location tab to generate data received by an emulated device as if from a location provider.

Set the following orientation measurements:

• Azimuth: Horizontal direction

• Pitch: Vertical elevation angle

• Roll: Rotation of the terminal around its longitudinal axis

By default, emulated devices have two location providers assigned to them. Select a state from the drop-down lists under Location Provider #1 and Location Provider #2 to test how your Java ME Embedded application handles unexpected conditions (that is, when location information is not available). The default state is Available. You can change it to Temporarily Unavailable or Out of Service.

Specify the latitude, longitude, altitude, speed (ground speed), and course (degrees relative to true north) for each location provider. Applications that use the Location API retrieve these values as the location of the emulator. Click Send to transmit these values to the emulator as if sent from a location provider.

You can also create a script to simulate the movement of the device by specifying different locations for different times. Specify the path to the location script file in the Script field, or click Browse and select the script file in the file explorer window.

Use the Time slider to change the starting point within the script. You can run the script, pause it, or move to the beginning or end of the script by using the buttons below the slider.

The script for the location provider is an XML file with the root <waypoints> element and a series of child <waypoint> elements. Each <waypoint> element must contain the time attribute that specifies the time in milliseconds from the previous waypoint or from the beginning. Position is specified using the latitude, longitude, and altitude attributes. You can specify the position for each provider separately. If only one position is present, the other one is given the same position. You can also specify the state of each provider using the state attribute with one of three values:

• off: means the provider is out of service

• available: means the provider is working and has data available

• unavailable: means the provider is working, but no data is available

The following example shows a sample script. The first waypoint is set to 1.5 seconds after beginning, the position is set only for default provider, the other provider is automatically set to the same position, both providers are available. The second waypoint is set to 2 seconds after the first one (or 3.5 seconds after beginning), the position is set only for the first provider, the second provider is automatically set to the same position, but this time first provider is out of service, and only second is available. The third waypoint is set to 3 seconds after the second one (or 6.5 seconds after beginning), the position is set only for second provider, the first provider is automatically set to the same position, but data from the first provider is not available, and only the second provider is available.

<waypoints>
  <waypoint time=1500 latitude="14.4" longitude="50.1" altitude="310" state1="available" state2="available" /> 
  <waypoint time=2000 latitude1="14.7" longitude1="49.7" altitude1="305" state1="off" state2="available" />
  <waypoint time=3000 latitude2="14.9" longitude2="49.3" altitude2="303" state1="unavailable" state2="available" />
</waypoints> 

Generating Input From Memory-Mapped Peripherals

Some devices support communication with peripheral devices over the Memory-Mapped Input/Output (MMIO) interface bus. The MMIO APIs enable low-level control over the peripheral by reading from and writing to registers or memory blocks of the peripheral mapped to the memory of the emulated device.

You can either create a simple emulated peripheral device that echoes back any data that is sent to it, or add an implementation of the device using the Embedded Support API.

If you implement an MMIO peripheral device, you can use the MMIO tab to generate events from the peripheral to the embedded memory of the emulated device. On real devices, these events are produced by the hardware of the peripheral device.

Select an MMIO device from the Device drop-down list. For example, in the default implementation of the EmbeddedDevice1 emulator, BIG_ENDIAN_DEVICE is the only possible choice.

Use the Block or Register drop-down list to select a memory block or register of the selected device, from which the event is sent.

Specify an event identifier in the Event ID field.

Click Send event to send the event from the specified device.

You can add a listener in your application to capture events with a particular identifier from a specific MMIO memory register or block. See the Javadoc for the Device I/O API, specifically the MMIODevice.setMMIOEventListener() methods. By default, Javadocs are located in the Oracle Java ME SDK installation directory under docs/api.

Generating Power Management Events

Use the Power Management tab to configure power settings of the emulated device. You can select between emulating an external power source or battery.

Under Power Source, select Battery to emulate a device powered by a battery, or select External to emulate a device powered from an external power source. If you select the battery as the power source, then specify the remaining time in seconds by using either the slider or the numeric field. If you do not want to set a specific value as the remaining time, then select Unknown.

Also, when the battery is selected as the power source, you can send power alerts. Select an alert from the Power Alert drop-down list and click Send. The following alerts are available:

• Battery level is critically low

• Battery level is getting low

• Battery level has returned to normal value

• Phone connection is about to be terminated due to insufficient power

• Infrared connection is about to be terminated due to insufficient power

• Network connection is about to be terminated due to insufficient power

Generating Pulses Counters Tab

Some devices can receive and count pulses (or events) sent on a digital input line, including a GPIO pin. Use the Pulse Counters tab to generate pulses for an emulated device with a pulse counter. The default implementation displays a counter name followed by a Send Pulse button.

Counter names correspond to the counters on the emulator's Pulse Counters tab in the main window of the Java ME Embedded Emulator. Click Send Pulse to send a pulse.