PC Connectivity

Note about new version

Note: the information on this page applies to a bundle of software available for Maemo 4.1 Diablo Extras and released in June 2008, and supercedes other maemo.org wiki pages.

The next edition of this software is currently available, in testing and due for release in September 2009, which has much-improved host-side and device-side support.  The same essential low-level software is used, but configuration and setup is much easier.  If you're willing to test this out and provide feedback, please see http://pc-connectivity.garage.maemo.org for complete instructions.

(That content supercedes this content and anything else in maemo.org wikis.)

Introduction

The default maemo development environment consists of two parts: The host PC environment with a maemo SDK installation, and the Tablet. Components are usually developed as far as possible using the maemo SDK (on the host PC). Only after everything seems to function is testing done with the true Tablet environment to make sure there are no problems. During this final verification phase with the Tablet it must be as easy as possible to run, test and debug components using the Tablet.

To simplify setting up of communication between the host PC and the Tablet, maemo provides a PC Connectivity meta package maemo-pc-connectivity which installs the necessary components to the Tablet, along with these instructions for configuring connectivity between the host PC and the Tablet.

The PC Connectivity meta package is available from the maemo SDK community repository. For instance, for maemo Chinook the package is in the Chinook Extras repository and for maemo Diablo the package is in the Diablo Extras repository. The package will install components and tools to the tablet needed to set up and configure USB Networking, ssh connection, disk mounting (with sshfs/fuse and NFS) and the Scratchbox Remote Shell. Notice that for NFS client support some extra packages need to be installed and configured to the Tablet.

Maemo PC connectivity supports both N800 and N810 Internet Tablet devices.

Notice that there is no PC Connectivity meta package available for the host PC installation, because the host PC side of maemo PC connectivity uses only standard components available for most Linux distributions (and most components are available even for other operating systems like Unixes, Windows and Mac).

Installation to the Tablet

To install the maemo-pc-connectivity meta package on the Tablet you need to enable the maemo SDK Extras repository for the Tablet and install the package with "apt-get" or the Application Manager using the single click installation file.

First, be sure your tablet is configured to access the internet properly over wifi. If you are behind a firewall and need to use a web proxy, enter the settings in Settings > Control Panel > Connectivity > Connections > your wifi connection > Edit > Next > Next > Advanced > Proxies .

To install the maemo-pc-connectivity meta package using a single click installation file:

Note that there may be a long delay during installation. This is normal because some basic configuration is done during installation.

To install maemo PC Connectivity using apt-get you need to enable the Extras repository with the following steps:

  • Run Settings > Application Manager

  • Go to menu > Tools > Application Catalog...

  • Click “maemo Extras”

  • Click “Edit”

  • Then uncheck “Disabled”

  • Hit “Ok”

  • Answer “OK” for “Refresh application list?”

and then install the "maemo-pc-connectivity" meta package

  • Become root, and invoke "apt-get install maemo-pc-connectivity" .

Installation to the host PC

These installation instructions support only Debian-based Linux distributions such as Ubuntu. If you need to use a different Linux distribution (or even a different operating system than Linux) then you must discover the necessary connectivity components and installation instructions yourself.

Note that host PC connectivity components need to be installed to the host PC and not to the scratchbox rootstraps.

Verify kernel USB networking support

Verify that your host PC supports USB networking and has USB gadget support enabled. These are necessary to establish networking and to handle the specific USB-over-ethernet protocol used by the Tablet:

  • cat /boot/config-`uname -r` | grep -E 'CONFIG_USB_(NET_CDCETHER|GADGET)='

  • If "/boot/config-*" doesn't exist, try replacing the "cat /boot/..." command with "zcat /proc/config.gz"

These should show two lines ending in either "=m" or "=y" . If either is "=n" then you need to find or build a kernel with USB networking and USB gadget support.

If the lines show "m" , then you can test inserting the modules with "sudo modprobe cdc_ether g_ether" (this usually happens automatically, but if you get errors here then it's worth diagnosing them).

If you do not natively run Linux, or you want to experiment, you may choose to use a VMware image (such as the maemo VMware appliance version 0.7 or newer. In a VMware image, be sure that “USB Controller” is added as a device under the Hardware for the guest.

Install SSH

To connect to the Tablet, install an SSH client. If you plan to use SBRSH, install a server too. “openssh-client” and “openssh-server” are suitable.

  • sudo apt-get install openssh-client openssh-server

Install SSHFS

If you want to explore or modify the Tablet file system directly from the host, install SSHFS on the host. The “sshfs” package contains what you need.

  • sudo apt-get install sshfs

Install SBRSH

Support for sbrsh is included in Scratchbox CPU transparency devkit versions 1.0.7 and later. Be sure to manually update this since earlier maemo SDK installers (for releases before Diablo) may give you an older version by default.

Note that is is possible to have more than one version of the same scratchbox devkit installed at the same time.

On a Debian-based system add the following line to your host PC system "/etc/apt/sources.list" file

  • deb http://scratchbox.org/debian/ apophis main

and run "sudo apt-get update" .

Upgrade the package outside scratchbox by running "sudo apt-get install scratchbox-devkit-cputransp" .

On non-Debian based systems, refer to the Scratchbox Apophis download page .

Verify the version:

/scratchbox/devkits/cputransp/bin/sbrsh -v

Scratchbox Remote Shell Client 7.6

Configure USB networking

After the maemo PC connectivity components have been installed on the Tablet and host PC they need to be configured to use USB Networking between the Tablet and the host PC.

Tablet setup

After installing the maemo-pc-connectivity meta package, the Tablet will be configured like this:

  • When USB networking is enabled, the "g_ether.ko" module will be loaded

  • The "usb0" interface will be configured for the static device address 192.168.2.15 and host address 192.168.2.14.

If you need to use different addresses, perhaps due to a conflict with a LAN, edit "/etc/network/interfaces" on the Tablet and substitute appropriate values in the remainder of the document.

Host PC setup

On your Ubuntu host PC you need to edit "/etc/udev/rules.d/85-ifupdown.rules" file and change following line

  • SUBSYSTEM=="net", DRIVERS=="?*", GOTO="net_start"

to this line

  • SUBSYSTEM=="net", GOTO="net_start"

For Debian this change is not needed. For Ubuntu if this workaround is not done and USB cable will be unplugged and plugged back to Tablet, the usb0 network interface will not get its IP address back and network needs to be restarted with "/etc/init.d/networking restart". This is a bug in Ubuntu (related bug report is here ).

On your Ubuntu or Debian host PC, set up your network interfaces so that the USB network will be routed properly:

  • Edit the network interface configuration in the host's "/etc/network/interfaces" file.

  • Add these lines to the end, if not already present:

auto usb0
allow-hotplug usb0

mapping hotplug
script grep
map usb0

iface usb0 inet static
address 192.168.2.14
netmask 255.255.255.0
network 192.168.2.0
broadcast 192.168.2.255
up iptables -t nat -A POSTROUTING -s 192.168.2.15 -j MASQUERADE
up echo 1 > /proc/sys/net/ipv4/ip_forward
down iptables -t nat -D POSTROUTING -s 192.168.2.15 -j MASQUERADE
down echo 0 > /proc/sys/net/ipv4/ip_forward

These will ensure that "ifup usb0" will set up the same IP addresses that the Tablet side default configuration expects. It also allows the Tablet to access the Internet through the connection. But don't run that command yet – you need to connect cables and set up things in the right order as specified in the following sections.

Test USB connection

Once the previous installation and configuration tasks are complete, you should be able to test the connection.

After rebooting, the Tablet is configured for USB mass storage access. If you plug-in the USB cable, the flash drives on the Tablet will be visible to your host. It is easiest to use the USB networking control panel applet (installed to the Tablet by the maemo-pc-connectivity meta package) to switch to USB networking before connecting cables.

Follow this process whenever you want to set up USB networking:

On the Tablet:

  • Run Settings > Control Panel > USB networking

  • Click “Setup USB networking”

  • You may see a message saying “Unable to connect via USB. Memory card in use: Removable memory card”.

  • If so:

    • Unmount the drives on the host.

    • Unplug the cable.

    • Click “Setup USB networking” again.

  • Plug in the USB cable.

The USB networking applet is still unstable, and users can experiment some missbehaviours in some ocasions.

As an alternative, you can configure USB networking manually on the Tablet:

  • Run Utilities > X Terminal

  • Type "sudo gainroot"

  • Type "insmod /mnt/initfs/lib/modules/2.6.21-omap1/g_ether.ko"

  • Type "ifup usb0"

  • Plug in the USB cable

  • To disable USB network:

    • Type "ifdown usb0"

    • Type "rmmod g_ether"

On the host PC:

  • If you are in a VMware Linux image:

    • Go to VM > Removable Devices > USB Devices and enable “Netchip Modem”. This setting should be sticky, but will sometimes be reset if you plug in to alternate USB ports.

    • If this hangs VMware, unplug the cable and wait a short time until you get two “device in use” error messages, one from Windows and one from VMware (likely because of automatic USB Mass Storage).

    • Plug in the cable again.

  • Invoke "sudo ifdown usb0 ; sudo ifup usb0" . The down/up sequence ensures that the host PC will attempt to reconnect the interface.

  • If this results in a lot of errors that end with "Failed to bring up usb0" , try again a few times – there can be a delay as the host PC and the Tablet become aware of each other. If it doesn't succeed (empty output), you may have to unplug/plug the USB cable again, and/or press “Setup USB networking” in the USB networking applet again.

  • Test the connection: "ping 192.168.2.15"

  • If you get ping times then it is working (use Ctrl-C to exit). Otherwise, try again. This can be an annoying process, especially in VMware where the USB connection may be automatically configured for mass storage every time you plug in the cable. It may even require restarting VMware in some cases.

Configure the SSH connection

SSH (secure shell) allows you to run programs on the Tablet from the comfort of your host PC. Also, SSH packages come with SCP (secure copy) to let you copy files from the host to the Tablet.

Verify connection

Verify the installation from the host:

  • ssh root@192.168.2.15

If this is your first connection attempt to the Tablet, you will be asked to verify the connection:

The authenticity of host 'host (192.168.2.15)' can't be established.
RSA key fingerprint is ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'host,192.168.2.15' (RSA) to the list of known hosts.

Then you will be asked the root password (changed during the maemo-pc-connectivity setup of openssh):

  • ssh root@192.168.2.15's password:

Then, assuming success, you should be presented with a shell (the exact text depends on the OS image):

BusyBox v1.6.1 (2007-09-27 18:08:59 EEST) Built-in shell (ash)
Enter 'help' for a list of built-in commands.
Nokia-Nxxx:~#

Eliminate password prompt

To avoid entering the password every time, you need to authorize the target to accept your identity from the host.

This process works in either direction, so “host” and “target” will change meaning. Initially you want “host” to be your Linux machine (host PC) and “target” to be the Tablet. For SBRSH setup (below), you will swap these, since the Tablet needs to make an ssh connection to the host PC as well.

The general steps are:

  • Create a public/private keypair for a given user's identity on the host

  • Copy the public key to the target user's database of authorized keys

  • Ensure the database is readable only by the target user

Please, note:

  • You must apply the appropriate steps for every host and target user combination. (You will probably want to connect to the “root” and “user” accounts on the Tablet for a given Linux user.)

  • You will only need to generate a given user's public key once, but it must be copied into every target user's database.

To create the host user's public key:

<host> ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/hostuser/.ssh/id_rsa):
Created directory '/home/hostuser/.ssh'.
Enter passphrase (empty for no passphrase): <hit Enter>
Enter same passphrase again: <hit Enter>
Your identification has been saved in /home/hostuser/.ssh/id_rsa.
Your public key has been saved in /home/hostuser/.ssh/id_rsa.pub.
The key fingerprint is: f:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff

To copy the public key to the target user's database:

<host> scp ~/.ssh/id_rsa.pub targetuser@TARGET-IP:/tmp #(e.g., root@192.168.2.15 )
 targetuser@ TARGET-IP 's password:

<host> ssh targetuser@TARGET-IP
targetuser@ TARGET-IP 's password:

<target> mkdir -p ~/.ssh
<target> cat /tmp/id_rsa.pub >> ~/.ssh/authorized_keys
 <target> chmod 600 ~/.ssh/ authorized_keys

Exit the ssh session and test the connection. There should be no need for a password, For instance:

  • ssh root@192.168.2.15

Configure SSHFS

SSHFS (SSH FileSystem) allows you to access the Tablet's file system from a mount on the host PC.

If you want to test mounting of the Tablet file system, enter commands like this (it's your choice how much to see, or where to mount): ~ $ mkdir -p ~/tablet
~ $ sudo sshfs user@192.168.2.15:/ ~/tablet -o rw,allow_other,nonempty
user@192.168.2.15's password:

Note that sshfs is a user file system so you cannot use "mount" directly.

Use "sudo umount ~/tablet" to unmount.

Configure SBRSH

Sbrsh is the Scratchbox Remote Shell. It allows you to run programs from the host PC, using the host filesystem, but execute them on the Tablet. This lets you execute programs on the Tablet without using "scp " and "ssh " (or other more time consuming methods).

Filesystems may be exported from the host PC to the Tablet using sshfs or NFS. Because the Tablet does not support NFS mounts by default, the Tablet file system cannot be exported to the host PC using NFS. Notice also that for NFS client support some extra packages need to be installed and configured to the Tablet.

There are two major ways to use sbrsh:

  • Standalone use: If you run "sbrsh <program>" outside scratchbox, then it will launch an ARMEL program on the Tablet.

  • CPU transparency: If you configure scratchbox to use sbrsh as the CPU transparency method then, within scratchbox, any ARMEL binary will be executed on the Tablet instead of being emulated by qemu-arm.

In either mode, you usually configure sbrsh to use the scratchbox rootstrap as the file system exposed to the Tablet.

You will want to verify that sbrsh runs in standalone mode before setting it up as CPU transparency mode. Otherwise it may be difficult to troubleshoot.

The official Scratchbox Remote Shell documentation is here , though it has not yet been updated for sshfs usage.

Tablet configuration

Passwordless ssh validation

The recommended protocol for sbrsh filesystem exporting is sshfs. Ensure you can ssh to the target without a password. The previous chapter explained how to eliminate the ssh password prompt.

Configuration file /etc/default/sbrshd

You can configure sbrsh basic functionality in "/etc/default/sbrshd" , by uncommenting lines and setting variables to different values. Some useful options are DEBUG, NO_SANDBOX, and EXPIRATION. You must restart the sbrsh daemon after changing this configuration file (use "/etc/init.d/sbrsh restart" ).

The DEBUG option triggers logging to "/var/log/sbrshd.log" (or whatever value DEBUG_FILE has). This can be useful if you are having trouble connecting. Note: you may run "sbrshd --enable-debug" or "sbrshd --disable-debug" to toggle this option dynamically.

The NO_SANDBOX option is usually false, meaning a sandbox is used. This means that the filesystem from your host (usually the scratchbox rootstrap) is exposed to the Tablet. Otherwise, you will be executing programs against the actual Tablet filesystem.

The EXPIRATION option controls how long in minutes sbrshd will wait before unmounting shares. Since the typical sandboxed usage of sbrshd will cause a significant delay the first time you connect – because most of the shared libraries and shell-related binaries from the host must be passed over the wire – you will usually want a longer delay.

The installation of the maemo-pc-connectivity meta package has configured these for you for no debugging, sandboxed enabled, and a 15 minute expiration.

Configuration file "/etc/sbrsh.conf"

You can configure access to the sbrshd daemon using /etc/sbrshd.conf. You need to manually edit this file and add an entry for your host (192.168.2.14).

Note: sbrsh does not use a secure protocol, so be judicious in granting access!

Adding a user

Add your user to the Tablet, using the matching username (replace you with your username) and uid/gid from the host PC (replace 1000 with your host PC uid/gid, run "id" to see your uid/gid).

Example commands run on Tablet:

~ > groupadd -g 1000 you
~ > useradd -u 1000 -g you -d /home/you -s /bin/sh you
~ > mkdir /home/you
~ > chown you:you /home/you
~ > passwd you

Adding your user means that your identity will be available on the Tablet for the purpose of reading/writing files in the sandboxed mode.

Note: this user mapping is not strictly required – sbrsh version 7.6 and later has a "-r" or "--remote" option which takes the uid, gid, and username that you want to become on the Tablet (to become root, you must enable ALLOW_ROOT=true in "/etc/default/sbrsh.conf" ).

Host PC configuration

Passwordless ssh validation

The recommended protocol for sbrsh filesystem exporting is sshfs. Ensure you can ssh to the host PC from the Tablet without a password as explained earlier.

sbrsh configuration

In order to use sbrsh (the client), you need a file describing which named configuration targets to select from and which file systems they export to the host.

In standalone mode, by default, "~/.sbrsh" is used, and "sbrsh -c <file>" may override this. The first target in the file is used by default, and "sbrsh -t <target>" may override this.

In CPU transparency mode, the configuration file is determined from the SDK target location, and the first target is used. See details from below.

sbrsh file format

The format of "~/.sbrsh" file is as follows:

# Format:
#
# <target name> <hostname>[:<port>]
# nfs|bind|sshfs <host filesystem> <target mountpoint> [<options>]
# ...

A blank line separates entries and in sbrsh client version 7.6 or later a hash mark "#" denotes commented lines.

"nfs" or "sshfs" lines describe the protocol for exporting host PC file systems to the Tablet. We recommend sshfs for new users since this line is all you need. For NFS you need to edit NFS system configurations as well so the setup is more complicated.

The mounts must appear in order of increasing depth. For instance, the root must be mounted first, followed by entries that live inside the root, etc.

"bind" lines override the host filesystem exports by overriding portions of the filesystem from the target. This is essential for filesystems which contain Tablet specific files (/tmp, /var, /sys, /dev, /proc ... see details below).

Notice that when changing the sbrsh configuration file, "sbrsh [-c <file> -t <target>] --umount" should be done before editing the configuration because these commands read the current sbrsh configuration and don't remember previous mounts. Otherwise you might experience strange errors or failures to mount.

Example configuration

Example sbrsh configuration file "~/.sbrsh" for username you and target DIABLO_ARMEL :

sshfs-target 192.168.2.15
ssh you @192.168.2.14:/scratchbox/users/you /targets/DIABLO_ARMEL/ / rw,nonempty,allow_other
ssh you @192.168.2.14:/scratchbox/users/you /home/you / /home/you rw,nonempty,allow_other
bind /tmp /tmp
bind /dev /dev
bind /dev/pts /dev/pts
bind /proc /proc
bind /sys /sys
bind /var /var

To use sbrsh as CPU transparency

  • Place this configuration in "/scratchbox/users/you/targets/DIABLO_ARMEL.sbrsh"

  • Either create a new target using sb-conf or sb-menu, or edit DIABLO_ARMEL target configuration in "/scratchbox/users/you /targets/DIABLO_ARMEL.config" configuration file.

  • Change "SBOX_CPUTRANSPARENCY_METHOD" to read :

    SBOX_CPUTRANSPARENCY_METHOD=/scratchbox/devkits/cputransp/bin/sbrsh

Test sbrsh

Try running the following command on the host PC to see if the mount works:

~ $ sbrsh ls /
bin cdrom etc home lib mnt proc sbin sys usr
boot dev floppy initrd media opt root srv tmp var
~ $ sbrsh /bin/sh
sh-2.05b$

If this does not work, see the next section.

Troubleshoot

Authentication failed error:

~ $ sbrsh /bin/sh
sbrsh: authentication failed

This means you forgot to add your host PC's IP address to the Tablet's /etc/sbrsh.conf file.

Connection reset by peer error:

~ $ sbrsh /bin/sh
sbrsh server: read: Connection reset by peer
sbrsh server: Can't mount to point: /var/sbrshd/you@192.168.2.14/sshfs-target/

First, be sure the account “you ” exists on the Tablet.

Then, be sure you authenticate the account so that ssh connection from the Tablet can access the host PC for passwordless login.

Can't execute command (Permission denied) error:

~ $ sbrsh /bin/sh
sbrsh server: Can't execute command: /bin/sh (Permission denied)

This error is misleading – it usually means you're missing a mount for the root directory on the Tablet, when sandbox mode is enabled (the default). The error comes from "chroot()" .

Can't execute command (No such file or directory) error:

/scratchbox/users/you/home/you $ sbrsh myprogram
sbrsh server: Can't execute command: myprogram (No such file or directory)

Be sure the resolved program path is visible from the Tablet or specify a full path. If you map, e.g., "/scratchbox/users/you/home/you /" to "/home/you /" , then run "sbrsh /home/you /myprogram" instead.

osso_initialize() failed error:

~ $ sbrsh maemoapp


maemoapp[2096]: GLIB ERROR ** default – file ... assertion failed: (result->osso)

or

maemoapp[2096]: osso_initialize() failed

OSSO applications initialize the DBUS connection very early, so DBUS problems are probably the cause.

When launching maemo applications, you must override the "DBUS_SESSION_BUS_ADDRESS" environment variable. The value from your host system is probably completely incorrect (especially since "/tmp" is bind-mounted to the target).

Try this instead:

DBUS_SESSION_BUS_ADDRESS=unix:path=/tmp/session_bus_socket sbrsh maemoapp

Improve this page