Skip to content

Latest commit

 

History

History
230 lines (152 loc) · 7.06 KB

brltty.md

File metadata and controls

230 lines (152 loc) · 7.06 KB
Raw

BRLTTY in Chrome OS

Chrome OS uses the open-source BRLTTY library to provide support for refreshable braille displays.

We typically ship with a stable release build of BRLTTY plus some permanent or cherry-picked patches.

Updating BRLTTY or adding a patch

First, follow the public Chromium OS Developer Guide to check out the source. At a minimum you'll need to create a chroot. You do not need to build everything from source. You do need to start the devserver.

Next, flash your device to a very recent test build. Internally at Google you can do this with the following command when the dev server is running, where CHROMEBOOK_IP_ADDRESS is the IP address of your Chromebook already in developer mode, and $BOARD is your Chromebook's board name.

cros flash ssh://CHROMEBOOK_IP_ADDRESS xbuddy://remote/$BOARD/latest-dev/test

The BRLTTY files can be found in this directory:

third_party/chromiumos-overlay/app-accessibility/brltty

###Major release

You'll first want to rename all files to the new major release. For example, brltty-5.6.ebuild and remove all revision symlinks (see below).

###Revision release

A revision release is the same release build of brltty, but with additional patches.

The first thing you'll need to do is edit the ebuild symlink to change the revision number. The real file is something like brltty-5.4.ebuild, but the revision will be something like brltty-5.4-r5.ebuild. You'll need to increment it.

To increment it from r5 to r6, you'd do something like this:

rm brltty-5.4-r5.ebuild
ln -s brltty-5.4.ebuild brltty-5.4-r6.ebuild
git add brltty-5.4-r6.ebuild

The changes we make are all patches against a stable release of brltty. To add a new patch, put it in the files/ directory and reference it in brltty.bashrc

Once you're done adding patches or making other changes, flash it to your device like this:

emerge-$BOARD brltty
cros deploy CHROMEBOOK_IP_ADDRESS brltty

After that, reboot your Chromebook and verify that brltty works.

To upload a change, use repo, something like this:

repo start <branch_name> .
git commit -a
  Bug: chromium:12345
  Test: Write what you tested here
repo upload .

Note that you shouldn't need to run cros_workon.

Uprevving Brltty

This section outlines the process to upgrade Brltty to a major release.

Prerequisites

First, download the latest brltty release tarball http://mielke.cc/brltty/archive E.g. brltty-5.6.tar.gz

The server holding all Chrome OS source packages is Google Cloud Storage. In order to update Brltty, you will need to first get started with GCS. Google-internal only

If you follow the alternative cli workflow, you should have the ability to list the Chrome OS GCS bucket:

gsutil ls gs://chromeos-localmirror/

for example: gs://chromeos-localmirror/distfiles/brltty-5.6.tar.gz is the latest release as of writing.

It will also be handy to checkout brltty.

Git clone http://github.com/brltty/brltty

And follow the instructions in the readme to configure/build.

Upload the latest stable release of brltty.

You can do this via gsutil cp.

After copying, you will likely want the package to be world readable:

gsutil acl ch -u AllUsers:R gs://chromeos-localmirror/distfiles/brltty-5.6.tar.gz

Upreving

Next, you will need to uprev the ebuild. Do this by renaming all files from the previous version to the new one. E.g. Brltty-5.4.ebuild -> brltty-5.6.ebuild

Start a build with your changes by doing

emerge brltty (or emerge{$BOARD} brltty).

Note: Manifest has various checksums computed based on the release you uploaded to GCS. Each of these will need to be replaced/updated.

This should be enough to kick off a build. It is likely patches won’t apply cleanly. Apply patches It is often much easier to apply patches to your local checkout of brltty from github, an build there.

git tags

Will ensure you find the right release. You can then checkout that release via

Git checkout tags/<tag_name>

Finally apply each of the *.patch files to this tag of brltty.

This is more or less straightforward. If conflicts arise, it is useful to list commits to the file containing the conflict

git log --oneline <file>

then understanding the history since the last release. If the patch is already upstreamed, you can remove it from the Chrome OS repo.

Chrome side changes

Chrome communicates with brltty using libbrlapi. libbrlapi resides at //third_party/libbrlapi.

Chrome loads this library dynamically and hard-codes the expected version of the api so in chrome/browser/extensions/api/braille_display_private/braille_controller_brlapi.cc

which should match up with the header in third_party/libbrlapi/brlapi.h.

During uppreving, if brltty increments its api version, it will be necessary to update the header for libbrlapi, as well as incrementing the supported api version of the libbrlapi shared object.

First, grab the generated header from your Chrome OS build above. cp /build/$BOARD/usr/include/brlapi.h <chrome_root>/third_party/libbrlapi/brlapi.h

This header contains the specific socket path for Chrome OS which differs from brltty defaults.

Next, ensure the version in chrome/browser/extensions/api/braille_display_private/braille_controller_brlapi.cc

matches the one in the new brltty.

ChromeVox

ChromeVox keeps a list of bluetooth braille display names (search for bluetooth_display_manager.js).

Within the brltty sources (as of 6.3), one can find all bluetooth display names in: brltty/Programs/bluetooth_names.c

Testing

Firstly, try to test against brltty on linux. This involves building brltty at the proposed stable release and fully patching all of our changes from Chrome OS.

You would do something like:

./autogen
./configure
make
./run-brltty -n

This will launch brltty (in the foreground and not as a daemon).

Any connected displays should automatically work.

Next, once you have a build deployed on a Chrome OS machine, here are a few useful things to check:

  • Routing keys within a text field
  • Routing keys on a link
  • Basic braille output
  • Chorded commands (e.g. space + s to toggle speech)
  • Typing (e.g. dots 1-2-3 within a text field)
  • Display specific hardware keys
  • Unload ChromeVox (ctrl+alt+z), plug in a display; ChromeVox should auto start

Try to test with at least two displays. ###Debugging

In the event things don't go well (such as no braille appearing on the display), you may find it helpful to:

  1. examine chrome logging

/var/log/chrome

Look for any errors in brl related files. For example, a new release of libbrlapi could require additional so versions be added to our loader.

  1. modify the way in which brltty gets run.

In particular, look at the invocation of the minijail in

third_party/chromiumos-overlay/app-accessibility/brltty/files/brltty

You may want to add the '-l debug' flag to the brltty call and redirect stderr/stdout to a file. ... brltty -n ... -l debug,server,usb,brldrv ... > /tmp/brltty_errors 2>&1