Preparing Your Host for Building Android Applications
=====================================================

Install the Android SDK (Software Development Kit).

Install the Android NDK (Native Development Kit).

The SDK initially only includes support for the current Android API 
level. Brltty, however, needs to support earlier API levels so that it 
can run on older releases of Android. Support for any missing API levels 
is added whenever the SDK is updated. To do this, use the following 
command:

  android update sdk -u

The "-u" option, which is the short form of the "--no-ui" option, means
to bypass the graphical interface. There may still be command-line
password prompts for installing packages which are provided by various
vendours. Any of these can be easily skipped.

The 64-bit versions of the SDK and NDK depend on 32-bit system 
libraries. If you're using a 64-bit version then you need to first 
ensure that these are installed on your system. This at least includes:

   libc6
   libz
   libstdc++6
   libncurses

If you are using a modern Debian GNU/Linux system (wheezy or later), you 
can install these packages from a foreign architecture (in this case, 
i386) with the following commands (as root):

   dpkg --add-architecture i386
   apt-get install libncurses5:i386 libstdc++6:i386 zlib1g:i386 libc6:i386

----------------------------------------------------------------------


Installing and Preparing the BRLTTY Source Tree
===============================================

Select the directory which should contain BRLTTY's source tree (which 
needn't yet exist). Then extract the latest BRLTTY source into it with 
the following command:

   svn checkout svn://mielke.cc/main/brltty /path/to/brltty

The directory operand (of svn checkout) is optional. If you don't 
specify it then it'll assume the directory named "brltty" within the 
current working directory.

Next, you need to prepare the source tree. This is done as follows:

   cd /path/to/brltty
   ./autogen

At this point, the source tree is essentially just like what you'd get 
were you to unpack an officially released BRLTTY archive. It doesn't yet 
know anything about the specifics of your system. It also doesn't yet 
know anything about the platform you intend to build BRLTTY for.

Adding information to BRLTTY's source tree regarding the spefiics of 
your system, as well as of your intent to build BRLTTY for Android, is 
done as follows:

   export ANDROID_NDK=/path/to/Android/NDK
   ./cfg-android -q

The "-q" option, which is the short form of the "configure" command's 
"--quiet" option, means to not display any progress information (there's 
usually quite a lot of it). Only warnings and errors are displayed.

In fact, all of the options you give to the "cfg-android" command are 
passed directly through to the "configure" command. So, while 
"cfg-android" supplies a default set of options to "configure", it's 
easy for you to do your own customization.

----------------------------------------------------------------------


Building BRLTTY for Android
===========================

In order to be able to build an Android application, a number of Android 
build tools need to be added to the command search path. This is done 
with the following command:

   export PATH=/path/to/Android/SDK/tools:/path/to/Android/SDK/platform-tools:$PATH

The next step is to build the BRLTTY core for Android. This is done as 
follows:

   cd /path/to/brltty/Android/Core
   make -s

The final step is to build the BRLTTY service for Android. This is done 
as follows:

   cd /path/to/brltty/AndroidApplication
   make -s

The "-s" option of the make command, which is short for its "--silent" 
option, means to not display any progress information (there's usually 
quite a lot of it). Only warnings and errors are displayed.

The result of the build is the file "BRLTTY_App-debug.apk".  It will
be in the "bin" subdirectory of the Android Application subdirectory.

   /path/to/brltty/Android/Application/bin/BRLTTY_App-debug.apk

"apk" is the file extension used for an installable Android package.

----------------------------------------------------------------------


Preparing Your Android Device for Installing an Android Package File
====================================================================

What you need is for "USB Debugging" to be enabled. This is done from 
the "Developer Options" screen, which you can get to from the "Settings" 
screen.

Launch the "Settings" aplication, and look, way down near the bottom, 
for "Developer Options". If you can't find it, the most likely cause is 
a new feature which was introduced in Android 4.2 (Jelly Bean). If you 
need to enable it, click on "About Phone", which, again, can be found at 
the bottom of the "Settings" screen. Then, on the "About Phone" screen, 
look for the "Build Number" line. Tap on "Build Nubmer" seven times and 
your device will officially declare you to be a developer. You should 
then be able to find "Developer Options" on the "Settings" screen.

There's a checkbox at the top-right of the "Developer Options" screen. 
It needs to be checked so that all of the other controls on that screen 
will be enabled. After doing that, check the "USB Debugging" checkebox 
(which can be found within the "Debugging" section). This enables the 
"adb" (Android Debug Bridge) tool to be used with your Android device.

----------------------------------------------------------------------


Installing BRLTTY on Your Android Device
========================================

In order to install BRLTTY onto your Android device, or to uninstall it 
from your device, you need to be in BRLTTY's Android Application 
subdirectory.

   cd /path/to/brltty/Android/Application

You also need to connect your device to your host via USB.

You only need the Android SDK for installing or uninstalling an
application from your device. You only need the Android NDK if you want
to do your own builds.

To install BRLTTY, use this command:

   make -s install

To uninstall BRLTTY, use this command:

   make -s uninstall

The "make install" command will fail if BRLTTY is already installed. If 
you're wanting to upgrade BRLTTY, however, then uninstalling it first is 
probably what you don't want to be doing. This is because uninstalling 
BRLTTY also causes its settings to be lost. What you should do instead 
is to reinstall it. You can do this with the following command:

   make -s reinstall

If you've obtained your Android package file (apk) from some other 
source (than building it for yourself), then it may have a different 
name than the make file is expecting. It's useful, therefore, to know 
what the actual host commands are for installing and uninstalling BRLTTY 
from your device.

The host command for installing an Android application is:

   adb install /path/to/file

The host command for reinstalling an Android application is:

   adb install -r /path/to/file

The host command for uninstalling an Android appliation is:

   adb uninstall appliation.package.name

So, to uninstall BRLTTY, the host command is:

   adb uninstall org.a11y.brltty.android

If any of these "make" or "adb" commands fail with an error like "device 
not found", it's probably because your host's USB device permissions are 
requiring root access. The solution to this problem is to restart the 
adb (Android Debug Bridge) server such that it is running as root. With 
this done, you yourself will then be able to use adb as a regular user.

The commands to restart the adb server such that it's running as root 
are as follows:

   su
   cd /path/to/android/sdk/platform-tools
   ./adb kill-server
   ./adb start-server
   exit

----------------------------------------------------------------------


Starting and Stopping BRLTTY
============================

BRLTTY isn't a regular Android application - it's an accessibility 
service. As such, it can't be started and stopped in the usual way - 
from the launcher. In fact, it can't even be found within the 
applications list.

BRLTTY can be started and stopped from within the accessibility 
settings. To get there, launch the "Settings" application, and then 
click on "Accessibility" (way down near the bottom). This window 
contains a "Services" section, which lists all of the accessibility 
services that are currently installed on the device. For each installed 
accessibility service, there's an associated indicator which says "On" 
if that service is currently running, and "Off" if it isn't.

Find "BRLTTY" and click on it. This brings up a window with two items in 
it. One is a "switch" (which accessibility services present as a 
"checkbox") for turning BRLTTY on and off. The other is a button which 
takes you to BRLTTY's "Settings" window. You should go through BRLTTY's 
settings, making changes as desired, as well as define your braille 
device(s), before starting BRLTTY.

----------------------------------------------------------------------


Connecting and Defining Your Braille Device
===========================================

In order to use a Bluetooth braille device, it must first be paired with 
your Android device. To do this, launch Android's "Settings" app, click 
on "Bluetooth", and then click on "Search for Devices". For Android to 
be able to find your braille device, you may need to do something on it 
in order to make it discoverable (visible). The instructions for your 
braille deivce should tell you how to do this.

In order to use a USB braille device, you'll need a special cable known 
as a "Micro USB Host Adapter". The USB port on an Android device usually 
acts as a device (rather than as a host) port. This is so that, for 
example, you can control your Android device from your computer. The 
Micro USB Host Adapter has a special plug which, when inserted into the 
Android device's USB port, instructs Android to act as a USB host. Be 
aware, though, that your braille device will begin to draw power from 
your Android device's battery (unless you can disable USB charging). 
This special cable, by the way, also allows you to connect any other USB 
device (keyboard, mouse, printer, hub, etc) to your Android device.

After you've connected your braille deivce to your Android device, 
you'll need to tell BRLTTY about it. Go to BRLTTY's "Settings" window, 
and click on "Manage Devices". From there, find your braille device, and 
then click "Add". To find your device, select its communication method, 
then select the device from the list that's presented, and then select 
the correct braille driver.

After you've added your braille device to BRLTTY, click on "Selected 
Device" and select it from the list of devices that BRLTTY knows about.

----------------------------------------------------------------------


Navigation
==========

The cursor is usually placed on the first character of the screen 
element which currently has accessibility focus. The one exception to 
this is that, within an editable input area, the cursor is placed at the 
location within that area where input will be inserted.

The cursor routing keys of the braille device perform their usual 
function when within an editable input area - the key above a given 
character brings the cursor to that character. In any other context, 
however, a cursor routing key performs an action on the screen element 
under it. Starting with the leftmost routing key over a screen element, 
which we'll call key #0, the actions are as follows:

   0  Set Accessibility Focus (used for cursor tracking)
   1  Click
   2  Long Click
   3  Scroll Backward
   4  Scroll Forward

----------------------------------------------------------------------


Using a Braille Keyboard
========================

Braille keyboard input is supported, but, like all Android input 
methods, it must be explicitly enabled, and then selected. BRLTTY cannot 
do either of these automatically on your behalf. Although this may be 
inconvenient, Android imposes this manual process so that you're very 
consciously aware of which input methods can process, and which input 
method is currently processing, whatever you're typing. Such 
applications, after all, handle extremely sensitive personal data (such 
as passwords, credit card numbers, etc), so it's crucial that you make 
your own decisions regarding which of them you trust.

You can enable BRLTTY's braille keyboard support ahead of time by 
launching the "Settings" application, and then clicking on "Language and 
Input". The "Keyboard and Input Methods" section of this screen contains 
a selector labeled "Default" which is used to select the current input 
Method, as well as a checkbox for each installed input method. An input 
method is enabled if its checkbox is checked, and can only be selected 
if it has been enabled.

BRLTTY's input method is called "BRLTTY Input Service. While you may 
wish to enable it ahead of time, you probably don't want to select it 
ahead of time. The reason for this is that Android only allows exactly 
one input method to be in use at a time. When you explicitly select 
BRLTTY's input method, therefore, you're also implicitly deselecting the 
system keyboard.

If you use a braille keyboard when BRLTTY's input method is either 
disabled or enabled but not selected, the Android "input method picker" 
will be automatically displayed. This dialog asks you to select an input 
method, and presents a set of radio buttons - one for each currently 
enabled input method. If there's no radio button for BRLTTY's input 
method then it hasn't been enabled yet.

To enable it, click the button within the dialog labeled "Set up input 
methods". This screen contains a checkbox for each installed input 
method. Check the checkbox for BRLTTY's input method to enable it. Then, 
click the "Back" button to get to the "Language and Input" screen, find 
the "Keyboard and Input Methods" section of that screen, and set the 
"Default" input method to BRLTTY's input method.

----------------------------------------------------------------------


When BRLTTY Crashes
===================

We hope, of course, that BRLTTY won't crash. If it does, though, we want 
to know about it.

If BRLTTY does crash, you'll get a dialog with a message like this:

   Unfortunately, BRLTTY has stopped.

This dialog will stay on the screen until you dismiss it by clicking its 
"OK" button. Android will then try to automatically restart BRLTTY, so 
don't be overly concerned if this dialog comeds up again. Android will 
eventually give up if, after a few automatic restart attempts, it 
detects that BRLTTY simply won't stay running.

If this ever happens, then, if you can, connect your device to your host 
via SUB as soon as possible in order to capture a debug log. To capture 
the debug log, use this command:

   adb logcat -v time -d >/path/to/logfile

The "-v time" option means to add a timestamp to each log record. The 
"-d" option means to dump the current Android system log. The "adb 
logcat" command writes the log to its standard output, so you need to 
redirect its standard output to whichever file you'd like the log to be 
dumped into.

The reason for capturing the log as soon as possible after a problem is 
that Android imposes limits on its log storage so that the log can't 
consume too much of your device's resources. If the log becomes too 
large, Android automatically removes older entries from it. If you wait 
too long, therefore, the part of it that shows how BRLTTY crashed may 
already have been automatically removed.

----------------------------------------------------------------------


Known Issues
============

BRLTTY needs to be manually stopped and then restarted for settings 
changes to take effect. This is unacceptable from a user perspective. 
Any settings change should be automatically reloaded.

Serial devices aren't supported. Even though Android devices don't have 
serial ports, serial devices still can be connected via a USB to Serial 
adapter. Users who have older, serial-only braille devices should still 
be able to use them with their Android devices.

----------------------------------------------------------------------


