BRLTTY on Android

Contents

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.

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.

  1. 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.
  2. 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

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.

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.

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