Beta Draft: 2014-03-25

2 Tooling Over Serial Connection

This chapter demonstrates how to configure the Qualcomm IoE board using the serial connection of the Oracle Java ME Embedded software so that external communication is possible. However, in order to successfully communicate with the Qualcomm Internet-of-Everything (IoE) board through a serial connection, the Oracle Java ME SDK 8 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 for managing and monitoring 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 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 utils directory of the Oracle Java ME Embedded distribution, named proxy.jar. The Developer Agent 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 manually as described in Starting the Developer Agent Manually.
- The CLI is available via PuTTY terminal window on port 65002 (see Using the Command-Line Interface.)
- The Java Logging is available via a console window used for running the Developer Agent (see Java Logging Interface Using a Developer Agent.)
Start the Java ME Embedded SDK (see Installing and Configuring the Java ME SDK 8.)
- The CLI is available via PuTTY terminal window on port 65002 (see Using the Command-Line Interface.)
- The Java Logging is available via the Output window of the Java ME Embedded Emulator included with the Java ME Embedded SDK.

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.

Downloading and Installing the PuTTY Terminal Emulator Program

First, 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 AMS command-line interface (CLI) that issues commands to the board.

WARNING:

Using the PuTTY Terminal Emulator Program is highly recommended. You can use any terminal program to connect to the CLI. However, Oracle cannot guarantee that other terminal programs work with the CLI in the same manner as PuTTY.

Installing and Configuring the Java ME SDK 8

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

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

To start the Java ME SDK, run the Oracle Java ME SDK Device Manager (located at <SDK Installation Folder>/bin/device-manager.exe) by right-clicking on its icon in the taskbar and selecting Manage Device Connections. Selecting this option will bring up a dialog box shown in Figure 2-1.

Figure 2-1 Oracle Java ME SDK Device Connections Manager

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

Restart the Java runtime on the Qualcomm IoE board. At this point, the Oracle Java ME SDK Device Manager should locate the device and report that an EmbeddedExternalDevice1 has now become registered as shown in Figure 2-2.

Figure 2-2 Registering the External Device

Description of "Figure 2-2 Registering the External Device"

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

Starting the Developer Agent Manually

You need to start the Developer Agent manually if only you wish to use the CLI or connect to the Java Logger and do not wish to use the Java ME Embedded SDK.

Open a console window, navigate to the utils directory of the Oracle Java ME Embedded distribution, and type 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, for example

java -jar proxy.jar -serial COM22

If you have issues with running the Device Manager, please see Chapter 4, "Troubleshooting."

Java Logging Interface Using a Developer Agent

To connect to the Java logger, start the Developer Agent on your desktop computer as described in Starting the Developer Agent Manually.

Once connected, you should start seeing output from the Java Logger.

Connecting to Java logger 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.

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 must be running.

If you are using the Java ME Embedded SDK, ensure that the Java ME SDK 8 Device Manager has already successfully detected the device, as shown earlier in Figure 2-2.

If you don't use the Java ME Embedded SDK, start the Developer Agent as described in Starting the Developer Agent Manually.

To use the command-line interface, start a PuTTY executable 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-3.

Figure 2-3 PuTTY Configuration for CLI Connection

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

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

Figure 2-4 Oracle Java ME Embedded Command Line Interface

Description of "Figure 2-4 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, Table 2-2, and Table 2-3.

Table 2-1 AMS CLI Commands

Syntax	Description
`ams-list [INDEX or NAME\|VENDOR]`	List all installed IMlet suites and their statuses or MIDlets in a specific suite
`ams-install <URL>` `[auth=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 either in the URL or by the `auth` parameter.
`ams-update <INDEX or NAME\|VENDOR> [auth=username[:password]]`	Update the specified suite
`ams-remove <INDEX or NAME\|VENDOR>`	Remove the specified suite
`ams-run <INDEX or NAME\|VENDOR> [MIDLET_ID]`	Execute a default suite's MIDlet or the MIDLet specified with `MIDLET_ID` parameter
`ams-stop <INDEX or NAME\|VENDOR> [MIDLET_ID]`	Stop a default suite's MIDlet or the MIDlet specified with the `MIDLET_ID` parameter
`ams-info <INDEX or NAME\|VENDOR>`	Show information about the specific MIDlet

Table 2-2 System Commands

Syntax	Description
`help [command name]`	Lists the available commands or detailed usages for a single command
`properties-list`	Shows the list of names of properties which control the Java ME runtime (properties that are set in the `properties.ini` file)
`set-property <NAME> <VALUE>`	Sets a property identified by `<NAME>` with the value `<VALUE>`
`get-property <NAME> [i]`	Returns a value of the property identified by `<NAME>`
`save-properties`	Saves properties to an internal storage
`blacklist -client <NAME> blacklist -app <NAME\|VENDOR>`	Blacklists clients and applications
`shutdown [-r]`	Performs either a shutdown of the board or a reboot if the `-r` parameter has been passed

Table 2-3 File System Commands

Syntax	Description
`cd <deviceDirectoryName>`	Changes the working directory on the device
`delete <deviceFileName>`	Deletes a file on the device
`get <deviceFileName> <hostFileName>`	get <deviceFileName> <hostFileName>
`ls [<deviceDirectoryName>]`	Displays a list of files and subdirectories in a device directory
`mkdir <deviceDirectoryName>`	Creates a directory on the device.
`pwd`	Outputs the current working directory on the device.
`put <hostFileName> <deviceFileName>`	Copies a local host file to the device.

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

Table 2-4 Qualcomm IoE Specific Commands

Syntax	Description
`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

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

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.

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.

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

The ams-remove command can be used 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 up 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

In order to check the current WiFi settings of the board, activate the system menu commands and 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

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:

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 8 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 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 a Developer Agent, 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.

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 a console window and Brew MP 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.

Setting-Up the System Time

In order to run signed IMPlets 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 into the board's SIM-card slot.

However, an automatic setup does not work in the following cases:

A SIM-card is not available.
A carrier does not provide the current time data.

If there are any issues with the automatic setup, set the system time manually either by using CLI or editing the jwc_properties.ini file.

Manual Setup of the System Time Using CLI

Open the CLI

Execute the following commands:

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

Enter either save-properties or shutdown -r command.

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 IoE board.