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.

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.

This is a one-time step. Once the box has been checked, it stays checked.

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.

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.

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

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 can't even be found within the applications 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 "Services" section
that 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" for turning BRLTTY on and off. The other 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.

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.

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.

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.

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.

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 labeled
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 labeled Set up input methods. This screen contains a check box for
each installed input method. Check the box labeled 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.

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
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 of the 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:

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:

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:

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.

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.

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.

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

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.

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.

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