Previous Next Table of Contents

1. Introduction

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.

1.1 Brief History

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 has been released during summer 1998.

Version 2.1 is about to be released (March 1999). This new version adds support for Ecobraille (thanks to Oscar Fernandez), Alva Delphi (thanks to Terry Barnaby) and BrailleLite 18 (from Nikhil Nair). Some small improvements and fixes.

See section Support for contact details of the BRLTTY team.

1.2 System Requirements

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.

1.3 Initial Installation and Testing

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
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 (/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
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:

txt2hlp

This produces files in the format needed for the help function from standard ASCII files. txt2hlp is compiled and used automatically during installation.

txt2tbl

This program can be used to generate new Braille translation tables from ASCII files. See section Table Utilities for instructions.

tbl2txt

This program is the inverse of txt2tbl. It can be used if you are not sure of what a particular dot combination represents.

1.4 Installation for Day-to-day Use

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.


Previous Next Table of Contents