Skip Headers
Oracle® Java Micro Edition Software Development Kit Developer's Guide
Release 3.4 for NetBeans on Windows
E24265-06
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

7 Working With Devices

The Oracle Java ME SDK provides default device skins. A skin is a thin layer on top of the emulator implementation that defines the appearance, screen characteristics, and input controls. This chapter discusses the default emulators provided by Oracle Java ME SDK and describes how you can create and modify a custom device. To make your own device, see "Using the Custom Device Editor."

The Oracle Java ME SDK emulator simulates a CLDC, CDC, IMP-NG, or Qualcomm device on your desktop computer. The CLDC, CDC, and IMP-NG emulators do not represent a specific device, but provide correct implementations of the supported APIs for these platforms.

The Qualcomm_IoE_Device emulator provides an emulation of the Qualcomm Orion IoE embedded device. For more information on the Qualcomm Orion IoE device, see the Oracle Java ME Embedded Getting Started Guide for the Reference Platform (Qualcomm Orion IoE).

7.1 The Device Manager on Windows

The Oracle Java ME SDK uses the Device Manager to detect devices and displays the available devices in the Device Selector window (Tools > Java ME > Device Selector). The Device Manager is a service used to manage both emulators and external devices.

The Device Manager runs in your Windows system tray. Once you have installed the Oracle Java ME SDK software, it starts automatically when you start Windows. In the task manager, the process is labeled device-manager.exe.

Figure 7-1 The Device Manager Icon

Description of Figure 7-1 follows
Description of "Figure 7-1 The Device Manager Icon"

You can right-click the icon and select Exit to stop the service. To restart the Device Manager, double-click device-manager.exe in your installdir\bin directory. You can also start it from the command line as described in "Run the Device Manager."

In the Windows system tray, click the icon or right-click the icon and select Manage Device Addresses from the menu to open the Device Address Manager, a shown in Figure 7-2.

Figure 7-2 The Device Manager Menu

Description of Figure 7-2 follows
Description of "Figure 7-2 The Device Manager Menu"

Enter an IP address and select Add to add a device. Select an address and click Remove if you have an address you no longer want to detect. The device is no longer displayed in the Device Selector.

If an embedded device is attached, the user can select a COM port for the hardware connection in the Select COM Port field. If Disable is selected, Oracle Java ME SDK stops detecting external devices via COM port, as shown in Figure 7-3.

Figure 7-3 The Device Address Manager

Description of Figure 7-3 follows
Description of "Figure 7-3 The Device Address Manager"

Right-click the icon in the system tray and select Registered Devices to see a list of registered devices and their configuration information such as, screen dimensions, screen depth, security domains, supported APIs, and more, as shown in Figure 7-4.

Figure 7-4 The Registered Devices Screen

Description of Figure 7-4 follows
Description of "Figure 7-4 The Registered Devices Screen"

7.1.1 Adding an External Device

The device selector can detect a device that has a compatible runtime. Typically this device has network capabilities and is connected to the computer running Oracle Java ME SDK.

  1. To detect a physical device, click CTRL-D, or click the device icon at the top of the Device Selector window.

  2. Type an IP address and click Next. Click Finish.

    You can also enter an IP address in the Device Manager, as described in "The Device Manager on Windows."

  3. The physical device is listed in the appropriate platform tree. By default, the device has "ExternalDevice" appended to the name.

    For example, if an IMP-NG device is detected it is placed in the IMP-NG node and given the name IMPNGExternalDevice1.

  4. If your device is supported by a serial connection, you can define a port for the connection in the Device Address Manager. To define a COM port, click the Select COM Port field and select a port, as shown in Figure 7-5.

    Figure 7-5 Adding a COM Port

    Description of Figure 7-5 follows
    Description of "Figure 7-5 Adding a COM Port"

The Oracle Java ME SDK provides support for several embedded external devices through the Oracle Java ME Embedded runtime, including:

  • Keil MCBSTM32F200

  • Raspberry Pi

  • Qualcomm Orion IoE

For additional information on how to install, configure, and work with a supported external device, see the Oracle Java ME Embedded documentation at:

http://docs.oracle.com/javame/embedded/embedded.html

7.2 Starting and Running Emulators

The Oracle Java ME SDK runs applications on an emulator or an external device. Before you can run an application from the SDK, the Device Manager, must be running. When the Oracle Java ME SDK runs, the Device Manager automatically launches and starts detecting devices. The default emulators shipped with the SDK are automatically found and displayed in the NetBeans Device Selector window (Tools > Java ME > Device Selector).

7.2.1 Starting an Emulator

Typically an emulator is launched when a Oracle Java ME SDK project is run from the NetBeans IDE or the command line. The default emulator is determined by the Java ME platform selected for the project, as described in "Managing Java Platforms."

You can open an emulator without running an application from the IDE. From the Windows Start menu, click Programs -> All Programs and select Java(TM) ME Platform SDK 3.4. On the pull-right menu, select the desired emulator. You can also click the emulator shortcuts installed on your Windows desktop.

To run an application from the emulator, click the Application menu and select Run MIDlet Suite (or Run IMlet Suite). Provide the path to the application and any other information, and click OK.

7.3 The IMP-NG Emulator

IMP-NG is a Java ME profile commonly used on small embedded devices. Figure 7-6 shows the IMP-NG emulator provided in Oracle Java ME SDK.

Figure 7-6 The IMP-NG Emulator

Description of Figure 7-6 follows
Description of "Figure 7-6 The IMP-NG Emulator"

Device Name. Shown in the upper window frame. See Table 8-1 for a list default emulator names.

Menus. See "Emulator Menu Settings."

Toolbar. For the IMP-NG Emulator, the Toolbar provides shortcuts for the following operations:


Note:

When the Device Manager detects an external IMP-NG device, only the Application, View, and Help menus and the Run IMlet Suite, Install IMlet Suite, and Emulator window always on top icons in the Toolbar are available in the device display.


Device ID. Numerical identifier that is unique for each device.

Display Panel and Tabs. The display panel displays fields and information dependent on the selected tab:

Emulator Status Bar. Information about the current system state is shown in the status bar at the bottom of the emulator window. Also shown is the memory indicator showing used and total memory.

7.3.1 The External Events Generator

The following menu options each have a tab on the External Events Generator. The use of the External Events Generator is addressed in the discussion for each JSR:

  • ADC. The Analog-to-Digital Conversion tab is only visible for the IMP-NG emulator.

  • Access Points. This tab displays connection information for the selected access point.

  • GPIO. This General Purpose Input Output (GPIO) option.

    By default, this tab displays ports and pins for a specific device described in "Running the GPIODemo." You can create a custom device to represent a different device. See "General Purpose Input Output (GPIO)."

    See the Device Access API (installdir\docs\api\deviceaccess) for a description of the GPIO interface.

  • Location. "Setting the Emulator's Location at Runtime."

  • MMIO. The memory-mapped I/O (MMIO) option is visible only for the IMP-NG emulator. From the Device drop down list, select one of the default devices:

    • TEST_DEVICE. A Little Endian device that contains all block types: byte, short, int, long, and block. Writes to this device also affect BIG_ENDIAN_DEVICE which shares the address space.

    • WDOGLOG. A Little Endian device that supports only the block type.

    • RTC. STM32F200 RTC device. A Little Endian device that supports only the int type.

    • BIG_ENDIAN_DEVICE. A Big Endian device that shares the address space with the TEST_DEVICE, therefore it contains the same memory blocks. Writes to this device also affect TEST_DEVICE which shares the address space.

    If you are using a custom device created with the Custom Device Editor (see "Using the Custom Device Editor"). The device list might include additional devices.

    See the Device Access API (installdir\docs\api\deviceaccess) and the Embedded Support API (installdir\docs\api\embedded-support-api) for descriptions of the MMIO interface.

  • Mobile. The unique International Mobile Subscriber Identity (IMSI) and the International Mobile Station Equipment identity (IMEI) identifiers of the device.

  • Pulse Counter. This tab displays the current pulse counters on the device. The default configurations are:

    • COUNTER_PA0

    • COUNTER_PB3

    • COUNTER_PB10

    • COUNTER_PA3

    You can configure the pulse counters you want and send a signal to the configured pulse counter by clicking Send Pulse.

7.3.2 IMP-NG Device Options

For in-depth descriptions of the IMP-NG interfaces or devices, see the following resources:

  • Device Access API (installdir\docs\api\deviceaccess)

  • Embedded Support API (installdir\docs\api\embedded-support-api)

  • For more information about default devices and their properties, you can use the Properites View from the Device Selector. For more information, see "Viewing Device Properties."

7.4 The Qualcomm IoE Emulator

The Qualcomm_I0E_Device emulator is based on IMP-NG, but for a specific embedded platform, the Qualcomm Orion IoE device. Many of the menus and settings are the same as in the IMP-NG emulator.

For more information on Qualcomm_IoE_Device emulator menus and settings that are not mentioned in this section, see "The IMP-NG Emulator."

The Qualcomm_IoE_Device emulator is launched from the Windows command prompt:

  1. Change to the bin directory of the Oracle Java ME SDK distribution:

    C:\>cd Java_ME_platform_SDK_3.4\bin

  2. Enter the following command, as shown here:

    emulator.exe -Xdevice:Qualcomm_IoE_Device -Xdescriptor:location_of_jad_file

    For example:

    emulator.exe -Xdevice:Qualcomm_IoE_Device -Xdescriptor:C:\Java_ME_platform_SDK_3.4\apps\sample\sample_imlet.jad

This launches the Qualcomm_IoE_Device emulator, as shown in Figure 7-7.

Figure 7-7 The Qualcomm_IoE_Device Emulator

Description of Figure 7-7 follows
Description of "Figure 7-7 The Qualcomm_IoE_Device Emulator"

7.4.1 The External Events Generator

The tabs on the External Events Generator for the Qualcomm_IoE_Device emulator largely match those of the IMP-NG emulator. Those that differ are shown below.

7.4.1.1 The Serial Peripheral Interface (SPI) Tab

The Qualcomm_IoE_Device emulator External Events Generator SPI tab provides a sample accelerometer sensor, G-Sensor, as shown in Figure 7-8.

Figure 7-8 The External Events Generator SPI Tab

Description of Figure 7-8 follows
Description of "Figure 7-8 The External Events Generator SPI Tab"

The G-Sensor sample allows an IMlet to read accelerometer values from the emulator through the Serial Peripheral Interface. Move the slider of the X, Y, and Z acceleration scale to change the x, y, and z values transmitted over SPI. The minimum and maximum values for the sliders in the G-Sensor are defined by the Java ME application.

The G-Sensor sample duplicates in emulation the functionality of the digital, triaxial acceleration sensor on the Qualcomm Orion IoE embedded device. The acceleration sensor is used to sense tilt, motion, and shock vibration in embedded devices, such as medical instruments, computer peripherals, and monitoring devices.

7.4.1.1.1 The G-Sensor Fields

The G-Sensor has the following fields:

  • Range. Allows you to specify a range to be sensed.

  • Bandwidth. Allows you to specify a bandwidth to be sensed.

  • Accelerator-X. Allows you to select a value within a specified range by moving the slider position.

  • Accelerator-Y. Allows you to select a value within a specified range by moving the slider position.

  • Accelerator-Z. Allows you to select a value within a specified range by moving the slider position.

For more information on working with the Qualcomm Orion IoE embedded device, see the Oracle Java ME Embedded Getting Started Guide for the Reference Platform (Qualcomm Orion IoE).

7.4.1.2 The Inter-Integrated Circuit (I2C) Tab

The Inter-Integrated Circuit (I2C) tab displays information for the selected slave device, and data sent to and received from a master device. The Qualcomm_IoE_Device emulator External Events Generator I2C tab provides three sample sensors, as shown inFigure 7-9.

Figure 7-9 The External Events Generator I2C Tab with Available Sensors

Description of Figure 7-9 follows
Description of "Figure 7-9 The External Events Generator I2C Tab with Available Sensors"

The three sample sensors in the I2C tab are:

  • G-Sensor. Operates in the same way as described in the External Events Generator SPI tab. However, the sample IMLet reads the accelerometer values through the I2C interface. For more information, see "The Serial Peripheral Interface (SPI) Tab."

  • Light Sensor. Allows the user to test three kinds of light sensing: ambient light, proximity, and Infrared (IR). A lux value can be specified, and the values changed within the lux value range by moving the Light slider.

  • Temperature Sensor. High and Low temperature values can be set, and temperature values read when the slider is moved.

7.4.1.2.1 The Light Sensor Fields

The Light Sensor has the following fields:

  • Type. Three types of light sensing are possible:

    • Ambient Light. Allows changes in light brightness to be registered by the emulated sensor.

    • Proximity. Allows changes in light proximity (distance) to be registered by the emulated sensor.

    • Infrared (IR). Allows changes in infrared light to be registered by the emulated sensor.

  • Range. Four values of illuminance (luminous flux) are possible:

    • 1. (0.015 - 100 lux)

    • 2. (0.06 - 4000 lux)

    • 3. (0.24 - 16000 lux)

    • 4. (0.96 - 64000 lux)

  • Resolution. Allows, 4, 8, 12, or 16 bits.

  • Low Limit (lux). Defined by the value set in the Range field.

  • High Limit (lux). Defined by the value set in the Range field.

  • Interrupt Flag Set. If the user changes the sensor value and the new value is out of the High-Low Limits interval, the Interrupt Flag is set to Yes and the Java ME application reads the value. If the sensor values stay within the defined range, the Interrupt Flag is not set and the value is No. If the Interrupt Flag is set to Yes and the values returned within the defined range, the Interrupt Flag is reset to No.

  • Light (lux). Allows the user to define the lux value for the application by moving the slider. The high and low lux limits are defined by the value set in the Range field.

7.4.1.2.2 The Temperature Sensor Fields

The Temperature Sensor has the following fields:

  • Low Temperature Limit (Celsius). Defines a low temperature setting, beyond which a Limit Flag is tripped. Has a corresponding Limit Tripped field.

  • High Temperature Limit (Celsius). Defines a high temperature setting, beyond which a Limit Flag is tripped. Has a corresponding Limit Tripped field.

  • Limit Tripped. Applies to both High and Low Temperature fields. If the user moves the slider and the new value is outside the High or Low Limits, the Limit Tripped flag is set to Yes and the Java ME application reads the value in Status Register 1. When the Limit Tripped value is read in Status Register 1, the Limit Tripped flag is reset to No. If the slider values stay within the defined range, no Limit Tripped flag is set and the value is No.

  • Temperature (Celsius). Allows the user to define the temperature value for the application by moving the slider. The high and low temperature limits are defined by the value set in the Low Temperature and High Temperature fields.

The Temperature Sensor can operate in Default or Extended mode.

  • In Default mode, the user can change the temperature from 0 to 127 degrees Celsius.

  • In Extended mode, the user can change the temperature from -64 to 191 degrees Celsius.

To set the Default or Extended mode, use setDefaultMode() and setExtendedMode()in the Java ME application.

7.5 The CLDC Mobile Emulator

The Oracle Java ME SDK provides a Mobile emulator based on CLDC, as shown in Figure 7-10.

Figure 7-10 Emulator Features

Description of Figure 7-10 follows
Description of "Figure 7-10 Emulator Features"

7.5.1 CLDC Application Management System

The CLDC AMS home screen features three utilities:

  • Install Application. This utility opens a form in which you can specify a URL (or a file path) for a JAD file to install.

  • Manage Certificate Authorities. This feature displays the certificates authorities for the device. In this interface the white box indicates the certificate is checked (active). You can uncheck certificates that are not needed.

  • Output Console. The output console displays system output statements from a running application. The application must write to the Java standard output console using, for example:

    System.out.println("text");
    

    Start the emulator's Output Console, then start your application. Use F7, Switch running MIDlet, to switch between the application and the Output Console.

    Note that the emulator's Output Console is an application that consumes resources. If you get the message "No more concurrent applications allowed," you must close some applications before continuing.

    Figure 7-11 The Output Console Window

    Description of Figure 7-11 follows
    Description of "Figure 7-11 The Output Console Window"

See "The CLDC Mobile Emulator" and "Emulator Menu Settings."

You can also access system output information from the emulator by clicking the View menu and selecting Output Console..., which opens an Output Console dialog box. Select a filter from the drop down list to display specific system output. Click Save to save the output as a .log file.

7.5.2 Mobile Emulator Menus

Device Name. Shown in the upper window frame. See Table 8-1for a list of default emulator names.

Transmission Indicator. On the upper left of the emulator image, this blue light turns on when a transmission is occurring. Typically you see it when an application is installed over-the-air, or when a message is being sent or received. For example, when you receive a message from the WMA console.

Menus. See "Emulator Menu Settings."

Toolbar. For the CLDC emulator, the Toolbar provides shortcuts for the following operations:

  • Run MIDlet Suite

  • Install MIDlet Suite

  • Resume

  • Suspend

  • Rotate Clockwise

  • Rotate Counterclockwise

  • External Events Generator

  • Emulator window always on top

Device ID. Numerical identifier that is unique for each device.

Exit Button. On the upper right of the emulator image, is the termination button. Pushing this button the same effect as clicking Application and selecting Exit.

Emulator Status Bar. Information about the current system state is shown in the status bar at the bottom of the emulator window.

7.5.3 Running Projects Simultaneously on a Single Device

CLDC-based devices are capable of running multiple virtual machines. To test this feature, follow these steps:

  1. Display the Output window. Select Window > Output > Output.

    The Output window does not need to be open to run this procedure. You can open the Output window at any time to display all output from the beginning of the emulator session.

  2. Open the sample projects Games and AudioDemo.

  3. In the device selector, select a CLDC device and run Games. When the emulator launches, run AudioDemo on the same device.

    As each MIDlet loads, the AMS automatically installs it.

  4. In AudioDemo, launch the Audio Player, and play the JavaOne theme.

    Select AudioPlayer, then from the soft menu, select 1, Launch. Select JavaOne Theme and press the Play soft button.

  5. In the emulator, click the Application menu and select AMS Home, or press F4.

    Select Games. From the soft menu, select 1, Open. The music continues to play while you are able to simultaneously launch and play games.

  6. Click the Application menu and select AMS Home, or press F4. Highlight AudioSamples, and from the soft menu, select 2, Bring to foreground. Press the Pause soft key. The music stops playing.

  7. Click the Application menu and select AMS Home, or press F4. Highlight AudioSamples and from the soft menu, select 1, Open. Select Bouncing Ball from the list and press the Launch soft button. Select MIDI background and press the Play soft button.

  8. Click the Application menu and select AMS Home, or press F4. Then click the Application menu and select Switch Running MIDlet. Select Audio Player and press the Switch to soft button. You can press the Play soft button to resume the Audio Player.

7.6 Emulator Menu Settings

The Menus available on the three Oracle Java ME SDK emulators are very similar, with differing suboptions. The following tables describe the operations of each menu in more detail.

7.6.1 The Application Menu

The Application menu is fully populated for the CLDC platform. Table 7-1 describes the Application options:

Table 7-1 Emulator Application Menu

Option Accelerator Description

Install MIDlet Suite


Permanently add a MIDlet suite to the emulator.

Enter the path or URL of the MIDlet suite to install on the emulator. Select the desired level of the permissions in the Security Domain field.

Install IMlet Suite


Permanently add a IMlet suite to the emulator. (IMP-NG emulator)

Enter the path or URL of the IMlet suite to install on the emulator. Select the desired level of the permissions in the Security Domain field.

Run MIDlet Suite


Emulator interface for launching MIDlets.

Run IMlet suite


Emulator interface for launching IMlets. (IMP-NG platform)

AMS Home

F4

Exit the current application and return to the Application Management Software home. (CLDC emulator)

Stop

F10

Stops the currently running MIDlet. (CLDC emulator)

Change Locale


This option only works with localized MIDlets. (CLDC emulator)

Enter a locale identifier. The format is similar to Java SE 6, as follows:

2-letter-lang-code separator 2-letter-country-code

For example, en-US, cs-CZ, zh-CN, ja-JP. The separator can be a dash or an underscore.

Resume

F6

Resume a suspended application. (CLDC emulator)

Suspend

F5

Pause a running application. (CLDC emulator)

Do not use this option if you are running the memory monitor.

Switch Running MIDlet

F7

When you have multiple MIDlets running, toggle between them. You see a list of running MIDlets and you can chose the one you want to switch to. See "Running Projects Simultaneously on a Single Device" (CLDC emulator).

Exit

Exit button on emulator upper right

Close the emulator process and stop the build process (or processes).


7.6.2 The Device Menu

This menu is available on CLDC and IMP-NG platforms.

7.6.2.1 Messages

Click the Device menu and select Messages to see what is written in the message area. This is the emulator's Inbox. The Inbox displays WMA messages that are addressed to the device, not an application on the device. Messages are sent to this interface in the following cases:

  • An MMS message is sent without an AppID in the address

  • An SMS message is sent without a port in the address (or the port number is 0)

  • An SMS text message is sent with a port in the address, but there is not a Java ME application listening on the specified port

To test sending messages to the inbox use the WMA Console in NetBeans, or from the command line, use wma-tool.exe to send SMS messages. Note, wma-tool.exe requires an AppID for MMS, so wma-tool cannot be used to send an MMS.

7.6.2.2 Orientation

This option is only visible for the CLDC emulator.

Use this feature to test your application's ability to display in portrait and landscape formats. The default is 0 degrees. Change the orientation to 90, 180, or 270 degrees. You can also rotate 90 degrees clockwise (F8) or counterclockwise (F9) from the current position.

7.6.3 The Edit Menu

Table 7-2 describes the Edit menu, which provides basic editing operations for the CLDC platform.

Table 7-2 Emulator Edit Menu

Option Accelerator Description

Copy

CTRL-C

Copy selected material to the paste buffer.

Cut

CTRL-X

Move selected material to the paste buffer.

Paste

CTRL-V

Insert the contents of the paste buffer.


7.6.4 The Tools Menu

Table 7-3 describes the utilities accessible from the Tools menu.

Table 7-3 Emulator Tools Menu

Option Description

Manage Landmarks

Opens the Landmark Store utility.

In this interface, you can view and edit a landmark store installed as part of an application. You can also create a new landmark store, define landmarks, define landmark categories, and assign landmarks to categories.

Manage File System

Opens the File System manager and displays the mounted file system root directories.

You can mount or unmount a file system directory, copy a mounted file system directory, remount or remove directories. For a description of managing a file system, click the Tools menu and select Manage File System. Click Help in the dialog box.

External Events Generator

Opens the External Events Generator.

The External Events Generator provides a way to interact with an application by injecting events. The interaction may be through a user interface, or through a script file.

For a description of the External Events Generator, see "The External Events Generator."

Take Screenshot

Takes a screenshot of the emulator display screen and saves it to the clipboard. (CLDC emulator)


7.6.5 The View Menu

Table 7-4 describes the View menu, which is available for the CLDC, CDC, and IMP-NG platforms.

Table 7-4 Emulator View Menu

Option Description

Always On Top

Keeps the emulator in the foreground.

This option is especially useful when you are running multiple emulator instances and you want to see them all and send messages between devices.

Output Console

Displays system output statements from a running application in the Output Console window.

You can filter the output statements for IMP-NG emulators by selecting All, Standard, or Error from the Show dropdown list. Error messages are highlighted.

Filtering of output statements and highlighting of error messages are not available for CLDC emulators or external devices.

You can save system output information to a .log file by clicking Save in the window.

Device Log

Displays emulator log messages in the Device Log window.

The following filters are available from the Level dropdown list:

  • Trace - Tracing information, such as garbage collection, exceptions, and method calls.

  • Debug - General debugging information.

  • Info - Information messages.

  • Warn - Alerts that issues were encountered during runtime. Warnings are highlighted.

  • Error - Errors encountered during runtime but do not prevent the application from running. Error messages are highlighted.

  • Fatal - Non-recoverable errors that can potentially prevent the application from running and might cause the application to quit.

You can save system output information to a .log file by clicking Save in the window.


7.6.6 The Help Menu

The Help menu displays an abbreviated helpset specifically for the emulator window.

7.7 Using the Device Selector

The Device Selector lists the devices currently available in NetBeans, grouped by platform, as shown in Figure 7-12.

If the Device Selector is not visible, click on the Device Selector tab, or select Tools > Java ME > Device Selector.

Figure 7-12 The Device Selector

Description of Figure 7-12 follows
Description of "Figure 7-12 The Device Selector"

The list in the Device Selector matches the list displayed in the Registered Devices window.

7.7.1 Viewing Device Properties

If no Java ME platform is registered in NetBeans, the Device Selector displays a node labeled No Device Found. If you see this message at startup, it typically means device discovery is incomplete and you must wait a few seconds.

Each sub node represents a device. Two instances are provided for some CLDC devices, for example, JavaMEPhone1 and JavaMEPhone2. Instances of the same device have the same capabilities but unique names and phone numbers, making it easy for you to test communication between devices of the same type. To make your own device, see "Using the Custom Device Editor."

For Device names, see "Oracle Java ME SDK Directories." The properties for each device are stored in XML files in your user work directory. See Table 8-1.

7.7.1.1 Platform Properties

To view platform properties from the device selector, click on the platform node (for example, CLDC or IMP-NG). The Properties window is, by default, docked in the upper right portion of the user interface. If the Properties window is not visible, click the Windows menu and select Properties.

To view the platform properties in a separate window, right-click the platform node and select Properties. This displays a Properties window for the selected device, as shown in Figure 7-13.

Figure 7-13 Separate Device Properties Window

Description of Figure 7-13 follows
Description of "Figure 7-13 Separate Device Properties Window"

The information in the docked properties window and the separate window is the same.

7.7.1.2 Device Information

In the Device Selector window, double-click a device node. The Device Information tab opens in the central Main window. It displays a picture of the device and displays details, supported hardware capabilities, keyboard support, supported media formats, and the supported runtimes.

7.7.1.3 Device Properties

In the Device Selector window, click a device node (such as JavaMEPhone1) to display the device properties. The Properties window is, by default, docked in the upper right portion of the user interface. If the Properties window is not visible, click the Windows menu and select Properties.

7.7.2 Setting Device Properties

In the Device Selector window, right-click a device and select Properties. Any properties shown in gray font cannot be changed. You can adjust the device properties shown in black. Only CLDC and IMP-NG options can be adjusted. The CDC options cannot be changed.

7.7.2.1 General Device Properties

This section lists general properties that can be changed.

Phone Number. You can set the phone number to any appropriate sequence, considering country codes, area codes, and so forth. If you reset this value, the setting applies to future instances. The number is a base value for the selected device.

Heapsize. The heap is the memory allocated on a device to store your applications's objects. The Heapsize property is the maximum heap size for the emulator. You can select a new maximum size from the drop down menu.

Security Domain. Select a security setting from the drop down menu. See "Specify the Security Domain for an Emulator." Applies to CLDC platforms.

JAM storage size in KB. The amount of space available for applications installed over the air.

Locale. Type in the locale as defined in the MIDP 2.1 specification at:

http://download.oracle.com/otndocs/jcp/midp-2.1-mrel-oth-JSpec

Remove MIDlet Suite in execution mode. If this option is enabled, record stores and other resources created by the MIDlet are removed when you exit the MIDlet (assuming the MIDlet was started in execution mode).

7.7.2.2 Monitor

If enabled (checked), the Check boxes for Trace GC (garbage collection), Trace Class Loading, Trace Exceptions, and Trace Method Calls activate tracing for the device the next time the emulator is launched. The trace output is displayed at runtime in the user interface Output window. Trace Method Calls returns many messages, and emulator performance can be affected. See Chapter 11, "Monitoring Memory."

7.7.2.3 IMP-NG Device Properties

When you create a new IMP-NG device using the Custom Device Editor (Run > Custom Device Editor) you can use the default implementation or create your own custom implementation for the interfaces discussed in this section.

See the following resources for in-depth descriptions of the IMP-NG interfaces or devices:

  • Device Access API (installdir\docs\api\deviceaccess)

  • Embedded Support API (installdir\docs\api\embedded-support-api)

  • For more information about default devices and their properties, you can use the Properites View from the Device Selector. For more information, see "Viewing Device Properties."

7.7.2.3.1 General Purpose Input Output (GPIO)

A GPIO port is a platform-defined grouping of GPIO pins that may be configured for output or input. Output ports are both writable and readable while input ports are only readable. Note that GPIO pins that are part of a GPIO port cannot be retrieved nor controlled individually as GPIO Pin instances.

Click Add Port to add entries to the Ports table. Each item in a Ports table row is editable. Check Output to set the port direction to output.

A GPIO pin may be configured for output or input. Output pins are both writable and readable while input pins are only readable. Note, an input listener can only be assigned to a pin set for input.

Click Add Pin to add a row to the Pins table. The ID and name are editable. Click Output to make a pin both readable and writable. Click in the Initial Value column to toggle the Initial Value from Low to High.

7.7.2.3.2 Inter-Integrated Circuit (I2C) and Serial Peripheral Interface (SPI)

The process for configuring I2C and SPI interfaces is very similar.

On an I2C bus, data is transferred between the I2C master device and an I2C slave device through single or combined messages. On an SPI bus, data is transferred between the SPI master device and an SPI slave device in full duplex. That is, data is transmitted by the SPI master to the SPI slave at the same time data is received from the SPI slave by the SPI master. See the Embedded Support API for more details.

  • Select Sample Echo to select the default bus implementation. This default implementation simply reads buffered written data from the slave.

  • Select Custom to specify your own bus implementation.

    1. Supply your bus implementation JAR file and the name of the Java class that implements the bus.

      For I2C, the bus is:

      com.oracle.jme.toolkit.deviceaccess.i2c.I2CSlaveBus

      For SPI, the bus is:

      com.oracle.jme.toolkit.deviceaccess.spi.SPISlaveBus

    2. To add Slaves, click Add and specify an ID and Name. For SPI, specify the Word Length as well.


Note:

On an SPI bus, data is transferred between the SPI master device and an SPI slave device in full duplex. So every com.oracle.deviceaccess.spibus.SPIDevice.read(...) method also writes an array of zeros to the slave device. The length of this array equals a length of read data. In the default implementation this array of zeros is appended to the loopback's buffer.


7.7.2.3.3 Memory-Mapped I/O (MMIO)

The default devices are described in "The External Events Generator."

If you want to provide your own MMIO emulation, you must specify a custom handler.

Supply your implementation JAR file and the name of the Java class that implements com.oracle.jme.toolkit.deviceaccess.mmio.MMIOHandler. For comparison, the default JAR file is:

installdir\toolkit-lib\devices\IMPNGDevice\code\emulator_deviceaccess_mmio-sample-handler.jar

To add devices to the custom MMIO implementation, use the Devices and Device Memory tables as follows:

  1. Click Add Device to add a row to the Devices table.

    • A default ID is assigned but you can double-click in the ID column to edit the value.

    • A default Name is supplied, but it can also be edited.

    • In the Byte Ordering column, make a selection from the drop down list.

  2. Click a row in the Device table to select a Device.

  3. Click Add Memory.

    • In the Type column, make a selection from the drop down list. Double-click to edit the Address column entries.

      If the type is Block, you can double-click to edit the Size column entries as well as the Address column entries.

  4. Click OK.

7.7.2.4 Location Provider #1 and #2

These properties determine the selection of a location provider. Two providers are offered so that your application can test matching the location provider criteria.

If you select a property a short explanation is shown in the description area just below the Properties table. For more information on these values, see the Location API at:

http://jcp.org/en/jsr/detail?id=179.

7.7.2.5 SATSA

For more information on working with Security and Trust Services (SATSA), see Chapter 20, "JSR 177: Smart Card Security (SATSA)."

7.7.2.6 Bluetooth and OBEX

For more information on working with Bluetooth and Object Exchange (OBEX), see Chapter 17, "JSR 82: Bluetooth and OBEX Support."

7.7.3 Running a Project from the Device Selector

The SDK determines which open projects are suitable for a device. Right-click the device and select a project from the context menu.

You can also launch the emulator to run a project from the command line, as explained in "Emulator Command Line Options."+

7.8 Using the Custom Device Editor

With the Custom Device Editor you can create your own devices. The appearance of the custom devices is generic, but the functionality can be tailored to your own specifications. The Custom Device Editor is shown in Figure 7-14.

Figure 7-14 The Custom Device Editor

Description of Figure 7-14 follows
Description of "Figure 7-14 The Custom Device Editor"

7.8.1 Creating a Custom Device

Follow these steps to create a custom device.

  1. Select Tools > Java ME > Custom Device Editor.

    The custom device tree displays Java ME platforms and custom devices, if any.

    Alternatively, you can launch the Custom Device Editor from the your installation's bin directory. For example:

    C:\Java_ME_platform_SDK_3.4\bin\device-editor.exe

    The custom device tree displays Java ME platforms and custom devices, if any.

  2. Select a platform and click the New... button.

  3. Change the default configuration to match your specifications, and click OK.

Your device is added to the custom device tree and eventually appears in the Device Selector. You can run projects from the IDE or from the command line from the custom device.

The custom device tree affects what appears in the Device Selector. For example, if you do not want a custom device to appear in the device selector, you must remove it from the custom device tree.

The device definition is saved in installdir\toolkit-lib\devices.

7.8.2 Managing Custom Devices

Custom devices should always be managed using the Custom Device Editor. Using the tool ensures that your device can be detected and integrated with the Oracle Java ME SDK.

  • New. Select a platform and click New to add a new device.

  • Edit. Select a device to change, and click Edit.

  • Clone. Select a device to copy, and click Clone. To prevent confusion, be sure to provide a unique name.

  • Remove. Select a device to delete and click Remove. This action completely deletes the device.

  • Import. Select a node in the custom device tree and click Import. Select a .zip file created with the Export command.

  • Export. Select a device to save, and click Export.

    When a custom device is created it is saved in installdir\toolkit-lib\devices, therefore you could lose your device if you reinstall.

    An exported device is stored in a .zip file and saved in the user's My Documents directory (typically username\My Documents).

7.9 Making Device Connections

The configuration of all peripherals, except UART, can be inspected in the emulator main window. The configuration of UART is defined by the hardware configuration of the COM ports on your Windows XP or Windows 7 PC.

For more information on connecting to a UART Device, see "Connecting to a UART Device."

To open a serial port, such as COM1 or COM2, in Windows you can use the Device Address Manager. In application code, you can use Connector.open("comm:COM1")

7.9.1 Connecting to a UART Device

To utilize the Universal Asynchronous Receiver/Transmitter (UART) functionality, you need to create a configuration file (for example UARTConfig.xml). The configuration file defines the device ID and Name, and the Name must point to a real serial port name defined by the operating system. For example,

deviceaccess.uart.dev14.name = COM1

For an already opened UART, you can add it to the peripheral manager by calling PeripheralManager.open with the configuration object.