[# BRLTTY on Android #]

# Using BRLTTY #

## Activation and Configuration ##

Go to `Settings` -> `Accessibility` -> `Downloaded Apps` -> `BRLTTY` in
order to start/stop `BRLTTY`, adjust its settings, and select your
braille device(s).

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, i.e.
from the launcher. In fact, it won't even show up within the `All Apps`
list.

BRLTTY must be started and stopped from the `Accessibility Settings`
screen. To get there, launch the `Settings` application, and then tap on
`Accessibility` (near the bottom). This screen contains a "Downloaded
Apps" section which lists all of the accessibility services that are
currently installed on the device. For each of them, there's an
associated indicator that shows either `On` if it's currently running or
`Off` if it isn't.

Find `BRLTTY` and tap on it. This brings up a window with a few items in
it. One is a "switch" for turning BRLTTY on and off. Another is a button
that takes you to BRLTTY's `Settings` screen. You can go through
BRLTTY's settings, making changes as desired, as well as define your
braille device(s), either before starting BRLTTY or while it's running.

### Connecting Your Braille Device ###

#### Connecting Via Bluetooth ####

In order to use a Bluetooth braille device, 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'll
probably 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 the Bluetooth Pairing Request, enter its PIN (see its
manual for details), and tap `OK`.

There's an additional step that became mandatory in Android 12 (API
level 31). You need to explicitly tell Android that BRLTTY is allowed to
connect to Bluetooth devices. To do this, go to BRLTTY's [Actions
Screen] and tap **Allow Bluetooth Connections**. If you don't see this
button then this step has already been performed.

#### 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 the 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 USB 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 that offer
this capability.

### Defining Your Braille Device ###

You don't actually need to define your braille device, but BRLTTY will
connect to it much faster if you do. If you don't, BRLTTY will search
through all of the devices that have been connected via either Bluetooth
or USB (see [Connecting Your Braille Device]) for one that it
recognizes. If there's more than one, it'll select the first one that it
finds.

To define your braille device, go to BRLTTY's `Settings` screen, tap on
`Manage Devices`, and then on `Add Device`. From there, find your
braille device, and then tap `Add`. To find your braille device:

1.  Select its communication method (Bluetooth, USB).
2.  Select your device from the list that's presented.
3.  Select the correct braille driver. This step is optional, i.e. you
    can usually leave it set to `autodetect`. Going through the effort
    of selecting the correct driver, however, ensures a fast and
    reliable connection.

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.
Android doesn't permit BRLTTY to do either of these automatically on
your behalf. Although it's 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.

If you type on your braille device's keyboard when BRLTTY's input method
is either disabled or enabled but not selected, then BRLTTY will alert
you to this fact via a message on your braille display. You may wish to
enable BRLTTY's keyboard support ahead of time, but 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.

You can enable BRLTTY's keyboard support in one of the following ways:

- Launch Android's `Settings` application and tap on
  `Language and Input`. The `Keyboard and Input Methods` section of this
  screen shows the `Default` (currently selected) input method, and
  contains a check box for each installed input method. An input method
  is enabled if its check box is checked, so, to enable BRLTTY's
  keyboard support, check the box labelled `BRLTTY Input Service`. Once
  it's been enabled, you can select it at any time by adjusting the
  `Default` setting.
- If BRLTTY is running then switching between input methods is much
  easier. Go to BRLTTY's [Actions screen] and tap `Switch Input Method`.
  This brings up Android's Input Method Picker, which presents a set of
  radio buttons - one for each 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 labelled `Set up input methods`. This screen
  contains a check box for each installed input method. Check the box
  labelled `BRLTTY Input Service`. Then tap the `Back` button to return
  to the `Language and Input` screen, find the
  `Keyboard and Input Methods` section, and set the `Default` input
  method to BRLTTY's input method.

### Actions Screen ###

BRLTTY's Actions screen presents several common actions that you may
wish to perform:

- Switch Input Method
- Allow Bluetooth Connections
- BRLTTY Settings
- View User Guide
- Browse Web Site
- Browse Community Messages
- Post Community Message
- Manage Community Membership
- Update Application
- About Application

You can get to this screen using any of the following methods:

- From your braille device via global action #5. See [Global Actions]
  for details.

- From your braille device via Space + Dots12345678.

- Via `Settings` -> `Accessibility` -> `BRLTTY` -> `Settings`.

- From the notifications shade. Open it by dragging the status bar
  downward:

  - With two fingers (if Explore by Touch is active).
  - With one finger (if Explore by Touch isn't active).

  Then find BRLTTY's service notification and tap it.

- Via the Accessibility button on the system navigation bar. This
  capability was introduced in Android 8.0 (Oreo). The button may not be
  visible for a number of reasons, for example:

  - The device's system navigation bar isn't rendered via software.
  - An application has chosen to hide the system navigation bar.

### Customized Data Files ###

You can customize any of BRLTTY's data files, e.g. a text, contraction,
or key table or subtable. To do this, add a file with the same name
directly into a folder named `brltty` at the top-level of your Android
device's primary shared/external storage area. This area might be
internal (on the device itself) or external (on a removable storage
device, e.g. an SD card). Normally, it's the area that `/sdcard` is
symbolically linked to.

BRLTTY won't be aware of your customized data files if this area has
been mounted by a computer.

It's safe to include the original data file from your customized copy.
If you're only adding lines, therefore, then your customized copy need
only contain those additions and the include statement.

## Navigating the Screen ##

### Using Multiple Hosts ###

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.

### Accessibility Focus ###

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 input area. If that area has input focus then the
cursor is placed at the location within it where input will be inserted.

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.

### The Cursor Routing Keys ###

The cursor routing keys of your braille device perform their usual
function when within an 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.  Bring accessibility focus (cursor)
2.  tap (click)
3.  hold (long click)
4.  scroll backward (up or left)
5.  scroll forward (down or right)
6.  context click
7.  accessibility actions

A range control (progress bar, volume slider, etc) can be adjusted
up/down via the scroll forward/backward actions.

### Input Areas ###

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

### Widget Representations ###

#### Check Boxes ####

A check box is rendered as a three-cell symbol:

1.  dots 123478 (the left side of the box)
2.  dots 2356 (the check mark)
3.  dots 145678 (the right side of the box)

The check mark is present if the box is checked and absent if it isn't.
If the check box has a label then it appears to the right of the symbol.
The braille representations are:

- ⣏⠶⣹ checked
- ⣏ ⣹ not checked

#### Radio Buttons ####

A radio button is rendered as a three-cell symbol:

1.  dots 2348 (the left side of the button)
2.  dots 2356 (the check mark)
3.  dots 1567 (the right side of the button)

The check mark shows which of the radio buttons is currently selected.
The label for each radio button appears to the right of its symbol. The
braille representations are:

- ⢎⠶⡱ selected
- ⢎ ⡱ not selected

#### Switches ####

A (two-position) switch is rendered as a three-cell symbol:

1.  dots 4568 (the left side of the switch)
2.  dots 1478 (the top and bottom of the switch)
3.  dots 1237 (the right side of the switch)

Dots 25 are added to the middle cell if the switch is on, and dots 36
are added to the middle cell if the switch is off. In other words, the
switch is up when on and down when off. The label for the switch's
current state appears to the right of the symbol. The braille
representations are:

- ⢸⣛⡇ on
- ⢸⣭⡇ off

#### Range Controls ####

A range control is one which can be adjusted (rather than set or
edited). They include widgets like progress bars, volume sliders, etc.
They're rendered as a three-value summary:

    <```
    * An at sign followed by the current setting.
    * The minimum and maximum settings, separated by a dash, within parentheses.
    ```>

The developer of an application can choose which value range a given
control uses. For example, a 16-position volume control currently set to
75% might look like this:

    <```
    @11 (0 - 15)
    ```>

It could, however, also look like this:

    <```
    @75% (0% - 100%)
    ```>

#### Disabled Controls ####

If a control is currently disabled then the word `disabled`, enclosed
within parentheses, appears to the right of its label. For example:

    <```
    Connect (disabled)
    ```>

#### When There's No Text ####

A screen element that has no text of its own, and that BRLTTY doesn't
explicitly support, is normally not rendered. Examples of these include:

- A graphic (e.g. an image view).
- A container used to construct the screen's layout (e.g. a frame
  layout).

It's still necessary to render it, however, if it implements an action
(e.g. a tap) which the user needs to be able to perform.

If the application's developer has provided descriptive text then that
text is rendered. If not, then BRLTTY renders a generic description
within (parentheses). It contains the widget's type, and, if available,
its source code identifier.

### Global Actions ###

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 the global actions.
  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.
- If your braille device has a braille keyboard then you can perform the
  global actions via chords that also include dots 7 and 8. For example,
  Space + Dots78 + Dots125 (h) goes to the home screen.

  -------- ---------- ----------------------------------- -------------------
  FN-Key   Chord78+   Action                              As of Android
                                                          Release

  `F1`     125 (h)    go to the Home screen               4.1 (Jelly Bean)

  `F2`     12 (b)     tap the Back button                 4.1 (Jelly Bean)

  `F3`     1345 (n)   go to the Notifications screen      4.1 (Jelly Bean)

  `F4`     1235 (r)   tap the Recent Apps (Overview)      4.1 (Jelly Bean)
                      button                              

  `F5`     123456     go to BRLTTY's [Actions screen]     *

  `F6`     23         move to the first item              *

  `F7`     2          move to the previous item           *

  `F8`     5          move to the next item               *

  `F9`     56         move to the last item               *

  `F10`    134 (m)    tap the Menu button                 *

  `F11`    36         return to the active window         4.0 (Kitkat)

  `F12`    3          switch to the previous window       4.0 (Kitkat)

  `F13`    6          switch to the next window           4.0 (Kitkat)

  `F14`    2345 (t)   show the window title               6.0 (Nougat)

  `F15`    24 (i)     show various device status          *
                      indicators                          

  `F16`    234 (s)    go to the Quick Settings screen     4.2 (Jelly Bean
                                                          MR1)

  `F17`    135 (o)    go to the Device Options screen     5.0 (Lollipop)
  -------- ---------- ----------------------------------- -------------------

  : Global Android Actions

### Text Selection and the Clipboard ###

As with the [global actions], if your braille device has a braille
keyboard then you can perform text selection actions via chords that
also include dots 7 and 8. For example, Space + Dots78 + Dots14 (c)
copies the selected text to Android's clipboard. This works as of
Android release 4.3 (Jelly Bean MR2).

  ------------ ----------------------------------------------------------
  Chord78+     Action

  1 (a)        select all of the text

  4            clear the text selection

  14 (c)       copy the selected text to the clipboard

  1236 (v)     paste the text on the clipboard

  1346 (x)     cut the selected text to the clipboard
  ------------ ----------------------------------------------------------

  : Text Selection and Clipboard Actions

The text selection extends inclusively from its first endpoint through
its second one. The attribute underlining feature (see the Show
Attributes preference) is used to show which text has currently been
selected. It may be helpful to set the attribute underline to blink if
the cursor isn't set to blink, and vice versa.

In addition to being able to select all of the text, there are ways to
select a specific portion of the text. Exactly how this is done depends
on which braille device you're using. There is, however, one way to do
it that works on any braille device that has cursor routing keys.

The cursor routing key where the cursor is normally doesn't serve any
useful purpose. If, however, you enable the Start Text Selection
preference (which can be found within the Navigation Options submenu),
then it enters [text selection mode] with that character being both the
first and second endpoints. This method has the constraint that the
first endpoint of the text selection must be a character that the cursor
can get to.

When in text selection mode, pressing a cursor routing key changes the
second endpoint of the selection. This may be done any number of times.
The second endpoint may be either after or before the first one.

#### Commands ####

HOST_COPY
    Copy the selected text to the host clipboard and then deselect it.

HOST_CUT
    Copy the selected text to the host clipboard and then delete it.

HOST_PASTE
    Insert the text on the host clipboard after the screen cursor.

TXTSEL_ALL
    Select all of the text.

TXTSEL_CLEAR
    Clear (deselect) the current text selection.

TXTSEL_SET
    Select a specific portion of the text. This command requires that
    both endpoints of the text are within the current braille window.
    The key combination needs two cursor routing (or equivalent) keys.
    We recommend a long press of two cursor routing keys (if the braille
    device supports it).

TXTSEL_START
    Enter [text selection mode] with that character being both
    endpoints. With this method, the first endpoint of the text
    selection can be anywhere, i.e. it isn't constrained to be a
    character that the cursor can get to. The key combination needs a
    cursor routing (or equivalent) key. We recommend a long press of a
    cursor routing key (if the braille device supports it).

### Web Pages ###

#### Element Annotations ####

A number of elements within a web page are annotated in order to help
distinguish them from the surrounding text. Each annotation is placed
immediately before the text of the element that it describes. It
consists of a three-letter tag, optionally followed by descriptive data,
all enclosed within (parentheses). Here are some examples:

  --------------------------- -----------------------------------------------------
  Example                     Meaning

  (btn) Submit                a Submit button

  (lnk                        the target URL of a link
  [https://] {https://}...)   

  (tbl 4x9)                   the start of a table with four columns and nine rows

  (col 2@3)                   the second column of the third row of a table
  --------------------------- -----------------------------------------------------

  : Web Page Element Annotation Examples

The following table lists all of the annotations:

  ------------ --------------------------------------------- -------------
  Annotation   Meaning                                       Data

  btn          button                                         

  cap          table caption                                  

  col          column in table row                           coordinates

  frm          start of form                                  

  hdg          heading (unspecified level)                    

  hd1          level one heading                              

  hd2          level two heading                              

  hd3          level three heading                            

  hd4          level four heading                             

  hd5          level five heading                             

  hd6          level six heading                              

  hdr          header of table column                        coordinates

  lnk          target of link                                URL

  lsi          list item                                     coordinates

  lsm          list marker                                    

  lst          start of list                                 dimensions

  pop          combo box (single or Multiple choice)          

  pwd          password field                                 

  row          start of table row                             

  tbl          start of table                                dimensions

  txt          text field or area                             

  --------     horizontal divider                             
  ------------ --------------------------------------------- -------------

  : Web Page Element Annotations

#### Structural Navigation ####

Pressing Dots2578 enters Structural navigation mode. When in this mode,
a web page, when being browsed with Chrome, can be structurally
navigated by pressing dot combinations on your braille device. Press
Dots78 (without Space) to return to the default key bindings.

When in this mode, combinations of dots 1 through 6 specify the type of
element that you'd like to navigate to. Adding dot 7 means move to the
previous element of that type, and adding dot 8 means move to the next
element of that type. If neither dot 7 nor dot 8 is added then the
current direction is used.

The current direction defaults to (starts out as) `next`. Pressing dot 7
by itself sets it to `previous`, and pressing dot 8 by itself sets it to
`next`.

If the key table for your braille device defines a key to be the Left
Alt (meta) modifier then you don't need to switch to/from structural
navigation mode. Just hold that key while pressing the desired
structural navigation dot combination.

The following element types are supported (where possible, a hopefully
easy-to-remember character has been chosen):

  --------- ------ --------------------------------------------------------
  Dots      Char   Go to the Previous/Next

  1         a      article

  12        b      button

  14        c      control

  145       d      ARIA landmark

  15        e      editable text

  124       f      focusable item

  1245      g      graphic

  125       h      heading (any level)

  24        i      list item

  123       l      link (visited or unvisited)

  134       m      media

  135       o      list (ordered or unordered)

  1235      r      radio button

  234       s      section

  2345      t      table

  136       u      unvisited link

  1236      v      visited link

  1346      x      check box

  1356      z      combo box (single or multiple choice)

  2         1      level one heading

  23        2      level two heading

  25        3      level three heading

  256       4      level four heading

  26        5      level five heading

  235       6      level six heading
  --------- ------ --------------------------------------------------------

  : Structurally Navigable Web Page Elements

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

# Installing BRLTTY #

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 can be installed via Google Play. You can either search for it by
name or go directly to [BRLTTY on Google
Play] {https://play.google.com/store/apps/details?id=org.a11y.brltty.android}.

## Required Permissions ##

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

`BIND_ACCESSIBILITY_SERVICE`

    - For inspecting the layout and content of the screen.

`BIND_INPUT_METHOD`

    - For Android to accept input via BRLTTY from your braille device's
      keyboard.

`FOREGROUND_SERVICE`

    - To prevent Android from pausing, killing, etc BRLTTY if there's a
      resource shortage.

`WAKE_LOCK`

    - For resetting the Android device's lock timer each time you
      interact with a control on your braille device.

`BLUETOOTH`

    - For communicating with a braille device via Bluetooth (API level
      <= 30).

`BLUETOOTH_CONNECT`

    - For connecting to an already-paried Bluetooth device (API level >
      30).

`BLUETOOTH_SCAN`

    - For checking if Bluetooth device discovery is currently active
      (API level > 30).

`INTERNET`

    - For listening on a TCP/IP port for BrlAPI client connection
      requests.

`READ_EXTERNAL_STORAGE`

    - For reading customized data files from your Android device's
      primary shared/external storage area.

`SYSTEM_ALERT_WINDOW`

    - For presenting the Accessibility Actions chooser.

`RECEIVE_BOOT_COMPLETED`

    - For knowing when locked storage can be accessed after a reboot.

`REQUEST_INSTALL_PACKAGES`

    - For sideloading an upgrade (debug version only).

`ACCESS_WIFI_STATE`

    - For getting Wi-Fi status values (for the INDICATORS command).

`ACCESS_FINE_LOCATION`

    - For getting the Wi-Fi SSID (for the INDICATORS command).
    - For getting cell information (for the INDICATORS command).

`ACCESS_COARSE_UPDATES`

    - For getting the cell signal strength (for the INDICATORS command).

`READ_PHONE_STATE`

    - For getting the cell data network type (for the INDICATORS
      command).

## The Old Way ##

Before it was on Google Play, BRLTTY had to be installed and updated
manually. For now, this way still works.

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.

### On Your Computer ###

1.  Go to [BRLTTY's web site] {https://brltty.app/}.
2.  Find the `Download` link and press Enter on it.
3.  Go to the `Android` section, 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.

### On Your Android Device ###

1.  Go into `Settings` -> `Security`, and ensure that `Unknown Sources`
    is enabled. 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 its installation, and
    answer any prompts. If you use the Dropbox method, you might need to
    tap on the file twice - once to download it, and a second time to
    install it.

4.  Tap `OK` when installation is complete.

# Building BRLTTY #

## Preparing Your Host Environment ##

BRLTTY is currently being built using:

- Version 29.0.3 of the Android SDK build tools.
- Version r21e (21.4.7075529) of the Android NDK.
- Version 1.7 of OpenJDK.

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] {https://developer.android.com/sdk/index.html}.

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] {https://developer.android.com/tools/sdk/ndk/index.html}.

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 vendors. 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 (or glibc)
- libz (or zlib)
- libstdc++6 (or libstdc++)
- 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 specifics 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` application, 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 Number` 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 check box 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` check box
(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 (rather 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 application is:

    <```
    adb uninstall application.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
    ```>
