Beta Draft: 2014-03-25

1 Running on the Raspberry Pi Board

This chapter describes installing the Oracle Java ME Embedded 8 software on the Raspberry Pi board, installing and using the Developer Agent on the desktop host, configuring the Java ME Embedded system, connecting to the Raspberry Pi using a secure shell, and installing and running an Oracle Java ME Embedded application.

The following items are required for developing on the Raspberry Pi board:

The Raspberry Pi Rev. B 512 MB Board
The Oracle Java ME Embedded 8 distribution
A micro-USB power supply of .7 or greater amps, and 5 volts. Note that the power supply must have a micro-USB type B connector, not a regular USB or mini-USB connector.
A USB keyboard and mouse, as well as a monitor. If necessary for your monitor, an HDMI to DVI video cable or adapter.
An SD card of 2 GB or greater. An SD-HC class 10 card is recommended. Do not use a high speed SD card, as it may be too fast for the Raspberry Pi board.
An ethernet cable with an RJ-45 connection, as well as a connection to a network with a DHCP server.
A terminal emulation program, such as PuTTY, if you wish to connect to the board using the Application Management System (AMS) interface.

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

Preparing the Raspberry Pi Board

To develop on the Raspberry Pi board, you must first download and install the Wheezy variant of Raspbian Debian Linux on the Pi board. If you have not already done this, use the following steps:

Download the Raspbian "Wheezy" hard-float (Debian Linux) Raw Image ZIP file to your desktop from the following site:

http://www.raspberrypi.org/downloads
Unzip the distribution file, which creates a single disk image (.img) file.
Mount the SD card to the desktop, and use a utility to write the disk image file to the SD card. Note that this is not the same as copying the file to the base-level directory on the SD card. Instead, it is akin to "burning" a disk image onto a CD-ROM or DVD-ROM. There are a number of utilities that will perform this action.
- For the Windows operating system, you can use the Disk Image Writer utility located at https://launchpad.net/win32-image-writer to perform this task.
- For the Mac platform, use the RPi-sd Card Builder located at http://alltheware.wordpress.com/2012/12/11/easiest-way-sd-card-setup.
- For Linux, use the dd command. For more information, see http://en.wikipedia.org/wiki/Dd_(Unix).
Eject or unmount the SD card from the desktop computer.
Connect the RJ-45 network cable, monitor, keyboard, and mouse.
Install the SD card in the Raspberry Pi.
Connect power to the Pi. The red light on the Raspberry Pi should glow, then in a few seconds, the green light should blink. The blinking green light indicates that the Raspberry Pi is booting Linux.
If the Linux installation was successful, the Raspberry Pi will boot and obtain a DHCP address.
Next, a configuration program (raspi-config) runs, which helps you expand the filesystem partition on the SD card, configure the keyboard, timezone, reset the default password, and several other useful system items. Use the up-down arrow keys to make a menu choice. Use the left-right arrow keys to select OK or Cancel. Press Return to execute your choice. Note that the default user name is "pi", and the default password is "raspberry".
If you wish, perform an update, start the ssh server, and set the graphical desktop to automatically start, then press Finish. At this point, the board should reboot. Login if necessary, and if you're using the desktop, start a LXTerminal. Then, run the ifconfig command to display the Pi's IP address. This is necessary so you can access and control the board remotely. Remember this IP address; it will be used in the next set of steps.

Installing the Java ME Embedded Software

Version 8 of the Oracle Java ME Embedded contains a different architecture than previous versions. With version 8, the user has the option to run a Developer agent on the desktop side under Windows. Commands that are sent to the board from the Windows desktop are no longer sent directly across the network. Instead, they are sent to the Developer Agent, which transmits all communication to and from the Oracle Java ME Embedded executable on the Raspberry Pi board.

The Oracle Java ME Embedded ZIP archive consists of four directories:

/appdb - This directory is used on the Pi and contains internal Java libraries
/bin - This directory is used on the Pi and contains executables and the jwc_properties.ini file
/legal - This directory contains important legal documentation
/lib - This directory is used on Windows and contains the files needed to execute the Developer Agent on the desktop side.

You will need to make two copies of the Oracle Java ME Embedded ZIP archive file. The first remains on the Windows desktop, while the second must be transferred to the Raspberry Pi.

First, use an sftp client or scp command to transfer once copy of the Oracle Java ME Embedded ZIP archive to the Raspberry Pi. For example, on a Unix or Mac system, you can transfer the ZIP file using a command similar to the following:

$sftp pi@[IP address of board]

Windows users can download the psftp.exe to obtain a free SFTP client; it is available from the same address as the PuTTY executable:

http://www.putty.org/

Once the ZIP archive is transferred, either go directly to the keyboard and the mouse connected to the Raspberry Pi, or start a secure shell script on your desktop to connect to the board using the following command:

$ssh -l pi [IP address of board]

Unzip the archive on the Pi and perform the following command:

$ chmod -R 777 appdb bin

Next, cd to the bin directory. The contents of the bin directory are shown in Figure 1-1.

Figure 1-1 Raspberry Pi Bin Directory

Description of "Figure 1-1 Raspberry Pi Bin Directory"

Adding an HTTP Proxy for Network Connections on the Pi

If an HTTP proxy server is required for the Java IMlets on the Pi to make network connections (such as for HTTP or apt-get), the Oracle Java ME Embedded on the Pi can be configured by adding the following lines to the end of the bin/jwc_properties.ini file.

com.sun.midp.io.http.proxy.host = proxy.mycompany.com
com.sun.midp.io.http.proxy.port = 80

Using the Java Runtime on the Raspberry Pi

There are several ways to use the Oracle Java ME Embedded platform on the Raspberry Pi.

Directly execute commands using an LXTerminal command-line shell interface or logging in via ssh.
Manually start a Developer Agent on the desktop host and run commands using the AMS.
Use NetBeans IDE 8.0 Beta.

Running IMlets on the Raspberry Pi Using the Command Shell

If you wish to run IMlets directly on the Raspberry Pi board without a Developer Agent, you can use the commands shown in Table 1-1.

Table 1-1 Raspberry Pi Shell Commands

Syntax	Description
`listMidlets.sh [SUITE_ID or NAME]`	List all installed IMlet suites and their statuses or show the detail of a single suite.
`installMidlet.sh <URL> [<URL label>]`	Install an IMlet using the specified JAR file.
`removeMidlet.sh <SUITE_ID>`	Remove an installed IMlet.
`sudo runSuite.sh <SUITE_ID or NAME> [IMLET_ID or classname]`	Execute the specified IMlet or the default if none is specified. All logging information from the IMlet appears in the stdout of this command.

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 following is a typical example of using the commands to install, list, run, and remove a Java ME Embedded application on the Raspberry Pi board. Note that the runSuite.sh shell command is preceded by the sudo request to ensure that the command can run with superuser privileges and access all the peripherals on the board. Most commands can be terminated with the Ctrl-C key combination if they become unresponsive.

First, install the application using the installMidlet.sh command, specifying its location on the local filesystem.

pi@raspberrypi ~/pi/bin $ ./installMidlet.sh EmbeddedTestProject.jar
argv[1] = runMidlet
argv[2] = -1
argv[3] = com.sun.midp.scriptutil.CommandLineInstaller
argv[4] = I
argv[5] = EmbeddedTestProject.jar
Command line parameters are passed.
javacall_event_initialize: events system initialized
Events system initialized.
Time system initialized.
JavaTask thread initialized.
Starting JavaTask
The suite was successfully installed, ID: 2
Exited JavaTask

Once an IMlet is installed, note its ID: in this case, it is 2. Next, verify it using the listMidlets.sh command.

pi@raspberrypi ~/pi/bin $ ./listMidlets.sh 
argv[1] = runMidlet
argv[2] = -1
argv[3] = com.sun.midp.scriptutil.SuiteLister
Command line parameters are passed.
javacall_event_initialize: events system initialized
Events system initialized.
Time system initialized.
JavaTask thread initialized.
Java is starting. Press Ctrl-C to exit
Starting JavaTask
Suite: 2
  Name: EmbeddedTestProject
  Version: 1.0
  Vendor: Vendor
  MIDlets:
    IMlet: GPIODemo
Exited JavaTask

The sudo runSuite.sh command can be used to execute any installed IMlet. This command will execute the IMlet that was just installed, passing any logging information to the stdout of this command. Note that you can press the Ctrl-C key to exit from this command, which will terminate the app.

pi@raspberrypi ~/pi/bin $ sudo ./runSuite.sh GPIODemo 
argv[1] = GPIODemo
Command line parameters are passed.
javacall_event_initialize: events system initialized
Events system initialized.
Time system initialized.
JavaTask thread initialized.
Java is starting. Press Ctrl-C to exit
Starting JavaTask
Watchdog is starting
Network: Init
App started

The removeMidlet.sh command can be used to remove any installed IMlet.

pi@raspberrypi ~/pi/bin $ ./removeMidlet.sh 2
argv[1] = runMidlet
argv[2] = -1
argv[3] = com.sun.midp.scriptutil.SuiteRemover
argv[4] = 2
Command line parameters are passed.
javacall_event_initialize: events system initialized
Events system initialized.
Time system initialized.
JavaTask thread initialized.
Java is starting. Press Ctrl-C to exit
Starting JavaTask
Suite removed
Exited JavaTask
pi@raspberrypi ~/pi/bin $

The results can again be verified with the listMidlets.sh command.

pi@raspberrypi ~/pi/bin $ ./listMidlets.sh 
argv[1] = runMidlet
argv[2] = -1
argv[3] = com.sun.midp.scriptutil.SuiteLister
Command line parameters are passed.
javacall_event_initialize: events system initialized
Events system initialized.
Time system initialized.
JavaTask thread initialized.

Java is starting. Press Ctrl-C to exit
Starting JavaTask
No suites installed
Network: Init
Exited JavaTask

Starting the Developer Agent on the Desktop

If you wish to use the Developer Agent, extract files from the copy of the Oracle Java ME Embedded ZIP archive on the Windows desktop and delete the /appdb and the /bin directory. The Developer Agent program is found as a JAR file inside the lib directory of the Oracle Java ME Embedded distribution, named proxy.jar. You can start the Developer Agent on the desktop host computer either in a server or a client mode as described below. After the Developer Agent is started, use the AMS CLI.

Server Mode Connection

A Server mode is used by default. In this mode, the Developer Agent must be started after the Java runtime is started on the Raspberry Pi board. You must start the Application Management System (AMS) on the Raspberry Pi board with the usertest.sh command in the command-line shell interface. The command must be run using sudo to obtain superuser privileges to access all the peripherals on the board

Change to the bin directory on the Raspberry Pi and run the sudo ./usertest.sh command:
```
pi@raspberry ~ /pi/bin $ sudo ./usertest.sh
```

Change to the lib directory on your desktop host and enter the following command. You should see an output similar to the following:

C:\mydir\lib> java -jar proxy.jar -socket <RPI IP ADDRESS>

Channel 8 CLOSED -> AVAILABLE
Trying to open socket connection with device: <IP Address>:2201
Connected to the socket Socket[addr=/<IP address>, port 2201, localport=54784]
Debugger Connection initialized

Client Mode Connection

To switch to a client mode connection, perform the following steps.

Edit the jwc_properties.ini file in the bin directory on the Raspberry Pi board as follows:
- Set the proxy_connection_mode property to the client value.
- Set the proxy.client_connection_address property to the IP address of the host running the Developer Agent.
Run the sudo usertest.sh command in the /bin directory:
```
pi@raspberry ~ /pi/bin $ sudo ./usertest.sh
```

Change to the lib directory on your desktop host and enter the following command. You should see an output similar to the following:

C:\mydir\lib> java -jar proxy.jar
Starting with default parameters: -ServerSocketPort 2200 -jdbport 2801Channel 8 CLOSED -> AVAILABLEWaiting for device connections on port 2200

Running IMlets on the Raspberry Pi Using the AMS CLI

The next step is to make a raw connection to the AMS CLI. Note, however, that first the Developer Agent must be running on the desktop host and the Application Management System (AMS) - on the Raspberry Pi as described in the previous sections.

At this point, you can start a PuTTY executable on your desktop computer. Use this to create raw socket connections to the IP address of the host running the Developer Agent, and port 65002. For example, a connection to localhost and the port 65002 is shown in Figure 1-2.

Figure 1-2 Using PuTTY to Connect to the Command-Line Interface

Description of "Figure 1-2 Using PuTTY to Connect to the Command-Line Interface"

The window from port 65002 provides a command-line interface (CLI), and is shown in Figure 1-3:

Figure 1-3 Command-Line Interface to the Raspberry Pi

Description of "Figure 1-3 Command-Line Interface to the Raspberry Pi"

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 the AMS commands shown in Table 1-2.

Table 1-2 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-info <INDEX or NAME\|VENDOR>`	Show information about the installed IMlet
`help [command name]`	List the available commands or detailed usages for a single command
`exit`	Terminates the current session.

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.

oracle>> ams-install file:///some/directory/hello.jar
<<ams-install,start install,file:///some/directory/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.

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

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

Table 1-3 Properties 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)
`get-property <NAME> [-i]`	Returns a value of the property identified by `<NAME>`
`set-property <NAME> <VALUE>`	Sets a property identified by `<NAME>` with the value `<VALUE>`
`save-properties`	Saves properties to an internal storage
`blacklist -client <NAME> blacklist -app <NAME\|VENDOR>`	Blacklists clients and applications
`shutdown [-r]`	Perform either a shutdown of the board or a reboot if the `-r` parameter has been passed

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