2 Using NetBeans or Eclipse with the Raspberry Pi Board

Installing the Oracle Java ME SDK 3.3 Plugin for NetBeans

After installing NetBeans, use these steps to install the remaining software.

1. Ensure that Java ME is enabled in NetBeans. This can be done by selection Tools -> Plugins and selecting the Installed pane. Activate the Java ME plugin if it is not already activated.

2. Install the Java ME SDK 3.3 distribution. See the Java ME SDK 3.3 documentation for details.

3. Install the Oracle Java ME SDK 3.3 NetBeans plugin. This is a downloadable ZIP file that consists of a number of NetBeans modules (.nbm files) that can be added using the Tools -> Plugins dialog and selecting the Downloaded pane. The Oracle Java ME SDK 3.3 NetBeans plugin is required to use the Device Selector to connect to the board. See the Oracle Java ME SDK 3.3 Release Notes for installation instructions:

   http://docs.oracle.com/javame/dev-tools/jme-sdk-3.3/release-notes/toc.htm

4. Ensure that the Oracle Java ME Embedded 3.3 appears in the list of Java ME platforms. In the NetBeans IDE, go to Tools -> Java Platforms. If the Oracle Java ME Embedded 3.3 does not appear in the list of J2ME platforms, follow these steps:

   • Click on Add Platform.

   • Select Java ME CLDC Platform Emulator and click Next.

   • Select the folder where the Oracle Java ME SDK 3.3 runtime for Raspberry Pi resides and follow the instructions to install it. Then, click Finish to close the dialog.

5. Ensure that the Raspberry Pi board has the Oracle Java ME Embedded distribution. See Chapter 1 for more information on how to install the runtime distribution on the Raspberry Pi board.

Adding the Raspberry Pi Board to the Device Selector

Follow these steps to add the board to the Device Selector in the Oracle Java ME SDK:

1. Ensure that the property odt_run_on_start is set to true in the file bin/jwc_properties.ini on the Raspberry Pi.

2. Ensure that the sudo usertest.sh script in the /bin directory on the Raspberry Pi is running. This allows the IDE to connect to the board. If an error occurs at any point during the debug process, you will need to restart this script.

3. If necessary, open TCP port 55123 in the firewall settings of your computer. The exact procedure to open a port differs depending on your version of Windows or the firewall software that is installed on your computer.

4. Start the NetBeans IDE. In the NetBeans IDE, go to Tools -> Java ME -> Device Selector

5. On the Device Selector, click on the Add a Device button at the top of the Device Selector window.

   
   Description of the illustration adddevice.jpg
   
   

6. Write the IP address of the Raspberry Pi board in the IP Address field and click Next. You can find the IP address of the Raspberry Pi board by starting an LXTerminal program and entering the ifconfig command. The address should be listed in the inet addr field in the eth0 entry.

   
   Description of the illustration devicedetect.jpg
   
   

7. Once the device is detected, click Finish on the Device Detection screen.

The list of devices in the Device Selector should now include IMPNGExternalDevice1.

Assigning the Raspberry Pi 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, follow these steps:

1. Right-click on your project and choose Properties.

2. Select the Platform category on the properties window.

3. Select IMPNGExternalDevice1 from the device list.

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

1. Select File -> New Project.

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

3. Provide a project name and click Next. Be sure that the Create Default Package and IMlet Class option is checked.

4. Ensure the Emulator Platform is Oracle Java ME Embedded 3.3. Then, select IMPNGExternalDevice1 from the device list and click Finish.

After you assign the board to your project, the IMlets run on the board instead of on the emulator when you click on Run Project on the NetBeans IDE.

Sample Source Code

Once the project is created, use the source code in Example 2-1 for the default IMlet.java source file.

package embeddedapplication1;
 
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.gpio.GPIOPin;
import java.io.IOException;
import javax.microedition.midlet.*;
 
 
public class IMlet extends MIDlet {
 
    public void startApp() {
        
        try {
            GPIOPin pin = (GPIOPin)PeripheralManager.open(2);
            boolean b = pin.getValue();
        } catch (PeripheralNotAvailableException ex) {
            ex.printStackTrace();
        } catch (PeripheralNotFoundException ex) {
            ex.printStackTrace();
        } catch (IOException ex) {
            ex.printStackTrace();
        }
        
    }
    
    public void pauseApp() {
    }
    
    public void destroyApp(boolean unconditional) {
    }
}

This sample application will obtain an object representing GPIO pin 1 from the PeripheralManager, and attempt to obtain its high/low value.

Method #1: Modifying the Security Policy File

Modifying the security policy file is only necessary in the event that a user must manually install the application on the board, at which point the unsigned application will be installed in the untrusted security domain.

With this method, simply add the line "allow: device_access" to the "untrusted" domain of the security policy file. By default, this is located on the SD card in the appdb/_policy.txt file, but be sure to check the security.policy file entry in the bin/jwc_properties.ini file to verify the current file name.

Note that if an application is installed on the board using NetBeans or Eclipse during development, the application will automatically be installed in the maximum security domain as a convenience. Manual installation, however, will install the unsigned application into the untrusted security domain. Note that after development is finished, you should publish your applications with signed API permissions.

Method #2: Signing the Application with API Permissions

The second method is more complex, but is the preferred route for applications that are widely distributed. First, the JAD file must have the proper API permissions. Right-click the project name (EmbeddedApplication1 in this example) and choose Properties. Select Application Descriptor, then in the resulting pane, select API Permissions. Click the Add... button, and add the com.oracle.deviceaccess.gpio API, as shown in Figure 2-1. Click OK to close the project properties dialog.

Figure 2-1 Adding API Permissions with NetBeans

Description of "Figure 2-1 Adding API Permissions with NetBeans"

Applications that access the Device Access APIs must also be signed. Here are the instructions on how to setup a keystore with a local certificate that can be used to sign the applications.

1. Generate a new self-signed certificate with the following command on the desktop, using the keytool that is shipped with the Java SE JDK.

   keytool -genkey -v -alias mycert -keystore mykeystore.ks -storepass spass -keypass kpass -validity 360 -keyalg rsa -keysize 2048 -dname "CN=thehost"

   This command will generate a 2048-bit RSA key pair and a self-signed certificate, placing them in a new keystore with a keystore password of "spass" and a key password of "kpass" that is valid for 360 days.

2. Copy the appdb/_main.ks keystore file from the Raspberry Pi over to the desktop and perform the following command using the mekeytool.exe command (or alternatively java -jar MEKeyTool.jar... if your distribution contains only that) that ships with the Oracle Java ME SDK 3.3 distribution.

   {mekeytool} -import -MEkeystore _main.ks -keystore mykeystore.ks -storepass spass -alias mycert -domain trusted

   This will import the information in mykeystore.ks you just created to the _main.ks keystore. Once this is completed, copy the _main.ks file back to its original location on the Raspberry Pi.

Use the following steps to sign your application before deploying to the Raspberry Pi board.

1. Right click your project and select Properties.

2. Choose the Signing option under the Build category.

3. Open the Keystores Manager and import the mykeystore.ks file that you created.

4. Check the Sign Distribution box. If you wish, unlock the keystore and the key with the passwords that you specified earlier. This is shown in Figure 2-2.

5. When the project is built and run, it will be digitally signed and deployed to the Raspberry Pi.

Figure 2-2 The Signing Pane in the NetBeans Project Properties

Description of "Figure 2-2 The Signing Pane in the NetBeans Project Properties"

Installing the Oracle Java ME SDK 3.3 Plugin for Eclipse

After installing Eclipse, use these steps to install the remaining software.

1. Install the Java ME SDK 3.3 distribution. See the Java ME SDK 3.3 documentation for details.

2. Install the Oracle Java ME SDK 3.3 Eclipse plugin. This is required to use the Device Selector to connect to the board. See the Oracle Java ME SDK 3.3 Release Notes for installation instructions:

   http://docs.oracle.com/javame/dev-tools/jme-sdk-3.3/release-notes/toc.htm

3. Ensure that the Raspberry Pi board has the Oracle Java ME Embedded 3.3 runtime. See Chapter 1 for more information on how to install the runtime distribution on the Raspberry Pi board.

4. Ensure that the Oracle Java ME Embedded 3.3 appears in the list of Java ME platforms. If it doesn't appear, follow these steps for your project properties.

   • Under the Java ME category, select Device Management. In the Device Management window, press the Manual Install... button.

   • The Manual Device Installation window appears, without the Oracle Java ME Embedded devices. Press the Browse button. A browser window appears.

   • Browse to the base directory of the Java ME SDK environment and press the OK button. After the platform is scanned and the devices are installed, close each of the respective dialogs.

Adding the Raspberry Pi Board to the Device Selector

Follow these steps to add the board to the Device Selector in the Oracle Java ME SDK:

1. Ensure that the property odt_run_on_start is set to true in the file bin/jwc_properties.ini on the Raspberry Pi.

2. Ensure that the sudo usertest.sh script in the /bin directory on the Raspberry Pi is running. This allows the IDE to connect to the board. If an error occurs at any point during the debug process, you will need to restart this script.

3. If necessary, open TCP port 55123 in the firewall settings of your computer. The exact procedure to open a port differs depending on your version of Windows or the firewall software that is installed on your computer.

4. Start the Eclipse IDE. In the Eclipse IDE, go to Window -> Show View -> Other. In the popup window that appears, expand the Java ME node and select Device Selector.

   
   Description of the illustration showview.jpg
   
   

5. On the Device Selector, click on the Add a Device button at the top of the Device Selector window.

   
   Description of the illustration devselecl.jpg
   
   

6. Write the IP address of the Raspberry Pi board in the IP Address field and click Next. You can find the IP address of the Raspberry Pi board by starting an LXTerminal program and entering the ifconfig command. The address should be listed in the inet addr field in the eth0 entry.

   
   Description of the illustration devdetecl.jpg
   
   

7. Once the device is detected, click Finish on the Add Device screen.

The list of devices in the Device Selector should now include IMPNGExternalDevice1.

Assigning the Raspberry Pi Board to Your Project

If you already have an existing Eclipse project with an IMlet that you want to run or debug on the board, follow these steps:

1. Right-click on your project and choose Properties.

2. Select the Java ME category on the properties window.

3. Select IMPNGExternalDevice1 from the device list. If the device is not shown, add it using the Add... button, selecting Oracle Java ME Embedded 3.3 as the SDK and IMPNGExternalDevice1 as the device.

If you are creating a new Eclipse project from scratch, follow these steps:

1. Select New -> Other. Then expand the Java ME tree node, and create a new MIDlet Project.

2. Expand the Java ME tree node, and create a new MIDlet Project.

3. In the Configuration pane of the creation dialog, select IMPNGExternalDevice1 from the device list.

4. Select the appropriate Profile and Configuration for your project.

After you assign the board to your project, the IMlets run on the board instead of on the emulator when you click on Project -> Run on the Eclipse IDE.

Sample Source Code

Once the project is created, use the source code in Example 2-2 for a default source file.

package embeddedapplication1;
 
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.gpio.GPIOPin;
import java.io.IOException;
import javax.microedition.midlet.*;
 
 
public class IMlet extends MIDlet {
 
    public void startApp() {
        
        try {
            GPIOPin pin = (GPIOPin)PeripheralManager.open(2);
            boolean b = pin.getValue();
        } catch (PeripheralNotAvailableException ex) {
            ex.printStackTrace();
        } catch (PeripheralNotFoundException ex) {
            ex.printStackTrace();
        } catch (IOException ex) {
            ex.printStackTrace();
        }
        
    }
    
    public void pauseApp() {
    }
    
    public void destroyApp(boolean unconditional) {
    }
}

This sample application will obtain an object representing GPIO pin 1 from the PeripheralManager, and attempt to obtain its high/low value.

Method #1: Modifying the Security Policy File

Modifying the security policy file is only necessary in the event that a user must manually install the application on the board, at which point the unsigned application will be installed in the untrusted security domain.

With this method, simply add the line "allow: device_access" to the "untrusted" domain of the security policy file. By default, this is located on the SD card in the appdb/_policy.txt file, but be sure to check the security.policy file entry in the bin/jwc_properties.ini file to verify the current file name.

Note that if an application is installed on the board using NetBeans or Eclipse during development, the application will automatically be installed in the maximum security domain as a convenience. Manual installation, however, will install the unsigned application into the untrusted security domain. Note that after development is finished, you should publish your applications with signed API permissions.

Method #2: Signing the Application with API Permissions

The second method is more complex, but is the preferred route for applications that are widely distributed. Open the Application Descriptor for your project in the Packages window, and select the Application Descriptor pane. You will need to manually add or change the following lines in the Application Descriptor.

MIDlet-Permissions: com.oracle.deviceaccess.gpio
Microedition-Profile: IMP-NG

Applications that access the Device Access APIs must also be signed. Here are the instructions on how to setup a keystore with a local certificate that can be used to sign the applications.

1. Generate a new self-signed certificate with the following command on the desktop, using the keytool that is shipped with the Java SE JDK.

   keytool -genkey -v -alias mycert -keystore mykeystore.ks -storepass spass -keypass kpass -validity 360 -keyalg rsa -keysize 2048 -dname "CN=thehost"

   This command will generate a 2048-bit RSA key pair and a self-signed certificate, placing them in a new keystore with a keystore password of "spass" and a key password of "kpass" that is valid for 360 days.

2. Copy the appdb/_main.ks keystore file from the Raspberry Pi over to the desktop and perform the following command using the mekeytool.exe command (or alternatively java -jar MEKeyTool.jar... if your distribution contains only that) that ships with the Oracle Java ME SDK 3.3 distribution.

   {mekeytool} -import -MEkeystore _main.ks -keystore mykeystore.ks -storepass spass -alias mycert -domain trusted

   This will import the information in mykeystore.ks you just created to the _main.ks keystore. Once this is completed, copy the _main.ks file back to its original location on the Raspberry Pi.

Use the following steps to sign your application before deploying to the Raspberry Pi board.

1. Right click your project and select Properties.

2. Choose the Signing option under the Java ME category.

3. Check the Enable Project Specific Settings checkbox. Import the mykeystore.ks file that you created as an External... keystore file. Provide the keystore and key passwords that you created earlier. Ensure that the mycert key alias is present.

4. Ensure that the project is being signed in the project's Application Descriptor. When the project is built and run, it will be digitally signed when deployed to the Raspberry Pi.