Next Previous Contents

3. Using BRLTTY

Before starting BRLTTY, you need to set up your braille display. In most cases this is done simply by connecting it to an available serial port, and then turning it on. After your display has been set up, run BRLTTY simply by typing the command brltty at a shell prompt (this must be done as root). Check the -d command line option, the braille-device configuration file directive, and the --with-braille-device build option for alternatives regarding how to tell BRLTTY which device your display is connected to. Check the -b command line option, the braille-driver configuration file directive, and the --with-braille-driver build option for alternatives regarding how to tell BRLTTY which kind of braille display you have. Check the -B command line option, and the braille-parameters configuration file directive for alternatives regarding how to pass parameters to the driver for your braille display.

A message giving the program name (BRLTTY) and its version number will appear briefly (see the -M command line option) on the braille display. The display will then show a small area of the screen including the cursor. By default, the cursor is represented as dots 7 and 8 superimposed on the character it is on.

Any screen activity will be reflected on the braille display. The display will also follow the progress of the cursor on the screen. This feature is known as cursor tracking.

Just typing on the keyboard and reading the display, however, isn't enough. Try entering a command which will cause an error, and pressing enter. The error appears on the screen, but, unless you have a multi-line display, the chances are that it isn't visible on the braille display. All you see thereon is another shell prompt. What's needed, then, is some way to move the braille window around the screen. The keys on the braille display itself can be used to send commands to BRLTTY which, in addition to a lot of other things, can also do exactly that.

3.1 Commands

Unfortunately, the various braille displays don't offer a standard set of controls. Some have the six standard dot keys, some have eight, and others have none. Some have thumb keys, but there's no standard number of them. Some have a button above each braille cell. Some have rocker switches. Some have an easy-to-reach bar which works much like a joystick. Most have varying combinations of the above. Because the nature and layout of each display is so different, please refer to the documentation for your particular display in order to find out exactly what its keys do.

BRLTTY commands are referred to by name within this manual. If you forget which key(s) on your braille display to use for a paticular command, then refer to its driver's help page. The main key you should immediately commit to memory, therefore, is the one for the HELP command. Use the regular motion keys (as described below) to navigate the help page, and press the help key again to quit.

Vertical Motion

See also the NXINDENT and the PRINDENT routing key commands.

LNUP

Go up one line. If identical line skipping has been activated (see the SKPIDLNS command), then this command, rather than moving exactly one line, is an alias for the PRDIFLN command.

LNDN

Go down one line. If identical line skipping has been activated (see the SKPIDLNS command), then this command, rather than moving exactly one line, is an alias for the NXDIFLN command.

WINUP

Go up several lines.

WINDN

Go down several lines.

PRDIFLN

Go up to the nearest previous line with different content. If identical line skipping has been activated (see the SKPIDLNS command), then this command, rather than skipping identical lines, is an alias for the LNUP command.

NXDIFLN

Go down to the nearest next line with different content. If identical line skipping has been activated (see the SKPIDLNS command), then this command, rather than skipping identical lines, is an alias for the LNDN command.

ATTRUP

Go up to the nearest previous line with different character highlighting (attributes).

ATTRDN

Go down to the nearest next line with different character highlighting (attributes).

TOP

Go up to the top line.

BOT

Go down to the bottom line.

TOP_LEFT

Go to the top-left corner.

BOT_LEFT

Go to the bottom-left corner.

PRPGRPH

Go up to the last line of the previous paragraph (the first non-blank line beyond the nearest previous blank line). The current line is included when searching for the inter-paragraph space.

NXPGRPH

Go down to the first line of the next paragraph (the first non-blank line beyond the nearest next blank line). The current line is included when searching for the inter-paragraph space.

PRPROMPT

Go up to the previous command prompt.

NXPROMPT

Go down to the next command prompt.

PRSEARCH

Search backward for the nearest occurrence of the character string within the cut buffer (see Cut and Paste). The search starts at the character immediately to the left of the braille window, proceeds from right to left, and, at the beginning of a line, wraps to the end of the previous line. The search isn't case sensitive.

NXSEARCH

Search forward for the nearest occurrence of the character string within the cut buffer (see Cut and Paste). The search starts at the character immediately to the right of the braille window, proceeds from left to right, and, at the end of a line, wraps to the beginning of the next line. The search isn't case sensitive.

Horizontal Motion

See also the SETLEFT routing key command.

CHRLT

Go left one character.

CHRRT

Go right one character.

HWINLT

Go left half a window.

HWINRT

Go right half a window.

FWINLT

Go left one window. This command is particularly useful when reading backward because it automatically wraps up to the end of the previous line when invoked at the beginning of the current line. Other features like its ability to skip blank windows (see the SKPBLNKWINS command) further enhance its usefulness for this purpose.

FWINRT

Go right one window. This command is particularly useful when reading forward because it automatically wraps down to the beginning of the next line when invoked at the end of the current line. Other features like its ability to skip blank windows (see the SKPBLNKWINS command) further enhance its usefulness for this purpose.

FWINLTSKIP

Go left to the nearest previous non-blank window.

FWINRTSKIP

Go right to the nearest next non-blank window.

LNBEG

Go to the beginning (left) of the line.

LNEND

Go to the end (right) of the line.

Implicit Motion

See also the GOTOMARK routing key command.

HOME

Go to where the cursor is.

BACK

Go back to where the most recent motion command put the braille window. This is an easy way to get right back to where you were reading after an unexpected event (like cursor tracking) moves the braille window at an inopportune moment.

Feature Activation

Each of these commands has three forms: activate (turn the feature on), deactivate (turn the feature off), and toggle (if it's off then turn it on, and if it's on then turn it off). Unless specifically noted, each of these features is initially off, and, when on, affects BRLTTY's operation as a whole. The initial setting of some of these features can be changed via the preferences menu.

FREEZE

Freeze the screen image. BRLTTY makes a copy of the screen (content and attributes) as of the moment when the screen image is frozen, and then ignores all updating of the screen until it's unfrozen. This feature makes it easy, for example, to sample the output of an application which writes too much too quickly.

DISPMD

Show the highlighting (the attributes) of each character within the braille window, rather than the characters themselves (the content). This feature is useful, for example, when you need to locate a highlighted item. When showing screen content, the text translation table is used (see the -t command line option, the text-table configuration file directive, and the --with-text-table build option). When showing screen attributes, the attributes translation table is used (see the -a command line option, the attributes-table configuration file directive, and the --with-attributes-table build option). This feature only affects the current virtual terminal.

SIXDOTS

Show characters using 6-dot, rather than 8-dot, braille. Dots 7 and 8 are still used by other features like cursor representation and highlighted character underlining. If a contraction table has been selected (see the -c command line option and the contraction-table configuration file directive), then it is used. This setting can also be changed with the Text Style preference.

SLIDEWIN

If cursor tracking (see the CSRTRK command) is on, then, whenever the cursor moves too close to (or beyond) either end of the braille window, horizontally reposition the window such that the cursor, while remaining on that side, is nearer the centre. If this feature is off, then the braille window is always positioned such that its left end is a multiple of its width from the left edge of the screen. This setting can also be changed with the Sliding Window preference.

SKPIDLNS

Rather than explicitly moving exactly one line either up or down, skip passed lines which have the same content as the current line. This feature affects the LNUP and LNDN commands, as well as the line wrapping feature of the FWINLT, FWINRT, FWINLTSKIP, and FWINRTSKIP commands. This setting can also be changed with the Skip Identical Lines preference.

SKPBLNKWINS

Skip passed blank windows when reading either forward or backward. This feature affects the FWINLT and FWINRT commands. This setting can also be changed with the Skip Blank Windows preference.

CSRVIS

Show the cursor by superimposing a dot pattern (see the CSRSIZE command) on top of the character where it is. This feature is initially on. This setting can also be changed with the Show Cursor preference.

CSRHIDE

Hide the cursor (see the CSRVIS command) in order to accurately read the character beneath it. This feature only affects the current virtual terminal.

CSRTRK

Track (follow) the cursor. If the cursor moves to a location which isn't within the braille window, then automatically move the braille window to the cursor's new location. You'll usually want this feature turned on since it minimizes the effects of screen scrolling, and since, during input, the region wherein you're currently typing is always visible. If this feature causes the braille window to jump at an inopportune moment, then use the BACK command to get back to where you were reading. You may need to turn this feature off when using an application which continually updates the screen while maintaining a fixed data layout. This feature is initially on. This feature only affects the current virtual terminal.

CSRSIZE

Represent the cursor with all eight dots (a solid block), rather than with just dots 7 and 8 (an underline). This setting can also be changed with the Cursor Style preference.

CSRBLINK

Blink (turn on and off according to a predefined interval) the symbol representing the cursor (see the CSRVIS command). This setting can also be changed with the Blinking Cursor preference.

ATTRVIS

Underline (with combinations of dots 7 and 8) highlighted characters.

no underline

White on black (normal), gray on black, white on blue, black on cyan.

dots 7 and 8

Black on white (reverse video).

dot 8

Everything else.

This setting can also be changed with the Show Attributes preference.

ATTRBLINK

Blink (turn on and off according to a predefined interval) the attribute underline (see the ATTRVIS command). This feature is initially on. This setting can also be changed with the Blinking Attributes preference.

CAPBLINK

Blink (turn on and off according to a predefined interval) capital (uppercase) letters. This setting can also be changed with the Blinking Capitals preference.

TUNES

Play a short predefined tune (see Alert Tunes) whenever a significant event occurs. This feature is initially on. This setting can also be changed with the Alert Tunes preference.

Mode Selection

HELP

Switch to the braille display driver's help page. This is where you can find an on-line summary of things like what your braille display's keys do, and how to interpret its status cells. Use the regular vertical and horizontal motion commands to navigate the help page. Invoke the help command again to return to the screen.

INFO

Switch to the status display (see section The Status Display for full details). It presents a summary including the position of the cursor, the position of the braille window, and the states of a number of BRLTTY's features. Invoke this command again to return to the screen.

LEARN

Switch to command learn mode (see section Command Learn Mode for full details). This is how you can interactively learn what your braille display's keys do. Invoke this command again to return to the screen. This command isn't available if the --disable-learn-mode build option was specified.

Preference Maintenance

PREFMENU

Switch to the preferences menu (see The Preferences Menu for full details). Invoke this command again to return to normal operation. This command isn't available if the --disable-preferences-menu build option was specified.

PREFSAVE

Save the current preferences settings (see Preferences for full details).

PREFLOAD

Restore the most recently saved preferences settings (see Preferences for full details).

Menu Navigation

MENU_FIRST_ITEM

Go to the first item in the menu.

MENU_LAST_ITEM

Go to the last item in the menu.

MENU_PREV_ITEM

Go to the previous item in the menu.

MENU_NEXT_ITEM

Go to the next item in the menu.

MENU_PREV_SETTING

Decrement the current menu item's setting.

MENU_NEXT_SETTING

Increment the current menu item's setting.

Speech Controls

SAY

Speak the current line.

SAYALL

Speak the rest of the screen (starting with the current line).

MUTE

Stop speaking immediately.

SPKHOME

Go to where the speech cursor is.

Virtual Terminal Switching

See also the SWITCHVT routing key command.

SWITCHVT_PREV

Switch to the previous virtual terminal (the one whose number is one less than the current one).

SWITCHVT_NEXT

Switch to the next virtual terminal (the one whose number is one greater than the current one).

Other Commands

CSRJMP_VERT

Route (bring) the cursor to anywhere on the top line of the braille window (see Cursor Routing for full details). The cursor is moved by simulating vertical arrow-key presses. This command doesn't always work because some applications either move the cursor somewhat unpredictably or use the arrow keys for purposes other than cursor motion. It's somewhat safer than the other cursor routing commands, though, because it makes no attempt to simulate the left- and right-arrows.

PASTE

Insert the characters within the cut buffer at the current cursor location (see Cut and Paste for full details).

RESTARTBRL

Stop, and then restart the braille display driver.

RESTARTSPEECH

Stop, and then restart the speech synthesizer driver.

Routing Keys

ROUTE

Route (bring) the cursor to the character associated with the routing key (see Cursor Routing for full details). The cursor is moved by simulating arrow-key presses. This command doesn't always work because some applications either move the cursor somewhat unpredictably or use the arrow keys for purposes other than cursor motion.

CUTBEGIN

Anchor the start of the cut block at the character associated with the routing key (see Cut and Paste for full details). This command clears the cut buffer.

CUTAPPEND

Anchor the start of the cut block at the character associated with the routing key (see Cut and Paste for full details). This command doesn't clear the cut buffer.

CUTRECT

Anchor the end of the cut block at the character associated with the routing key, and append the rectangular region to the cut buffer (see Cut and Paste for full details).

CUTLINE

Anchor the end of the cut block at the character associated with the routing key, and append the linear region to the cut buffer (see Cut and Paste for full details).

SWITCHVT

Switch to the virtual terminal whose number (counting from 1) matches that of the routing key.

PRINDENT

Go up to the nearest previous line which isn't indented more than the column associated with the routing key.

NXINDENT

Go down to the nearest next line which isn't indented more than the column associated with the routing key.

DESCCHAR

Momentarily (see the -M command line option) display a message describing the character associated with the routing key. It reveals the decimal and hexadecimal values of the character, the foreground and background colours, and, when present, special attributes (bright and blink). The message looks like this:

char 65 (0x41): white on black bright blink

SETLEFT

Horizontally reposition the braille window so that its left edge is at the column associated with the routing key. This feature makes it very easy to put the window exactly where it's needed, and, therefore, for displays which have routing keys, almost eliminates the need for a lot of elementary window motion (like the CHRLT, CHRRT, HWINLT, and HWINRT commands).

SETMARK

Mark (remember) the current position of the braille window in a register associated with the routing key. See the GOTOMARK command. This feature only affects the current virtual terminal.

GOTOMARK

Move the braille window to the position formerly marked (see the SETMARK command) with the same routing key. This feature only affects the current virtual terminal.

3.2 The Configuration File

System defaults for many settings may be established within a configuration file. The default name for this file is /etc/brltty.conf, although it may be overridden with the -f command line option. It doesn't need to exist. A template for it can be found within the DOCS subdirectory.

Blank lines are ignored. A comment begin with a number sign (#), and continues to the end of the line. The following directives are recognized:

attributes-table file

Specify the attributes translation table (see section Translation Tables for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). See the --with-attributes-table build option for the default established during the build procedure. This directive can be overridden with the -a command line option.

braille-driver driver

Specify the braille display driver. Either a two-letter driver identification code or the full path to a dynamically loadable shared object may be supplied. See the --with-braille-driver build option for the default established during the build procedure. This directive can be overridden with the -b command line option.

braille-device device

Specify the device to which the braille display is connected. The full path must be supplied. See the --with-braille-device build option for the default established during the build procedure. This directive can be overridden with the -d command line option.

braille-parameters name=value,...

Specify parameters for the braille display driver. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. This directive can be overridden with the -B command line option.

contraction-table file

Specify the contraction table (see section Contracted Braille for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). The contraction table is used when the 6-dot braille feature is activated (see the SIXDOTS command and the Text Style preference). The default is to display uncontracted 6-dot braille. This directive can be overridden with the -c command line option. It isn't available if the --disable-contracted-braille build option was specified.

preferences-file file

Specify the location of the preferences file. If it's not specified, then /etc/brltty-driver.prefs is assumed, where driver is a two-letter driver identification code. The preferences file doesn't need to exist. This directive can be overridden with the -p command line option.

screen-parameters name=value,...

Specify parameters for the screen driver. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. This directive can be overridden with the -X command line option.

speech-driver driver

Specify the speech synthesizer driver. Either a two-letter driver identification code or the full path to a dynamically loadable shared object may be supplied. See the --with-speech-driver build option for the default established during the build procedure. This directive can be overridden with the -s command line option.

speech-parameters name=value,...

Specify parameters for the speech synthesizer driver. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. This directive can be overridden with the -S command line option.

text-table file

Specify the text translation table (see section Translation Tables for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). See the --with-text-table build option for the default established during the build procedure. This directive can be overridden with the -t command line option.

3.3 Command Line Options

Many settings can be explicitly specified when invoking BRLTTY. The brltty command accepts the following options:

-afile --attributes-table=file

Specify the attributes translation table (see section Translation Tables for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). See the attributes-table configuration file directive for the default run-time setting. This setting can be changed with the Attributes Table preference.

-bdriver --braille-driver=driver

Specify the braille display driver. Either a two-letter driver identification code or the full path to a dynamically loadable shared object may be supplied. See the braille-driver configuration file directive for the default run-time setting.

-cfile --contraction-table=file

Specify the contraction table (see section Contracted Braille for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). The contraction table is used when the 6-dot braille feature is activated (see the SIXDOTS command and the Text Style preference). See the contraction-table configureation file directive for the default run-time setting. This setting can be changed with the Contraction Table preference. This option isn't available if the --disable-contracted-braille build option was specified.

-ddevice --braille-device=device

Specify the device to which the braille display is connected. The full path must be supplied. See the braille-device configuration file directive for the default run-time setting.

-e --standard-error

Write diagnostic messages to standard error. The default is to record them via syslog.

-ffile --configuration-file=file

Specify the location of the configuration file which is to be used for the establishing of default run-time settings.

-h --help

Display a summary of the command line options accepted by BRLTTY, and then exit.

-llevel --log-level=level

Specify the severity threshold for diagnostic message generation. The following levels are recognized.

0

emergency

1

alert

2

critical

3

error

4

warning

5

notice

6

information

7

debug

Either the number or the name may be supplied, and the name may be abbreviated. If not specified, then information is assumed (see the -q option for more details).

-n --no-daemon

Specify that BRLTTY is to remain in the foreground. If not specified, then BRLTTY becomes a background process (daemon) after initializing itself but before starting any of the selected drivers.

-pfile --preferences-file=file

Specify the location of the preferences file. The preferences file doesn't need to exist. See the preferences-file configuration file directive for the default run-time setting.

-q --quiet

Log less information. This option changes the log level (see the -l option) to notice.

-sdriver --speech-driver=driver

Specify the speech synthesizer driver. Either a two-letter driver identification code or the full path to a dynamically loadable shared object may be supplied. See the speech-driver configuration file directive for the default run-time setting.

-tfile --text-table=file

Specify the text translation table (see section Translation Tables for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). See the text-table configureation file directive for the default run-time setting. This setting can be changed with the Text Table preference.

-v --version

Display the current version of BRLTTY, identify the selected drivers, and then exit. If the -q option isn't specified, then copyright information, and the parameter settings for each of the selected drivers are also displayed, and the working directory, the preferences file, the text and attributes translation tables, and the braille display device and help file are identified.

-Bname=value,... --braille-parameters=name=value,...

Specify parameters for the braille display driver. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the braille-parameters configuration file directive for the default run-time setting.

-E --environment-variables

Recognize environment variables when determining the default settings for unspecified command line options (see section Command Line Options). If this option is specified, and if the environment variable associated with an unspecified option is defined, then the value of that environment variable is used. The names of these environment variables are based on the long names of the options they correspond to:

This option is particularly useful on the Linux operating system as it allows default settings to be passed to BRLTTY via boot parameters. The following environment variables are supported:
BRLTTY_ATTRIBUTES_TABLE

The attributes translation table (see the -a command line option).

BRLTTY_BRAILLE_DEVICE

The braille display device (see the -d command line option).

BRLTTY_BRAILLE_DRIVER

The braille display driver (see the -b command line option).

BRLTTY_BRAILLE_PARAMETERS

Parameters for the braille display driver (see the -B command line option).

BRLTTY_CONFIGURATION_FILE

The configuration file (see the -f command line option).

BRLTTY_CONTRACTION_TABLE

The contraction table (see the -c command line option).

BRLTTY_PREFERENCES_FILE

The preferences file (see the -p command line option).

BRLTTY_SCREEN_PARAMETERS

Parameters for the screen driver (see the -X command line option).

BRLTTY_SPEECH_DRIVER

The speech synthesizer driver (see the -s command line option).

BRLTTY_SPEECH_PARAMETERS

Parameters for the speech synthesizer driver (see the -S command line option).

BRLTTY_TEXT_TABLE

The text translation table (see the -a command line option).

-Mcsecs --message-delay=csecs

Specify the message hold time (in hundredths of a second). If not specified, then 400 (4 seconds) is assumed. This is the amount of time that BRLTTY keeps its own internally generated messages on the braille display.

-N --no-speech

Don't automatically start the speech synthesizer driver. This option is unfortunately necessary on some systems when BRLTTY is started before the sound subsystem within the kernel has been initialized.

-Pfile --pid-file=file

Specify the file wherein BRLTTY is to write its process identifier (pid). If not specified, BRLTTY doesn't write its process identifier anywhere.

-Rcsecs --refresh-interval=csecs

Specify the braille window refresh internal (in hundredths of a second). If not specified, then 4 (40 milliseconds) is assumed.

-Sname=value,... --speech-parameters=name=value,...

Specify parameters for the speech synthesizer driver. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the speech-parameters configuration file directive for the default run-time setting.

-Xname=value,... --screen-parameters=name=value,...

Specify parameters for the screen driver. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the screen-parameters configuration file directive for the default run-time setting.


Next Previous Contents