2 Tooling Over Serial and Networking

This chapter demonstrates how to configure the Qualcomm IoE embedded board using the serial and networking connections of the Oracle Java ME Embedded software so that external communication is possible: a process known as tooling. However, in order to successfully communicate with the Qualcomm Orion Internet-of-Everything (IoE) board through a serial connection, the Oracle Java ME SDK 3.4 distribution must be installed, and the Device Manager must be configured to recognize the board.

Note:

The term IMlet, in the context of the Oracle Java ME Embedded command-line interface and references in this chapter, is synonymous with MIDlet.

Tooling Overview

The Oracle Java ME Embedded platform offers the following tools that can be used to communicate and configure the Qualcomm IoE embedded board:

A command-line interface (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 terminal emulator program.
On-Device Tooling (ODT): the ability to install, run, and debug applications from an IDE on the desktop such as NetBeans or Eclipse.

It is important to 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 the chapter. However, the ports used for ODT are invisible to the user, and used by external development tools.

There are two tooling modes available: serial and network. The default tooling mode for the Oracle Java ME Embedded 3.4 release is serial. It's important to note that setting a particular tooling mode alters all the tooling's components. All the tooling components always work in the same mode. In other words, if the tooling mode is set to serial, all connections to the board will be made through that serial connection.

Using Serial Mode

In order to use the serial mode for tooling with the Qualcomm IoE embedded board, perform the following steps:

Connect the Qualcomm IoE board to the PC using a USB cable.
Ensure that the com.oracle.tooling.mode property in the jwc_properties.ini file on the board is set to serial, and that the odt_run_on_start property is set to true. See Appendix B, "Configuring the Java Runtime Properties" for more information.
Start the Oracle Java ME SDK 3.4 Device Manager on the desktop, if it is not already started, and ensure that the device is connected, as shown in the following section.

Installing and Configuring the Java ME SDK 3.4

Download and install the Java ME SDK 3.4 distribution onto your Windows desktop platform from the Oracle Technology Network website.

http://www.oracle.com/technetwork/java/javame/javamobile/download/sdk/index.html

Once this is installed, start the Oracle Java ME SDK Device Manager (located at <SDK Installation Folder>/bin/device-manager.exe) and right click on its icon in the taskbar, then select Manage Device Addresses. Selecting this option will bring up a small dialog box that looks similar to Figure 2-1.

Figure 2-1 Oracle Java ME SDK Device Manager

Description of "Figure 2-1 Oracle Java ME SDK Device Manager"

Choose the COM port that corresponds to the Qualcomm IoE HT-USB Serial Port, as reported earlier by the Windows Device Manager. At this point, the Oracle Java ME SDK Device Manager should locate the device and report that an external IMP-NG device has now become available.

Note that you can freely reboot the board or restart Java on the board without rebooting the Oracle Java ME SDK Device Manager. However, if you reboot the Device Manager, you must reboot Java or the board as well. If you have issues with the Device Manager connecting to the board, please see Chapter 4, "Troubleshooting".

Downloading and Installing the PuTTY Terminal Emulator Program

Next, download the PuTTY Terminal Emulator Program (putty.exe) from the following site:

http://www.putty.org/

The terminal emulator executable is directly downloadable as putty.exe. The terminal emulator is used to connect to both the Java logger and the command-line interface (CLI) that issues commands to the board.

WARNING:

Using the PuTTY Terminal Emulator Program is highly recommended. You're free to use any terminal program to connect to the Java Logger or CLI. However, Oracle cannot guarantee that other terminal programs will work with the Java Logger and CLI in the same manner as PuTTY.

Using the Java Logging Interface

To connect to the Java logger, start a PuTTY executable on your desktop computer. Use this to create a Raw network connection to the board's IP address (127.0.0.1 in the case of serial mode) with the port 65000, as shown in Figure 2-2.

Figure 2-2 PuTTY Configuration for Java Logger Connection

Description of "Figure 2-2 PuTTY Configuration for Java Logger Connection"

Once connected, you should start seeing output from the Java Logger, as shown in Figure 2-3.

Figure 2-3 Oracle Java ME Embedded Logger

Description of "Figure 2-3 Oracle Java ME Embedded Logger"

Connecting to port 65000 will display 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 as well as the Qualcomm IoE board itself.

Finally, if you're using an IDE such as NetBeans or Eclipse, application output sent to System.out or System.err will appear in the Java output window of the IDE, as shown in Chapter 3, "Installing and Running Applications on the Qualcomm IoE Board".

Note:

The NetBeans and Eclipse IDEs also connect to port 65000 of the device to capture Java logs and display them in the appropriate logging windows. If you cannot connect to port 65000 with PuTTY, check that NetBeans or Eclipse is not already using this port. The same is true if you don't see any logs in NetBeans or Eclipse IDEs: ensure that there are no active connections to port 65000 from PuTTY.

Using the Command-Line Interface

The command-line interface is used to issue commands directly to Java runtime.

To use the command-line interface, start a PuTTY executable on your desktop computer. Use this to create a Raw network connection to the board's IP address (127.0.0.1 in the case of serial mode) with the port 65002, as shown in Figure 2-4.

Figure 2-4 PuTTY Configuration for CLI Connection

Description of "Figure 2-4 PuTTY Configuration for CLI Connection"

If you are using the serial mode to connect to the board, ensure that the Java ME SDK 3.4 Device Manager has already successfully detected the device, as shown earlier in Figure 2-1.

The window from the connection provides a command-line interface (CLI), and is shown in Figure 2-5:

Figure 2-5 Oracle Java ME Embedded Command Line Interface

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

WARNING:

The command-line interface (CLI) feature in this Oracle Java ME Embedded software release is provided only as a concept for your reference. It uses insecure connections with no encryption, authentication, or authorization.

AMS and System Commands

You can use the command-line interface to run numerous AMS and system commands, as shown in Table 2-1 and Table 2-2.

Table 2-1 AMS CLI Commands

Syntax	Description
`ams-list [INDEX or NAME\|VENDOR]`	List all installed IMlet suites and their statuses or show the detail of a single suite
`ams-install <URL>` `[username:password]`	Install an IMlet using the specified JAR or JAD file, specified as a URL. An optional username and password can be supplied for login information as well.
`ams-update <INDEX or NAME\|VENDOR>`	Update the installed IMlet
`ams-remove <INDEX or NAME\|VENDOR>`	Remove an installed IMlet
`ams-run <INDEX or NAME\|VENDOR> [IMLET_ID]` `[-debug]`	Execute the specified IMlet or the default if none is specified. An optional debug parameter can be specified to run the IMlet in debug mode.
`ams-stop <INDEX or NAME\|VENDOR> [IMLET_ID]`	Stop the specified IMlet or the default if none is specified
`ams-suspend <INDEX or NAME\|VENDOR> [IMLET_ID]`	Suspend (pause) the specified IMlet or the default if none is specified
`ams-resume <INDEX or NAME\|VENDOR> [IMLET_ID]`	Resume the specified IMlet or the default if none is specified
`ams-setup <INDEX or NAME\|VENDOR>`	Display the setup menu of the IMlet
`ams-info <INDEX or NAME\|VENDOR>`	Show information about the installed IMlet
`ams-logger-list [INDEX or NAME\|VENDOR]`	Retrieve the logger list for the IMlet or all the tasks if one is not specified
`ams-logger-info <INDEX or NAME\|VENDOR> [LOGGER_NAME]`	Retrieve logger info for the specified IMlet and logger or all the loggers if is one is not specified
`ams-logger-level-set <INDEX or NAME\|VENDOR> [LOGGER_NAME] <LOGGER_LEVEL>`	Set the logger level for specified IMlet or all loggers if one is not specified

Table 2-2 Additional System Commands

Syntax	Description
`help [command name]`	List the available commands or detailed usages for a single command
`sysmenu <on\|off>`	Enable hidden system menu commands.
`exit`	Terminates the current session.

When the sysmenu command is entered with the on option, additional system menu commands are available with the CLI, as shown in Table 2-3.

Table 2-3 Additional System Commands Available when System Menu is Activated

Syntax	Description
`setprop <KEY> <VALUE>`	Sets a property identified by `<KEY>` with the value `<VALUE>`
`getprop <KEY>`	Returns a property identified by `<KEY>`
`saveprops`	Saves properties to an internal storage
`net info`	Shows the network information of the system
`net set ssid <SSID>`	Sets the SSID value for WIFI access
`net set passwd <PASSWD>`	Sets the password for WIFI access
`net set pref <0\|1\|2\|3\|4\|5>`	Sets 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
`net set apn <APN>`	Sets APN
`net set pdp_authtype <0\|1\|2>`	Sets the APN's auth type: 0: NONE, 1: PAP, 2: CHAP
`net set pdp_username <USERNAME>`	Resets the PDP username
`net set pdp_password <PASSWORD>`	Resets the PDP password
`net reconnect`	Reconnects the network and reboots Java
`odd [on\|off]`	Explicitly sets the on-device debugging (ODD) property to on or off. If no parameters are passed, returns the current ODD value.
`shutdown [-r]`	Perform either a shutdown of the board, or a reboot if the `-r` parameter has been passed.

Here is a typical example of using the Application Management System (AMS) to install, list, run, and remove a 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'.

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

oracle>> 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. If the install process shows any error code, see Table C-1 in Appendix C, "AMS Installer Error Codes" for more information on how to resolve the error.

Once an IMlet is installed, verify it using the ams-list command. Here, we have added an additional IMlet: rs232dem. Each IMlet has been assigned a number by the AMS for convenience.

oracle>> 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

The ams-remove command can be used to remove any installed IMlet.

oracle>> ams-remove 0
<<ams-remove,OK,hello removed

The results can again be verified with the ams-list command.

oracle>> ams-list
<<ams-list,1.netdemo|Oracle,STOPPED
<<ams-list,2.rs232dem|Oracle,RUNNING
<<ams-list,OK,2 suites are installed

Finally, start up the IMlet using the ams-run command. The application can be terminated with the ams-stop command.

oracle>> ams-run 1
<<ams-run,OK,started

oracle>> ams-list
<<ams-list,1.netdemo|Oracle,RUNNING
<<ams-list,2.rs232dem|Oracle,RUNNING
<<ams-list,OK,2 suites are installed

In order to check the current WiFi settings of the board, activate the system menu commands and use the net info command.

oracle>> sysmenu on
oracle>> 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

Networking Mode

The Qualcomm Orion Internet-of-Everything (IoE) can be configured for tooling over networking as well as serial. This allows the user to bypass the USB serial connections when connecting to the board. However, in order to do this, the board must first be configured for networking first.

Configuring Wi-Fi networking

WiFi access must first be configured using the CLI. Connect the to CLI using the instructions above and perform the following steps:

Activate the system commands by entering the following CLI command: sysmenu on
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 only necessary if the security of WiFi network is enabled.
Enter the net reconnect command to apply the settings. Note that the Oracle Java ME SDK 3.4 Device Manager will temporarily lose its connection to the Qualcomm IoE device while it resets.

Once completed, you can verify the settings on the board by connecting to the CLI and performing the following steps.

Activate the system commands using the command: sysmenu on
Verify the network settings and state using the command: net info

If 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 network are correct, then try to reset the board to re-initialize the WiFi. You can use "IP Address Periodic Logging" feature described below to see the IP address that has been assigned.

Note:

Each time you make a connection to the Java Logger with PuTTY, you will see logs labeled with [NetSetup] channel. The logs contain information about a connection result to a WiFi access point specified earlier. If you can't connect to the Java Logger, try connecting to the board with Brew MP Loader and finding the same logs in the /shared/netlog.txt file

If you see a valid IP address, then the network is configured successfully. At this point, you can reset the following option in the jwc_properties.ini file.

com.oracle.tooling.mode = network

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 issued to the board. The log can be seen through Java Logger and Brew MP SDK Logger application.

The behavior of this feature is controlled by 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.

TCP-to-Serial Fallback

If you are using the tooling network mode and the Wi-Fi connection does not work, you can also try the TCP-to-Serial Fallback functionality provided by the Oracle Java ME Embedded software. The feature switches the CLI to serial mode for this session in order to allow the user to identify the problem and fix it.

To leverage the feature, make sure that:

The Device Manager is executing and trying to connect to address "127.0.0.1" (see the "Tooling Over Serial" section earlier). Note that the state of Device Manager's connection to "127.0.0.1" will not be changed to "connected" because the ODT port will be still in the network mode.
Ensure that the com.oracle.midp.ams.headless.cli.tcp2comm.fallback property from is set to true. This value is the default.
Ensure that the com.oracle.midp.ams.headless.cli.reconnect.timeout is set to 0. This is also the default.
Attempt to open the CLI as normal. Note that sometimes it can take up to a couple of minutes until the runtime switches the CLI to serial mode for the session.

If the Device Manager wasn't connecting to a COM port when the problem of connecting over TCP/IP occurred, then try resetting both Device Manager and the board.

Automatic Recovering for Java Logger and CLI Connections

If you are using the tooling network mode, or you are going to deploy an application that is based on Oracle Java ME Embedded 3.4 somewhere remotely, then it is worthwhile to turn on a feature that will automatically reopen both the Java Logger and CLI socket connections on the board side in the event that a network related error occurs.

To turn on the CLI's auto-recovering feature, make sure that the com.oracle.midp.ams.headless.cli.reconnect.timeout property is set to a value, which is measured in milliseconds.
To turn on Java Logger's auto-recovering feature, make sure that log.tcp.reconnect.timeout is set to a value, which is measured in milliseconds.
If both of these properties are set to 0, then the feature is turned off.

Note that there can be situations when the underlying platform will not be able to recover a network subsystem after some network-related issue occurs. In such cases your application should be designed in a way that allows it to:

Catch network-related issues and reopen application- level network connections
Reboot the board using Device Access API's watchdog if an app assumes that the network subsystem is unrecoverable.