Oracle® Java ME Embedded Getting Started Guide for the Reference Platform (Qualcomm IoE) Release 8 E48513-03 |
|
Previous |
Next |
This chapter describes how to install and run an IMlet on the board, as well as how to debug an IMLet in NetBeans.
Note: The term IMlet, in the context of the Oracle Java ME Embedded command-line interface (CLI) and references in this chapter, is synonymous with MIDlet. |
The Oracle Java ME Embedded platform offers the following tools for managing and monitoring the Qualcomm IoE board:
A CLI via a terminal emulator program for Application Management System (AMS) commands and for system configuration commands
A logging interface for obtaining JVM diagnostic information using a console window
On-Device Tooling (ODT): the ability to install, run, and debug applications from the desktop using the NetBeans IDE
The CLI is integrated in the Developer Agent program that can be found as a JAR file inside the util
directory of the Oracle Java ME Embedded distribution, named proxy.jar
. The Developer Agent program can also be used to access the Java Logger output.
There are two options for tooling with the Qualcomm IoE embedded board.
Start the Developer Agent program manually as described in Starting the Developer Agent Program Manually.
The CLI is available through a PuTTY terminal window on port 65002 (see Using the Command-Line Interface.)
The Java Logging is available through a console window used for running the Developer Agent (see Obtaining Java Logs from a Device.)
Start the Oracle Java ME Embedded SDK (see Installing and Configuring the Oracle Java ME SDK 8.)
The CLI is available through a PuTTY terminal window on port 65002 (see Using the Command-Line Interface.)
The Java Logging is available via the Output window of the Oracle Java ME Embedded Emulator included with the Oracle Java ME Embedded SDK (see Obtaining Java Logs from a Device.)
Note that tooling works over one physical channel. However, the CLI, logging, and ODT functions all use different ports. The ports for CLI and logging are available to the user, and will be discussed later in this chapter. However, the ports used for ODT are invisible to the user, and used by external development tools.
Start the Developer Agent program manually only if you want to use the CLI or connect to the Java Logger and do not wish to use the Oracle Java ME Embedded SDK.
Open a console window and go to the util
directory of the Oracle Java ME Embedded distribution.
Enter the following command, specifying the COM port that corresponds to the Qualcomm IoE HT-USB Serial Port, as reported earlier by the Windows Device Manager:
java -jar proxy.jar -serial COM22
If you have trouble with running the Device Manager, please see Chapter 3, "Troubleshooting."
To connect to the Java logger, start the Developer Agent program on your desktop computer as described in Starting the Developer Agent Program Manually.
After you are connected, you should see output from the Java Logger.
Connecting to the Java logger displays the logging information from only the Oracle Java ME Embedded platform. However, you can use the Brew MP SDK Logger application, as shown in Chapter 1, to capture logging output from both the Oracle Java ME Embedded system and the Qualcomm IoE board.
The command-line interface is used to issue commands directly to Java runtime.
Note that only one instance of the Developer Agent program must be running.
If you are using the Oracle Java ME Embedded SDK, then ensure that the Oracle Java ME SDK 8 Device Connections Manager has already successfully detected the device, as shown earlier in Figure 1-5.
If you do not use the Oracle Java ME Embedded SDK, start the Developer Agent program as described in Starting the Developer Agent Program Manually.
To use the command-line interface, start a PuTTY executable file on your desktop computer. Use this to create a Raw network connection to the address 127.0.0.1 with the port 65002, as shown in Figure 2-1.
Figure 2-1 PuTTY Configuration for CLI Connection
The window from the connection provides a CLI, and is shown in Figure 2-2.
Figure 2-2 Oracle Java ME Embedded Command-Line Interface
Caution: The CLI feature in this Oracle Java ME Embedded software release is provided only as a concept for your reference. It uses connections that are not secure, without encryption, authentication, or authorization. |
You can use the command-line interface to run numerous AMS and system commands, as shown in Table 2-1, Table 2-2, and Table 2-3.
Table 2-1 AMS CLI Commands
Syntax | Description |
---|---|
|
List all installed IMlet suites and their status or MIDlets in a specific suite. |
|
Install an IMlet using the specified JAR or JAD file, specified as a URL. An optional user name and password can be supplied for login information either in the URL or by the |
|
Update the specified suite. |
|
Remove the specified suite. |
|
Run a default suite's MIDlet or the MIDlet specified with |
|
Stop a default suite's MIDlet or the MIDlet specified with the |
|
Show information about the specific MIDlet. |
You can use the properties commands summarized in Table 2-2 and file system commands summarized in Table 2-3.
Table 2-2 Security and Properties Commands
Syntax | Description |
---|---|
|
List the available commands or detailed usages for a single command. |
|
Show the list of names of properties which control the Oracle Java ME Embedded runtime (properties that are set in the |
|
Set a property identified by |
|
Return a value of the property identified by |
|
Save properties to an internal storage. |
|
Blacklist clients and applications. |
Table 2-3 File System Commands
Syntax | Description |
---|---|
|
Change the working directory on the device. |
|
Delete a file on the device. |
|
Copy a file from the device to the host. |
|
Display a list of files and subdirectories in a device directory. In a result listing, subdirectories are marked with a trailing file separator symbol, such as "\" on Windows. |
|
Create a directory on the device. |
|
Write the current working directory on the device. |
|
Copy a local host file to the device. |
The CLI supports working with multiple devices. You can use the device commands summarized in Table 2-4
Table 2-4 Device Commands
Syntax | Description |
---|---|
|
List all connected devices. |
|
Make the specified device current. |
|
Perform either a shutdown of the board or a reboot if the |
|
Terminate the current CLI session. |
You can use the keystore commands summarized in Table 2-5.
Table 2-5 Keystore Commands
Syntax | Description |
---|---|
|
Delete a key from a ME store. |
|
Export a key from a device keystore by index. |
|
Import a public key from a JCE keystore into a ME keystore. |
|
List the owner and validity period of each key in a ME keystore. |
Qualcomm IoE board supports the following network related commands, as shown in Table 2-6.
Table 2-6 Qualcomm IoE Specific Commands
Syntax | Description |
---|---|
|
Show the network information of the system. |
|
Set the SSID value for WiFi access. |
|
Set the password for WiFi access. |
|
Set the network mode preferences. Possible values are: 0: AUTO, 1: NO OP, 2: WLAN Only, 3: GSM/WCDMA only, 4: WCDMA only, 5: GSM/WCDMA/WLAN |
|
Set the APN. |
|
Set the APN's auth type: 0: NONE, 1: PAP, 2: CHAP |
|
Reset the PDP user name. |
|
Reset the PDP password. |
|
Reconnect the network and reboots Java. |
Here is a typical example of using the AMS to install, list, run, and remove an Oracle Java ME Embedded application on the board. Note that /Shared
is a root directory name that can be accessed from Java. Files can be placed in this directory with the help of Qualcomm's Loader tool. However, in the Loader tool, this directory is named shared
. For more information about mapping the virtual root directory names, see Virtual Root Paths.
COM22@115200>> ams-install file:////Shared/hello.jar <<ams-install,start install,file:///Shared/hello.jar <<ams-install,install status: stage 0, 5% <<ams-install,install status: stage 3, 100% <<ams-install,install status: stage 4, 100% <<ams-install,OK,Install success COM22@115200>> ams-install http://www.example.com/netdemo.jar <<ams-install,start install,http://www.example.com/netdemo.jar <<ams-install,install status: stage 0, 5% <<ams-install,install status: stage 3, 100% <<ams-install,install status: stage 4, 100% <<ams-install,OK,Install success COM22@115200>> ams-install http://www.example.com/notthere.jar <<ams-install,start install,http://www.example.com/notthere.jar <<ams-install,FAIL,errorCode=103 (OTHER_ERROR)
Note that the final installation example failed with an error code and matching description.
Similarly, install an additional IMlet: rs232dem
. After an IMlet is installed, verify it using the ams-list
command. Each IMlet has been assigned a number by the AMS for convenience.
COM22@115200>> ams-list <<ams-list,0.hello|Oracle,STOPPED <<ams-list,1.netdemo|Oracle,STOPPED <<ams-list,2.rs232dem|Oracle,RUNNING <<ams-list,OK,3 suites are installed
You can use the ams-remove
command to remove any installed IMlet.
COM22@115200>> ams-remove 0 <<ams-remove,OK,hello removed
The results can again be verified with the ams-list
command.
COM22@115200>> ams-list <<ams-list,1.netdemo|Oracle,STOPPED <<ams-list,2.rs232dem|Oracle,RUNNING <<ams-list,OK,2 suites are installed
Finally, start the IMlet using the ams-run
command. The application can be terminated with the ams-stop
command.
COM22@115200>> ams-run 1 <<ams-run,OK,started
COM22@115200>> ams-list <<ams-list,1.netdemo|Oracle,RUNNING <<ams-list,2.rs232dem|Oracle,RUNNING <<ams-list,OK,2 suites are installed
To check the current WiFi settings of the board, use the net-info
command.
COM22@115200>> net-info <<net,info,Address=192.168.1.103 <<net,info,SSID=network001 <<net,info,Preference=0 <<net,info,PDP APN=wap.cingular <<net,info,PDP Auth Type=0 <<net,info,PDP Auth Username=user <<net,info,PDP Auth Password=password <<net,info,OK,success getting info
Virtual root paths are used for access from IMlets. To get access from the Qualcomm tools, these root names are mapped to physical directories as shown in Table 2-7.
WiFi access must first be configured using the CLI. Connect to the CLI using the instructions in the section Using the Command-Line Interface and perform the following steps:
Set the SSID of the WiFi network using the command: net-set ssid
{SSID Name}
Set the security password of the SSID network using the command net-set passwd
{WiFi Password}. This is necessary only if the security of the WiFi network is enabled.
Enter the net-reconnect
command to apply the settings. Note that the Oracle Java ME SDK 8 Device Connections Manager will temporarily lose its connection to the Qualcomm IoE device while it resets.
After you have completed these steps, you can verify the settings on the board by connecting to the CLI and performing the following command: net-info
If the IP address is 0.0.0.0
, then the connection to the WiFi network was not established successfully; check the network settings and try again. If the SSID and password of the network are correct, then try to reset the board to reinitialize the WiFi. You can use "IP Address Periodic Logging" feature to see the IP address that has been assigned.
Note: Each time you make a connection to the Java Logger with the Developer Agent program, you will see logs labeled with the |
If you see a valid IP address, then the network is configured successfully.
Finally, restart Java again using the net-reconnect
command and connect to port 65000 and 65002 using the IP address that has been assigned to the board.
The Oracle Java ME Embedded implementation has the ability to log the IP address that has been assigned to the board. The log can be seen through a console window and Brew MP Logger application.
The behavior of this feature is controlled by the com.oracle.periodic.logging.interval
property that accepts the values counter in milliseconds. By default, the logging period is set to 10 seconds (10000 milliseconds.) To disable the periodic logging, set the value of the property to 0.
To run the signed IMlets on the IoE board, ensure that the system time is set on the board.
By default, the system time on the IoE board is set automatically by the operating system. Because the current time is obtained from a cellular network, a SIM card must be plugged in to the board's SIM-card slot.
However, an automatic setup does not work in the following cases:
A SIM card is not available.
A network carrier does not provide the current time data.
If there are any problems with the automatic setup, then set the system time manually either by using the CLI or editing the jwc_properties.ini
file.
Manual Setup of the System Time Using CLI
Open the CLI.
Run the following commands:
set-property system.time.value yyyy/mm/dd hh:mm:ss GMT set-property system.time.update true
Execute either the save-properties
with a subsequent board restart or shutdown -r
command. In the latter case, the property values will be saved automatically.
Manual Setup of the System Time in the jwc_properties.ini
file
Edit the following properties:
system.time.value = yyyy/mm/dd hh:mm:ss GMT system.time.update = true
Restart Java on the Qualcomm IoE board.
Note: The dates before the GPS epoch, such as 06.01.1980 00:00:00, are not supported due to the Brew MP API restrictions. |
You can configure a network type of an access point to connect to and other specific access point preferences by using the system.network.*
, system.wlan.*
, and system.netsetup.*
properties.
An ability to reconnect to a WiFi access point is controlled by the following WiFi rescanning process properties:
system.netsetup.wifi.rescan.enabled
if true
, then Java starts rescanning the WLAN to find an access point with the SSID specified by the system.wlan.ap.ssid
property in the following cases:
upon the board's startup, if the access point with specified SSID is not available and system.network.pref
property is set to 2
when an access point with the specified SSID becomes unavailable and system.network.pref
property is set to 5, 2, or 0 (AUTO
)
if false
, the Java makes no attempts to reconnect to an access point. However, the Brew MP operating system might try to reconnect to the previously connected access point at some unknown time.
system.netsetup.wifi.rescan.timeout
: a frequency in millis with which the WiFi rescanning occurs if the access point with the specified SSID is not available
system.netsetup.wifi.rescan.attempts:
a number of attempts during which Java tries to reconnect to the access point with the specified SSID
After the connection to a 3GPP network was lost and then restored, there is no guarantee that the 3GPP network becomes available to the application. An ability to reconnect to a 3GPP system access point is a network carrier-specific.
Note that Java starts with a delay that depends on a network initialization.
Installing and running IMlet projects on the Qualcomm IoE board using the NetBeans IDE requires the following software:
NetBeans IDE 8.0 with Oracle Java ME, which can be downloaded from https://netbeans.org/
.
Oracle Java ME SDK 8
Oracle Java ME SDK 8 NetBeans Plug-in
After installing NetBeans, follow these steps to install the remaining software:
Ensure that Oracle Java ME is enabled in NetBeans. This can be done by clicking Tools then Plugins and clicking the Installed pane. Activate the Java ME plugin if it is not already activated.
Install the Oracle Java ME SDK 8 distribution, if you have not done so already. See the Oracle Java ME SDK Developer's Guide for details.
Install the Oracle Java ME SDK 8 NetBeans plug-in. This is a downloadable ZIP file that consists of a number of NetBeans modules (.nbm
files) that can be added by clicking Tools then Plugins. Select the Downloaded pane. Unzip the plugin file, and add all of the.nbm
files to NetBeans. The Oracle Java ME SDK 8 NetBeans plug-ins are required to interface with the Device Selector and connect to the board.
Ensure that the Oracle Java ME SDK 8 appears in the list of Java ME platforms. In the NetBeans IDE, click Tools then Java Platforms. If the Oracle Java Platform Micro Edition SDK 8 does not appear in the list of Java ME platforms, then follow these steps:
Click Add Platform.
Select Java ME CLDC Platform Emulator and click Next.
Select the folder where the Oracle Java ME SDK 8 distribution resides and follow the instructions to install it. Then, click Finish to close the dialog.
Ensure that the Qualcomm IoE board has the Oracle Java ME Embedded distribution. See Chapter 1, "Installing Oracle Java ME Embedded Software on the Qualcomm IoE Board" for more information about how to install the runtime distribution on the Qualcomm IoE board.
If you already have an existing NetBeans project with an IMlet that you want to run or debug on the board, then follow these steps:
Right-click your project and select Properties.
Select the Platform category on the properties window.
Select the entry that represents the board (EmbeddedExternalDevice1) from the device list.
If you are creating a new NetBeans project, then follow these steps:
Click File then New Project.
Select the Java ME Embedded category and Java ME Embedded Application in the Projects list. Click Next.
Provide a project name and click Next. Ensure that the Create MIDlet option is selected.
Ensure that the Java ME platform is Oracle Java Micro Edition SDK 8.0. Then, select the entry that represents the board (EmbeddedExternalDevice1) from the device list and click Finish.
The configured Platform dialog is shown in Figure 2-3. After you assign the board to your project, the IMlets run on the board instead of on the emulator when you click Run Project on the NetBeans IDE.
Figure 2-3 NetBeans Platform Properties Dialog
After the project is created, use the following source code for the default IMlet.java
source file.
package embeddedapplication1; import jdk.dio.DeviceManager; import jdk.dio.gpio.GPIOPin; import java.io.IOException; import javax.microedition.midlet.*; public class EmbeddedApplication1 extends MIDlet { public void startApp() { try { GPIOPin pin = (GPIOPin)DeviceManager.open(14); for (int i = 0; i < 10; i++) { pin.setValue(true); Thread.sleep(1000); pin.setValue(false); Thread.sleep(1000); } pin.close(); } catch (IOException ex) { ex.printStackTrace(); } catch (InterruptedException ex) { ex.printStackTrace(); } } public void pauseApp() { } public void destroyApp(boolean unconditional) { } }
This sample code gets an object that represent GPIO pin 14 from the DeviceManager
instance, and sets it from low to high at intervals of one second. This has the effect of blinking one of the LEDs on the Qualcomm IoE board. For more information about using the Device I/O APIs, see the Device I/O API 1.0 specification at:
Follow these steps to debug an IMlet using NetBeans:
Open your IMlet class on the NetBeans editor.
Click once directly on the line number where you want to set a breakpoint. The line number is replaced by a red square and the line is highlighted in red.
Click Debug then Debug Project or use the Debug button on the toolbar.
The debugger connects to the debug agent on the board and the program stops running at your breakpoint, as shown in Figure 2-4.
Figure 2-4 Debugging an IMlet on the Qualcomm IoE Board Using NetBeans
Figure 2-4 shows an entire NetBeans debugging environment that allows the programmer to run a program step-by-step, as well as add and remove variables from a watch list on the bottom of the screen.
For more information about using the Device I/O APIs, see the Device I/O API 1.0 specification at:
Applications that require access to Device I/O APIs must request appropriate permissions in JAD files. For more information about using the Device I/O APIs, please see the Device I/O API 1.0 specification at:
http://docs.oracle.com/javame/8.0/api/dio/api/index.html
First, the JAD file must have the proper API permissions. Follow these steps how to sign the application both in NetBeans and without an IDE:
In NetBeans, right-click the project name (ME8EmbeddedApplication1 in this example) and select Properties.
Click Application Descriptor, then in the resulting pane, click API Permissions.
Click the Add button, and add the jdk.dio.DeviceMgmtPermission
API, as shown in Figure 2-5.
Click OK to close the project properties dialog.
Figure 2-5 Adding API Permissions with NetBeans
If you are not using an IDE, then manually modify the application descriptor file to contain the following permission:
MIDlet-Permission-1: jdk.dio.DeviceMgmtPermission "*:*" "open"
This NetBeans IDE enables developers both to sign the applications with a local certificate and upload the certificate on the device. Use the following procedure.
Right-click the project name and select Properties.
Under the Build category, click Signing.
Select the Sign JAR check box and specify a certificate to sign with as shown in Figure 2-6.
Figure 2-6 Signing Application JAR with NetBeans
Note: The selected certificate must be uploaded on the device and associated with the security client. |
Click the Open Keystores Manager button.
Select the key and click Export as shown in Figure 2-7.
In the Export Key window, select the EmbeddedExternalDevice1, select the certificate, and click Export as shown in Figure 2-8.
Download the _policy.txt
file from the /sys/mod/java/appdb
directory of the Qualcomm IoE board and add a section with the client name and a set of permissions. For more information about the policy file format, see the External Client Policy Format section in the Java ME Embedded Profile 8 specification.
Ensure that the certificate with the specified common name (CN) is associated with the client by adding a section similar to the following one.
client Signed [C=US,O=manufacturer CA,OU=TCK,CN=thehost]
Copy the modified _policy.txt
file back to the /appdb
directory on the Qualcomm IoE board.
This method is the preferred route for applications that are widely distributed. Follow these steps to set up a keystore with a local certificate that can be used to sign the applications:
Generate a new self-signed certificate with the following command on the desktop, using the keytool
that is shipped with the Java SE JDK:
keytool -genkey -v -alias mycert -keystore mykeystore.ks -storepass spass -keypass kpass -validity 360 -keyalg rsa -keysize 2048 -dname "CN=thehost"
Note: You must specify the full host name in the |
This command generates a 2048-bit RSA key pair and a self-signed certificate, placing them in a new keystore with a keystore password of spass
and a key password of kpass
that is valid for 360 days. You can change both passwords as desired.
Copy the appdb/_main.ks
keystore file from the Qualcomm IoE over to the desktop using the Loader tool. Run the following command with the mekeytool.exe
command (or alternatively java -jar MEKeyTool.jar...
if your distribution contains only that) that ships with the Oracle Java ME SDK 8 distribution:
{mekeytool} -import -MEkeystore _main.ks -keystore mykeystore.ks -storepass spass -alias mycert -domain trusted
This command imports the information in mykeystore.ks
that you just created to the _main.ks
keystore. After this is completed, copy the certs
directory back to the Qualcomm IoE board using the Loader tool.
Use the following commands to sign your application before deploying it to the Qualcomm IoE board:
jadtool -addcert -chainnum 1 -alias myalias -keystore mykeystore.ks -storepass spass -inputkad myjad.jad -outputjad myjad.jad
jadtool -addjarsig -chainnum 1 -jarfile myjar.jar -alias myalias -keystore mykeystore.ks -storepass spass -keypass kpass -inputjad myjad.jad -outputjad myjad.jad
This method allows you to bypass a certificate check and run unsigned applications as if they were signed and given all requested permissions. This method should be used only for development and debugging. Final testing must be done using a real certificate as described in method #1.
To use NullAuthenticationProvider
, set the following property in the jwc_properties.ini
file on the Qualcomm IoE board:
[internal] authentication.provider = com.oracle.meep.security.NullAuthenticationProvider
Restart the Java runtime.
If you are not using an IDE, then you can still use the Oracle Java ME Embedded 8 CLI to install an application. Connect to the device at port 65002, and install and run the IMlet manually. For example:
COM22@115200>> ams-install file:///Shared/hello.jar <<ams-install,start install,file:///Shared/hello.jar <<ams-install,install status: stage 0, 5% <<ams-install,install status: stage 3, 100% <<ams-install,install status: stage 4, 100% <<ams-install,OK,Install success
COM22@115200>> ams-list <<ams-list,0.hello|Oracle,STOPPED <<ams-list,OK,1 suites are installed
COM22@115200>> ams-run 0 <<ams-run,OK,started
COM22@115200>> ams-list <<ams-list,o.hello|Oracle,RUNNING <<ams-list,OK,1 suites are installed
See "Using the Command-Line Interface" for more details.
There are multiple ways in Oracle Java ME 8 to obtain a device log. Three ways to view the device log are:
Using an SDK Output Console window.
Using the NetBeans IDE:
Run the NetBeans IDE.
Select an IMlet in the Projects window and run it.
The NetBeans IDE opens the EmbeddedExternalDevice1 window.
Click the Output button. The log is available in the SDK EmbeddedExternalDevice1 Output Console window shown in Figure 2-9.
Figure 2-9 Java Logging Through the SDK Output Console Using NetBeans IDE
Without the NetBeans IDE:
Run the SDK Device Connections Manager located at <SDK Installation Folder>/bin
/device-manager.exe
.
Wait until the device connection status displays Connected.
Run the SDK EmbeddedExternalDevice1 by using the following command:
emulator.exe -Xjam -Xdevice:EmbeddedExternalDevice1
Install and run an IMlet using the GUI of the SDK EmbeddedExternalDevice1 window.
Click the Output button. The log is available in the SDK EmbeddedExternalDevice1 Output Console window shown in Figure 2-10.
Figure 2-10 Java Logging Using the SDK Output Console
Using a console application such as Windows Command Line or Far. In this case, you must run the Developer Agent program manually (see Starting the Developer Agent Program Manually.)
Start a console application and enter the following command specifying the COM port that corresponds to the Qualcomm IoE HS-USB serial port:
java -jar proxy.jar -serial COM22
Install and run IMlets using the CLI.
The log will be available in the same console window shown in Figure 2-11.
Figure 2-11 Java Logging Using a Console Application
Using the Brew MP Logger application.
Start the Brew MP Logger application.
When the Logger application starts, connect to the board using the Connection type: Brew Devices (COM/DIAG), and whichever port matches the Qualcomm HS-USB diagnostics port.
Connect to the board, click the Start Logging button, and verify that the Java VM is sending logging information to the Logger application by checking for messages that come from the [JVMStdout] file name.
Note: Options 1 and 2 are mutually exclusive because only one instance of the Developer Agent program can be run. Option 3 can be used both independently and in parallel with either option 1 or 2. |