BRLTTY is intended to provide a Braille user with access to the console of a Unix system. In the past, the only way this could effectively be done was through an appropriate terminal connected to the host. BRLTTY will run a soft Braille display, reproducing a part of the screen image (referred to in this manual as `the window') as Braille dots.
The BRLTTY project started in July 1995, the team then comprising Nikhil Nair and James Bowden. The first version ran with Blazie Engineering's Braille Lite; however, since this is not designed to be a dedicated soft Braille display for a computer, the response time was far too slow. The Braille Lite is no longer supported for this and other reasons.
In September 1995, the second version, 0.22 BETA, became the first to be released publicly. As well as the Braille Lite, it supported Tieman B.V.'s CombiBraille series.
Since then, much has changed. James Bowden is no longer an active developer, although his help in other areas (including documentation) has been well appreciated.
The project has benefited greatly from the efforts of two new members, Nicolas Pitre and Stephane Doyon. Between them, they have brought support for two more brands of Braille displays, as well as many excellent ideas for the system as a whole.
See section Support for contact details of the BRLTTY team.
To date BRLTTY only runs under Linux (both PC and DEC Alpha). Ports to other Unix-like operating systems are not currently planned, but we do welcome any interest in such projects.
This Linux version of BRLTTY uses, apart from the standard serial
driver, the special device introduced in kernel version 1.1.92 which
provides easy access to the contents of the current virtual console.
This is normally called /dev/vcsa
or /dev/vcsa0
(the
name is configurable). For this reason kernel 1.1.92 or later is
required.
BRLTTY only works with text-based applications, so any form of graphics, including the X Window System, will not produce Braille output.
You must also, of course, possess an appropriate soft Braille display. BRLTTY currently works with
We hope that other devices will be supported in the future, so if you have any vaguely technical programming information on a device you would like to see supported, please let us know (see section Support).
Before compiling BRLTTY, you must configure it for your system.
Read through and edit the file Makefile
in the top-level
directory, following the instructions. Then read the README
file
in the directory containing the driver for your Braille display and
check for any further display specific instructions.
Type
make
to compile BRLTTY, the test programs and other small utilities. Then,
as root, type
make install
to install the BRLTTY executable, together with the help
and table files for your Braille display in the correct place. This
also creates /dev/vcsa0
or equivalent if it does not already
exist.
You will have to install BRLTTY before you can use the test programs.
BRLTTY will probably have to run with root privilege. It needs to access the virtual console screen information, the serial port selected and, most awkwardly, the console (this is needed for keystroke simulation during cursor routing, for the cut & paste function and for beeps). If you do manage to get BRLTTY running without being root, please let us know (see section Support).
The programs brltest
and scrtest
can be used as diagnostic
tools if something goes wrong. Both must be run as root.
If you get the error message `brltty: Cannot read screen', try running scrtest. This should read a rectangle from the middle of the screen, and after reporting the screen dimensions and cursor position, print this block to standard output.
If BRLTTY appears to load, but the Braille display doesn't seem to work, try running brltest. This program should print a short message on the display, ask you to hit return, and exit.
The shell script install-brltty
copies a fully-functional,
installed BRLTTY to a new location; this can be used to copy BRLTTY to
or from a rootdisk. For instance, if the rootdisk floppy is mounted
on /mnt
, and BRLTTY is working on the main system, then typing
install-brltty /mnt
copies BRLTTY, with all its data and configuration files, as well as
/dev/vcsa0
or equivalent to the rootdisk.
Usage:
install-brltty dest-prefix [source-prefix]
Note: Some problems have been experienced when moving BRLTTY between systems with different versions of the shared C library. This is worth investigating if you have difficulties.
Also included are several small programs:
This produces files in the format needed for the help function from standard ASCII files. txt2scrn is compiled and used automatically during installation.
This program can be used to generate new Braille translation tables from ASCII files. See section Table Utilities for instructions.
This program is the inverse of txt2tbl. It can be used if you are not sure of what a particular dot combination represents.
BRLTTY, once installed, is invoked by the single command
brltty
. Command line switches allow the default configuration
file name, serial device and Braille translation table to be
overridden---see section
Command Line Options for full details.
However, particularly if it is being used by a system's administrator, it should probably be loaded at boot-time before the filesystems are checked, so that if anything goes wrong during these checks and the system drops into single user mode, the Braille display will still be active.
The way this is done will vary according to the type of system being used. For instance, on a Debian GNU/Linux 0.93R5 system, the following code was inserted near the beginning of /etc/init.d/boot:
if [ -x /sbin/brltty ]
then
/sbin/brltty
fi
This could be abbreviated to the rather less readable form:
[ -x /sbin/brltty ] && /sbin/brltty
(On a Slackware system, the file to edit is /etc/rc.d/rc.S
.)
One possible alternative is to start BRLTTY from /etc/inittab.
Note: A killall5 -15
command would be enough to stop BRLTTY in
its tracks: if such a command is issued from an rc script when
entering single user mode, this may be a problem which needs
attention.