Oracle® Java ME Embedded Getting Started Guide for the Reference Platform (Qualcomm IoE) Release 3.4 E47914-01 |
|
Previous |
Next |
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. |
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.
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.
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
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".
Next, download the PuTTY Terminal Emulator Program (putty.exe
) from the following site:
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. |
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
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
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. |
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
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
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. |
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 |
---|---|
|
List all installed IMlet suites and their statuses or show the detail of a single suite |
|
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. |
|
Update the installed IMlet |
|
Remove an installed IMlet |
|
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. |
|
Stop the specified IMlet or the default if none is specified |
|
Suspend (pause) the specified IMlet or the default if none is specified |
|
Resume the specified IMlet or the default if none is specified |
|
Display the setup menu of the IMlet |
|
Show information about the installed IMlet |
|
Retrieve the logger list for the IMlet or all the tasks if one is not specified |
|
Retrieve logger info for the specified IMlet and logger or all the loggers if is one is not specified |
|
Set the logger level for specified IMlet or all loggers if one is not specified |
Table 2-2 Additional System Commands
Syntax | Description |
---|---|
|
List the available commands or detailed usages for a single command |
|
Enable hidden system menu commands. |
|
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 |
---|---|
|
Sets a property identified by |
|
Returns a property identified by |
|
Saves properties to an internal storage |
|
Shows the network information of the system |
|
Sets the SSID value for WIFI access |
|
Sets the password for WIFI access |
|
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 |
|
Sets APN |
|
Sets the APN's auth type: 0: NONE, 1: PAP, 2: CHAP |
|
Resets the PDP username |
|
Resets the PDP password |
|
Reconnects the network and reboots Java |
|
Explicitly sets the on-device debugging (ODD) property to on or off. If no parameters are passed, returns the current ODD value. |
|
Perform either a shutdown of the board, or a reboot if the |
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
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.
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 |
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.
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.
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.
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.