BRLTTY(1) The BRLTTY Project BRLTTY(1)

NAME brltty - refreshable braille display driver for Linux/Unix

SYNOPSIS brltty [option ...]

DESCRIPTION brltty is a background process (daemon) which provides access to the console screen (when in text mode) for a blind person using a refresh- able braille display. It drives the braille display, and provides com- plete screen review functionality. Some speech capability has also been incorporated.

OPTIONS Options can be passed to brltty in a number of ways. From most to least influential, these are:

1. Command Line Options

2. Boot Parameters

3. Environment Variables (if the -E (--environment-variables) option is in effect)

4. The Configuration File

5. Built-in Defaults

Command Line Options The options are processed sequentially from left to right. If an option is specified more than once, or in case of a conflict, the rightmost specification takes precedence.

The following options are supported:

-a table (--attributes-table=) The path to the attributes translation table. Relative paths are anchored at /etc/brltty/. The .atb extension is optional. The built-in default is attributes.atb.

-b driver,...|auto (--braille-driver=) The driver for the braille display (see Driver Specification). The built-in default is auto.

-c table (--contraction-table=) The path to the contraction table. Relative paths are anchored at /etc/brltty/. The .ctb extension is optional.

-d device,... (--braille-device=) The device to which the braille display is connected. The built-in default is usb:.

The general form of a braille device specification is quali- fier:data. For backward compatibility with earlier releases, if the qualifier is omitted then serial: is assumed. The following device types are supported:

Bluetooth For a bluetooth device, specify bluez:address. The address must be six two-digit hexadecimal numbers sepa- rated by colons, e.g. 01:23:45:67:89:AB.

Serial For a serial device, specify serial:/path/to/device. The serial: qualifier is optional (for backward compatibil- ity). If a relative path is given then its anchored at /dev/ (the usual location where devices are defined on a Unix-like system). The following device specifications all refer to the primary serial device: serial:/dev/, serial:, /dev/, .

USB For a USB device, specify usb:. brltty will search for the first USB device which matches the braille display driver being used. If this is inadequate, e.g. if you have more than one USB braille display which requires the same driver, then you can refine the device specification by appending the serial number of the display to it, e.g. usb:12345. N.B.: The "identification by serial number" feature doesnt work for some models because some manu- facturers either don t set the USB serial number descrip- tor at all or do set it but not to a unique value.

A comma-delimited list of braille devices may be specified. If this is done then autodetection is performed on each listed device in sequence. This feature is particularly useful if you have a braille display with more than one interrface, e.g. both a serial and a USB port.

-e (--standard-error) Write logs to standard error rather than to the system log (use- ful for debugging).

-f file (--configuration-file=) The path to the configuration file. Relative paths are anchored at the current working directory. The built-in default is /etc/brltty.conf.

-h (--help) Print a command line usage summary and then exit.

-l level (--log-level=) The minimum severity level for messages written to the log. Any of the following numbers, or any abbreviation of their corre- sponding names, may be specified:

0 emergency

1 alert

2 critical

3 error

4 warning

5 notice

6 information

7 debug

The built-in default is notice.

-m device (--midi-device=) The device to use for the Musical Instrument Digital Interface. For ALSA its client:port, where each may be either a number or a case-sensitive substring of its name. For other interfaces it s the full path to an appropriate system device. The built- in default is:

Linux/ALSA the first available MIDI output port

Linux/OSS /dev/sequencer

-n (--no-daemon) Remain in the foreground (useful for debugging).

-p device (--pcm-device=) The device to use for digital audio. For ALSA its name[:argu- ment,...]. For other interfaces its the full path to an appro- priate system device. The built-in default is:

FreeBSD /dev/dsp

Linux/ALSA hw:0,0

Linux/OSS /dev/dsp

NetBSD /dev/audio

OpenBSD /dev/audio

Qnx the preferred PCM output device

Solaris /dev/audio

-q (--quiet) Suppress the start-up messages. This is done by reducing the default log level (see the -l (--log-level=) option) to warning (information if either -v (--verify) or -V (--version) is also specified).

-r (--release-device) Release the device to which the braille display is connected when the current screen or window cant be read.

-s driver,...|auto (--speech-driver=) The driver for the speech synthesizer (see Driver Specifica- tion). The built-in default is auto.

-t table (--text-table=) The path to the text translation table. Relative paths are anchored at /etc/brltty/. The .ttb extension is optional. The built-in default is nabcc.ttb (the North American Braille Com- puter Code).

-v (--verify) Print the start-up messages and then exit. This always includes the versions of brltty itself, the server side of its applica- tion programming interface, and each of the selected braille and speech drivers. If the -q (--quiet) option isnt also specified then it also includes the values of the options after all sources have been considered. If more than one braille driver and/or more than one braille device has been specified then braille display autodetection is performed. If more than one speech driver has been specified then speech synthesizer autode- tection is performed.

-x driver (--screen-driver=) The screen driver. The built-in default is operating system appropriate.

-A name=value,... (--api-parameters=) Parameters for the application programming interface. If the same parameter is specified more than once then the rightmost specification is used. Parameter names may be abbreviated.

-B [driver:]name=value,... (--braille-parameters=) Parameters for the braille display driver. If the same parame- ter is specified more than once then the rightmost specification is used. Parameter names may be abbreviated. If a parameter assignment is qualified with a driver identification code then it s only processed if that braille display driver is being used.

-E (--environment-variables) Recognize environment variables.

-F fifo (--speech-fifo=) The FIFO which gives other applications access to brlttys speech driver. Its created at start-up and removed at termina- tion. Relative paths are anchored at /etc/brltty/. The built- in default is that no FIFO is created.

-I (--install-service) (Windows only) Install brltty as the BrlAPI service so that it will be automatically started when the system is booted and so that applications can know that a BrlAPI server is running.

-M csecs (--message-delay=) The message hold time in hundredths of a second. The built-in default is 400 (4 seconds).

-N (--no-api) Dont start the application programming interface.

-P file (--pid-file=) The full path to the process identifier file. If this option is supplied, brltty writes its process identifier (pid) into the specified file at start-up. The file is removed when brltty terminates.

-R (--remove-service) (Windows only) Remove the BrlAPI service so that brltty will not be automatically started when the system is booted and so that applications can know that no BrlAPI server is running.

-S [driver:]name=value,... (--speech-parameters=) Parameters for the speech synthesizer driver. If the same parameter is specified more than once then the rightmost speci- fication is used. Parameter names may be abbreviated. If a parameter assignment is qualified with a driver identification code then it s only processed if that speech synthesizer driver is being used.

-U csecs (--update-interval=) The braille window update interval in hundredths of a second. The built-in default is 4 (25 times per second).

-V (--version) Print the versions of brltty itself, the server side of its application programming interface, and those drivers which were configured in at build-time, and then exit. If the -q (--quiet) option isn t also specified then also print copyright informa- tion.

-X name=value,... (--screen-parameters=) Parameters for the screen driver. If the same parameter is specified more than once then the rightmost specification is used. Parameter names may be abbreviated.

Environment Variables The following environment variables are recognized if the -E (--envi- ronment-variables) option is specified:

BRLTTY_API_PARAMETERS=name=value,... Parameters for the application programming interface. See the -A (--api-parameters=) option for details.

BRLTTY_ATTRIBUTES_TABLE=table The attributes translation table. See the -a (--attributes-ta- ble=) option for details.

BRLTTY_BRAILLE_DEVICE=device,... The device to which the braille display is connected. See the -d (--braille-device=) option for details.

BRLTTY_BRAILLE_DRIVER=driver,...|auto The driver for the braille display. See the -b (--braille- driver=) option for details.

BRLTTY_BRAILLE_PARAMETERS=[driver:]name=value,... Parameters for the braille display driver. See the -B (--braille-parameters=) option for details.

BRLTTY_CONFIGURATION_FILE=file The configuration file. See the -f (--configuration-file=) option for details.

BRLTTY_CONTRACTION_TABLE=table The contraction table. See the -c (--contraction-table=) option for details.

BRLTTY_MIDI_DEVICE=device The device to use for the Musical Instrument Digital Interface. See the -m (--midi-device=) option for details.

BRLTTY_PCM_DEVICE=device The device to use for digital audio. See the -p (--pcm-device=) option for details.

BRLTTY_RELEASE_DEVICE=on|off Release the device to which the braille display is connected when the current screen or window can t be read. See the -r (--release-device) option for details.

BRLTTY_SCREEN_DRIVER=driver The screen driver. See the -x (--screen-driver=) option for details.

BRLTTY_SCREEN_PARAMETERS=name=value,... Parameters for the screen driver. See the -X (--screen-parame- ters=) option for details.

BRLTTY_SPEECH_DRIVER=driver,...|auto The driver for the speech synthesizer. See the -s (--speech- driver=) option for details.

BRLTTY_SPEECH_FIFO=fifo The FIFO which gives other applications access to brlttys speech driver. See the -F (--speech-fifo=) option for details.

BRLTTY_SPEECH_PARAMETERS=[driver:]name=value,... Parameters for the speech synthesizer driver. See the -S (--speech-parameters=) option for details.

BRLTTY_TEXT_TABLE=table The text translation table. See the -t (--text-table=) option for details.

The Configuration File Blank lines are ignored. If the character # occurs on any line then all characters from it to the end of that line are treated as a com- ment.

The following configuration directives are supported:

api-parameters name=value,... Parameters for the application programming interface. See the -A (--api-parameters=) option for details.

attributes-table table The attributes translation table. See the -a (--attributes-ta- ble=) option for details.

braille-device device,... The device to which the braille display is connected. See the -d (--braille-device=) option for details.

braille-driver driver,...|auto The driver for the braille display. See the -b (--braille- driver=) option for details.

braille-parameters [driver:]name=value,... Parameters for the braille display driver. See the -B (--braille-parameters=) option for details.

contraction-table table The contraction table. See the -c (--contraction-table=) option for details.

midi-device device The device to use for the Musical Instrument Digital Interface. See the -m (--midi-device=) option for details.

pcm-device device The device to use for digital audio. See the -p (--pcm-device=) option for details.

release-device on|off Release the device to which the braille display is connected when the current screen or window cant be read. See the -r (--release-device) option for details.

screen-driver driver The screen driver. See the -x (--screen-driver=) option for details.

screen-parameters name=value,... Parameters for the screen driver. See the -X (--screen-parame- ters=) option for details.

speech-driver driver,...|auto The driver for the speech synthesizer. See the -s (--speech- driver=) option for details.

speech-fifo fifo The FIFO which gives other applications access to brlttys speech driver. See the -F (--speech-fifo=) option for details.

speech-parameters [driver:]name=value,... Parameters for the speech synthesizer driver. See the -S (--speech-parameters=) option for details.

text-table table The text translation table. See the -t (--text-table=) option for details.

Driver Specification A braille display or speech synthesizer driver must be specified via its identification code:

al Alva

at Albatross

ba BrlAPI

bd Braudi

bl BrailleLite

bm Baum

bn BrailleNote

cb CombiBraille

ec EcoBraille

es ExternalSpeech

eu EuroBraille

fl FestivalLite

fs FreedomScientific

fv Festival

gs GenericSay

hm HIMS

ht HandyTech

il IrisLinux

lb Libbraille

lt LogText

mb MultiBraille

md MDV

mn MiniBraille

mp Mikropuhe

no no driver

pg Pegasus

pm Papenmeier

sd SpeechDispatcher

sk Seika

sw Swift

th Theta

tn TechniBraille Systems Inc.

ts Telesensory Systems Inc.

tt TTY

vd VideoBraille

vo Voyager

vr Virtual

vs VisioBraille

vv ViaVoice

xw XWindow

A comma-delimited list of drivers may be specified. If this is done then autodetection is performed using each listed driver in sequence. You may need to experiment in order to determine the most reliable order since some drivers autodetect better than others.

If the single word auto is specified then autodetection is per- formed using only those drivers which are known to be reliable for this purpose.

SEE ALSO For full documentation, see brltty s on-line manual at [http://mielke.cc/brltty/doc/Manual-HTML/Manual.html].

brltty 4.1 October 2009 BRLTTY(1)