~~~~~~~~~~~~~~~~~
BRLTTY on Android
~~~~~~~~~~~~~~~~~

.. include:: prologue.rst

Using BRLTTY
============

System Requirements
-------------------

BRLTTY has been designed to run on at least Android 4.1 (Jelly Bean). While it
does run on Android 4.0 (Ice Cream Sandwich), many of its highly desirable
features won't work.

BRLTTY requires access to a number of privileged Android operating system
capabilities. The required permissions are as follows:

``BIND_ACCESSIBILITY_SERVICE``
   This permission is required so that BRLTTY can inspect the layout and
   content of the screen.

``BIND_INPUT_METHOD``
   This permission is required so that Android will accept input from your
   braille device's keyboard.

``WAKE_LOCK``
   This permission is required so that BRLTTY can reset the Android device's
   lock timer each time you interact with a control on your braille device.

``BLUETOOTH``
   This permission is required so that BRLTTY can use Bluetooth to communicate
   with your braille device.

``BLUETOOTH_ADMIN``
   This permission is required on Android 4.0 (ICS) so that BRLTTY can use
   Bluetooth to communicate with your braille device.

``INTERNET``
   This permission is required so that BRLTTY can listen on a TCP/IP port for
   BrlAPI client connection requests.

``READ_EXTERNAL_STORAGE``
   This permission is required so that BRLTTY can read customized data files
   from your SD card.

Quick Start
-----------

If you'd just like to install BRLTTY onto your Android device and get going, 
then here's what you need to do. These instructions are from the perspective of 
a Firefox user on Windows, but the process should be much the same when using a 
different web browser and/or operating system.

A) On your computer:

   1) Go to `BRLTTY's Web Site`_.

   2) Find the ``Download`` link and press enter on it.

   3) Find the ``Android`` heading, down-arrow from there to the link that says
      ``Latest APK``, and press enter on it.

   4) You'll be prompted to open or save the file at this point. Save it.

   5) Go to your ``Downloads`` folder (or wherever you save downloads), and
      find the ``brltty-latest.apk`` file.

   6) If the file has been saved on your computer as ``brltty-latest.zip``,
      then press the ``Context`` key, arrow to and press enter on
      ``Rename``, and change the file extension from ``zip`` to
      ``apk``. Don't worry if you get a warning about the possibility of
      rendering the file unusable. Go ahead with the rename.

B) On your Android device:

   1) Go into ``Settings`` -> ``Security``, and tap to check ``Unknown
      Sources``. This option says something like:
      
         Allow the installation of apps from unknown sources
         
      This is a one-time step. Once the box has been checked, it stays checked.

   2) Copy the ``apk`` file to your device. There are a number of ways to do
      this:

      *  The easiest way may be to email it to yourself as a file attachment so
         that it will go to the email on your Android device.

      *  Another option is to save the file in Dropbox on your computer, and
         then wait for it to show up in Dropbox on your Android device.

      *  Another option is to connect your Android device to your computer via
         a USB cable, and then to copy the file to it in the same way that
         you'd copy a file to a thumb drive.

   3) Tap the ``brltty-latest.apk`` file to start installation, and answer any
      prompts. If you use the Dropbox method, you may need to tap on the file
      twice - once to download it, and a second time to start installation.

   4) Tap ``OK`` when installation is complete.

At this point, BRLTTY has been installed. Next, you'll need to go into
``Settings`` -> ``Accessibility`` -> ``BRLTTY`` in order to turn the ``BRLTTY``
accessibility service on, adjust its settings, and select your braille device.

If you'll be connecting to your braille device via Bluetooth,
see `Connecting Via Bluetooth`_.

If you'll be connecting to your braille device via USB, see
`Connecting Via USB`_.

If your braille device has a braille keyboard, see `Using a Braille Keyboard`_.

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 must be started and stopped from within the ``Accessibility Settings``
screen. To get there, launch the ``Settings`` application, and then tap on
``Accessibility`` (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 that says ``On`` if that service is currently running, and ``Off`` if
it isn't.

Find ``BRLTTY`` and tap 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 that takes you to BRLTTY's
``Settings`` screen. 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
-------------------------------------------

.. _Connecting Via Bluetooth:

In order to use a Bluetooth braille devic, you'll need to first "pair" it with
your Android device. Go into ``Settings`` -> ``Bluetooth``. If your braille
device is already listed within the ``Paired Devices`` section of that screen
then it has already been paired. If you still need to pair it then tap ``Search
for Devices``. This will add an ``Available Devices`` section to the screen. If
your braille device isn't listed then you may need to perform a model-specific
action on it in order to make it visible (also known as discoverable) - see its
manual for details. After doing that, tap ``Search for Devices`` again. Tap on
your braille device to begin a Bluetooth Pairing Request, enter its PIN (see
its manual for details), and tap ``OK``.

.. _Connecting Via USB:

In order to use a USB braille device, you'll need a special cable known as a
"Micro USB Host Adapter". The reason for this is that 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, known as an OTG
(on-the-go) connector, that, when inserted into the Android device's USB port,
instructs Android to act as a USB host.

The Micro USB Host Adapter also allows you to connect any other USB 
device (keyboard, mouse, printer, hub, etc) to your Android device. Be aware,
though, that if any such device, including your braille device, draws power via
its USB port then your Android device's battery will become the source of that
power. If portability isn't an issue, you may wish to consider using your Micro
USB Host Adapter to connect your Android device to a powered hub so that your
devices will draw power from the hub rather than from your Android device's
battery. You may also wish to consider disabling USB charging on any devices
which offer this capability.

After you've connected your braille deivce to your Android device, you'll need
to tell BRLTTY about it. Go to BRLTTY's ``Settings`` screen, and tap on
``Manage Devices``. From there, find your braille device, and then tap ``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, tap on ``Selected Device``
and select it from the list of devices that BRLTTY knows about.

Using a Braille Keyboard
------------------------

Braille device keyboard input is supported, but, like all Android input
methods, it must be explicitly enabled, and then explicitly selected. BRLTTY
cannot do either of these automatically on your behalf. Although this might 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're willing to trust.

You can enable BRLTTY's braille keyboard support ahead of time by launching the
``Settings`` application, and then tapping on ``Language and Input``. The
``Keyboard and Input Methods`` section of this screen contains a selector
labeled ``Default`` (that's 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 on-screen keyboard.

If you use a braille keyboard when BRLTTY's input method is either disabled or
enabled but not selected, Android's 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, tap 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 tap the
``Back`` button to return 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.

Navigating the Screen
---------------------

BRLTTY only remains connected to your braille device while your Android device
is unlocked or while its screen is on. If your Android device is locked and its
screen is off then BRLTTY automatically disconnects from your braille device.
This is so that you can easily share your braille device amongst multiple
hosts.

Pressing your Android device's power button (or similar action) to wake it up,
even though it may still be locked, is sufficient to cause BRLTTY to
automatically reconnect to your braille device. This allows you to enter your
password or PIN via your braille keyboard.

You can continue using your braille device even though your Android device's
screen may have turned off, as long as its lock timer hasn't yet expired.
Pressing keys on your braille device resets your Android device's lock timer in
the same way that pressing its keys, touching its screen, etc does. This means
that your Android device will stay awake and unlocked even though you're only
controlling it from your braille device, and that it'll also still
automatically lock once you're no longer using it.

The "accessibility focus" feature of Android is used for cursor tracking and
routing. It's a soft cursor, not visible on the screen, that can be 
programmatically associated with any screen element. All screen readers that
use it to define the current element for actions (like tapping) will implicitly
cooperate reasonably seamlessly with one another.

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

The cursor routing keys of the braille device perform their usual function when
within an editable input area if it has input focus - 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 #1,
these actions are as follows:

1) set accessibility focus (used for cursor tracking and routing)
2) tap (or click)
3) hold (or long click)
4) scroll backward (or up)
5) scroll forward (or down)

When an editable input area has input focus, BRLTTY's attribute underlining
feature is used to highlight the selected text region.

When a home screen folder is opened, BRLTTY automatically sets accessibility
focus to that folder's first entry. This eliminates the need to search for it.

A checkbox is rendered as a pair of [square brackets]. A space between them
means that the box isn't checked, and an ``X`` between them means that it is
checked.

A two-position switch is rendered as though it were a checkbox. The box isn't
checked if the switch is in its ``off`` position, and is checked if the switch
is in its ``on`` position. The label associated with the switch's current
position appears just after the [square brackets].

Android supports a number of global actions that can be performed by pressing
special hardware buttons and/or by touching reserved areas on the screen.
BRLTTY also offers a way to perform these actions from your braille device.
While a better way may be developed in the future, this is how it can be done
right now.

Since Android doesn't use the keyboard function keys (commonly named ``F1``
through ``F12``), BRLTTY uses them to perform global Android actions according
to the following table:

  =======  =====================  ===================
  Key      Actgion                Android Release
  -------  ---------------------  -------------------
  ``F1``   Home                   4.1 (Jellybean)
  ``F2``   Back                   4.1 (Jellybean)
  ``F3``   Notifications          4.1 (Jellybean)
  ``F4``   Recent Apps            4.1 (Jellybean)
  ``F5``   BRLTTY Settings        *
  ``F6``   Quick Settings         4.2 (Jellybean MR1)
  ``F7``   Move to Previous Item  *
  ``F8``   Move to Next Item      *
  ``F9``   Power Dialog           5.0 (Lollipop)
  ``F10``  Menu Key               *
  =======  =====================  ===================

The way a braille device emulates keyboard function keys differs from model to
model, so you should check the BRLTTY documentation for your braille device.
The most common way is to press the corresponding cursor routing key along with
some other key or key combination. For braille devices that have a braille
keyboard, the most common key to be used in conjunction with a cursor routing
key in order to emulate a keyboard function key is the space bar.

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 tapping its ``OK``
button. Android will then try to automatically restart BRLTTY, so don't be
overly concerned if this dialog comes up again. Android will eventually give up
if, after a few automatic restart attempts, it decides that BRLTTY simply won't
stay running.

If this ever happens, then, if you can, connect your device to your host via
USB as soon as possible in order to capture a debug log. To capture a 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 (with ``>``) to wherever you'd like the log to be written.

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
------------

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.

Building BRLTTY
===============

Preparing Your Host Environment
-------------------------------

You need the Android SDK (Software Development Kit) for:

*  installing an application onto your device
*  removing an application from your device

You can get it from `The Android SDK Web Page`_.

You need the Android NDK (Native Development Kit) if you want to do your own
builds. You can get it from `The Android NDK Web Page`_.

The SDK initially only includes support for the current Android API
(Application Programming Interface) 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 be password prompts for installing packages that 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're using a modern Debian GNU/Linux system (``Wheezy`` or later), you can
install these packages for 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
-----------------------------------------------

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

   git clone https://github.com/brltty/brltty.git /path/to/brltty

The directory operand (of ``git clone``) is optional. If you don't specify it
then the directory named ``brltty`` within the current working directory is
assumed.

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.

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 your command search path. This is done via the
following command::

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

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

   cd /path/to/brltty/Android/Application
   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 BRLTTY's Android Application directory::

   /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
-----------------------------

You need ``USB Debugging`` to be enabled. This is done from the ``Developer
Options`` screen. You can get to it from the ``Settings`` screen.

Launch the ``Settings`` aplication, and look, near the bottom, for ``Developer
Options``. If you can't find it, the most likely cause is a new feature that
was introduced in Android 4.2 (Jelly Bean). If you need to enable it, tap on
``About Phone``, which, again, can be found near 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 perform functions on your Android device.

Installing BRLTTY on Your Android Device
----------------------------------------

In order to install BRLTTY onto your device, or to remove it from your device,
you need to be in BRLTTY's Android Application directory::

   cd /path/to/brltty/Android/Application

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

To install BRLTTY, use this command::

   make -s install

To remove 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 removing it first is probably
what you don't want to be doing. This is because removing BRLTTY also causes
its settings to be lost. What you should do instead is reinstall it. You can do
this with the following command::

   make -s reinstall

If you've obtained your Android package file (``apk``) for BRLTTY 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 removing Android applications.

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 removing an Android appliation is::

   adb uninstall appliation.package.name

So, to remove BRLTTY, the host command is::

   adb uninstall org.a11y.brltty.android

If any of these ``make`` or ``adb`` commands fails 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``
server such that it is running as root. With this done, you yourself will still
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

