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 was 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.
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 Stéphane Doyon. Between them, they have brought support for Alva and TSI series of Braille displays, as well as many excellent ideas for the system as a whole.
A stable version (1.0) and a few updates were released sometime around the end of 1996.
Since then, support for the Papenmeier brand has been contributed by a team from the Technical High School, Department for electrical engineering, Vienna, Austria. The BRLTTY development team has completed support for TSI displays and added support for the Eurobraille brand. New features have also been added to the system. Regretably, Nikhil Nair has stopped working on the BRLTTY project. Nicolas Pitre assumes the job of maintainer. Version 2.0 will be released during summer 1998.
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.
An experimental patch for running BRLTTY from a program named screen is
available. This would make porting possible to platforms that do not have
Linux's vcsa devices.
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. To clarify, X can be installed but must not run simultaneously with BRLTTY.
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).
Finally, you need tools to build the executable from the sources: make, C and C++ compiler, etc. The tools provided in standard Linux distributions should do the trick. If you have problems, contact us and we will compile a binary for you.
In the past, BRLTTY has been tested on many distributions, including Slackware, Debian and Red Hat. The current version is known to compile on Red Hat 5.0 and 5.1.
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 clean; make
make install
/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 (/dev/vcsa0), the serial
port selected and, most awkwardly, the console (/dev/console), which is
used for keystroke simulation during cursor routing, for the cut & paste
function, for arrow keys simulation using keys on the braille display and for
beeps. Access to the serial port as well as to the vcsa0 device can be
granted to a non-root user by changing the permissions on the divice
files. However, having access to the console device is not enough: you
need to be root to sound beeps and simulate key strokes. So, if you're willing
to give up cursor routing, beeps and all that, you can run BRLTTY without root
priviledges.
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
/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. txt2hlp 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 port 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
If you have installed the Red Hat distribution, modify the file
/etc/rc.d/rc.sysinit.
On a Slackware system, the file to edit is /etc/rc.d/rc.S.
On a SuSE system the above code can be inserted at the top of
/sbin/init.d/boot.
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.