General questions:

Download and Installation:

Development with Scratchbox:

Working with Maemo devices:

General questions:

What is ESbox?

ESbox is an Eclipse product for developing applications and libraries on the Maemo software platform.

ESbox is strongly integrated with Scratchbox, reducing time and effort for configuration and increasing the productivity for Linux-based embedded systems development. It supports C/C++ and Python programming languages. Maemo 4.x and 5.x SDKs are supported.

Applications may be built, run, debugged, and profiled in Scratchbox.  ESbox also supports deploying, running, debugging, and profiling applications and libraries on the Maemo device.

How is ESbox licensed?

This software is produced by the ESbox team combined with third party software developed from other Open Source Projects. This software has been licensed under Eclipse Public License Version 1.0 ("EPL").

How is the ESbox Project organized?

ESbox consists of three major layers:

  • Eclipse platform
    A popular and extensible framework for developing IDEs. See the website.
  • Mica (Maemo IDE Common Architecture)
    A plugin framework supporting both the ESbox and PluThon products, which provides an extensible platform for Maemo development:
    • Unified project model, with C/C++ and Python implementations
    • Linux development (e.g. Debian packaging, autotools, externalizing strings with gettext)
    • Support for copying files or mounting a project to run, debug, and profile programs on Maemo devices
    • and more! See the Mica project website for more information.
  • ESbox product
    A targeted set of product plugins, providing the top-level project and import wizards, this help, graphics, and user interface modifications giving ESbox its unique feel as a product.

How do I find out about future releases of ESbox?

To find out about releases see the ESbox Garage Project News page.

For regular integration releases, see the ESbox releases page

Note that at this time, there are no plans for further ESbox development.

Which operating systems does ESbox support?

The ESbox product runs on Linux (32 or 64 bit), Windows XP/Vista, and Mac OS X.

The underlying Scratchbox, on the other hand, only runs on Linux/i386. To support non-Linux hosts, ESbox can communicate with a virtual machine hosting the Maemo SDK.

ESbox, though Mica, operates essentially the same way regardless of which host you're running on. A limitation, though, is that your projects or workspace must be visible to both Scratchbox and the host. When Scratchbox is running on a virtual machine, we support this via Samba sharing from the host to the VM.

See the Maemo SDK virtual image page for configured and supported images and the ESbox virtual machine documentation.

How do I ask questions?

The website provides some mailing lists. Choose a list to browse, search, and post messages. Keep in mind that these newsgroups are public, so do not include any confidential information in your questions. You should also read "How to ask questions the smart way" by Eric Raymond before participating in the newsgroups.

How do I report a bug or request a feature?

The bug and feature trackers are stored at the ESbox project page.

Before entering a bug report, you should search to see if someone else has already entered a bug report similar to yours. If you find a bug report that outlines the problem you are seeing, you can simply annotate it with your comments to let the developers know that you have also hit the bug. Also you can add yourself to the "Monitor" list of the bug so that you will be notified when the status of the bug changes or someone adds comments.

Download and Installation:

Are there complete HowTos for setting up ESbox?

Yes, please see the ESbox installation guide. You may install either a fully packaged product or update an existing Eclipse 3.4.2 installation over the Internet.

How do I uninstall ESbox?

Removing plugins from Eclipse is easy. You can browse and manage your configuration from the Eclipse Software Updates dialog under Help > Software Updates.

Select the ESbox 2nd Edition and Mica 2nd Edition features from the list of Installed Software and click Uninstall.

Development in Scratchbox

How do I work with Scratchbox in ESbox?

System configuration

When you first use a command or run a wizard that needs Scratchbox, ESbox will automatically scan for Scratchbox 1 and Scratchbox 2 (if enabled) installations. Currently these conditions must be met:

  • Scratchbox 1: sb-conf visible and configured on search path in the Window > Preferences > ESbox > Scratchbox 1 preferences page.
  • Scratchbox 2: sb2-config and sb2 visible on PATH. (Scratchbox 2 is hidden by default, since it is not officially supported. See the General > Capabilities preferences.)

If the programs are not found, then the respective Scratchbox will not be usable.

If your system is not properly configured for Scratchbox, or you're using a non-default installation which does not configure itself at startup, you may need to right-click a Scratchbox SDK (in the Window > Preferences > Maemo > Installed Targets preferences) and invoke Startup to enable it.

Metaphors in ESbox

In ESbox, a Scratchbox installation is called an “SDK”. An individual target (like DIABLO_ARMEL) is a “target”.

See the preference page Window > Preferences > Maemo > Installed Targets to confirm and modify the Scratchbox installations. You should see a node for your Scratchbox installations (as configured on the ESbox > Scratchbox 1 preferences) based on what you have installed, and entries for each recognized target underneath. If not, try the Refresh button.

How do I work with ESbox in Windows or Mac OS X?

The Maemo SDK and tools only run on Linux/x86 at the moment, but you may run ESbox on Windows or Mac OS X. To do this, ESbox can use a virtual machine to handle all the building and running work.

You may install a virtual machine using the Maemo SDK Virtual Machine installer under File > New > Other > Maemo Installers.

The preference page Window > Preferences > ESbox > Build Machines is the gateway to configuring this facility for already-downloaded images.

Please see the ESbox virtual machine support documentation for all the details.

How do I install new versions of Scratchbox or new SDKs?

You can use the wizards in File > New > Other > Maemo Installers to install or upgrade Scratchbox 1. Currently Maemo 4 (Diablo) and Maemo 5 (Fremantle) are supported.

These wizards are also visible via Window > Preferences > Maemo > Installed Targets by clicking the New... button.

How do I install new Scratchbox targets?

You can use the wizards in File > New > Other > Maemo Installers to install or upgrade Scratchbox 1. Currently Maemo 4 (Diablo) and Maemo 5 (Fremantle) are supported for Scratchbox 1.

These wizards are also visible via Window > Preferences > Maemo > Installed Targets by clicking the New... button.

How do I synchronize packages with my project?

When you create a new project (File > New > Project > Maemo C or C++ Project or File > New > Project > Maemo Python Project), or when you invoke the Project > Validate Installed Packages command, ESbox will help you install the packages required by one or more projects into one or more Scratchbox rootstraps or with configured Maemo devices (see the next section).

ESbox will scan autotools-based projects for the packages implied by the PKG_CONFIG_CHECK macros in and install these if missing. For Python projects, module imports from source files are scanned and for other projects, default metapackages recommended by the Maemo Eclipse Integration project will be installed.

Networking setup

Be sure to visit the Network Connections preferences before updating packages, so any proxy settinges are established.

If you can't connect to any repositories...

At the time of this writing, there are sometimes issues where no combination of settings will allow you to connect to the repositories to update packages inside Scratchbox, when using proxies and running Scratchbox in a virtual machine. This is either a problem in scratchbox, in ESbox, in VMware, or in the hosting providers, or some combination – you choose :).

As a last resort, you may to edit /etc/hosts inside each Scratchbox rootstrap and enter a manual address for, e.g.:

(ping the address before using the example, since the addresses may change.)

When updating packages inside a Maemo device, you may also need to disconnect any “static” USB, WLAN, or Bluetooth connections and directly connect the device to a WLAN that can access the Internet, otherwise traffic may simply flow into the host computer and die there.

Working with Maemo devices

How do I set up my device for development?

The first important step is to install the maemo-pc-connectivity metapackage. This will install the proper servers on your device so you can access it from your PC for the purpose of remote SSH launching, copying files, debugging, and using Scratchbox Remote Shell.

You also need to set up your device for R&D mode (so you may become root, and install Debian packages, update the system from ESbox, etc).

Also, you must install the host-side programs needed for communication with the daemons and servers in maemo-pc-connectivity. (These are preinstalled in the virtual machine images or available in the host-pc-connectivity package.)

All the details are on the PC connectivity garage project page.

How do I configure my device for use with ESbox?

ESbox integrates the Eclipse Remote System Explorer project, which provides a common framework for interacting with remote machines.

ESbox will automatically create a set of RSE connections for the account "user" corresponding to the methods of network access supported by PC connectivity.

For example, Maemo device (USB) is preconfigured with the standard USB address ( and "user" account.

Whenever you see these connections in ESbox dialogs, you can right-click and Configure... to edit the address or username if your configuration is different. Alternately, open the Remote Systems view (Window > Show View > Other > Remote Systems > Remote Systems) to see more complete UI.

If you forget the address or otherwise mess up the connection, you can delete it (using the Remote Systems view) and it will be recreated anew the next time you start ESbox.

Currently, there is no special behavior associated with any of these connections other than the name and default address.

How do I run and debug on a device?

ESbox supports running and debugging C/C++ and Python programs on a Maemo device. The N800, N810, and N900 series are currently supported. Please set up your device for development first.

After you create or import a project, you may for example right-click project and invoke Run / Debug As ... > Maemo Remote ... Application. Choose the Copy Programs (SSH) download selection method, and then select one of the Maemo device connections.

The Mount Project (SBRSH) option is also available, but you must enable SBRSH and allow your host access to your device using the Connection Switcher utility on the device, and then Exchange Keys between the host and device.

If this fails, see the next entry.

How do I resolve networking issues?

Network configurations can be tricky (and doubly, or triply so, if you are running on Windows or OS X). You can expect to become familiar with the “Connection problem” dialog.

The primary thing to check is to make sure the connection works from the command line and that all the daemons and configurations are set up properly. See the PC connectivity site for details. Also, be sure you understand the utilities provided in the maemo-pc-connectivity project and follow the instructions for configuring various types of networks.

The second thing to know is that, in a virtual machine environment, it is best to use Bridged networking.  NAT networking will not allow your host, VM, and device to communicate together.

The third place to check is the Eclipse networking preferences.  The Window > Preferences > General > Network Connections preference contains the HTTP proxy configuration. This will be used when communicating with apt repositories (when validating packages). If you do use a proxy, be sure your host and your device are both referenced in the “No proxy” section. (Note: from my experience, you need to specify exact IP addresses here; wildcards and “slash notation” do not work.)

General issues with virtual machines and networking:

For most networking scenarios, the device must be visible to the host. In other words, they should be on the same network.

For SBRSH usage, the device must be visible to the virtual machine. This is because sbrsh runs in the VM and the device mounts the filesystem from a Scratchbox rootstrap.

In general, I have the easiest configuration experience using a WLAN on a network common to the host, virtual machine, and device. This requires the Bridged Networking configuration in VMware or VirtualBox. Unfortunately, this is slower for debugging.

For USB networking:

By default, a USB connection will mount the removable storage from the device into your computer. Use the Connection Switcher toolbar icon from the PC connectivity project to change the USB connection into a networking connection.

Typically the addresses used are static: (for the device) and (for the host).

If the command-line connection (verified with ssh) does not work, and the device is configured for USB networking, use sudo ifdown usb0; sudo ifup usb0 to try to reset. This should fix things.

In VMware, an icon in the toolbar or the VM > Removable Devices > Netchip RNDIS / Ethernet Gadget menu will help you quickly “connect” the device to the VM or to the host.

In VirtualBox, use a similar pattern. Connect or disconnect the device via Devices > USB Devices > Nokia N8x0 Table or the corresponding toolbar icon.

QEMU and VirtualBox OSE (at this writing) does not support USB at all, so you will probably need to use WLAN, or install host-pc-connectivity on host machine and set virtual machine networking to NAT mode.

For wireless networking:

The maemo-pc-connectivity package will let you configure and use several types of wireless networks (WLAN, ad-hoc WLAN, Bluetooth). Refer to that configuration to discover the configured IP addresses. For WLAN, the device will receive a semi-random IP address from the DHCP server.

In any case, you can verify the address and update the corresponding RSE connection like this:

  • In the device, run Utilities > X Terminal.
  • Execute /sbin/ifconfig to see what address is assigned to the wlan0 (WLAN, ad-hoc WLAN) or bnep0 (Bluetooth) interface.
  • Copy this address into the connection (in ESbox UI, right-click the Maemo device (...) connection and use Configure..., or edit it via Remote Systems view using Properties > Host).

SBRSH issues

SBRSH is quite tricky to configure right.

  • If you see the "sbrsh: authentication failed" message, be sure you have:
  1. Make sure you have a passwordless connection to and from the device.  Run ssh-key-exchange from the host-pc-connectivity package or use the Exchange SSH Keys... command from an SBRSH launch configuration > Download pane.  Verify the connection by using "ssh user@<remote>" (there should be no password) and then from inside that shell, "ssh <you>@<host>" (again, there should be no password).
  2. Ensure that the host is allowed to use sbrsh. Use the PC-Connectivity Manager, set up a Default or custom environment, and under the Tool Manager, ensure that SBRSH is enabled and that the Allowed IPs includes your host's address or IP range (e.g. 10.0.2.*). Alternately, manually edit /etc/sbrshd.conf.
  • If you see errors from sshfs about invalid mounts, these may be a transient issue. Retry once and it might go away.
  • If you see permission errors about changing to the working directory on the device, this may also be a transient issue. Try deleting the directory and trying again.

And, of course, consult the PC Connectivity documentation for more details.