Maemo for mobile developers

Scratchbox configuration

Note that the example application was compiled and tested in an i386 target. To run the application on a device, you need to build it on a proper ARMEL target. When you install the maemo SDK using the VMWare package or the installation script for Linux, the ARMEL target is installed by default. To compile and run the created application inside an ARMEL architecture simulation, follow these instructions.

Note: This process is the same for both Linux and Windows machines.

1. Stop the application framework with the following command:

   [sbox-SDK_X86: ~] > af-sb-init.sh stop

2. Type the following command and press Enter to open the Scratchbox configuration menu:

   [sbox-SDK_X86: ~] > sb-menu

3. The Scratchbox opens:
   
4. Use the DOWN ARROW key to navigate to the Select Activate a target menu option and press Enter.
5. In the Select target submenu, select the SDK_ARMEL target and press Enter:
   
6. Now, install the C++ bindings and necessary packages for this tutorial as explained in Updating and installing development packages. After you have completed the installation, you can build your application.
7. Test your environment framework with the following command:

   [sbox-SDK_ARMEL: ~] > af-sb-init.sh start

   The maemo framework should load up just as before with the PC_ARMEL target.
8. Now you can build and run the "Hello World" application as explained in building the application. If there are no errors, the application is ready to be packaged and embedded into your Linux device. You can try moving the application to a device or proceed to the Advanced build and packaging section.

Moving the application to a device

There are several ways to get an application to a device. This section focuses on copying the application to the device instead of packaging it.

Upload via USB

This section explains how to upload an application to a device using an USB cable and a memory card. If you have a memory card inserted on your device, do as follows:

1. Plug a USB cable into your device and on your computer. Your system recoginzes the device as a new USB disk drive.
2. Copy the binary application file (in this case called helloworld) to the device.
3. After copying the file, unmount the disk drive and remove the USB cable from both devices.
4. Your application is now installed in the device, but not yet ready for execution. In order to execute it, open X-terminal and run this command (mmc1 for the internal memory card, mmc2 for the removable memory card):

$ run-standalone.sh /media/mmc1/helloworld

Upload via Bluetooth

In this case, your computer needs to support Bluetooth (for example, a Bluetooth dongle).

1. From your computer, select the binary application file (in this case helloworld) and send it via Bluetooth to your device.
2. The device will display a warning that a file is being sent to it. Choose 'Save' and select the name and directory where you want save the file.
3. Your application is now saved to the device, but not yet ready for execution. In order to execute it, open X-terminal and run this command (this example assumes that the file is in the MyDocs folder):

$ run-standalone.sh ~/MyDocs/helloworld

Upload via WLAN/SSH

First of all, you need a wireless infrastucture, such as a wireless router, or you can choose to have an ad-hoc connection between the device and the computer.

Part 1: Creating a wireless connection

Wireless infrastucture

If you have a wireless router (or similar), your computer does not necessarily need to have a wireless card (it can be connected through a network cable, for example). The computer and the device are in the same subnet coverage, so you can simply grab the IP address from the device and connect to it. The process of grabbing the device's IP address is explained below.

Ad-hoc connection

An ad-hoc connection connects a set of devices (in this case, your computer and your device) on a wireless, non-centered connection. In this case you can start the ad-hoc network from both devices. To start an ad-hoc connection through the device:

1. On the device, click the menu and go to Settings > Connection manager.
   
2. A new window opens. Click the tab, then Tools and Connectivity settings.
   
   Note: You can also go to this window from the 'wireless' icon on the status bar. Click Connectivity Settings.
3. A new window opens. Click Connections.
   
4. Again, a new window opens. Choose New. A new window opens. Click Next.
   
5. Give the connection a name and set the connection type to WLAN. Click Next and No when asked to search for networks.
   
6. Choose the Network name (SSID), and mark the network mode as Ad hoc. Choose the security method you want for your connection and click Next.
   
7. Click Finish to conclude, Done to close the previous window, and then OK to close the other window.
   
8. Now, in the Connection manager window, click Select connection, select the ad-hoc connection you just created, and click Connect.
   

Grabbing the IP address from your device

Your device is now connected to a wireless network. It is time to grab its IP address in order to connect to it via SSH as explained below.

1. On the device, click on the menu and go to Settings > Connection manager.
2. A new window opens. Click the window tab and go to Internet connection > IP address.
   
3. A new window opens. Write the IP address down.

Part 2: Installing osso-xterm and ssh from maemo diable repository

X terminal

In order to install the 'osso-xterm' application, you need a working Internet connection on your device. After connecting to the Internet, follow these steps:

1. On the device, click the menu and go to Settings > Application manager.
   
2. A new window opens. Click the tab and go to Tools > Application catalogue.
   
3. Click New and fill in the following data:
   • Catalogue name: Maemo Diablo
   • Web address: http://repository.maemo.org
   • Distribution: diablo
   • Components: free non-free
   • Disabled: leave unchecked
   
   Click OK and Close to return to the main window.
4. The device asks if you want to refresh the package list. Click OK.
5. Now click Browse installable applications > All, select osso-xterm, and click Install.
   

Osso-xterm is now installed on your device.

SSH client/server

In order to install the ssh client/server, the maemo diablo repository must have been added and osso-xterm installed.

1. On the device, click the menu and go to Utilities > X Terminal.
   
2. The application opens and you will be logged in.
   
3. Run this command to become root and to get privileges:

   $ sudo gainroot

4. Now you are logged in as 'root'. Install 'ssh' using the apt-get command:

   $ apt-get install -y ssh

5. Now you have installed both ssh client/server applications. They do not have a graphical user interface (GUI), even though you can use 'SSH' and 'SCP' commands from the terminal (these are explained below).

Part 3: Connecting to the device via SSH/SCP

Creating a remote shell connection to your device

Now that you have a connection between your computer and your device, it's time to create a secure shell (SSH) connection between them. It enables you to download and upload files and also work on the device from your computer, from a remote shell. Run the following command on your computer:

$ ssh root@<device_ip_address>

Note: Password: rootme

This remote shell allows you to create, execute, modify, and access files on your device. You can, for example, execute your application on the device remotely from your computer and check for console output at the same time you have the 'hello world' window open on the device.

Transfering files between your computer and your device through SCP

SCP is a tool used to copy files from one device to another, through a secure remote connection. You can send or receive files from this. In general, the SSH-server acts as a daemon for incoming connections, so you will not be notified if someone wants to connect to your computer (but log-in access is, of course, needed). Run this command to send your application to the device from your computer using SCP:

$ scp helloworld root@<device_ip_address>:~/MyDocs

You can also make the invert: copy a file from the device to your computer, as in this example:

$ scp root@<device_ip_address>:~/foo.txt .

The file foo.txt is saved in the top directory where you are at the moment. Your application is now installed in the device, but not yet ready for execution. In order to execute it, open X-terminal on the device and run this command:

$ run-standalone.sh <folder>/helloworld

Preparing the device for applications

In order to install the application's dependencies, you have to complete the step (add maemo diablo repository and install osso-xterm) with an Internet connection working on your device. Follow the steps below:

1. From your device, click the menu and go to Utilities > X Terminal.
   
2. The application opens and you get a cursor waiting for user input.
   
3. Type this command to become root and to get administrator rights:

   $ sudo gainroot

4. Now you are logged in as 'root'. Install the libraries' dependencies using the apt-get command:

   $ apt-get install -y libhildonmm libhildon-fmmm libgconfmm

5. Now the example applications in this document can be run.