3 Installing and Running Applications on the Qualcomm IoE Board

Installing the Oracle Java ME SDK 3.4 Plugin for NetBeans

After installing NetBeans, use these steps to install the remaining software.

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

Adding the Qualcomm IoE Board to the Device Selector

Follow these steps to add the board to the Device Selector in NetBeans:

1. Ensure that the property odt_run_on_start has been set to true on the Qualcomm IoE.

2. Start the NetBeans IDE. In the NetBeans IDE, go to Tools -> Java ME -> Device Selector

3. 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

   
   Description of "Figure 3-1 NetBeans Device Selector "Add a Device" Button"
   
   

4. 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

   
   Description of "Figure 3-2 NetBeans Embedded Device Detection"
   
   

5. 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.

Assigning the Qualcomm IoE Board to Your Project

If you already have an existing NetBeans project with an IMlet that you want to run or debug on the board, follow these steps:

1. Right-click on your project and choose Properties.

2. Select the Platform category on the properties window.

3. 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:

1. Select File -> New Project.

2. Select the Java ME category and Embedded Application in Projects. Click Next.

3. Provide a project name and click Next. Be sure that the Create Default Package and IMlet Class option is checked.

4. 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

Description of "Figure 3-3 NetBeans Platform Properties Dialog"

Sample Source Code

Once the project is created, use the source code in Example 3-1 for the default IMlet.java source file.

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:

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

Installing the Oracle Java ME SDK 3.4 Plugin for Eclipse

After installing Eclipse, use these steps to install the remaining software.

1. 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.

2. Install the Oracle Java ME SDK 3.4 Eclipse plugin. This is required to use the Device Selector to connect to the board.

3. 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.

4. 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.

Adding the Qualcomm IoE Board to the Device Selector

Follow these steps to add the board to the Device Selector in the Oracle Java ME SDK:

1. Ensure that the property odt_run_on_start is set to true in the file jwc_properties.ini on the Qualcomm IoE.

2. 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.

   
   Description of the illustration showview.jpg
   
   

3. On the Device Selector, click on the Add a Device button at the top of the Device Selector window.

   
   Description of the illustration devselecl.jpg
   
   

4. 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.

   
   Description of the illustration devdetecl.jpg
   
   

5. Once the device is detected, click Finish on the Add Device screen.

The list of devices in the Device Selector should now include IMPNGExternalDevice1.

Assigning the Qualcomm IoE Board to Your Project

If you already have an existing Eclipse project with an IMlet that you want to run or debug on the board, follow these steps:

1. Right-click on your project and choose Properties.

2. Select the Java ME category on the properties window.

3. 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:

1. Select New -> Other. Then expand the Java ME tree node, and create a new MIDlet Project.

2. Expand the Java ME tree node, and create a new MIDlet Project.

3. In the Configuration pane of the creation dialog, select the appropriate entry (IMPNGExternalDevice1) from the device list.

4. 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.

Sample Source Code

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.

Method #1: Signing the Application with API Permissions

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

  
  Description of "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.

1. 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.

2. 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.

  1. Right click your project and select Properties.

  2. Choose the Signing option under the Build category.

  3. Open the Keystores Manager and import the mykeystore.ks file that you created.

  4. 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.

  5. 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

  
  Description of "Figure 3-7 The Signing Pane in the NetBeans Project Properties"
  
  

• In Eclipse, perform the following steps:

  1. Right click your project and select Properties.

  2. Choose the Signing option under the Java ME category.

  3. 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.

  4. 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.

Method #2: Modifying the Security Policy File

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:

1. Use the Loader tool to download the appdb/_policy.txt file to the desktop.

2. Add the line "allow: device_access" to the "untrusted" domain (often paired with "unsecured")

3. 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.