BRLTTY: Using BRLTTY

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 BRLDEV make file variable 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 BRL_TARGET make file variable 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.

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.

### 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 and Deactivation

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 TEXTTRANS make file variable). When showing screen attributes, the attributes translation table is used (see the -a command line option, the attributes-table configuration file directive, and the ATTRTRANS make file variable). 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 attribute underlining. 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, which presents a summary including the position of the cursor, the position of the braille window, and the states of a nmber of BRLTTY's features. See the section The Status Display for full details. Invoke the `info` command again to return to the screen.

LEARN

  Switch to command learn mode, which is an interactive way to learn what the keys on the braille display do. See the section Command Learn Mode for full details. Invoke the `learn` command again to return to the screen.

### Preferences Settings

PREFMENU

  Switch to the preferences menu (see The Preferences Menu for full details). Invoke the `PREFMENU` command again to return to normal operation.

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

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).

### Miscellaneous

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 Cursor Routing

When moving the braille window around the screen while examining the text, say, in an editor, you often need to bring the cursor to a specific character within the braille window. You'll probably find this to be a rather difficult task for a number of reasons. One is that you may not know where the cursor is, and that you may lose your place while trying to find it. Another is that the cursor may move unrpedictably as the arrow keys are pressed (some editors, for example, don't allow the cursor to be more to the right than the end of the line it's on). Cursor routing provides just such a capability by knowing where the cursor is, by simulating the same arrow-key presses which you'd have to enter manually, and by monitoring the progress of the cursor as it moves.

Some braille displays have a button, known as a routing key, above each cell. These keys use the ROUTE command to route the cursor right to the desired location.

Cursor routing, while very convenient and effective, is, strictly speaking, not completely reliable. One reason for this is that its current implementation assumes VT100 cursor key escape sequences. Another is that some applications do non-standard things in response to detecting that a cursor key has been pressed. A minor problem found within some editors (like `vi`), as already mentioned above, is that they throw in some unpredictable horizontal motion when vertical motion is requested because they don't allow the cursor to be to the right of the end of a line. A major problem found within some web browsers (like `lynx`) is that the up- and down-arrow keys are used to move among the links (which may skip lines and/or move the cursor horizontally, but which rarely just moves the cursor one line in the desired direction), and that the left- and right-arrow keys are used to select links (which has absolutely nothing to do with any form of cursor motion whatsoever, and which even totally changes the screen content).

Cursor routing may not work very well on a heavily loaded system, and definitely doesn't work very well when working on a remote system over a slow link. This is so because of all of the checks which must be made along the way in order to deal with unpredictable cursor motion and in order to ensure that any mistake has at least a fighting chance to be undone. Even though BRLTTY tries to be fairly clever, it must still essentially wait to see what happens after each simulated arrow-key press.

Once a cursor routing request has been made, BRLTTY keeps trying to route the cursor to the desired location until a timeout expires before the cursor reaches that location, the cursor seems to be moving in the wrong direction, or you switch to a different virtual terminal. An attempt is first made to use virtical motion to bring the cursor to the right line, and, only if that succeeds, an attempt is then made to use horizontal motion to bring the cursor to the right column. If another request is made while one is still in progress, then the first one is aborted and the second one is initiated.

A safer but less powerful cursor routing command, CSRJMP_VERT, uses just vertical motion to bring the cursor to anywhere on the top line of the braille window. It's especially useful in conjunction with applications (like `lynx`) wherein horizontal cursor motion must never be attempted.

## 3.3 Cut and Paste

This feature enables you to grab some text which is already on the screen and re-enter it at the current cursor position. Using it saves time and avoids errors when a long and/or complicated piece of text needs to be copied, and even when the same short and simple piece of text needs to be copied many times. It's particularly useful for things like long file names, complicated command lines, E-mail addresses, and URLs. Cutting and pasting text involves three simple steps:

1. Mark either the top-left corner of the rectangular area or the beginning of the linear area on the screen which is to be grabbed (cut). If your display has routing keys, then move the braille window so that the first character to be cut appears anywhere within it, and then:
   - invoke the CUTBEGIN command to start a new cut buffer
   - invoke the CUTAPPEND command to append to the existing cut buffer
   by pressing the key(s) associated with it and then pressing the routing key associated with the character.
2. Mark either the bottom-right corner of the rectangular area or the end of the linear area on the screen which is to be grabbed (cut). If your display has routing keys, then move the braille window so that the last character to be cut appears anywhere within it, and then
   - invoke the CUTRECT command to cut a rectangular area
   - invoke the CUTLINE command to cut a linear area
   by pressing the key(s) associated with it and then pressing the routing key associated with the character. Marking the end of the cut area appends the selected screen content to the cut buffer. Excess white space is removed from the end of each line in the cut buffer so that unwanted trailing spaces won't be pasted back in. Control characters are replaced with blanks.
3. Insert (paste) the text where it's needed. Place the cursor over the character where the text is to be pasted, and invoke the PASTE command. You can paste the same text any number of times without recutting it. This description assumes that you're already in some sort of input mode. If you paste when you're in some other kind of mode (like `vi`'s command mode), then you'd better be aware of what the characters in the cut buffer will do.

The cut buffer is also used by the PRSEARCH and NXSEARCH commands.

## 3.4 Alert Tunes

BRLTTY alerts you to the occurrence of significant events by playing short predefined tunes. This feature can be activated and deactivated with either the TUNES command or the Alert Tunes preference. The tunes are played on the PC speaker by default, but other alternatives can be selected with the Tune Device preference.

Each significant event is associated, from highest to lowest priority, with one or more of the following:

a tune

  If a tune has been associated with the event, if the Alert Tunes preference (see also the TUNES command) is active, and if the selected tune device (see the Tune Device preference) can be opened, then the tune is played.

a dot pattern

  If a dot pattern has been associated with the event, and if the Alert Dots preference is active, then the dot pattern is briefly displayed on every braille cell. Some braille displays don't respond quickly enough for this mechanism to work effectively.

a message

  If a message has been associated with the event, then it is displayed for a few seconds (see the -M command line option).

These events include:

- When the braille display driver starts or stops.
- When the start or end of the cut block is set.
- When a feature is activated or deactivated.
- When cursor tracking is turned on or off.
- When the screen image is frozen or unfrozen.
- When identical lines are skipped.
- When the braille window wraps either down to the beginning of the next line or up to the end of the previous line.
- When a requested motion cannot be performed.
- When a command cannot be executed.
- When a lengthy command completes.

## 3.5 The Status Display

The status display is a summary of BRLTTY's current state which fits completely within the braille window. Some braille displays have a set of status cells which are used to permanently display some of this information as well (see the documentation for your display's driver). The data presented by this display isn't static, and may change at any time in response to screen updates and/or BRLTTY commands.

Use the INFO command to switch to the status display, and use it again to return to the screen. The layout of the information contained therein is dependent on the size of the braille window.

### Displays with 21 Cells or More

Short pneumonics have been used, even though they're rather cryptic, in order to show the precise column layout.

> `wx:wy cx:cy vt tcmfdu`

wx`:`wy

  The column and row (counting from 0) on the screen corresponding to the top-left corner of the braille window.

cx`:`cy

  The column and row (counting from 0) on the screen corresponding to the position of the cursor.

vt

  The number (counting from 1) of the current virtual terminal.

t

  The state of the cursor tracking feature (see the CSRTRK command).

  blank

    Cursor tracking is off.

  `t`

    Cursor tracking is on.

c

  The state of the cursor visibility features (see the CSRVIS and CSRBLINK commands).

  blank

    The cursor isn't visible, and won't blink when made visible.

  `b`

    The cursor isn't visible, and will blink when made visible.

  `v`

    The cursor is visible, and isn't blinking.

  `B`

    The cursor is visible, and is blinking.

m

  The current display mode (see the DISPMD command).

  `t`

    Screen content (text) is being displayed.

  `a`

    Screen highlighting (attributes) is being displayed.

f

  The state of the frozen screen feature (see the FREEZE command).

  blank

    The screen isn't frozen.

  `f`

    The screen is frozen.

d

  The number of braille dots being used to display each character (see the SIXDOTS command).

  `8`

    All eight dots are being used.

  `6`

    Only dots 1 through 6 are being used.

u

  The state of the uppercase (capital letter) display features (see the CAPBLINK command).

  blank

    Uppercase letters don't blink.

  `B`

    Uppercase letters blink.

### Displays with 20 Cells or Less

Short pneumonics have been used, even though they're rather cryptic, in order to show the precise column layout.

> `xxyys vt tcmfdu`

xx

  The columns (counting from 0) on the screen corresponding to the position of the cursor (shown in the top half of the cells) and to the top-left corner of the braille window (shown in the bottom half of the cells).

yy

  The rows (counting from 0) on the screen corresponding to the position of the cursor (shown in the top half of the cells) and to the top-left corner of the braille window (shown in the bottom half of the cells).

s

  The settings of some of BRLTTY's features. A feature is turned on if its corresponding dot is raised.

  Dot 1

    Frozen screen image (see the FREEZE command).

  Dot 2

    Display attributes (see the DISPMD command).

  Dot 3

    Alert tunes (see the TUNES command).

  Dot 4

    Visible cursor (see the CSRVIS command).

  Dot 5

    Block cursor (see the CSRSIZE command).

  Dot 6

    Blinking cursor (see the CSRBLINK command).

  Dot 7

    Cursor tracking (see the CSRTRK command).

  Dot 8

    Sliding window (see the SLIDEWIN command).

vt

  The number (counting from 1) of the current virtual terminal.

t

  The state of the cursor tracking feature (see the CSRTRK command).

  blank

    Cursor tracking is off.

  `t`

    Cursor tracking is on.

c

  The state of the cursor visibility features (see the CSRVIS and CSRBLINK commands).

  blank

    The cursor isn't visible, and won't blink when made visible.

  `b`

    The cursor isn't visible, and will blink when made visible.

  `v`

    The cursor is visible, and isn't blinking.

  `B`

    The cursor is visible, and is blinking.

m

  The current display mode (see the DISPMD command).

  `t`

    Screen content (text) is being displayed.

  `a`

    Screen highlighting (attributes) is being displayed.

f

  The state of the frozen screen feature (see the FREEZE command).

  blank

    The screen isn't frozen.

  `f`

    The screen is frozen.

d

  The number of braille dots being used to display each character (see the SIXDOTS command).

  `8`

    All eight dots are being used.

  `6`

    Only dots 1 through 6 are being used.

u

  The state of the uppercase (capital letter) display features (see the CAPBLINK command).

  blank

    Uppercase letters don't blink.

  `B`

    Uppercase letters blink.

## 3.6 Command Learn Mode

Command learn mode is an interactive way to learn what the keys on the braille display do. It can be accessed either by the LEARN command or via the brltest utility.

When this mode is entered, the message `command learn mode` is written to the braille display. Then, as each key (or key combination) on the display is pressed, a short message describing its BRLTTY function is written. This mode exits immediately if the key (or key combination) for the LEARN command is pressed. It exits automatically, and the message `done` is written, if ten seconds elapse without any key on the display being pressed. Note that some displays don't signal the driver and/or some drivers don't signal BRLTTY until all the keys are released.

If a message is longer than the braille display is wide, then it's displayed in segments. The length of each segment but the last is one less than the display's width, with the rightmost character on the display being set to a minus sign. Each such segment remains on the display either for a few seconds (see the -M command line option) or until any key on the display is pressed.

## 3.7 Preferences Settings

When BRLTTY starts, it loads a file which contains your preferences settings. The file doesn't need to exist, and is created the first time the settings are saved with the PREFSAVE command. The most recently saved settings can be restored at any time with the PREFLOAD command.

The default name for this file is `/etc/brltty.conf`. A system default for its name can be established with the preferences-file configuration file directive. Its name can be explicitly set at run-time with the -p command line option.

### The Preferences Menu

The preferences settings are saved as binary data which, therefore, can't be edited by hand. BRLTTY, however, has a simple menu from which you can easily change them. It's activated by the PREFMENU command. The braille display briefly (see the -M command line option) shows the menu title, and then presents the current item and its current setting.

### Navigating the Menu

See Menu Navigation Commands for the full list of commands which enable you to select items and change settings within the menu. For backward compatibility with old drivers, the window motion commands, which have modified meanings in this context, can also be used.

`TOP`, `TOP_LEFT`

  Go to the first item in the menu (same as MENU_FIRST_ITEM).

`BOT`, `BOT_LEFT`

  Go to the last item in the menu (same as MENU_LAST_ITEM).

`LNUP`, `CURSOR_UP`

  Go to the previous item in the menu (same as MENU_PREV_ITEM).

`LNDN`, `CURSOR_DOWN`

  Go to the next item in the menu (same as MENU_NEXT_ITEM).

`WINUP`, `CHRLT`, `CURSOR_LEFT`

  Decrement the current menu item's setting (same as MENU_PREV_SETTING).

`WINDN`, `CHRRT`, `CURSOR_RIGHT`, `HOME`, `RETURN`

  Increment the current menu item's setting (same as MENU_NEXT_SETTING).

Notes:

- The routing keys can also be used to select a setting for the current item. If the item has numeric settings, then each routing key represents an integer (starting from 0), and a selection which is out of range is silently brought into range. If the item has named settings, then the routing keys correspond ordinally with the settings.
- Use the `PREFLOAD` command to undo all of the changes which were made since entering the menu.
- Use the `PREFMENU` command (again) to leave the new settings in effect, exit the menu, and resume normal operation. If the "Save Settings on Exit" item is set, then, in addition, the new settings are written to the preferences settings file. Any command not recognized by the menu system also does these same things.

### The Menu Items

Save on Exit

  When exiting the preferences menu:

  No

    Don't automatically save the preferences settings.

  Yes

    Automatically save the preferences settings.

  The initial setting is `No`.
Text Style

  When displaying screen content (see the id="options-DISPMD" name="DISPMD"> command), show characters:

  8-dot

    With all eight dots.

  6-dot

    With only dots 1 through 6.

  This setting can also be changed with the SIXDOTS command.
Meta Mode

  Enter a meta character by:

  Escape Prefix

    Prefixing it with an `escape` byte.

  High-order Bit

    Setting its high-order bit.

  Use the `setmetamode` command to find out how your system has been configured. The initial setting is `Escape Prefix`.
Skip Identical Lines

  When moving either up or down exactly one line with the LNUP and LNDN commands, as well as the line wrapping feature of the FWINLT, FWINRT, FWINLTSKIP, and FWINRTSKIP commands:

  No

    Don't skip passed lines which have the same content as the current line.

  Yes

    Skip passed lines which have the same content as the current line.

  This setting can also be changed with the SKPIDLNS command.
Skip Blank Windows

  When moving either left or right with the FWINLT and FWINRT commands:

  No

    Don't skip passed blank windows.

  Yes

    Skip passed blank windows.

  This setting can also be changed with the SKPBLNKWINS command.
Which Blank Windows

  If blank windows are to be skipped:

  All

    Skip all of them.

  End of Line

    Only skip those which are at the end (on the right side) of a line.

  Rest of Line

    Only skip those which are at the end (on the right side) of a line when reading forward, and at the beginning (on the left side) of a line when reading backward.

Sliding Window

  If the cursor is being tracked (see the CSRTRK command), and the cursor moves too close to (or beyond) either end of the braille window:

  No

    Horizontally reposition the window such that its left end is a multiple of its width from the left edge of the screen.

  Yes

    Horizontally reposition the window such that the cursor, while remaining on that side of the window, is nearer the centre.

  This setting can also be changed with the SLIDEWIN command.
Eager Sliding Window

  If the braille window is to slide:

  No

    Reposition it whenever the cursor moves beyond either end.

  Yes

    Reposition it whenever the cursor moves too close to either end.

  The initial setting is `off`.
Window Overlap

  When moving either left or right with the FWINLT and FWINRT commands, this setting specifies how many characters horizontally adjacent braille windows should overlap each other by. The initial setting is `0`.

Show Cursor

  When displaying screen content (see the id="options-DISPMD" name="DISPMD"> command):

  No

    Don't show the cursor.

  Yes

    Show the cursor.

  This setting can also be changed with the CSRVIS command.
Cursor Style

  When showing the cursor, represent it:

  Underline

    With dots 7 and 8.

  Block

    With all eight dots.

  This setting can also be changed with the CSRSIZE command.
Blinking Cursor

  When the cursor is to be shown:

  No

    Leave it visible all the time.

  Yes

    Make it alternately visible and invisible according to a predefined interval.

  This setting can also be changed with the CSRBLINK command.
Cursor Visible Period

  When the cursor is to be blinked, this setting specifies the length of time (see the note on time settings below) during each cycle that it is to be visible. The initial setting is `10`.

Cursor Invisible Period

  When the cursor is to be blinked, this setting specifies the length of time (see the note on time settings below) during each cycle that it is to be invisible. The initial setting is `10`.

Show Attributes

  When displaying screen content (see the id="options-DISPMD" name="DISPMD"> command):

  No

    Don't underline highlighted characters.

  Yes

    Underline highlighted characters.

  This setting can also be changed with the ATTRVIS command.
Blinking Attributes

  When highlighted characters are to be underlined:

  No

    Leave the indicator visible all the time.

  Yes

    Make the indicator alternately visible and invisible according to a predefined interval.

  This setting can also be changed with the ATTRBLINK command.
Attributes Visible Period

  When the highlighted character underline is to be blinked, this setting specifies the length of time (see the note on time settings below) during each cycle that it is to be visible. The initial setting is `4`.

Attributes Invisible Period

  When the highlighted character underline is to be blinked, this setting specifies the length of time (see the note on time settings below) during each cycle that it is to be invisible. The initial setting is `12`.

Blinking Capitals

  When displaying screen content (see the id="options-DISPMD" name="DISPMD"> command):

  No

    Leave capital letters visible all the time.

  Yes

    Make capital letters alternately visible and invisible according to a predefined interval.

  This setting can also be changed with the CAPBLINK command.
Capitals Visible Period

  When capital letters are to be blinked, this setting specifies the length of time (see the note on time settings below) during each cycle that they're to be visible. The initial setting is `4`.

Capitals Invisible Period

  When capital letters are to be blinked, this setting specifies the length of time (see the note on time settings below) during each cycle that they're to be invisible. The initial setting is `2`.

Alert Tunes

  Whenever a significant event with an associated tune occurs (see id="tunes" name="Alert Tunes">):

  No

    Don't play the tune.

  Yes

    Play the tune.

  This setting can also be changed with the TUNES command.
Tune Device

  Play alert tunes via:

  PC Speaker

    The built-in PC speaker. This setting is always safe to use, although it may be a bit too soft.

  Sound Card

    The Digital to Analog Converter on the sound card (via `/dev/dsp`). This setting doesn't work when the DAC is already being used by another application.

  MIDI

    The Musical Instrument Digital Interface on the sound card (via `/dev/sequencer`). This setting doesn't work when the MIDI is already being used by another application.

  AdLib

    OPL3/SB-FM/ The FM synthesizer on an AdLib, OPL3, Sound Blaster, or equivalent sound card. This setting works even if the FM synthesizer is already being used by another application. The results are unpredictable, and potentially not very good, if you use it with a sound card which doesn't support this feature.

  The initial setting is `PC Speaker`.
MIDI Instrument

  If the Musical Instrument Digital Interface (MIDI) of the sound card is being used to play the alert tunes, this setting specifies which instrument is to be used (see the MIDI Instrument Table). The initial setting is `Acoustic Grand Piano`.

Alert Dots

  Whenever a significant event with an associated dot pattern occurs (see id="tunes" name="Alert Tunes">):

  No

    Don't display the dot pattern.

  Yes

    Briefly display the dot pattern.

  If alert tunes are to be played (see the TUNES command and the Alert Tunes preference), if a tune has been associated with the event, and if the selected tune device can be opened, then, regardless of the setting of this preference, the dot pattern isn't displayed.
Status Cells Style

  This setting specifies the way that the status cells are to be used. You shuldn't normally need to play with it. It enables BRLTTY's developers to test status cell configurations for braille displays which they don't actually have.

  None

    Don't use the status cells. This setting is always safe, but it's also quite useless.

  Alva

    The status cells contain:

    1

      The location of the cursor (see below).

    2

      The location of the top-left corner of the braille window (see below).

    3

      A letter indicating BRLTTY's state. In order of precedence:

      a

        Screen attributes are being shown (see the DISPMD command).

      f

        The screen image is frozen (see the FREEZE command).

      f

        The cursor is being tracked (see the CSRTRK command).

      blank

        Nothing special.

    The locations of the cursor and the braille window are presented in an interesting way. Dots 1 through 6 represent the line number with a letter from `a` (for 1) through `y` (for 25). Dots 7 and 8 (the extra two at the bottom) represent the horizontal braille window number as follows:
    No Dots

      The first (leftmost) window.

    Dot 7

      The second window.

    Dot 8

      The third window.

    Dots 7 and 8

      The fourth window.

    In both cases, the indicators wrap: line 26 is represented by the letter `a`, and the fifth horizontal braille window is represented by no dots at the bottom.
  Tieman

    The status cells contain:

    1-2

      The columns (counting from zero) of the cursor (shown in the top half of the cells) and the top-left corner of the braille window (shown in the bottom half of the cells).

    3-4

      The rows (counting from zero) of the cursor (shown in the top half of the cells) and the top-left corner of the braille window (shown in the bottom half of the cells).

    5

      Each dot indicates if a feature is turned on as follows:

      Dot 1

        The screen image is frozen (see the FREEZE command).

      Dot 2

        Screen attributes are being displayed (see the DISPMD command).

      Dot 3

        Alert tunes are being played (see the TUNES command).

      Dot 4

        The cursor is being shown (see the CSRVIS command).

      Dot 5

        The cursor is a solid block (see the CSRSIZE command).

      Dot 6

        The cursor is blinking (see the CSRBLINK command).

      Dot 7

        The cursor is being tracked (see the CSRTRK command).

      Dot 8

        The braille window will slide (see the SLIDEWIN command).

  PowerBraille 80

    The status cells contain:

    1

      The row (counting from 1) corresponding to the top of the braille window. The tens digit is shown in the top half of the cell, and the units digit is shown in the bottom half of the cell.

  Generic

    This setting passes a lot of information to the braille driver, and the driver itself decides how to present it.

  MDV

    The status cells contain:

    1-2

      The location of the top-left corner of the braille window. The row (counting from 1) is shown in the top half of the cells, and the column (counting from 1) is shown in the bottom half of the cells.

  Voyager

    The status cells contain:

    1

      The row (counting from 0) corresponding to the top of the braille window (see below).

    2

      The row (counting from 0) whereon the cursor is (see below).

    3

      If the screen is frozen (see the FREEZE command), then the letter `F`. If it isn't, then the column (counting from 0) wherein the cursor is (see below).

    Row and column numbers are shown as two digits within a single cell. The tens digit is shown in the top half of the cell, and the units digit is shown in the bottom half of the cell.
  It's initial setting is braille display driver dependent.

Notes:

- All time settings are in braille window refresh intervals (see the -M command line option). They are integers within the range 1 through 16.

## 3.8 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 the section Translation Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the DATA_DIR and the PREFIX make file variables for more details). See the ATTRTRANS make file variable 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 BRL_TARGET make file variable for the default established during the build procedure. This directive can be overridden with the -a command line option.

`braille-device` device

  Specify the device to which the braille display is connected. The full path must be supplied. See the BRLDEV make file variable 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.

`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 SPK_TARGET make file variable 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 the section Translation Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the DATA_DIR and the PREFIX make file variables for more details). See the TEXTTRANS make file variable for the default established during the build procedure. This directive can be overridden with the -t command line option.

## 3.9 Command Line Options

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

`-a`file `--attributes-table=`file

  Specify the attributes translation table (see the section Translation Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the DATA_DIR and the PREFIX make file variables for more details). See the attributes-table configuration file directive for the default run-time setting.

`-b`driver `--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 variable for the default run-time setting.

`-d`device `--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`.

`-f`file `--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.

`-l`level `--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.

`-p`file `--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`.

`-s`driver `--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.

`-t`file `--text-table=`file

  Specify the text translation table (see the section Translation Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the DATA_DIR and the PREFIX make file variables for more details). See the text-table configureation file directive for the default run-time setting.

`-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.

`-B`name`=`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:

  - All letters are in upper case.
  - Underscores (`_`) are used instead of minus signs (`-`).
  - The prefix `BRLTTY_` is added.
  This option allows BRLTTY to be configured via Linux 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_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).

`-M`csecs `--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.

`-P`file `--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.

`-R`csecs `--refresh-interval=`csecs

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

`-S`name`=`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.

`-X`name`=`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