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 (need notes on automatically starting brltty):

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

NOTE: The /dev/term/0 portion will differ depending upon whether you're using a serial device, a USB device, or a USB-to-serial dongle. The /dev/term/0 portion was based upon using a USB-to-serial dongle. If you use a USB device, you might want to try -d usb: instead of -d /dev/term/0.

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

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.

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.