Oracle® Java ME Embedded Getting Started Guide for the Reference Platform (Qualcomm IoE) Release 3.4 E47914-01 |
|
Previous |
Next |
Developers can run and debug IMlets on the Qualcomm IoE board in serial mode using the Oracle Java ME SDK, or in networking mode without Java ME SDK usage, either using the CLI or directly from IDEs such as NetBeans or Eclipse. This chapter describes how to install and run an IMlet on the board, as well as debugging an IMLet in both the NetBeans and Eclipse IDE.
Installing and running IMlet projects on the Qualcomm IoE board using the NetBeans IDE requires the following software:
NetBeans IDE 7.3.1 and later with Java ME, which can be downloaded from http://www.netbeans.org/
.
Oracle Java ME SDK 3.4
Oracle Java ME SDK 3.4 NetBeans Plugin
After installing NetBeans, use these steps to install the remaining software.
Ensure that Java ME is enabled in NetBeans. This can be done by selection Tools -> Plugins and selecting the Installed pane. Activate the Java ME plugin if it is not already activated.
Install the Java ME SDK 3.4 distribution, if you have not done so already. See the Java ME SDK 3.4 documentation for details.
Install the Oracle Java ME SDK 3.4 NetBeans plugin. This is a downloadable ZIP file that consists of a number of NetBeans modules (.nbm
files) that can be added using the Tools -> Plugins dialog and selecting the Downloaded pane. Unzip the plugin file, and add all of the .nbm
files to NetBeans. The Oracle Java ME SDK 3.4 NetBeans plugins are required to interface with the Device Selector and connect to the board.
Ensure that the Oracle Java ME Embedded 3.4 appears in the list of Java ME platforms. In the NetBeans IDE, go to Tools -> Java Platforms. If the Oracle Java Platform Micro Edition SDK 3.4 does not appear in the list of J2ME platforms, follow these steps:
Click on Add Platform.
Select Java ME CLDC Platform Emulator and click Next.
Select the folder where the Oracle Java ME SDK 3.4 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 on the Qualcomm IoE Board" for more information on how to install the runtime distribution on the Qualcomm IoE board.
Follow these steps to add the board to the Device Selector in NetBeans:
Ensure that the property odt_run_on_start
has been set to true
on the Qualcomm IoE.
Start the NetBeans IDE. In the NetBeans IDE, go to Tools -> Java ME -> Device Selector
If the device is not already listeed in the Device Selector, click on the Add a Device button at the top of the Device Selector window, as shown in Figure 3-1.
Figure 3-1 NetBeans Device Selector "Add a Device" Button
If you are using tooling over the serial mode then the connection between the IoE board and NetBeans should appear automatically in the list in Figure 3-1. The IP address of the connection will be '127.0.0.1' If it is not already shown, enter the IP address of the Qualcomm IoE board in the IP Address field, as shown in Figure 3-2, and click Next.
Figure 3-2 NetBeans Embedded Device Detection
Once the device is detected, click Finish on the Device Detection screen.
The list of devices in the Device Selector should now include IMPNGExternalDevice1.
Alternatively, you can use the Oracle Java ME SDK 3.4 to detect the device, as shown in Chapter 2, "Tooling Over Serial and Networking". If the device has already been detected using the Oracle Java ME SDK 3.4, it should already appear in the Device Selector.
If you already have an existing NetBeans project with an IMlet that you want to run or debug on the board, follow these steps:
Right-click on your project and choose Properties.
Select the Platform category on the properties window.
Select the entry that represents the board (IMPNGExternalDevice1) from the device list.
If you are creating a new NetBeans project from scratch, follow these steps:
Select File -> New Project.
Select the Java ME category and Embedded Application in Projects. Click Next.
Provide a project name and click Next. Be sure that the Create Default Package and IMlet Class option is checked.
Ensure the Emulator Platform is Oracle Java ME Embedded 3.4. Then, select the entry that represents the board (IMPNGExternalDevice1) from the device list and click Finish.
The configured Platform dialog is shown in Figure 3-3. After you assign the board to your project, the IMlets run on the board instead of on the emulator when you click on Run Project on the NetBeans IDE.
Figure 3-3 NetBeans Platform Properties Dialog
Once the project is created, use the source code in Example 3-1 for the default IMlet.java
source file.
Example 3-1 Sample Code to Access a GPIO Pin
package embeddedapplication1; import com.oracle.deviceaccess.PeripheralManager; import com.oracle.deviceaccess.PeripheralNotAvailableException; import com.oracle.deviceaccess.PeripheralNotFoundException; import com.oracle.deviceaccess.gpio.GPIOPin; import java.io.IOException; import javax.microedition.midlet.*; public class IMlet extends MIDlet { public void startApp() { try { GPIOPin pin = (GPIOPin)PeripheralManager.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 (PeripheralNotFoundException ex) { ex.printStackTrace(); } catch (PeripheralNotAvailableException ex) { ex.printStackTrace(); } catch (InterruptedException ex) { ex.printStackTrace(); } } public void pauseApp() { } public void destroyApp(boolean unconditional) { } }
This sample application will obtain an object representing GPIO pin 14 from the PeripheralManager
, and set 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 on using the Device Access APIs, see the Device Access API (Version B) Guide and the associated Javadocs 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.
Select Debug -> Debug Project or use the Debug button on the toolbar.
The debugger connects to the debug agent on the board and the program execution stops at your breakpoint, as shown in Figure 3-4.
Figure 3-4 Debugging an IMlet on the Qualcomm IoE Board Using NetBeans
Figure 3-4 shown an entire NetBeans debugging environment that allows the programmer to execute 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 on using the Device Access APIs, see the Device Access API (Version B) Guide and the associated Javadocs at:
Running and debugging IMlet projects on the Qualcomm IoE board using the Eclipse IDE requires the following software:
Eclipse 3.7 Indigo or Eclipse 4.2 Juno, which can be downloaded from http://www.eclipse.org/
.
Oracle Java ME SDK 3.4
Oracle Java ME SDK 3.4 Eclipse Plugin
After installing Eclipse, use these steps to install the remaining software.
Install the Java ME SDK 3.4 distribution, if you have not done so already. See the Java ME SDK 3.4 documentation for details.
Install the Oracle Java ME SDK 3.4 Eclipse plugin. This is required to use the Device Selector to connect to the board.
Ensure that the Qualcomm IoE board has the Oracle Java ME Embedded 3.4 runtime. See Chapter 1, "Installing Oracle Java ME Embedded on the Qualcomm IoE Board" for more information on how to install the runtime distribution on the Qualcomm IoE board.
Ensure that the Oracle Java ME Embedded 3.4 appears in the list of Java ME platforms. If it doesn't appear, open "Window->Preferences" and follow these steps:
Under the Java ME category, select Device Management. In the Device Management window, press the Manual Install... button.
The Manual Device Installation window appears, without the Oracle Java ME Embedded devices. Press the Browse button. A browser window appears.
Browse to the base directory of the Java ME SDK environment and press the OK button. After the platform is scanned and the devices are installed, close each of the respective dialogs.
Follow these steps to add the board to the Device Selector in the Oracle Java ME SDK:
Ensure that the property odt_run_on_start
is set to true in the file jwc_properties.ini
on the Qualcomm IoE.
Start the Eclipse IDE. In the Eclipse IDE, go to Window -> Show View -> Other. In the popup window that appears, expand the Java ME node and select Device Selector.
On the Device Selector, click on the Add a Device button at the top of the Device Selector window.
If you are using tooling over the serial mode then the connection between the IoE board and NetBeans should appear automatically in the list in the figure above. If it is not listed already, enter the IP address of the Qualcomm IoE board in the IP Address field and click Next.
Once the device is detected, click Finish on the Add Device screen.
The list of devices in the Device Selector should now include IMPNGExternalDevice1.
If you already have an existing Eclipse project with an IMlet that you want to run or debug on the board, follow these steps:
Right-click on your project and choose Properties.
Select the Java ME category on the properties window.
Select the device entry for the Qualcomm IoE board (IMPNGExternalDevice1) from the device list. If the device is not shown, add it using the Add... button, selecting Oracle Java ME Embedded 3.4 as the SDK and choosing the appropriate device that represents the Qualcomm IoE board.
If you are creating a new Eclipse project from scratch, follow these steps:
Select New -> Other. Then expand the Java ME tree node, and create a new MIDlet Project.
Expand the Java ME tree node, and create a new MIDlet Project.
In the Configuration pane of the creation dialog, select the appropriate entry (IMPNGExternalDevice1) from the device list.
Select the appropriate Profile and Configuration for your project.
After you assign the board to your project, the IMlets run on the board instead of on the emulator when you click on Project -> Run on the Eclipse IDE.
Once the project is created, use the source code given earlier in Example 3-1 for a default source file. This sample application will obtain an object representing GPIO pin 14 from the PeripheralManager
, and set 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.
After you assign the board to your project, follow these steps to debug an IMlet:
Open your IMlet class on the Eclipse editor.
Click once directly on the line number where you want to set a breakpoint. The line number has a small circle next to it to indicate a breakpoint.
Select Run -> Debug or use the Debug button on the toolbar.
The debugger connects to the debug agent on the board and the program execution stops at your breakpoint, as shown in Figure 3-5.
Figure 3-5 Debugging an IMlet on the Board Using the Eclipse IDE
Figure 3-5 shown an entire Eclipse debugging environment that allows the programmer to execute 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 on using the Device Access APIs, please see the Device Access API (Version B) Guide and the associated Javadocs at the following site:
If you are not using an IDE, you can still use the Oracle Java ME Embedded 3.4 CLI to install an application. Simply connect to the device at port 65002, and install and run the IMlet manually. For example:
oracle>> 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
oracle>> ams-list
<<ams-list,0.hello|Oracle,STOPPED
<<ams-list,OK,1 suites are installed
oracle>> ams-run 0
<<ams-run,OK,started
oracle>> ams-list
<<ams-list,1.netdemo|Oracle,RUNNING
<<ams-list,OK,1 suites are installed
See "Using the Command-Line Interface" in Chapter 2, "Tooling Over Serial and Networking" for more details.
Note that if an application is installed on the board using NetBeans or Eclipse during development, the application will automatically be installed in the maximum
security domain as a convenience. IMlets that are not running through the NetBeans or Eclipse IDE, however, must have permission to access device peripherals using the Device Access APIs. For more information on using the device access APIs, please see the Device Access API (version B) Guide and the associated Javadocs at the following site:
http://docs.oracle.com/javame/embedded/embedded.html
There are two ways to allow access to the device peripherals on the Qualcomm IoE. The first is to digitally sign the application with the appropriate API permissions requested in the JAD file; the second is to use unsigned applications and modify the security policy file.
The first method is more complex, but is the preferred route for applications that are widely distributed. First, the JAD file must have the proper API permissions. Here is how to sign the application in NetBeans, Eclipse, and without an IDE.
In NetBeans, right-click the project name (EmbeddedApplication1 in this example) and choose Properties. Select Application Descriptor, then in the resulting pane, select API Permissions. Click the Add... button, and add the com.oracle.deviceaccess.gpio
API, as shown in Figure 3-6. Click OK to close the project properties dialog.
Figure 3-6 Adding API Permissions with NetBeans
In Eclipse, open the Application Descriptor for your project in the Packages window, and select the Application Descriptor pane. You will need to manually add or change the following lines in the Application Descriptor.
MIDlet-Permissions: com.oracle.deviceaccess.gpio Microedition-Profile: IMP-NG
If you are not using an IDE, manually modify the application descriptor file to contain the permissions listed in the Eclipse section.
Here are the instructions on how to setup 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"
This command will generate 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. Feel free to change both passwords as you see fit.
Copy the appdb/_main.ks
keystore file from the Qualcomm IoE over to the desktop using the Loader tool and perform the following command using the mekeytool.exe
command (or alternatively java -jar MEKeyTool.jar...
if your distribution contains only that) that ships with the Oracle Java ME SDK 3.4 distribution.
{mekeytool} -import -MEkeystore _main.ks -keystore mykeystore.ks -storepass spass -alias mycert -domain trusted
This will import the information in mykeystore.ks
you just created to the _main.ks
keystore. Once this is completed, copy the _main.ks
file back to its original location on the Qualcomm IoE using the Loader tool.
Use the following steps in to sign your application before deploying to the Qualcomm IoE board, depending on whether you are using NetBeans, Eclipse, or working without an IDE.
In NetBeans, perform the following steps.
Right click your project and select Properties.
Choose the Signing option under the Build category.
Open the Keystores Manager and import the mykeystore.ks
file that you created.
Check the Sign Distribution box. If you wish, unlock the keystore and the key with the passwords that you specified earlier. This is shown in Figure 3-7.
When the project is built and run, it will be digitally signed and deployed to the Qualcomm IoE.
Figure 3-7 The Signing Pane in the NetBeans Project Properties
In Eclipse, perform the following steps:
Right click your project and select Properties.
Choose the Signing option under the Java ME category.
Check the Enable Project Specific Settings checkbox. Import the mykeystore.ks
file that you created as an External... keystore file. Provide the keystore and key passwords that you created earlier. Ensure that the mycert key alias is present.
Ensure that the project is being signed in the project's Application Descriptor. When the project is built and run, it will be digitally signed when deployed to the Qualcomm IoE.
If you are not using an IDE, enter the following command to sign a JAD:
> jarsigner -keystore mykeystore.ks -storepass spass app.jad myalias
If there is an issue with a non-valid certificate, be sure to check the date and time which has been setup on the board. Refer to Chapter 4, "Troubleshooting" for more details.
With this method, the user will modify the Java security policy file. Typically, this is the appdb/_policy.txt
file, but be sure to check the security.policyfile
entry in the jwc_properties.ini
file to verify the current file name.
Perform the following steps:
Use the Loader tool to download the appdb/_policy.txt
file to the desktop.
Add the line "allow: device_access
" to the "untrusted
" domain (often paired with "unsecured
")
Use the Loader application to copy the file back, overwriting the original file in the appdb/
directory.
Remember that if an application is installed on the board using the NetBeans or Eclipse IDE during development, the application will automatically be installed in the maximum
security domain as a convenience. Manual installation using the AMS, however, will place the unsigned application into the untrusted
security domain.
After development is finished, you should always publish your applications with signed API permissions.