BRLTTY - Guidelines for Linux Distributions

Guidelines for Linux Distributions

Installing with Braille
The bp2cf Script
System Startup
Specifying Options
Required Devices
The Boot Prompt

Installing with Braille

Requesting that braille be activated during the install procedure, which, of course, must be done at a time when BRLTTY has not yet been started, should be easy so that a blind person can do it on his own with a low probability of error. It should, therefore, only involve the typing of a minimal number of common characters. A single boot parameter with a series of comma-separated operands is ideal.

parameter=operand,...

We recommend:

brltty=driver,device,table

This maps to the following command line invocation:

/bin/brltty -bdriver -ddevice -ttable

It also maps to the following set of /etc/brltty.conf directives:

braille-driver driver
braille-device device
text-table table

driver

The driver for the type of braille display being used. It may be specified as either a two-letter driver identification code (see the file /etc/brltty.conf) or the word auto.

brltty=al
brltty=auto

The default is to attempt to auto-detect which type of braille display is connected to the specified device. Some types, especially older ones, cannot be auto-detected.

device

The device to which the braille display is connected. It may be specified as either an absolute path or a relative path (anchored at /dev).

brltty=,/dev/ttyS0
brltty=,ttyS0

If devfs is being used:

brltty=,/dev/tts/0
brltty=,tts/0

The default device is the first serial port, i.e. /dev/ttyS0 (/dev/tts/0 if using devfs).

table

The braille translation table for the language being used. It may be specified as either an absolute path or a relative path (anchored at /etc/brltty). The complete set of provided tables is the set of files whose names match the pattern text.*.tbl in the directory /etc/brltty. The .tbl extension may be omitted. If a simple file name is specified then the text. prefix may be omitted.

brltty=,,text.us.tbl
brltty=,,it.tbl
brltty=,,text.es
brltty=,,da
brltty=,,/etc/brltty/text.fr.tbl
brltty=,,/etc/brltty/text.uk

The default language translation table is for the NABCC (North American Braille Computer Code).

All operands are optional. Trailing commas may be omitted.

brltty=pm,/dev/ttyS0,text.de.tbl: Papenmeier on first serial port with German table.
brltty=bl,/dev/tts/1,text.da.tbl: BrailleLite on second devfs serial port with Danish table.
brltty=al,ttyS0,es: Alva on first serial port with Spanish table.
brltty=eu,tts/0: EuroBraille on first devfs serial port with default table.
brltty=bn,,fr: BrailleNote on first serial port with French table.

If the brltty= boot parameter is supplied then the installer should:

Automatically start BRLTTY as soon as possible.
Automatically include BRLTTY in the set of packages selected for installation.

Installing the BRLTTY package should automatically generate a BRLTTY configuration file (/etc/brltty.conf) which corresponds to the specified boot operands. See the bp2cf script for one way to do this. The mapping from boot operand to configuration file directive is as follows:

driver: braille-driver
device: braille-device
table: text-table

BRLTTY (as of release 3.2) looks for and interprets the brltty= boot parameter as described above. It looks in /proc/cmdline if it exists (the /proc file system has already been mounted), and in the brltty environment variable if it doesn't. The boot parameter is given a lower precedence than the command line but a higher precedence than the configuration file.

BRLTTY relies on a number of devices. These must be defined within the installer's root file system and support for them must be configured into the installer's kernel.

If the braille display is connected to a serial port then the installer should not probe that port when autodetecting hardware. This is because port probing byte sequences can render a braille display useless by interfering with its protocol. The simplest solution to this problem is to do no serial port probing at all. A better, but more complex, solution would be to analyze BRLTTY's boot parameter and to exclude the specified device from any port probing which needs to be done. Another alternative might be to not probe any device which is already in use.

Braille users usually use a feature known as cursor tracking. This feature causes the braille display (which typically only presents part of a single line from the screen) to follow the cursor, i.e. whenever the cursor moves the braille display automatically jumps to the cursor's new position. Distributions should carefully review each of their installer screens to ensure that the cursor (not just catchy highlighting) is always being placed at an appropriate location. Examples of good cursor placement include:

The first new character in a text entry area.
The first character of the active selection in a menu.

Since good braille support hasn't been developed yet for graphics mode, there should be an easy way for the user to inform the installer (ideally, the mere presence of the brltty= boot parameter) that it should only use text mode. Graphically-oriented screens based on curses, slang, etc. are okay as long as the console itself remains in text mode. It may mean, however, that X should not be configured. It definitely means that X should not be used. The installed system, also, should not be configured to come up in X unless the user has specifically requested it.

The bp2cf Script

The bp2cf (boot parameter to configuration file) script in BRLTTY's Bootdisks subdirectory converts BRLTTY's current boot parameter into configuration file directives. If the special file /proc/cmdline exists then the brltty= boot parameter specified therein is used. If it doesn't exist then the brltty environment variable is used. If BRLTTY's boot parameter hasn't been specified then this script doesn't do anything.

This script accepts the following options:

-f file: Specify the path (relative or absolute) of the configuration file to be created/updated. If this option isn't supplied then this script functions as a filter, i.e. input is read from standard input and output is written to standard output.
-c: Create the configuration file (no input is read). The created configuration file contains only those directives for which a boot operand has been specified.
-u: Update the configuration file. Only those directives already in the configuration file for which a boot operand has been specified are updated. Each such directive is uncommented if necessary.
-n: Do not do any device path translation.
-d: Translate from old-style to devfs device paths.
-o: Translate from devfs to old-style device paths.
-p parameter: Explicitly specify the boot parameter. While there may be more imaginative uses for this option, it's main purpose is to make it easy to test the script.
-h: Display a command line usage summary and then exit.

The -c and -u options are mutually exclusive; the default is -c. The -n, -d and -o options are mutually exclusive; the default is -n. No other options have default values. The default function of this script, therefore, is to write to standard output those configuration directives which correspond to each specified boot operand.

We recommend that distributions use this script within their BRLTTY package's installation processing in order to automatically preconfigure BRLTTY during system installation. The bp2cf script which comes with the release of BRLTTY being packaged should be used. Copying portions of the script, rather than the whole script, into the package definition is a bad idea since:

It's an error prone practice.
The internal structure of the script may change significantly from release to release.
Fixes and enhancements can easily get missed.

Including the whole script is problematic for packages like rpms wherein special package installation code can only be added via scriptlets contained within a larger package definition file. The main problem is that the exit within bp2cf causes the installation scriptlet to terminate prematurely. Here, to stimulate your imagination and inventiveness, is how we do it for BRLTTY's rpm (as of release 3.3).

%pre
# The pre-install scriptlet.

# If a configuration file already exists then rpm installs the new one as
# <path>.rpmnew. If this is done then the .rpmnew file is overwritten if it
# already exists.

# There's no explicit way to tell if a configuration file has been installed
# as itself or as a .rpmnew file. The way we'll figure it out, therefore, is by
# erasing the .rpmnew file now so that we can see if it gets created later. 
rm -f /etc/brltty.conf.rpmnew

%post
# The post-install scriptlet.

# If BRLTTY's boot parameter has been specified then update the just installed
# configuration file template to reflect the options supplied thereby.

# First, we need to determine which file to update. If there's a .rpmnew file
# then update it since a previous configuration file must already have existed.
file=/etc/brltty.conf
new=$file.rpmnew
[ -f $new ] && file=$new

# Update the configuration file template via the Bootdisks/bp2cf script.
# Include it right within this scriptlet so that it needn't be installed.
# Imbed it within a subshell to ensure that it won't impact this scriptlet.
(
   # First, set bp2cf's command line arguments.
   set -- -u -f $file

   # Now run it by simply imbedding it right here.
)

System Startup

BRLTTY should be started as early as possible so that a blind user can handle system startup problems without requiring sighted assistance. Most distributions have a special initialization script which is run before the general package start sequence is performed. This script would be a good place wherein to start BRLTTY. Code like the following should be inserted into it:

# If a braille display is being used then start it now.
[ -x /bin/brltty ] && /bin/brltty

Note that BRLTTY, by default, puts itself into the background so there's no need to explicitly do this in the script.

The most common problems which occur during system startup tend to be those related to the lack of file system integrity. BRLTTY should be started, therefore, before the fscks are done.

BRLTTY relies on a number of devices. Distributions which use devfs should not start BRLTTY until after devfs has been activated.

Distributions which fork the initial system startup script, e.g. via initlog, should not start BRLTTY until after this fork has been done.

Braille displays can become confused by port probing byte sequences. System hardware detection/configuration packages like kudzu are known to cause problems in this area. One solution is to start BRLTTY only after all such port probing has been completed. This approach is usually inadequate, though, because it tends to impair the ability of a blind person to handle early system startup problems (see fsck paragraph above). Since most braille displays use a serial port connection, a better approach may be to disable serial port probing. For kudzu, this would mean using its --safe option.

If BRLTTY can safely be started before any other system initialization is performed, then it can be started by inserting the following lines into /etc/inittab.

# Start the braille display.
brl::sysinit:/bin/brltty

These lines should be placed before any other sysinit lines.

BRLTTY (as of release 3.1) provides a mechanism whereby it can be started as soon as the kernel is up and before any other system activity takes place. The trick is for the kernel to start brltty instead of init, and for brltty to then start init. To set this up, do:

Move the real init to a new location.
Configure BRLTTY to know init's new location.
Build BRLTTY and install it in init's original location.

The following command sequence illustrates how to do this:

cd brltty-release
./configure --with-init-path=/sbin/real_init
make
mv /sbin/init /sbin/real_init
cp Programs/brltty /sbin/init

Specifying Options

BRLTTY collects its options from a number of places. In descending order of precedence, these places are:

The command line.
The boot prompt (brltty=).
Environment variables (BRLTTY_...).
The configuration file (/etc/brltty.conf).

Options should be specified in the configuration file if at all possible. All the other methods are just to make BRLTTY as flexible as possible. Do NOT use command line options within a system startup script as they cannot be overridden in an emergency via the boot prompt.

BRLTTY (as of release 3.2) supports the guidelines for installers which are outlined within this document. If the special file /proc/cmdline exists (the /proc file system has already been mounted) then the boot options (the operands of the brltty= boot parameter) are retrieved from there. If not, then the value of the brltty environment variable is used. This means that options can be specified within boot manager configuration files (lilo.conf, grub.conf). This feature is very useful for rescue disks, installation CDs, system emergencies, etc. It should be avoided, however, for standard installations.

If you start BRLTTY manually from the command line and aren't sure where certain options are being specified, then, in this order, try:

grep brltty /proc/cmdline
echo $brltty
env | grep "^BRLTTY_"
grep -v "^ *#" /etc/brltty.conf

Required Devices

BRLTTY relies on the following devices:

Reason	Name	DevFS	Type	Major	Minor
Screen Content Inspection	vcsa	vcc/a	Char	7	128
General Console Operations	console	console	Char	5	1
Virtual Console Operations	tty0	vc/0	Char	4	0
Braille Display Operations	ttyS0	tts/0	Char	4	64

The last device (Braille Display Operations) should really be the set of possible devices to which the braille display might be connected. It is shown here as being the first serial port since most braille displays do use a serial connection. Some, however, can use a parallel and/or USB connection.

The Boot Prompt

Since BRLTTY runs as a background process, it can only be started after the kernel has been loaded. This means that the braille display isn't yet working during the boot manager (lilo, grub) prompt. A blind user, therefore, would be helped a great deal if the boot manager were configured to sound a console beep when it issues its first prompt.