1# BRLTTY in Chrome OS 2 3Chrome OS uses the open-source [BRLTTY](http://mielke.cc/brltty/) 4library to provide support for refreshable braille displays. 5 6We typically ship with a stable release build of BRLTTY plus some 7permanent or cherry-picked patches. 8 9## Updating BRLTTY or adding a patch 10 11First, follow the public 12[Chromium OS Developer Guide](http://www.chromium.org/chromium-os/developer-guide) to check out the source. 13At a minimum you'll need to create a chroot. 14You do not need to build everything from source. 15You do need to start the devserver. 16 17Next, flash your device to a very recent test build. Internally at Google 18you can do this with the following command when the dev server is running, 19where CHROMEBOOK_IP_ADDRESS is the IP address of your Chromebook already 20in developer mode, and $BOARD is your Chromebook's board name. 21 22```cros flash ssh://CHROMEBOOK_IP_ADDRESS xbuddy://remote/$BOARD/latest-dev/test``` 23 24The BRLTTY files can be found in this directory: 25 26```third_party/chromiumos-overlay/app-accessibility/brltty``` 27 28###Major release 29 30You'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). 31 32###Revision release 33 34A revision release is the same release build of brltty, but with additional patches. 35 36The first thing you'll need to do is edit the ebuild symlink to change the 37revision number. The real file is something like brltty-5.4.ebuild, 38but the revision will be something like brltty-5.4-r5.ebuild. You'll need 39to increment it. 40 41To increment it from r5 to r6, you'd do something like this: 42 43``` 44rm brltty-5.4-r5.ebuild 45ln -s brltty-5.4.ebuild brltty-5.4-r6.ebuild 46git add brltty-5.4-r6.ebuild 47``` 48 49The changes we make are all patches against a stable release of brltty. 50To add a new patch, put it in the files/ directory and reference it in 51brltty.bashrc 52 53Once you're done adding patches or making other changes, flash it to your 54device like this: 55 56``` 57emerge-$BOARD brltty 58cros deploy CHROMEBOOK_IP_ADDRESS brltty 59``` 60 61After that, reboot your Chromebook and verify that brltty works. 62 63To upload a change, use repo, something like this: 64 65``` 66repo start <branch_name> . 67git commit -a 68 Bug:chromium:12345 69 Test:Write what you tested here 70repo upload . 71``` 72 73Note that you shouldn't need to run cros_workon. 74 75## Uprevving Brltty 76 77This section outlines the process to upgrade Brltty to a major release. 78 79### Prerequisites 80 81First, download the latest brltty release tarball 82http://mielke.cc/brltty/archive 83E.g. 84brltty-5.6.tar.gz 85 86The server holding all Chrome OS source packages is Google Cloud Storage. In 87order to update Brltty, you will need to first get started with GCS. 88[Google-internal only](https://sites.google.com/a/google.com/chromeos/resources/engineering/releng/localmirror) 89 90If you follow the alternative cli workflow, you should have the ability to 91list the Chrome OS GCS bucket: 92 93```gsutil ls gs://chromeos-localmirror/``` 94 95for example: 96gs://chromeos-localmirror/distfiles/brltty-5.6.tar.gz 97is the latest release as of writing. 98 99It will also be handy to checkout brltty. 100 101```Git clone http://github.com/brltty/brltty``` 102 103And follow the instructions in the readme to configure/build. 104 105### Upload the latest stable release of brltty. 106 107You can do this via ```gsutil cp```. 108 109After copying, you will likely want the package to be world readable: 110 111``` 112gsutil acl ch -u AllUsers:R gs://chromeos-localmirror/distfiles/brltty-5.6.tar.gz 113 114``` 115 116### Upreving 117 118Next, you will need to uprev the ebuild. Do this by renaming all files from the previous version to the new one. 119E.g. 120Brltty-5.4.ebuild -> brltty-5.6.ebuild 121 122Note: Manifest has various checksums computed based on the release you uploaded to GCS. Each of these will need to be replaced/updated. 123 124This should be enough to kick off a build. It is likely patches won’t apply cleanly. 125Apply patches 126It is often much easier to apply patches to your local checkout of brltty from github, an build there. 127 128```git tags``` 129 130Will ensure you find the right release. You can then checkout that release via 131 132```Git checkout tags/<tag_name>``` 133 134Finally apply each of the *.patch files to this tag of brltty. 135 136This is more or less straightforward. If conflicts arise, it is useful to list 137commits to the file containing the conflict 138 139```git log --oneline <file>``` 140 141then understanding the history since the last release. If the patch is already 142upstreamed, you can remove it from the Chrome OS repo. 143 144### Testing 145 146Firstly, try to test against brltty on linux. This involves building brltty at 147the proposed stable release and fully patching all of our changes from Chrome 148OS. 149 150You would do something like: 151 152``` 153./autogen 154./configure 155make 156./run-brltty -n 157``` 158 159This will launch brltty (in the foreground and not as a daemon). 160 161Any connected displays should automatically work. 162 163Next, once you have a build deployed on a Chrome OS machine, here are a few 164useful things to check: 165* Routing keys within a text field 166* Routing keys on a link 167* Basic braille output 168* Chorded commands (e.g. space + s to toggle speech) 169* Typing (e.g. dots 1-2-3 within a text field) 170* Display specific hardware keys 171* Unload ChromeVox (ctrl+alt+z), plug in a display; ChromeVox should auto 172start 173 174Try to test with at least two displays. 175###Debugging 176 177In the event things don't go well (such as no braille appearing on the display), 178you may find it helpful to: 179 1801. examine chrome logging 181 182/var/log/chrome 183 184Look for any errors in *brl* related files. For example, a new release of 185libbrlapi could require additional so versions be added to our loader. 186 1872. modify the way in which brltty gets run. 188 189In particular, look at the invokation of the minijail in 190 191third_party/chromiumos-overlay/app-accessibility/brltty/files/brltty 192 193You may want to add the '-l debug' flag to the brltty call and redirect stderr/stdout to a file. 194... brltty -n ... -l debug,server,usb,brldrv ... > /tmp/brltty_errors 2>&1 195