Using Braille with Orca: BrlTTY

Orca uses BrlTTY for braille support. Orca does not automatically start BrlTTY for you -- you typically need to do that yourself, and it is something that is usually done at boot time. Start-up options are described in the BRTLTTY reference manual. A list of supported braille devices can be found here.

Orca currently works best with BrlTTY v3.8 or better. It works well with BrlTTY v3.7.2, but we're considering dropping support for it. So, if you can move to BrlTTY v3.8 or better, we'll be happier because we will have less code to maintain.

To get Orca working with BrlTTY v3.8 requires that the Python bindings for BrlAPI are built/installed as part of the BrlTTY build/install process. Below are descriptions of the necessary tasks to do this for Ubuntu and Solaris. For both, you need to first obtain brltty-3.8.tar.gz from the BrlTTY site.

Running BrlTTY on Ubuntu

Run BrlTTY as root (need notes on automatically starting brltty):

/bin/brltty -bauto -d/dev/ttyUSB0

Running BrlTTY on Solaris

Run BrlTTY as root

pfexec brltty -d usb:,serial:/dev/term/0 -bauto -xno -p none -A auth=none -n

NOTE: The /dev/term/0 portion was based upon using a USB-to-serial dongle and watching the contents of /dev/term as the dongle was plugged in.

If you are using OpenSolaris and want to have BrlTTY automatically start when you boot your machine, you can use the attached SMF manifest file: brltty.xml. To do so, save brltty.xml to /var/svc/manifest/application/brltty.xml:

pfexec cp brltty.xml /var/svc/manifest/application/

Then, run the following commands. Once you run these commands, brltty should start, and it should also start when you reboot your machine. Note that this configuration does not auto-detect when you plug or unplug your braille device. You need to make sure your braille device is connected and turned on before running these commands and when booting your machine.

svccfg import /var/svc/manifest/application/brltty.xml
svcadm enable brltty

You can check the status of the service by running the following command, which is shown with sample output:

wwalker@osolaptop:~$ svcs -lp brltty
fmri         svc:/application/brltty:default
name         BrlTTY/BrlAPI braille display driver
enabled      true
state        online
next_state   none
state_time   Mon Apr 27 21:07:50 2009
logfile      /var/svc/log/application-brltty:default.log
restarter    svc:/system/svc/restarter:default
contract_id  112 
dependency   require_all/none svc:/system/filesystem/local (online)
process      12890 brltty -d /dev/term/0 -bauto -xno -p none -A auth=none

The service has two options you can configure, options/braille-device which corresponds to the --braille-device option of the brltty command (the default value is usb:,serial:/dev/term/0, which means to probe the USB ports first then /dev/term/0 for a braille device), and options/braille-driver which corresponds to the --braille-driver option of the brltty command (the default value is auto). To set these options, use the svccfg option. An example that sets the braille driver to a Baum display, bm, is as follows. Setting the driver to a specific value can help brltty start faster.

svcadm disable brltty
svccfg -s brltty setprop options/braille-driver=bm
svcadm refresh brltty
svcadm enable brltty

What If You Don't Have a Braille Display???

So, you want to test, but you don't have a braille display? Well, the Orca braille monitor will tell you what Orca is sending to the display. But, you can also use BrlTTY's X Windows driver, which will allow you to click on cells as though there were cursor routing keys and also invoke BrlTTY input commands. Instead of -bauto, use -bxw. When you do this, a window will appear that emulates the braille display. For example, on OpenSolaris, you might type this command, and you don't need to be root for it to work:

brltty -d /dev/term/0 -bxw -xno -p none -A auth=none -n

Right click on the window for options.

Troubleshooting

The number one problem people have with BrlTTY is that they have built BrlTTY 3.8dev from source, but did not build the Python bindings for BrlAPI. Verify that the Python bindings for BrlAPI are installed. If the following command doesn't produce any errors, you've done things well:

python -c "import brlapi"

If the above produces errors, follow the steps above and take care to read them this time.

/etc/brltty.conf is overwritten

If you are wondering why your /etc/brltty.conf gets overwritten from time to time and you wish it not to be the case: comment out the mv lines and the sed line in /etc/init.d/brltty

so that it looks like this:

if [ -e /dev/.initramfs/brltty.conf ] && [ -e /etc/default/brltty ]; then
        if [ -e /etc/brltty.conf ]; then
                # following line is commented out!
                # mv /etc/brltty.conf /etc/brltty.conf.orig
        fi
        # mv /dev/.initramfs/brltty.conf /etc/brltty.conf
        # sed -i -e 's/^RUN_BRLTTY=.*/RUN_BRLTTY=yes/' /etc/default/brltty
        # above two lines are commented out!
fi

Interestingly enough the file gets overwitten on two of the machines on a regular basis, and on another never at all. Hardware detection issue? Observed on Ubuntu 6.06 onwards.

Contracted Braille for Orca 2.27.3 and earlier: Liblouis 1.5.2

Orca has an option for displaying text in grade 2 braille on a braille display. This page will give instructions how to enable grade 2 support. At this time an external library called liblouis is needed for Orca to support grade 2 braille.

Getting It

Just like any other projects out there. You could get liblouis either as a source package, or directly from the SVN repository for the bleeding edge.

Source Package

Get the latest tarball of liblouis from here.

Source Repository

Besides subversion, you will also need automake 1.9 and autoconf 2.57.

Get and bootstrap the latest liblouis from SVN using the following commands:

svn checkout http://liblouis.googlecode.com/svn/trunk/ liblouis
cd liblouis
./autogen.sh

Building and installing it

Linux

In the liblouis source directory do the following commands:

./configure --prefix=/usr --enable-ucs4
make
make install

Solaris

In the liblouis source directory do the following commands:

./configure --prefix=/usr --disable-ucs4
make
make install

Enabling Liblouis Support in Orca

Follow the instructions in the Orca/DownloadInstall page. Before running "make", do the following:

./configure --enable-liblouis=yes

If something is wrong with your liblouis installation, configure should fail, and thus remove any uncertainty of liblouis being or not being enabled in the Orca build.

Alternative prefixes

If you have a good idea about what you are doing, and have a habit of installing non distro packages in alternative prefixes, you might have ignored the instructions above, and installed liblouis in a different prefix, like "/opt". If this is the case the Orca configure stage will fail. To fix this you must define the alternative pkg-config path before the Orca configure stage.

export PKG_CONFIG_PATH=/opt/lib/pkgconfig

Of course substitute "/opt" with whatever prefix you use.

Contracted Braille for versions of Orca after 2.27.3: Liblouis 1.6.2

Orca has an option for displaying text in grade 2 braille on a braille display. This page will give instructions how to enable grade 2 support. At this time an external library called liblouis is needed for Orca to support grade 2 braille.

Getting It

Just like any other projects out there. You could get liblouis either as a source package, or directly from the SVN repository for the bleeding edge.

Source Package

Get the latest tarball of liblouis from here.

Source Repository

Besides subversion, you will also need automake 1.9 and autoconf 2.57.

Get and bootstrap the latest liblouis from SVN using the following commands:

svn checkout http://liblouis.googlecode.com/svn/trunk/ liblouis
cd liblouis
./autogen.sh

Building and installing it

In the liblouis source directory do the following commands:

./configure --prefix=/usr --enable-ucs4
make
make install
cd python
python setup.py build
python setup.py install

Enabling Liblouis Support in Orca

You should not need to do anything special except rebuild/reinstall Orca after you've built liblouis 1.6.2 and the liblouis 1.6.2 Python bindings. Follow the instructions in the Orca/DownloadInstall page.

Configuring Grade 2 In Orca

If everything went well there should be a checkbox called "Enable Contracted Braille" in the "Braille" page in Orca's preferences. Following the checkbox, there is a combobox with a list of all supported tables.