2 Installing and Running Applications on the Qualcomm IoE Board

Tooling Overview

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.

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

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

Starting the Developer Agent Program Manually

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.

1. Open a console window and go to the util directory of the Oracle Java ME Embedded distribution.

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

Java Logging Interface Using the Developer Agent Program

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.

Using the Command-Line Interface

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

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

Description of "Figure 2-2 Oracle Java ME Embedded Command-Line Interface"

AMS and System Commands

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.

You can use the properties commands summarized in Table 2-2 and file system commands summarized in Table 2-3.

The CLI supports working with multiple devices. You can use the device commands summarized in Table 2-4

You can use the keystore commands summarized in Table 2-5.

Qualcomm IoE board supports the following network related commands, as shown in Table 2-6.

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

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.

Configuring Wi-Fi Networking

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:

1. Set the SSID of the WiFi network using the command: net-set ssid {SSID Name}

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

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

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.

IP Address Periodic Logging

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.

Setting Up the System Time

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 

1. Open the CLI.

2. Run the following commands:

   set-property system.time.value yyyy/mm/dd hh:mm:ss GMT
   set-property system.time.update true
   

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

1. Edit the following properties:

   system.time.value = yyyy/mm/dd hh:mm:ss GMT
   system.time.update = true
   

2. Restart Java on the Qualcomm IoE board.

Reconnecting to Access Points

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.

Using NetBeans with the Qualcomm IoE Board

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

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, then follow these steps:

1. Right-click your project and select Properties.

2. Select the Platform category on the properties window.

3. Select the entry that represents the board (EmbeddedExternalDevice1) from the device list.

If you are creating a new NetBeans project, then follow these steps:

1. Click File then New Project.

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

3. Provide a project name and click Next. Ensure that the Create MIDlet option is selected.

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

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

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) {
    }
}

Debugging an IMlet on the Qualcomm IoE Board

Follow these steps to debug an IMlet using NetBeans:

1. Open your IMlet class on the NetBeans editor.

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

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

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

http://docs.oracle.com/javame/8.0/api/dio/api/index.html

Accessing Peripherals

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

Installing and Running an IMlet Using the AMS CLI

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.

Obtaining Java Logs from a Device

There are multiple ways in Oracle Java ME 8 to obtain a device log. Three ways to view the device log are:

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

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

     
     Description of "Figure 2-10 Java Logging Using the SDK Output Console "
     
     

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

   
   Description of "Figure 2-11 Java Logging Using a Console Application"
   
   

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