<!doctype linuxdoc system>

<article>

<title>Linux and Android HOWTO</title>
<author>Guido Gonzato, Ph.D. <tt>guido.gonzato at gmail.com</tt>
<date>March 2016, version 1.0.0

<abstract>
  This HOWTO provides information on how to manage your Android device
  using a GNU/Linux system. It's aimed at reasonably competent Linux
  users who want more control over their Android device.
</abstract>

<toc>

<!-- ----- -->

<sect>Introduction

<p>
I started this document at the end of 2014, over 15 years after my
previous HOWTOs. In the meantime, GNU/Linux on the desktop has
basically failed, but a GNU-less Linux variant has gained a large
market share in the mobile industry. It's Android: a partially open
platform, based on the Linux kernel and a mix of open and closed
programs (``apps''). As a matter of fact, Android is by far the most
widespread Linux distribution, even though most of its users don't
even know they're using Linux!

<p>
(A pocket-size Unix system that one can get for less than 100 bucks.
Amazing! If they'd told me about it in the early '90s, I would have
dismissed it as cheap science fiction.)

<p>
I purchased an Android phone and a mid-spec Android tablet, and I
wondered if I could do something interesting with them --- apart from
making phone calls and browsing the net, that is. Android is meant to
be very easy to use, and no trickery is required for normal use. The
thing is, I'm not a normal user: I'm a GNU/Linux sysadmin, and just
scratching the surface is not enough for me. So I started
experimenting and gathering information.

<!-- - - - -->

<sect1>Purpose of this guide

<p>
This guide is meant to be a quick reference for GNU/Linux users who
want to use their Android device in less-than-trivial ways, and want
their Linux and Android boxes to talk to each other. Most vendors
provide drivers and ancillary programs for Microsoft Windows or Apple
OS X only, but a GNU/Linux system is perfectly capable of interacting
with Android devices. With a bit of hacking, as usual.

<p>
In the following, I will share a few tricks I have collected:

<itemize>
 
  <item> using the Android Debug Bridge;
  <item> understanding and using the Android file system;
  <item> installing programs from other markets;
  <item> copying and syncing files and directories;
  <item> backing up stuff;
  <item> using a terminal emulator;
  <item> compiling native command-line programs;
  <item> remote control to/from Android;
  <item> and more.

</itemize>

<p>
I work on a GNU/Linux Mint box, but I'll try and be
distribution-agnostic. I'll concentrate on Free and Open Source
Software (FOSS) whenever possible, and I'll take standard, unrooted
Android devices into account. By the way: ``rooting'' means tweaking
your Andbox to gain root permissions, as you would do in Linux with
<tt>sudo</tt>. ``Unrooted'' means ``not tweaked''.

<p>
Since Android is very fragmented (hey, it's Linux after all!) and
several versions are available, I'll just provide information that is
applicable to what I own: Android 4.0.4, 4.1.1, and 5.0.1 on ARM
architecture. All examples and code in this HOWTO were actually tested
on my devices; hopefully, they should work on your device too. If you
want me to cover more Android versions, I'll be glad to receive new
equipment; or just tips. Equipment is preferred :-)

<p>
Currently, the majority of Android devices are ARM based; others are
based on x86 or MIPS CPUs, in both 32 and 64 bit flavours. This is not
a significant difference: most applications are written in Java with
no native code, so they are CPU-agnostic. Instructions in this HOWTO
should work for these Android versions, too. I guess that relevant
differences concern security policies.

<p>
Should you have trouble with your Android device, I suggest that you
refer to Android forums. Among the many available, I find the
following especially helpful:

<itemize>
 
  <item> <htmlurl url="http://forum.xda-developers.com/"
  name="http://forum.xda-developers.com/">

  <item> <htmlurl url="http://forums.androidcentral.com/"
  name="http://forums.androidcentral.com/">

</itemize>

<p>
Besides: if you find any errors in this guide, please report them to
me.

<p>
Thoughout this HOWTO, all instances of ``Linux'' actually mean
``GNU/Linux''. The GNU part is very important, and I'm very grateful
to GNU for its fantastic programs. ``Andbox'' will stand for ``Android
device''.

<!-- ----- -->

<sect1>Requirements

<p>
I shall assume that you are a reasonably competent Linux user: you
must be able to open a terminal, issue commands, become root, edit
files, compile and install software. No spoon-feeding here.

<p>
As far as Android expertise is concerned, only the very basics are
required. You are expected to be able to perform common tasks such as
installing software, enabling USB debugging, using Bluetooth, and so
on. Nothing special, really: in general, you'll have to be able to
find out where options are in your device. I would be glad to provide
information, but unfortunately no identical menus or screens can be
found across different devices of different brands and different
Android releases. You will have to figure it out yourself.

<p>
Finally: rooting your device might be desirable, but it's not
necessary as far as this HOWTO is concerned. Root permissions are
normally forbidden in Android, unless an enlightened vendor decides
otherwise. I will mention a great program that needs root access
(Webkey), but the rest of recommended software will not need it. By
the way: in the following, I'll use the appropriate term ``program''
or ``application'', not the marketing term ``app''. (Yep, I'm an old
and grumpy guy.)


<!-- ----- -->

<sect>The basics

<p>
To begin our journey, you will have to install some essential
programs. Please note that Linux-side programs might be available as
native packages for your distribution, i.e. as <tt>.rpm</tt> or
<tt>.deb</tt> archives.

<p>
The very first thing you should do is enable USB debugging; this
feature is found under ``Settings'', ``Developer options''. If your
device lacks this entry (shame on the vendor!), you can enable
developer options by tapping 7 times --- I'm not kidding! --- on the
``Build version'' menu.


<!-- - - - -->

<sect1>Linux ADB (Android Debug Bridge)

<p>
ADB is a command line tool, installable on your Linux box. It lets you
communicate with an Andbox, usually connected via USB, in order to
perform a wide range of operations.

<p>
If you're lucky, your distribution may include a package called
<tt>android-tools-adb</tt>, which contains the <tt>adb</tt> command.
If not, get the Android SDK Tools for Linux from:

<p>
<htmlurl url="http://developer.android.com/sdk/"
name="http://developer.android.com/sdk/">

<p>
and find out how to install it on your Linux box.

<p>
I suggest that you open a terminal and run <tt>adb</tt> with no
options to get an information screen. You should become familiar at
least with the following options:

<itemize>
 
  <item> <tt>adb devices</tt>: list connected devices
  <item> <tt>adb push</tt>: copy file/dir from Linux to device
  <item> <tt>adb pull</tt>: copy file/dir from device to Linux
  <item> <tt>adb shell</tt>: open command-line shell on the device
  <item> <tt>adb install</tt>: install a <tt>.apk</tt> on the device
  <item> <tt>adb backup</tt>: perform device backup
  <item> <tt>adb restore</tt>: perform device restore

</itemize>

<p>
Before using the <tt>adb</tt> commands, you must make your Andbox
visible to the Linux box. Enable USB debugging on your device and
connect it via USB cable to your Linux host; the Andbox will probably
make a sound and/or flash the screen and/or ask for your permission.
Issue this command:

<tscreen>
<verb>
Linux:~$ adb devices
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
List of devices attached 
245a16e41fe71a95427cc4e65d36cc9f	device
</verb>
</tscreen>

<p>
If you don't see any output after ``List of devices attached'', or if
a row of `<tt>?</tt>' is displayed, some steps and some patience are
required to make your device visible. First of all, find out your
device's Vendor ID and Product ID:

<tscreen>
<verb>
Linux:~$ lsusb
...
Bus 001 Device 004: ID 1e68:0072 TrekStor GmbH & Co. KG 
...
</verb>
</tscreen>

<p>
In this example, <tt>1e68</tt> is my tablet's Vendor ID, while
<tt>0072</tt> is the Product ID. 

<p>
I assume that your Linux distribution uses <tt>udev</tt>. As root,
edit the file:

<tscreen><verb>
/etc/udev/rules.d/50-android.rules
</verb></tscreen>

<p>
(create a new file if it's missing) and add this line:

<tscreen><verb>
SUBSYSTEM=="usb", SYSFS{idVendor}=="1e68", MODE="0666"
</verb></tscreen>

<p>
Change your Vendor ID and username as necessary, save the file and
restart udev:

<tscreen>
<verb>
Linux:~$ sudo udevadm control --reload
</verb>
</tscreen>

<p>
Some devices may also need this additional step:

<tscreen>
<verb>
Linux:~$ mkdir $HOME/.android
echo "0X1E68" >> $HOME/.android/adb_usb.ini
</verb>
</tscreen>

<p>
that is, <tt>0X</tt> (zero-ex) followed by your Vendor ID, all
uppercase. Now unplug the USB cable, plug it in again, and run the
commands:

<tscreen>
<verb>
Linux:~$ adb kill-server
Linux:~$ adb devices
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
List of devices attached 
245a16e41fe71a95427cc4e65d36cc9f	device
</verb>
</tscreen>

<p>
Now your Andbox should be visibile. If it's still not recognised, try
all the above as root. If it still doesn't work, there might be a
problem with your Andbox; you should consult your device's vendor.

<p>
If you have more than one device, you might have to restart the
<tt>adb</tt> service to make the new Andbox visible when you plug it:

<tscreen>
<verb>
Linux:~$ adb devices
List of devices attached

Linux:~$ # no luck. Unplug the device
Linux:~$ adb kill-server
Linux:~$ # plug the device
Linux:~$ adb devices
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
List of devices attached 
047011c34260a417	device
</verb>
</tscreen>

<!-- - - - -->

<sect1>The Android file system

<p>
Now we can talk to the Andbox via <tt>adb</tt>, so let's have a look
at the Android file system hierarchy. I assume that you're familiar
with the standard Linux directory hieararchy; Android's is fairly
similar, with a couple of important differences.

<p>
Connect your Andbox and run the <tt>adb shell</tt> command, which
launches Android's internal shell. Please be aware that Android's
native shell is much less sophisticated than <tt>bash</tt>; available
commands are not made by GNU either, so you should expect minor
differences.

<tscreen>
<verb>
Linux:~$ adb shell
shell@android:/ $ ls -l
drwxr-xr-x root     root              2015-10-19 09:48 acct
drwxrwx--- system   cache             2015-10-19 10:52 cache
dr-x------ root     root              2015-10-19 09:48 config
lrwxrwxrwx root     root              2015-10-19 09:48 d -> /sys/kernel/debug
drwxrwx--x system   system            2015-10-06 07:53 data
-rw-r--r-- root     root          116 1970-01-01 01:00 default.prop
drwxr-xr-x root     root              2015-10-19 09:48 dev
lrwxrwxrwx root     root              2015-10-19 09:48 etc -> /system/etc
-rwxr-x--- root     root        98692 1970-01-01 01:00 init
-rwxr-x--- root     root         7272 1970-01-01 01:00 init.antares.rc
-rwxr-x--- root     root         2344 1970-01-01 01:00 init.goldfish.rc
-rwxr-x--- root     root         2820 1970-01-01 01:00 init.nv_dev_board.usb.rc
-rwxr-x--- root     root        17549 1970-01-01 01:00 init.rc
drwxrwxr-x root     system            2015-10-19 09:48 mnt
drwx------ root     root              1970-01-01 01:00 modules
dr-xr-xr-x root     root              1970-01-01 01:00 proc
drwx------ root     root              2012-08-30 12:39 root
drwxr-x--- root     root              1970-01-01 01:00 sbin
lrwxrwxrwx root     root              2015-10-19 09:48 sdcard -> /mnt/sdcard
drwxr-xr-x root     root              2015-10-19 09:48 sys
drwxr-xr-x root     root              2014-01-15 13:23 system
-rw-r--r-- root     root         1308 1970-01-01 01:00 ueventd.antares.rc
-rw-r--r-- root     root          272 1970-01-01 01:00 ueventd.goldfish.rc
-rw-r--r-- root     root         3825 1970-01-01 01:00 ueventd.rc
lrwxrwxrwx root     root              2015-10-19 09:48 vendor -> /system/vendor
shell@android:/ $ _
</verb>
</tscreen>

<p>
Minor differences are possible; for example, in the above screenshot I
omitted a directory that is apparently tied to a specific vendor. Note
that all directories except three belong to <tt>root:root</tt>; as a
consequence, access to their contents will be limited on unrooted
devices.

<p>
Now run the <tt>mount</tt> command, to see what devices correspond to
what directories (line-broken for readability):

<tscreen>
<verb>
shell@android:/ $ mount
rootfs / rootfs ro,relatime 0 0
tmpfs /dev tmpfs rw,nosuid,relatime,mode=755 0 0
devpts /dev/pts devpts rw,relatime,mode=600 0 0
proc /proc proc rw,relatime 0 0
sysfs /sys sysfs rw,relatime 0 0
tmpfs /mnt tmpfs rw,relatime,mode=775,gid=1000 0 0
debugfs /sys/kernel/debug debugfs rw,relatime 0 0
none /acct cgroup rw,relatime,cpuacct 0 0
tmpfs /mnt/asec tmpfs rw,relatime,mode=755,gid=1000 0 0
tmpfs /mnt/obb tmpfs rw,relatime,mode=755,gid=1000 0 0
none /dev/cpuctl cgroup rw,relatime,cpu 0 0
/dev/block/platform/sdhci-tegra.3/by-num/p3 /system ext4 \
  ro,relatime,user_xattr,acl,barrier=1,data=ordered 0 0
/dev/block/platform/sdhci-tegra.3/by-num/p7 /data ext4 \
  rw,nosuid,nodev,noatime,errors=panic,user_xattr,acl,barrier=1,\
  journal_async_commit,nodelalloc,data=ordered 0 0
/dev/block/platform/sdhci-tegra.3/by-num/p4 /cache ext4 \
  rw,nosuid,nodev,noatime,errors=panic,user_xattr,acl,barrier=1,\
  journal_async_commit,nodelalloc,data=ordered 0 0
/dev/block/vold/179:8 /mnt/sdcard vfat \
  rw,dirsync,nosuid,nodev,noexec,relatime,gid=1015,fmask=0002,\
  dmask=0002,allow_utime=0020,codepage=cp437,iocharset=iso8859-1,\
  shortname=mixed,utf8,errors=remount-ro 0 0
/dev/block/vold/179:8 /mnt/secure/asec vfat \
  rw,dirsync,nosuid,nodev,noexec,relatime,gid=1015,fmask=0002,\
  dmask=0002,allow_utime=0020,codepage=cp437,iocharset=iso8859-1,\
  shortname=mixed,utf8,errors=remount-ro 0 0
tmpfs /mnt/sdcard/.android_secure tmpfs ro,relatime,size=0k,mode=000 0 0
/dev/block/dm-0 /mnt/asec/com.collabora.libreoffice-2 vfat \
  ro,dirsync,nosuid,nodev,relatime,uid=1000,fmask=0222,dmask=0222,\
  codepage=cp437,iocharset=iso8859-1,shortname=mixed,utf8,errors=remount-ro 0 0
shell@android:/ $ _
</verb>
</tscreen>

<p>
Note the similarities and the differences with Linux filesystems; it
looks a lot like standard Unix, anyway.

<p>
What you can actually do with the file system layout is <em>much</em>
less than you would with Linux. On standard, unrooted devices, you can
only access the internal storage, usually mounted on
<tt>/mnt/sdcard</tt>, and the external storage (if available), usually
mounted on <tt>/mnt/external_sd</tt>. The actual names of these
directories may vary; e.g. <tt>/storage/sdcard0</tt> or something
else. You'll probably have to figure it out for each device.

<p>
User data, programs included, are stored in <tt>/data</tt>. Using the
Android shell you can <tt>cd</tt> to that directory, but you can't
list its contents if you lack root permissions. Programs are usually
stored in <tt>/data/app</tt>, but others (typically, paid programs and
programs moved to the external storage) under <tt>/mnt/asec</tt>.

<p>
A very important directory under <tt>/data</tt> is accessible and
writeable: <tt>/data/local/tmp</tt>. We'll make use of this directory
later.

<p>
Note that internal and external storage is mounted as VFAT, the
beloved file system that lacks file permissions and many more
features. We will see in the following how to circumvent VFAT
limitations.

<!-- - - - -->

<sect1>Main directories in the internal storage
<label id="maindir">

<p>
Assuming that <tt>/mnt/sdcard</tt> is the directory containing the
internal storage, you should become familiar with the following
sub-directories. Remember that <tt>/mnt/sdcard</tt> is mounted as
VFAT; directory names are therefore case-insensitive.

<itemize>

  <item><tt>Android/data/</tt> contains directories with
  programs' user data. Each directory is named after the application,
  using a naming convention that will be explained in Section <ref
  id="programs" name="Installing/Uninstalling Programs from Linux">.
  For example, Firefox settings are stored in
  <tt>org.mozilla.firefox/</tt>.
  
  <item><tt>Download/</tt> may contain files downloaded by browsers,
  unless they're configured otherwise.
  
  <item><tt>DCIM/</tt> contains one or more directories, each of which
  contains photographs stored as <tt>.jpg</tt> files. In my phone,
  <tt>DCIM/</tt> contains two directories, <tt>Camera</tt> and
  <tt>OpenCamera</tt>. Each directory contains pictures taken with a
  specific camera program: the default (Camera) and an additional
  program I installed (OpenCamera).
  
  <item><tt>LOST.DIR/</tt> may contain files that were recovered at
  boot time, when Android performs a file system check.
  
  <item><tt>Notifications/</tt> contains sound files for notifications
  (SMS, etc.). You can add your favourite sound files there.
  
  <item><tt>Ringtones/</tt>, similarly, contains sound files used as
  ring tones. You can add your favourite sound files there.
  
  <item><tt>System/</tt> may contain system data; in my phone,
  contacts backups are saved in <tt>System/PIM/</tt>.
  
  <item><tt>Bluetooth/</tt> contains file transfered via Bluetooth.

</itemize>

<p>
In addition, some applications make their data directory under
<tt>/mnt/sdcard</tt> directly; for example,
<tt>/mnt/sdcard/Foo123</tt>.


<!-- ----- -->

<sect>Applications

<sect1>Alternative markets

<p>
In case you don't know: Android applications are distributed as
<tt>.apk</tt> (Android application package) files, which are simple
zip-compressed archives. Apk is the standard Android package format,
and it serves the same purpose as <tt>.rpm</tt> or <tt>.deb</tt>
archives in Linux distributions.  As you probably know, programs are
not downloaded as <tt>.apk</tt>s from Google Play; they're pushed to
your device.

<p>
If you don't want to use the Google Play repository, or if you can't,
there are alternative markets that provide Android FOSS:

<itemize>

  <item>F-Droid, 
  
  <p>
  <htmlurl url="https://f-droid.org" name="https://f-droid.org/">
  
  <p>
  lets you download programs <tt>.apk</tt>s directly, or via its
  client called <tt>FDroid.apk</tt>. I strongly suggest that you
  install the latter, that (from the F-Droid page) ``makes it easy to
  browse, install, and keep track of updates on your device.''
  
  <item>AOpenSource.com,
  
  <p>
  <htmlurl url="http://www.aopensource.com"
  name="http://www.aopensource.com">
  
  <p>
  is another repository dedicated to FOSS. In many cases, it simply
  redirects to Google Play; in other cases, to the application's home
  page.

</itemize>

<p>
In fact, many Android programs have their own web page, from which you
can download the <tt>.apk</tt> and, in some cases, the program
sources, documentation and so on.

<!-- - - - -->

<sect1>Useful tools

<p>
Advanced Android users will want to install a file manager and a
decent keyboard. Several FOSS programs are available, and my
suggestions are:

<itemize>

  <item>Hacker's Keyboard:
  
  <p>
  <htmlurl url="http://code.google.com/p/hackerskeyboard/"
  name="http://code.google.com/p/hackerskeyboard/">
  
  <p>
  is a ``real'' keyboard that provides arrow keys, Esc, Alt, Ctrl, and
  so on; you really can't do without it if you plan to use a terminal
  emulator. Released under the Apache License 2.0. 
  
  <item>Ghost Commander:
  
  <p>
  <htmlurl url="https://sites.google.com/site/ghostcommander1" 
  name="https://sites.google.com/site/ghostcommander1">
  
  <p>
  is a very powerful, easy to use and complete dual-pane file manager,
  released under the GPL3. In addition to the usual features, it also
  provides plugins for accessing files via SMB, SFTP, GoogleDrive,
  DropBox, and BOX.
  
</itemize>

<p>
There are many other free file managers, but I feel that Ghost
Commander is the most complete. Of course, feel free to install
another if you prefer.

<p>
In addition to the tools above, you may want to turn your Andbox into
something similar to a real Linux machine. You really want a terminal
emulator and BusyBox, <htmlurl url="http://www.busybox.net/"
name="http://www.busybox.net/">. The latter is a single executable
that provides the functionality of several commands that you normally
expect to find in any self-respecting Unix box, but that are missing
in Android. <tt>cp</tt> and <tt>tar</tt> are the first that spring to
mind.

<p>
In Section <ref id="terminals" name="Terminal Emulators and Shells">
some terminal emulators will be briefly described; they also include
BusyBox. The terminal emulator will let you run countless command-line
programs that you can port to Android yourself!

<!-- - - - -->

<sect1>Installing/uninstalling programs from Linux
<label id="programs">

<p>
You may find it convenient to download and store <tt>.apk</tt>s in
your Linux machine, possibly to install them on several Andboxes.

<p>
Let's suppose you downloaded an application, <tt>foo123.apk</tt>, and
want to install it in your Andboxes. The simplest solution is to use
the <tt>adb install</tt> command:

<tscreen>
<verb>
Linux:~$ ls *apk
884K foo123.apk
Linux:~$ adb install foo123.apk
3658 KB/s (898144 bytes in 0.239s)
	pkg: /data/local/tmp/foo123.apk
Success
Linux:~$ _
</verb>
</tscreen>

<p>
You might be surprised to find out that an application's real name
<em>does not correspond</em> to the name of its <tt>apk</tt>! For
example, the real name of <tt>foo123</tt> could be something similar
to <tt>com.android.foo123</tt>. This naming method is based on
Java package conventions, which are described at this page:

<p>
<htmlurl url="http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html"
name="http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html">

<p>
You must know a program's real name if you want to uninstall it using
<tt>adb</tt>. To find out a program's real name, you can use Ghost
Commander. Select ``Home'', ``Applications'', and carefully read the
list of installed <tt>.apk</tt>s; under each entry, the program's real
name is printed in smaller characters.

<p>
Now you have all the necessary information to uninstall
<tt>foo123</tt> using <tt>adb uninstall</tt>:

<tscreen>
<verb>
Linux:~$ adb uninstall foo123
Failure
Linux:~$ adb uninstall com.android.foo123
Success
Linux:~$ _
</verb>
</tscreen>

<!-- - - - -->

<sect1>Installing APKs via another Andbox

<p>
An Andbox can easily share its installed programs with another
device, provided that the Android versions are compatible. All you
need is Ghost Commander. In the next paragraph, you can see how to
send a file to Alice using Bob's Andbox.

<p>
From the ``Home'' position, select ``Applications'' to get a list of
installed <tt>.apk</tt>s ; click on the one you want and copy it to a
standard folder (say, <tt>/mnt/sdcard</tt>.) From this location, long
press on the program <tt>.apk</tt> and select ``Send To...''. Now
select Bluetooth, which is probably the easiest way to send the APK to
Alice; or choose another method from Section <ref id="copying"
name="Copying Files"> below. If your device refuses to send a
<tt>.apk</tt> file via Bluetooth, just rename or zip it before sending
it, then unpack it or rename it back on the new device.

<p>
From within the Ghost Commander, tap on the <tt>.apk</tt> file to
install the program. When done, you can delete the <tt>.apk</tt>.

<!-- - - - -->

<sect>Copying files
<label id="copying">

<p>
Exchanging files between Linux and Android should be trivial, right?
Well, it's not. There are several ways to copy files from/to your
Andbox, using a cable or Wi-Fi.


<!-- ----- -->

<sect1>Copying via USB cable (from Linux box)

<p>
When you connect your device via USB cable, Linux may see it either as
an external USB drive or as an <em>MTP device</em>, i.e. a multimedia
player. In the first case, <tt>udev</tt> mounts the device somewhere,
like <tt>/media/guido/DEVICE</tt>. Exchanging files is now trivial:

<tscreen>
<verb>
Linux~$ rsync -av --delete -i ~/Documents/MyStuff/ /media/guido/DEVICE/MyStuff/
</verb>
</tscreen>

<p>
If the Andbox is connected via MTP, more trickery might be required.
Some Linux versions will mount the device using <tt>gfsd-fuse</tt>;
for instance, my phone's internal storage is accessible at this
directory:

<p>
<tt>/run/user/1000/gvfs/mtp:host=%5Busb%3A001%2C111%5D/Internal Storage</tt>

<p>
You may want to make a directory like the above more accessible
creating a symbolic link, but unfortunately this directory is only
temporary. In fact, the next time you plug your Andbox, the string
<tt>mtp:host</tt> is bound to change.

<tscreen>
<verb>
Linux:~$ ln -s /run/user/1000/gvfs/mtp\:host\=%5Busb%3A001%2C111%5D/Internal\ Storage/ Phone
Linux:~$ cd Phone
Linux:~/Phone$ ls -l
totale 481K
32K drwx------ 1 guido guido 32K lug 29 13:09 Alarms/
32K drwx------ 1 guido guido 32K mar  2  2012 Android/
  0 drwx------ 1 guido guido   0 ago 26 11:59 Backups/
32K drwx------ 1 guido guido 32K mag 20  2014 baidu/
  0 drwx------ 1 guido guido   0 ott  6 19:57 bluetooth/
32K drwx------ 1 guido guido 32K mar 23  2015 CallRecordings/
512 -rw------- 1 guido guido 145 lug 29 12:46 customized-capability.xml
32K drwx------ 1 guido guido 32K lug 29 13:10 DCIM/
  0 drwx------ 1 guido guido   0 ott  9 12:40 Download/
  0 drwx------ 1 guido guido   0 dic 31  1999 LOST.DIR/
32K drwx------ 1 guido guido 32K lug 29 14:33 MIUI/
  0 drwx------ 1 guido guido   0 lug 31 10:00 Music/
  0 drwx------ 1 guido guido   0 ago  3 11:03 Notifications/
  0 drwx------ 1 guido guido   0 set 22 14:54 Pictures/
32K drwx------ 1 guido guido 32K mar 12  2014 Ringtones/
32K drwx------ 1 guido guido 32K gen  7  2013 svox/
32K drwx------ 1 guido guido 32K gen  9  2013 System/
  0 drwx------ 1 guido guido   0 ott 15 14:40 tmp/
Linux:~/Phone$ _
</verb>
</tscreen>

<p>
You will immediately notice that accessing the Andbox file system is
quite slow.

<p>
In other cases, nothing happens. To access files on the device, you'll
have to use programs that deal with MTP:

<itemize>
  
  <item> Libmtp, <htmlurl url="http://libmtp.sourceforge.net/"
  name="http://libmtp.sourceforge.net/">
  
  <p>
  Provides MTP Tools, i.e. command line utilities to manage files,
  albums, playlists etc. on the device.
  
  <item> Gmtp, <htmlurl url="http://gmtp.sourceforge.net/"
  name="http://gmtp.sourceforge.net/">
  
  <p>
  A graphical program to perform the same actions as MTP Tools.
  
</itemize>

<p>
In my personal experience, copying files with MTP has proven to be
unreliable and error-prone. Copying files is also possible via ADB
commands, which appear to be quite reliable. The following two
commands copy (push) a file from Linux to the Andbox, and the other
way around (pull):

<tscreen>
<verb>
Linux:~$ adb push file.txt /mnt/sdcard/directory/
Linux:~$ adb pull /mnt/sdcard/directory/file.txt
</verb>
</tscreen>

<p>
In the latter example, please note you must not add a dot at the end
of the command: it's not the same as the Linux command <tt>cp
/mnt/sdcard/file.txt .</tt>

<!-- - - - -->

<sect1>Syncing directories (from Linux box)

<p>
If you want to keep a directory synchronised between the Linux box and
the Andbox, in theory the command <tt>adb sync</tt> should suffice. In
practice, I never managed to make it work.

<p>
Fortunately, there's a nice tool called <tt>adb-sync</tt>. It's
written in Python and it's released under the Apache License at this
address:

<p>
<htmlurl url="https://github.com/google/adb-sync"
name="https://github.com/google/adb-sync">

<p>
get it by cloning the GIT repository, then copy the command to a
directory included in your <tt>$PATH</tt>:

<tscreen>
<verb>
Linux:~$ git clone https://github.com/google/adb-sync
Linux:~$ mv adb-sync/adb-sync ~/bin/
Linux:~$ _
</verb>
</tscreen>

<p>
<tt>adb-sync</tt> works in a similar manner as standard <tt>rsync</tt>:

<tscreen>
<verb>
Linux:~$ adb-sync --delete SYNC-ME/ /mnt/sdcard/SYNC-ME/
Sync: local SYNC-ME, remote /mnt/sdcard/SYNC-ME/
Scanning and diffing...
Warning: could not parse 'd---rwxr-x    2 system   sdcard_r \
32768 Oct 19 10:54 /mnt/sdcard/SYNC-ME/'.
Push: /mnt/sdcard/SYNC-ME/
Push: /mnt/sdcard/SYNC-ME//file1.txt
Push: /mnt/sdcard/SYNC-ME//file2.txt
Push: /mnt/sdcard/SYNC-ME//file3.txt
Total: 0 KB/s (0 bytes in 0.640s)
Linux:~$ _
</verb>
</tscreen>

<!-- - - - -->

<sect1>Sorting files: <tt>fatsort</tt> (from Linux box)

<p>
Let's suppose you copied a bunch of music files to your device. You
run your music player and open the directory containing the files.
Surprise: they're not sorted, and are displayed in (apparently) random
order!

<p>
It's the way the VFAT filesystem works, on Andboxes and MP3 players
too. Enter <tt>fatsort</tt>, a great tool available here:

<p>
<htmlurl url="http://fatsort.sourceforge.net/"
name="http://fatsort.sourceforge.net/">

<p>
It's a command line program for Linux that sorts VFAT file systems on
connected devices.

<p>
Plug the USB cable and mount the device. As root, run the
<tt>fdisk</tt> tool:

<tscreen>
<verb>
Linux:~# fdisk -l
...
Disk /dev/sdd: 15.9 GB, 15925772288 bytes
1 heads, 32 sectors/track, 972032 cylinders, total 31105024 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x00000000

   Device Boot      Start         End      Blocks   Id  System
/dev/sdd1              32    30777343    15388656    c  W95 FAT32 (LBA)
</verb>
</tscreen>

<p>
In the above example, <tt>/dev/sdd1</tt> is the Android VFAT file
system. To sort the files therein, check the consistency of the file
system and run <tt>fatsort</tt>:

<tscreen>
<verb>
Linux:~# fsck.vfat -a /dev/sdb1
dosfsck 3.0.16, 01 Mar 2013, FAT32, LFN
0x41: Dirty bit is set. Fs was not properly unmounted and some data may be corrupt.
 Automaticaly removing dirty bit.
Performing changes.
/dev/sdb1: 8060 files, 856099/1921702 clusters
Linux:~# fatsort -f /dev/sdb1
FATSort Utility 0.9.15 by Boris Leidner <fatsort(at)formenos.de>

File system: FAT32.

Sorting directory /
Sorting directory /CTR/
Sorting directory /Foto/
Sorting directory /Guido/
...
Linux:~# _
</verb>
</tscreen>

<p>
In theory, <tt>fatsort</tt> should be run on unmounted file systems,
but the above works and is reasonably safe.

<!-- - - - -->

<sect1>Copying files from an Andbox FTP server

<p>
This is the most traditional way to upload and download files to/from
a server. Among the several available, I picked up Swiftp FTP Server:
  
<p>
<htmlurl url="http://ppareit.github.io/swiftp/" 
name="http://ppareit.github.io/swiftp/">

<p>
also available on F-Droid.

<p>
This application is released under the GPL and runs on the
non-standard port 2121, so it can run on unrooted Andboxes. (21 is a
privileged port.) In the Login settings, set user and password for
uploads and downloads, or anonymous login for download only. In the
latter case, username and password are ``ftp'', ``guest''. Take note
of your Andbox's IP adress and, from the Linux box, start an ftp
session. The default remote directory is <tt>/mnt/sdcard</tt>:

<tscreen><verb>
Linux:~$ ftp 157.27.180.18 2121
Connected to 157.27.180.18.
220 SwiFTP 2.10.2 ready
Name (157.27.180.18:guido): ftp
331 Send password
Password:
230 Access granted
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> ls
200 PORT OK
150 Opening ASCII mode data connection for file list
drwxr-xr-x 1 owner group           40 Oct 23 08:23 .android_secure
drwxr-xr-x 1 owner group        32768 Sep 16 16:09 .MySecurityData
drwxr-xr-x 1 owner group        32768 Jul 29 13:09 Alarms
drwxr-xr-x 1 owner group        32768 Mar 02  2012 Android
...
drwxr-xr-x 1 owner group        32768 Oct 19 10:55 tmp
-rw-r--r-- 1 owner group          145 Jul 29 12:46 customized-capability.xml
226 Data transmission OK
ftp> put foo.dat
local: foo.dat remote: foo.dat
200 PORT OK
150 Data socket ready
226 Transmission complete
ftp> bye
ftp> 221 Goodbye
Linux:~$ _
</verb></tscreen>

<!-- - - - -->

<sect1>Copying files from an Andbox web server

<p>
Another way of getting files from your Andbox is making it a Web
server. Among the several free http servers available, I suggest that
you install ServDroid that is quite straightforward to use:

<p>
<htmlurl url="https://github.com/joanpuigsanz/servdroid/wiki"
name="https://github.com/joanpuigsanz/servdroid/wiki">.

<p>
Configuring ServDroid is very simple. Copy the files you want to make
available to 

<tscreen><verb>
/mnt/sdcard/servdroid/var/www/
</verb></tscreen>

<p>
then start ServDroid and point a browser to port 8080 of your Andbox's
IP.

<!-- ----- -->

<sect>Backup

<p>
This section may look pointless, as there are many backup & restore
programs (I regularly use one). But there are alternatives that may
come in handy.

<!-- ---- -->

<sect1>Backing up applications

<p>
Installed applications are stored in <tt>/data/apps/</tt>, which is
inaccessible on unrooted devices. You can, however, backup your
<tt>.apk</tt> files using Ghost Commander or the <tt>adb backup</tt>
command. I prefer the former, which is way faster and more convenient
(IMHO).

<p>
Start Ghost Commander and select a directory on the internal storage;
for example, <tt>/mnt/sdcard/Tmp</tt>. Move to the other pane, select
``Home'', then ``Applications''. Select the applications you want to
backup, the select ``Copy''. Please note that all applications will be
listed, including system applications.

<p>
To copy the selected <tt>.apk</tt> to your Linux box, all you have to
do is:

<tscreen>
<verb>
Linux~/backups/apk$ adb pull /mnt/sdcard/Tmp/
</verb>
</tscreen>

<p>
To restore, say, <tt>foo.apk</tt>, use this command:

<tscreen>
<verb>
Linux~/backups/apk$ adb push foo.apk /mnt/sdcard/Tmp/
</verb>
</tscreen>

<p>
Then open Ghost Commander, move to <tt>/mnt/sdcard/Tmp/</tt>, and tap
on <tt>foo.apk</tt> to install it. 

<!-- - - - -->

<sect1>Backing up applications data

<p>
As explained in Section <ref id="maindir" name="Main Directories in
the Internal Storage">, applications data is stored in directories
under <tt>/mnt/sdcard/Android/data</tt>. You already have all the
information you need to back up these directories!

<!-- ----- -->

<sect>Terminal emulator and shells
<label id="terminals">

<p>
If you're a geek, you'll want to use a command line interface on your
Andbox. Properly configured, a terminal emulator will give you
almost the same interface as the Linux terminal. This is especially
useful if your Andbox has a physical keyboard.

<p>
If you're not a geek, you should install a terminal emulator
nonetheless: it will be useful anyway, since you'll be able to use
some important command-line commands like Busybox. More about this
later.

<p>
One of the best FOSS options is Android Terminal Emulator, available
here:

<p>
<htmlurl
url="https://github.com/jackpal/Android-Terminal-Emulator/wiki"
name="https://github.com/jackpal/Android-Terminal-Emulator/wiki">

<p>
It provides a fully functional terminal emulator, which is invaluable
for at least two reasons. First and foremost, you will be able to run
most command-line programs available on Linux; in many cases, you can
even compile them yourself. Secondly, the terminal makes the standard
Android commands found in <tt>/system/bin</tt> and
<tt>/system/xbin</tt> available to you. But <em>beware</em>: these are
not the same as the standard Linux commands! They're only a subset of
the standard GNU commands (even <tt>cp</tt> is missing: use <tt>cat
file > newfile</tt> instead), and they usually don't behave exactly
the same.

<p>
If you need a more complete command-line experience, you will also
want to install a command-line environment like KBOX, ZShaolin,
Terminal IDE, or Termux:

<itemize>

  <item>KBOX3 (KBOX2 is an older version):
  
  <p>
  <htmlurl url="http://kevinboone.net/kbox3.html"
  name="http://kevinboone.net/kbox3.html">
  
  <p>
  KBOX is a compact and fully functional Linux-like command-line
  environment. It also provides additional software, such as
  <tt>gcc</tt>, <tt>tmux</tt>, the <tt>dropbear</tt> SSH server, and
  much more.
  
  <item>Zshaolin:
  
  <p>
  <htmlurl url="http://www.dyne.org/software/zshaolin/"
  name="http://www.dyne.org/software/zshaolin/">
  
  <p>
  Zshaolin is a <tt>zsh</tt>-based terminal that provides lots (I mean
  <em>lots</em>) of additional free software. The whole thing is FOSS,
  but is not cost-free.

  <item>Terminal IDE:
  
  <p>
  <htmlurl url="http://www.spartacusrex.com/terminalide.htm"
  name="http://www.spartacusrex.com/terminalide.htm">
  
  <p>
  It's a very complete Linux-like command-line environment. It's
  focused on development, providing Vim, <tt>gcc</tt>, <tt>mc</tt>,
  <tt>ssh</tt>, and loads of software. Once installed, it gives you
  the option ``Install System'' to install additional components,
  including the <tt>bash</tt> shell.
  
</itemize>

<p>
All of them are great programs: advanced users really can't do without
a terminal.

<p>
Which one to install depends on how much sdcard space you can afford.
If you have a few hundreds of MBytes to devote to it, I would suggest
that you install Terminal IDE: it provides a very Linux-like
experience. If you're short on storage, I suggest that you install
KBOX: it's a very good compromise.

Users of Android 5 and later versions may want to install an
alternative terminal emulator called Termux:

<p>
<htmlurl url="https://termux.com/" name="https://termux.com/">
  
<p>
It's very nice and self-contained, i.e. it does not need KBOX or
another command-line environment. Additional software can be installed
simply using apt (Debian users, does that ring a bell?):

<tscreen>
<verb>
$ gcc
The program 'gcc' is not installed. Install it by executing:
  apt install gcc
$ ...
</verb>
</tscreen>

<p>
Termux is released under GPLv3, but some add-ons are available for a
small fee.  


<!-- - - - -->

<sect1>Installing KBOX

<p>
Whether to install KBOX2 or KBOX3 depends on your Andbox' Android
version. I installed KBOX2 on two of my Andboxes, which run Android
4.*, and KBOX3 on my new phone. In the following, I'll show how to
install KBOX2; installing KBOX3 is very similar. Try KBOX3 first; if
you get a segmentation fault running the KBOX3 installer, then try
with KBOX2. 

<p>
Download the base installer, called <tt>kbox2-base-installer</tt> or
<tt>kbox3-install-base</tt>. Open Terminal Emulator and issue the
following commands:

<tscreen>
<verb>
foo@android:/ $ cd
foo@android:/.../app_HOME $ cat /sdcard/Download/kbox2-base-installer > kbox2-base-installer
foo@android:/.../app_HOME $ chmod 755 kbox2-base-installer
foo@android:/.../app_HOME $ ./kbox2-base-installer
UnZipSFX 6.00 of 20 April 2009, by Info-ZIP (http://www.info-zip.org).
  inflating: setup
   creating: installer-image/
  inflating: installer-image/install.sh
  inflating: installer-image/base-image.tar
  inflating: installer-image/busybox
  inflating: installer-image/.install.sh.swp
foo@android:/.../app_HOME $ ./setup
Running installer for KBOX2
Running installation script using busybox
CWD is /data/data/jackpal.androidterm/app_HOME
KBOX root directory is /data/data/jackpal.androidterm/app_HOME/kbox2
KBOX shell is /data/data/jackpal.androidterm/app_HOME/kbox2/bin/kbox_shell
</verb>
</tscreen>

<p>
If installation succeeds, you can replace the standard Android shell
with KBOX's. Open the Terminal Emulator preferences, select ``Command
line'', and change:

<p>
<tt>/system/bin/sh -</tt>

<p>
to:

<p>
<tt>/data/data/jackpal.androidterm/app_HOME/kbox2/bin/kbox_shell</tt>

<p>
Be very careful to write the above correctly! If you make a mistake,
Terminal Emulator will not start and you will have to remove it and
reinstall it.

<p>
Exit Terminal Emulator and reopen it. The command prompt should have
changed to <tt>kbox$</tt>:

<tscreen>
<verb>
kbox$ pwd
/home/kbox
kbox$ _
</verb>
</tscreen>

<p>
Now you're working in a fake UNIX environment; many commands are
provided by Busybox. If you want to access the Android file system,
you'll find it under the <tt>/android_root</tt> directory.

<p>
You may want to install additional software from KBOX home page.
Depending on your KBOX version, either link:

<p>
<htmlurl
url="http://kevinboone.net/kbox2_downloads.html"
name="http://kevinboone.net/kbox2_downloads.html">

<p>
<htmlurl
url="http://kevinboone.net/kbox3_downloads.html"
name="http://kevinboone.net/kbox3_downloads.html">

<p>
Additional programs are provided as <tt>.deb</tt> packages. This is
the very same format used by Debian and many other Linux
distributions, but obviously the packages provided for KBOX only work
on KBOX. Download the package you want and install it as in the
following example. Let's install coreutils, an improved implementation
that replaces the default provided by KBOX's BusyBox:

<tscreen><verb>
kbox$ dpkg -i /android_root/mnt/sdcard/Download/coreutils_8.22_kbox.deb
Unpacking coreutils (from /android_root/mnt/sdcard/Download/coreutils_8.22_kbox.deb)...
Setting up coreutils (8.22)...
kbox$ ls --color /android_root
...
</verb></tscreen>


<!-- - - - -->

<sect2>Printing via FTP

<p>
If you install the KBOX command-line ftp client, you <em>could</em> be
able to print PDF files from your Andbox. I don't mean Google Cloud
Print; and I repeat you <em>could</em>, because it actually depends on
your printer's capabilities.

<p>
Some network printers include an FTP server, and you can print
PostScript or PDF files sending them directly to the printer via FTP.
First of all, find out whether your printer supports FTP:

<tscreen><verb>
Linux:~$ nmap MY.OFFICE.PRINTER

Starting Nmap 6.40 ( http://nmap.org ) at 2015-10-22 11:08 CEST
Nmap scan report for MY.OFFICE.PRINTER (10.15.130.105)
Host is up (0.00023s latency).
rDNS record for 10.15.130.105: csf-p1-v7913500307.xxx.yyy.zzz
Not shown: 990 closed ports
PORT     STATE SERVICE
21/tcp   open  ftp
23/tcp   open  telnet
80/tcp   open  http
139/tcp  open  netbios-ssn
514/tcp  open  shell
515/tcp  open  printer
631/tcp  open  ipp
7443/tcp open  oracleas-https
8080/tcp open  http-proxy
9100/tcp open  jetdirect

Nmap done: 1 IP address (1 host up) scanned in 12.27 seconds
Linux:~$ _
</verb></tscreen>

<p>
As you can see, the above printer (it's an Aficio MP 4001) has an open
FTP port, in addition to the standard JetDirect port 9100 and many
others (that should be closed, but still...)

<p>
From KBOX, run the ftp client and copy a file to the printer as in the
following session. The user name is ``ftp'', the password is
``guest''. These are common FTP defaults.

<tscreen><verb>
kbox$ ftp MY.OFFICE.PRINTER
Connected to csf-p1-v7913500307.MY.OFFICE.DOMAIN
220 NRG MP 4001 FTP server (7.34) ready.
Name (MY.OFFICE.PRINTER:guido): ftp
331 Password required for ftp.
Password:
230 User ftp logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> put my_file.pdf
local: my_file.pdf remote: my_file.pdf
200 PORT command successful.
150 Opening BINARY mode data connection for 'my_file.pdf'.
226 Transfer complete.
24057 bytes sent in 0.00 secs (405054.5 kB/s)
ftp> bye
221 Goodbye.
kbox$ _
</verb></tscreen>

<p>
When the file is transfered to the printer, it will be printed.

<p>
I successfuly tested this method on several HP and Aficio network
printers. Obviously, you mileage may vary; for instance, you may need
to provide a real user name and password instead of ``ftp'',
``guest''. Ask your local sysadmin (and buy him/her a beer while
you're at it).

<p>
Ghost Commander provides access to ftp servers natively, so it can be
used instead of the command-line ftp client.


<!-- ----- -->

<sect1>Remote shell via SSH

<p>
In addition to local shells, you can open a shell on your device
remotely, via <tt>ssh</tt>; you will need a <tt>ssh</tt> server on the
Andbox. Such server is SSHelper (free software, GPL'ed):

<p>
<htmlurl
url="http://arachnoid.com/android/SSHelper/"
name="http://arachnoid.com/android/SSHelper/">

<p>
Since it runs on unrooted devices, it uses the port 2222 instead of
the standard port 22; i.e., to connect to it from the Linux terminal
you will do:

<tscreen>
<verb>
Linux:~$ ssh -p 2222 157.27.188.78
The authenticity of host '[xx.xx.xx.xx]:2222 ([xx.xx.xx.xx]:2222)' can't be established.
ECDSA key fingerprint is 20:3f:f1:c1:3b:ce:fb:61:3e:a3:bb:0d:a4:15:54:c7.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[xx.xx.xx.xx]:2222' (ECDSA) to the list of known hosts.
SSHelper Version 7.8 Copyright 2014, P. Lutus
Default password is "admin" (recommend: change it)
guido@157.27.188.78's password: 
Android:2.6.39.4-g9560a99
app_105@android:/data/data/com.arachnoid.sshelper/home $ _
</verb>
</tscreen>

<p>
The connection uses the standard Android shell,
<tt>/system/bin/sh</tt>. Nothing prevents you from starting, say,
KBOX. All you have to do is type the full path of the KBOX shell:

<tscreen>
<verb>
...home $ /data/data/jackpal.androidterm/app_HOME/kbox2/bin/kbox_shell
kbox$ _
</verb>
</tscreen>

<!-- TO DO: expand this section -->

<!-- - - - -->

<sect1>Compiling C programs, Linux side

<p>
Once you have a terminal emulator, you can add a lot of command-line
based software to your Android box. If you're a geek, this is an
invaluable extension that makes your Andbox closer to a ``real''
computer; but even if you're a casual user, please read on.

<p>
You can compile C programs directly on your Andbox, and also on your
Linux box. In the latter case, you use a so-called <em>cross compiler
toolchain</em>: a compiler and associated binutils that produce code
for Android. In many cases, but not only, for the ARM cpu.

<p>
Most Linux distributions provide one or more cross compiler toolchains
that target ARM on Android. On my box, I installed the package
<tt>gcc-arm-linux-androideabi</tt> and its dependencies. If your Linux
distributions doesn't include it by default, get the relevant
toolchain from the NDK home page:

<p>
<htmlurl url="http://developer.android.com/ndk/downloads/index.html"
name="http://developer.android.com/ndk/downloads/index.html">

<p>
Another toolchain that targets Android on x86 CPUs is called
<tt>gcc-i686-linux-android</tt>.

<p>
Choose the relevant architecture and download the binary package for
Linux 32-bit or 64-bit. The directory

<tscreen><verb>
toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86/bin/
</verb></tscreen>

<p>
contains prebuilt binaries: include that directory in the
<tt>$PATH</tt>. MIPS and x86 binaries are also available.

<p>
Supposing you're compiling for ARM, the compiler is called
<tt>arm-linux-androideabi-gcc</tt>. You use it instead of <tt>gcc</tt>
to compile Android binaries. In general, all binutils have a
<tt>arm-linux-androideabi-</tt> prefix.

<tscreen>
<verb>
Linux:~$ arm-linux-androideabi-gcc -static -o hello hello.c
Linux:~$ arm-linux-androideabi-strip hello
Linux:~$ file hello
hello: ELF 32-bit LSB  executable, ARM, EABI5 version 1 (SYSV), statically linked, stripped
Linux:~$ _
</verb>
</tscreen>

<p>
The <tt>-static</tt> option makes the executable self-contained. It
may be necessary to avoid problems with shared libraries, but it also
makes the executable larger.

<p>
Now you can copy the program to your Android box, but you can't copy
it to any directory of your choice. In fact, if you copy a program to
a directory in the internal memory, like <tt>/mnt/sdcard</tt>, you'll
be unable to run the program as it lacks the 755 permissions.
Remember, <tt>/mnt/sdcard</tt> is mounted as VFAT, so it cannot provide
file permissions.

<p>
Fortunately, the Android file system has a directory that is writeable
and supports file permissions: <tt>/data/local/tmp</tt>. Unlike the
<tt>/tmp</tt> directory in Linux, files in this directory are not
deleted at boot time.

<p>
Here is how to copy (all Android versions) and run (Android older than
5.*) your application on the Andbox:

<tscreen>
<verb>
Linux:~$ adb push hello /data/local/tmp
57 KB/s (2752 bytes in 0.046s)
geo:~$ adb shell
shell@android:/ $ cd /data/local/tmp
shell@android:/data/local/tmp $ chmod 755 hello
shell@android:/data/local/tmp $ ./hello
Hello, world!
32|shell@android:/data/local/tmp $ exit
Linux:~$ _
</verb>
</tscreen>

<p>
Beware: Android 5.* has better security policies and will not allow
running programs from <tt>/data/local/tmp</tt>, or even accessing that
directory. From the terminal, you'll have to copy the compiled
programs to a directory where you have write and execute permissions.
Beware: you will have to copy files in the blind, specifying their
exact names, no wildcards allowed!

<p>
For instance, using KBOX:

<tscreen>
<verb>
kbox$ ls /android_root/data/local/tmp
ls: cannot open directory  /android_root/data/local/tmp: permission denied
kbox$ cp /android_root/data/local/tmp/hello .
kbox$ ls
hello
kbox$ chmod 755 hello
kbox$ ./hello
hello, world!
kbox$ _
</verb>
</tscreen>

<p>
A remarkable list of command-line programs can be easily compiled for
Android. Among others, I ported the Bywater BASIC interpreter:

<p>
<htmlurl url="http://sourceforge.net/projects/bwbasic/"
name="http://sourceforge.net/projects/bwbasic/">

<p>
(minor tweaks were needed: I added <tt>-DHAVE_ISNAN=1</tt> to the DEFS
in the <tt>Makefile</tt>, and also <tt>#define uint64_t unsigned
long</tt> at the top of <tt>bwbasic.h</tt>)

<p>
The C version of the e3 text editor (version 2.7.1) can be compiled
with no tweaks at all:

<p>
<htmlurl
url="https://sites.google.com/site/e3editor/"
name="https://sites.google.com/site/e3editor/">

<p>
same for the ABC music tools:

<p>
<htmlurl url="http://abcplus.sourceforge.net/"
name="http://abcplus.sourceforge.net/">

<p>
In general, any program that doesn't depend on fancy libraries is
readily portable to Android. Explanations on compiling stuff in
Android are available here:

<p>
<htmlurl url="http://kevinboone.net/android_native.html"
name="http://kevinboone.net/android_native.html">.

<p>
Compile the programs you need, copy them to <tt>/data/local/tmp/</tt>,
and make sure this directory is included in the <tt>$PATH</tt> of your
favourite terminal.

<!-- ----- -->

<sect1>Compiling C programs, Android side

<p>
The simplest way to compile programs on an Android box is installing
Terminal IDE, cited above, and its ``System'' that includes the
<tt>gcc</tt> compiler. It's included, but as a compressed archive:
it's up to the user to unpack it and install it. Let's see how to do it.

<p>
Start Terminal IDE, enter the terminal and insert these commands:

<tscreen>
<verb>
cd system
tar zxvf android-gcc-4.4.0.tar.gz
cd
vi .bashrc
</verb>
</tscreen>

<p>
Surely you can use <tt>vi</tt>, can't you? Move to the end of the file
and add this line:

<code>
export PATH=$HOME/system/android-gcc-4.4.0/arm-eabi/bin:$PATH
</code>

<p>
save, exit <tt>vi</tt>, exit Terminal IDE then restart it. You have
expanded the PATH to include the directory containing the <tt>gcc</tt>
executable. Now you should be able to run it:

<tscreen>
<verb>
gcc
gcc: no input files
</verb>
</tscreen>

<p>
That's it! From now on, you can compile programs directly on your
Android box. Don't expect to be able to compile every single, though.

<!-- - - - -->

<sect1>CCTools

<p>
As the CCTools home page states, ``CCTools is native IDE for Android
devices. It includes C/C++/Lua/GNU Makefile/Shell source code editor
with syntax highlighting and complete android gcc toolchain for
arm/mips/x86 devices.''

<p>
CCTools is a very nice addition, and it also provides support for
Fortran, SDL and much more. I suggest that you give it a try.


<!-- ----- -->

<sect>Remote control

<p>
An Andbox can be turned into a remote that works via WiFi, Bluetooth,
or USB, to control a PC or other devices. Conversely, a PC can be used
to remotely control your Andbox.

<!-- - - - -->

<sect1>Web interface to android

<p>
There are several free-as-in-free-beer programs that provide a Web
interface to Wi-Fi connected Andbox: AirDroid, 3CX
DroidDesktop, RemoteDesktop, and many others. These programs let you
access your device and manage files, SMS, multimedia, and more. Great
programs, really: too bad they're not FOSS.

<p>
As of this writing, the only FOSS program that provides the same
functionality (and much more) is Webkey, released under the GPL:

<p>
<htmlurl
url="https://code.google.com/p/webkey-dev/downloads/list"
name="https://code.google.com/p/webkey-dev/downloads/list">

<p>
It lets you fully control your device via WiFi or 3/4G using a
browser. Unfortunately, it requires root: but it's such an incredibly
great program, you may want to root your device just to use it.

<p>
Enable Wi-Fi, start Webkey and take note of the https address. Open a
browser on the Linux box and go the https address to be greeted by
Webkey's login page. Click on ``Registration'', insert a username and
password and click on ``Create new user''. Webkey will ask for your
permission to allow the user to control the phone. Using the newly
created credentials, you can now log in.

<p>
Now, put the Andbox down and navigate through available options.
Everything you can do on the Andbox can be done in Webkey's page: it
provides a terminal, file manager, screenshot, program control, and
<em>much</em> more!

<!-- - - - -->

<sect1>Android as a remote

<p>
Many commercial and/or free-as-in-free-beer applications exist;
just search the web to find them. FOSS applications worth mentioning
are:

<itemize>

  <item>Gfx Tablet (MIT License): it turns the Andbox into a
  Wi-Fi graphics tablet, useful for drawing in applications like GIMP.
  It needs a sudo'ed Linux-side server (networktablet).
  
  <p>
  Home: <htmlurl url="http://rfc2822.github.io/GfxTablet/"
  name="http://rfc2822.github.io/GfxTablet/">
  
  <item>RemoteDroid: WiFi only, GPL'ed. It also provides a handy
  keyboard that includes T9.
  
  <p>
  Home: <htmlurl url="https://code.google.com/p/remotedroid/"
  name="https://code.google.com/p/remotedroid/">
  
  <item>PRemoteDroid: WiFi and Bluetooth (libbluetooth-dev required).
  Released under generic Open Source license.
  
  <p>
  Home: <htmlurl url="https://code.google.com/p/premotedroid/"
  name="https://code.google.com/p/premotedroid/">
  
  <item>Gmote: WiFi, it's meant to be a multimedia controller.
  Released under the Apache license.
  
  <p>
  Home: <htmlurl url="https://code.google.com/p/gmote/"
  name="https://code.google.com/p/gmote/">
  
  <item>DroidPad (GPL3): USB and WiFi. To make it work as a normal
  user, issue the command <tt>sudo chmod 666 /dev/uinput</tt>.
  
  <p>
  Home: <htmlurl url="http://www.digitalsquid.co.uk/droidpad/"
  name="http://www.digitalsquid.co.uk/droidpad/">.
  
  <item>Anyremote (GPL2): Bluetooth, Wi-Fi or just TCP/IP connection.
  
  <p>
  Home: <htmlurl url="http://anyremote.sourceforge.net/"
  name="http://anyremote.sourceforge.net/">
  
</itemize>

<p>
They all work in a similar manner. First off, you install a ``server''
program on the Linux box, then use the Android application that
talks to it. Let's see, for instance, how to install RemoteDroid.

<p>
Copy the server <tt>RemoteDroidServer.jar</tt> somewhere to your Linux
box, then run it:

<tscreen>
<verb>
Linux:~$ java -jar RemoteDroidServer.jar
</verb>
</tscreen>

<p>
A window will pop up, showing some information and the IP address you
can connect to. Activate WiFi on the Andbox (3G/4G/xG is not
supported), launch RemoteDroid, and provide the IP address you were
shown. There you are: slide your finger on the Android screen and see
the arrow move on the Linux box.

<!-- - - - -->

<sect1>X servers

<p>
If you're a geek, you know that you can run a program on a remote
computer and display its graphical user interface on another computer.
This useful feature is provided by the X server; most Linux
distributions use X.Org.

<p>
At least two Android X server implementations are available:

<itemize>
  
  <item>android-xserver: <htmlurl
  url="http://code.google.com/p/android-xserver/"
  name="http://code.google.com/p/android-xserver/">
  
  <item>XSDL, <htmlurl
  url="http://sourceforge.net/projects/libsdl-android/files/apk/XServer-XSDL/"
  name="http://sourceforge.net/projects/libsdl-android/files/apk/XServer-XSDL/">
  
</itemize>

<p>
I encountered a few issues using <tt>android-xserver</tt>, while XSDL
gave me no problems. XSDL is pretty self-explanatory: when you first
start it, it asks for your permission to download and install
additional fonts. Then, it gives you instructions on how to start a
window manager and an application on the remote Linux (or Unix)
machine.

<p>
Start XSDL, then start Terminal IDE and run these commands:

<tscreen>
<verb>
terminal++@157.27.100.1:~$ ssh user@remote.linux.machine
user@remote.linux.machine's password:
Linux:~$ export DISPLAY=157.27.0.1:0 # IP of Andbox
Linux:~$ marco & # window manager
Linux:~$ gimp
</verb>
</tscreen>

<p>
At this stage, you'll have the Gimp running on the remote machine and
displaying its user interface on the Andbox. Now you can enjoy
the awkward experience of using a graphical application without a
physical mouse!

<!-- ----- -->

<sect1>VNC client

<!-- TO DO: Android vnc server -->

<p>
Using a VNC client you can control a remote graphical session from
your Andbox. Several VNC clients exist; a GPL'ed one is
androidVNC,

<p>
<htmlurl
url="https://code.google.com/p/android-vnc-viewer/"
name="https://code.google.com/p/android-vnc-viewer/">

<p>
also available from F-Droid.

<p>
You will also need a VNC server on the Linux remote machine. There are
many VNC servers available; in the following example I'll use Tight
VNC, GPL'ed,

<p>
<htmlurl url="http://www.tightvnc.com/"
name="http://www.tightvnc.com">

<p>
The first command you must provide on the Linux box is
<tt>tightvncpasswd</tt>, which lets you set an access password for VNC
sessions (user name is not required). Once you've set your password,
start the server:

<tscreen>
<verb>
Linux:~$ tightvncserver 

New 'X' desktop is linux-machine:1

Creating default startup script /home/guido/.vnc/xstartup
Starting applications specified in /home/guido/.vnc/xstartup
Log file is /home/guido/.vnc/geo:1.log
</verb>
</tscreen>

<p>
The server is started, most probably on TCP port 5901 (check the log
file). A new file, <tt>$HOME/.vnc/xstartup</tt>, has been created:
you're free to modify it to customize your VNC session.

<p>
Now, run androidVNC and provide the connection information. Colour
depth will influence your connection speed; the fewer colours, the
faster the connection. Again, enjoy the awkward world of mouse-less
user interface!

<!-- ----- -->

<sect>Taking screenshots and screencasts

<p>
Some Android versions let the user take a screenshot natively,
usually holding the Power and Volume Down buttons together. For all
others, there's DroidAtScreen:

<p>
<htmlurl
url="http://droid-at-screen.ribomation.com/"
name="http://droid-at-screen.ribomation.com/">

<p>
This application is invaluable if you want to display your Android
screen on a computer and/or a projector.

<p>
On the Andbox, all you have to do is enable USB debug.
DroidAtScreen is a Java application that runs on the Linux box, where
it needs <tt>adb</tt>. Extract the .jar file and run it:

<tscreen>
<verb>
Linux:~$ java -jar droidAtScreen-1.0.2.jar &
</verb>
</tscreen>

<p>
Then configure DroidAtScreen telling it where to find the adb
executable; type in its full path. You may have to click on Restart
ADB and/or Reload Devices.


<!-- ----- -->

<sect>Sharing GPS via Bluetooth

<p>
One of the most useful features of many Andboxs is the
integrated GPS circuitry. GPS-enabled Android phones can share the
location with other devices, including Android and Linux machines. All
you need is Bluetooth and some software.

<sect1>Sharing from Android to Android

<p>
Let's suppose that you have a GPS-enabled Android phone and a GPS-less
Android tablet. On the phone, you can install a program that turns it
into an NMEA GPS---that is, a GPS receiver that can ``talk'' to other
devices using the NMEA protocol. On the tablet, you will install a
program that connects to the NMEA GPS and reads the location info.

<p>
Bluetooth GPS for Android,

<p>
<htmlurl
url="http://sourceforge.net/projects/bluegps4droid/"
name="http://sourceforge.net/projects/bluegps4droid/">

<p>
is the program you need to connect to the NMEA GPS. In our example,
you will install it on the tablet.

<p>
On the phone, you have more choice. I tested the following NMEA
programs, all of which worked well:

<itemize>
  
  <item>GPS over BT:
  
  <p>
  <htmlurl
  url="https://play.google.com/store/apps/details?id=com.Saenko.GpsOverBt"
  name="https://play.google.com/store/apps/details?id=com.Saenko.GpsOverBt">
  
  <p>
  It's the most complete of the bunch: provides a lot of information
  on the visible satellites, GPS position and so on. Free to use,
  unknown license.
  
  <item>Share GPS:
  
  <p>
  <htmlurl url="http://sharedroid.jillybunch.com/" 
  name="http://sharedroid.jillybunch.com/">
  
  <p>
  It's pretty simple to use; free to use, unknown licence.

  <item>GPS 2 Bluetooth:
  
  <p>
  <htmlurl url="http://android.cajax.net/"
  name="http://android.cajax.net/">
  
  <p>
  This program is extremely simple to use: it's basically an on/off
  button to enable the external GPS. Free to use, unknown licence.

  <item> BlueNMEA:
  
  <p>
  <htmlurl
  url="http://max.kellermann.name/projects/blue-nmea/"
  name="http://max.kellermann.name/projects/blue-nmea/">
  
  <p>
  It's a tiny, very basic program. It's free to use, sources
  available, unknown licence.

</itemize>

<p>
Once you have the software installed on the devices, you're ready to
go. First of all, enable GPS on the phone and get the fix. Then,
enable bluetooth on both devices and pair them. Then start the NMEA
app of your choice on the phone.

<p>
To get the GPS location on the tablet, start Bluetooth GPS for
Android. The location will become available in a few seconds, and will
be shown in applications. My favourite is Osmand, <htmlurl
url="http://www.osmand.net" name="http://www.osmand.net">.

<!-- ----- -->

<sect>The end, for now

<p>
Congratulations! You have now some basic information on how to turn
your Andbox into something even more useful, and how to interact with it using
your trusted GNU/Linux machine. 

<p>
At the end of this document, I can confess you the truth: while I'm a
long-term GNU/Linux fan, I'm afraid I've just started to appreciate
Android. I find it insanely fragmented; until recently, it was
unacceptably sluggish and laggy; I also believe it still suffers from
(at least) a couple of serious design flaws. Besides, I don't like
tablets, all of them; I find way too limited, if compared to a real
computer. That said, I can say that my 8-core, Android 5.0.1-based
phone is quite nice.

<p>
I hope this guide provided some useful information. It's only the
beginning: please stay tuned for updates.


<sect1>Copyleft

<p>
This document is released under the GNU Free Documentation License
1.3, obtainable here: 

<p>
<htmlurl url="http://www.gnu.org/licenses/fdl-1.3.html"
name="http://www.gnu.org/licenses/fdl-1.3.html">.

<p>
This document is provided ``as is''. I put a great amount of effort
into writing it as accurately as I could, but you use the information
contained in it at your own risk. In no event shall I be liable for
any damages resulting from the use of this work.

<p>
Enjoy,
<p>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;</tt>Guido <tt>=8-)</tt>

</article>

