Previous Next Table of Contents

2. Using BRLTTY

Before you activate the system, you should set up your Braille display device. In most cases this is simple: just connect it to an appropriate serial port and turn the display on, if necessary selecting the serial interface.

Having set up your display, to run BRLTTY simply type the command brltty at a shell prompt (this must be done as root). The program will load and a message giving the program name (BRLTTY) and current version number will appear briefly on the display device. After this, the display will show a small area of the console screen including a cursor. By default the cursor is represented as dots 7 and 8 superimposed over the character it is on.

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

However, just typing and reading the display is not enough: try entering a command which will cause an error and press enter. The error will appear on the screen, but unless you have a multi line display, the chances are that the error message will not be visible on the Braille display, all you will see is another shell prompt. What is needed then is some means of moving the Braille window around the screen.

2.1 Basic Movement Keys

All commands to BRLTTY are given using the Braille keys on the Braille display. Unfortunately, there seems to be no standard set of controls available across different displays: some have six dot keys (like a Braille writing machine), others have thumb keys; some even have buttons above each character in the display. Some displays have all three types. Because the nature and layout of such keys is so varied, refer to the README file for your display for the keys you press for each operation. In this manual functions will be indicated by name.

Commands generally consist of a single Braille key or combination of Braille keys, which can be issued at any time BRLTTY is running. The most important commands are those which move the Braille window around the console screen. Most of them do not affect the console cursor, or any program you are running.

Moving Vertically:

TOP

Move to top of screen

BOT

Move to bottom of screen

WINUP

Move up several lines

WINDN

Move down several lines

LNUP

Move up one line

LNDN

Move down one line

PRDIFLN

Skip to the previous different line

NXDIFLN

Skip to the next different line

ATTRUP

Skip to the previous line that contains characters with different attributes from those on the current line. (NEW)

ATTRDN

Skip to the next line that contains characters with different attributes from those on the current line. (NEW)

Moving Horizontally:

LNBEG

Move to start of line

LNEND

Move to end of line

HWINLT

Move left half a window

HWINRT

Move right half a window

CHRLT

Move left one character

CHRRT

Move right one character

Moving Both Horizontally and Vertically:

TOP_LEFT

Move to top left of screen

BOT_LEFT

Move to bottom left of screen

HOME

Move window to cursor

FWINLT

Move left one window distance

FWINRT

Move right one window distance

The FWINLT and FWINRT keys can be used to read backwards and forwards, as they scroll to the previous or next line respectively if invoked from the end of a line. This makes them particularly useful when reading text.

If you do not remember a command, help is available using the HELP command. Use the movement keys as above to navigate the help screen and HELP again to quit.

The behaviour of the LNUP and LNDN keys depends on whether the skipping of identical lines is enabled, either by the SKPIDLNS key or from the configuration menu (see section The Online Configuration Menu). If this is enabled, they act like the PRDIFLN and NXDIFLN keys. (Note that the line containing the cursor is considered to be different from other lines.)

2.2 Modes

In addition to the commands above, BRLTTY offers many other useful features:

CSRTRK: Toggle cursor tracking

Default: on. When cursor tracking is on, movement of the console cursor will automatically adjust the display window position so that the cursor is always in the window. It is sometimes useful to turn this feature off so you can monitor a particular region of the screen easily.

DISPMD: Toggle attribute display

Default: off. If the attribute display is on, the attributes (colour information) of each character, rather than the characters themselves are displayed. It can be useful to turn attribute display on to enable detection of highlighted items.

FREEZE: Toggle screen freezing

Default: off. The freeze function exists to allow easy reading of changing screens. When you turn freeze on, the current screen contents are stored temporarily and any new screen activity is not reflected in the Braille. Remember to turn freezing off again when you wish to resume normal operation.

INFO: Status information

Default: off. The status function switches the display to the status screen. This shows information including the physical cursor position, the position of the start of the Braille display window and the settings of various flags. Some display types have some of this information permanently shown in their status cells. See the README file for information about your display.

The window start position and physical cursor position are displayed in the form cc:rr, where cc is the current column and rr is the current row. Then follows a series of flags:

  1. Cursor tracking. When on t, space otherwise
  2. Cursor visibility.
    v

    Cursor visible, no blink

    B

    Cursor is visible and blinking

    b

    Cursor not visible but blinking is on

    space

    Cursor not visible and blinking is off

  3. Display mode. a attribute, t text
  4. Screen state. f frozen, space live
  5. Braille representation, 6 or 8 dot
  6. Blinking capitals. B on, space otherwise

When in the status screen, all information may be updated by console screen activity or BRLTTY commands. Press INFO to return to normal operation.

2.3 Cursor Routing

It often happens that you are moving the display window around the screen examining the text in, say, a text editor and you want to move the physical cursor to where your window display is. Cursor routing provides just such a facility by simulating your keystrokes. Type CSRJMP and your cursor will be moved to the start position of the display window. Some Braille displays have buttons above each cell: these may also be used to move the cursor to that position. Others bind Braille keys to the cursor keys on the keyboard to allow a manual form of cursor routing.

Note: Cursor routing is not yet completely reliable. It currently uses hard-wired vt100 cursor key codes to move in the correct directions. Also, this may not work as well on heavily loaded systems (see config.h for further details).

Once you give a cursor routing command, BRLTTY will keep trying to route the cursor until either the cursor seems to go in the wrong direction or 2 seconds elapse without reaching the target position or you change virtual console. If you give another cursor routing command, BRLTTY gives up the first and attempts the second.

A new command, called CSRJMP_VERT, routes the cursor to anywhere on the current line without adjusting the horizontal position. This is especially useful within lynx as left and right arrow keys are never simulated.

2.4 Cut & Paste

This feature enables you to grab some text already on the screen and re-enter it at the cursor, thus saving time and avoiding errors when copying complicated text. It is particularly useful for items such as long filenames, complicated commands, E-mail addresses or long URLs.

First, mark the (rectangular) area on the screen to grab (cut): To mark the top left corner press CUTBEG. The top left corner of the marked area is set to the extreme left position of the window and the cut buffer is cleared. To mark the bottom right corner press CUTEND: the bottom right corner of the area to cut is set to the last position of the braille window and the area you defined is then copied into the cut buffer. BRLTTY removes excess white space at the end of each line in the cut buffer so you don't get extra spaces after your cut text. Some displays support more accurate cut & paste using the buttons above the Braille cells, see the README file for your display.

To paste the text, i.e. type it at the cursor position, press PASTE. You can paste the stored text any number of times without re-cutting it.

2.5 The Online Configuration Menu

When BRLTTY starts, it loads a configuration file from which it reads your preference settings. Several features of BRLTTY can be enabled, disabled or adjusted. BRLTTY has a simple menu from which you can change these settings conviniently. The menu is activated by pressing CONFMENU. The display will briefly show the menu title and then display the current item and parameter.

To move around in the menu, that is to go from an item to another, use the normal window movement keys as follows:

LNUP and LNDN:

move to the previous or next item in the menu;

TOP or TOP_LEFT or HOME:

move to the first item;

BOT or BOT_LEFT:

moves to the last item.

To adjust the setting of a parameter use FWINLT and FWINRT: this selects alternative setting options. To undo all the changes made since entering the menu use RESET.

To leave the menu and return to normal operation, press CONFMENU again, or any key not listed above. If the save config option is on, the current settings will be written to the configuration file.

Most of the parameters available through the menu can also be set using single key strokes (shortcut keys) to toggle them.

Here is a description of each configurable parameter. The shortcut keys that toggle certain parameters are also listed.

csr is visible (shortcut CSRVIS): Toggle cursor visibility

Default: on. This function, when enabled, shows the position of the cursor (either steady or blinking) on the display. It is sometimes useful to turn this function off to examine text where a cursor symbol only serves to obscure reading.

Block cursor (shortcut CSRSIZE): Toggle cursor shape

Default: off. This function switches the cursor shape: all eight dots (block) or just the bottom two (underline). Choose the one you prefer.

csr blink (shortcut CSRBLINK): Toggle blinking cursor

Default: off. If this function is enabled, the screen cursor will blink on the display, that is, it will only be present a portion of the time. When the cursor is off, you will be able to view the character beneath the cursor.

cap blink (shortcut CAPBLINK): Toggle blinking caps

Default: off. Similar to the cursor blinking function, if this function is enabled, capital letters will blink on the display. This is most useful when using 6 dot Braille.

attr vis (shortcut ATTRVIS): Toggle attribute underlining (NEW)

Default off. When this mode is enabled, any characters with non plain attributes (inverse video, color, highlighting...) will be emphasized by superimposing either dots 7-8 or just dot 8 on the braille character. A seperate function controls whether the superimposed dots blink or not. Text marked with dots 7-8 is not in the same attribute as text marked only with dot 8. This is still experimental.

attr blink (shortcut ATTRBLINK): Toggle blinking of attribute underlining

Default: on. This controls whether or not dots superimposed on characters with special attributes will blink or not.

csr blink on and csr blink off: Control rate of cursor blinking

These parameters are not toggles. The value of the settings for these items is an integer. Together, these parameters control the rate at which the cursor blinks (when the cursor is visible and blinking is enabled). The cursor will alternatingly be present (on) and absent (off). csr on specifies how long, in BRLTTY main loop cycles, the cursor will be present (stay on). Similarly, csr off specifies how long the cursor stays off. The duration of a blink round is therefore the sum on the csr on and csr off settings. The duration of a cycle of the main loop is variable: very roughly about 0.1 seconds. It may be helpful to set cursor, cap and attribute blinking to different rates.

cap blink on and cap blink off: Control rate of capital letters' blinking

This option works like the cursor blinking rate parameter.

attr blink on and attr blink off: Control rate of attribute underlining blinking

This option works like the cursor blinking rate parameter.

six dot text (shortcut SIXDOTS): Braille representation

Default: 8 dot. This function switches between 6 and 8 dot Braille codes. When 6 dot mode is chosen, the bottom dots (7 and 8) of all ordinary characters are removed.

sliding window (shortcut SLIDEWIN): Toggle sliding window

Default: off. This feature, in conjunction with cursor tracking, moves the display window more smoothly when the physical cursor moves beyond the right edge of the window. With sliding window off, whenever the cursor moves beyond the right edge of the window, the window moves by one window width. When on, the window moves by a quarter of this width.

skip ident lns (shortcut SKPIDLNS): Toggle skipping of identical lines

Default: off. This feature provides an alternative interface to line skipping on displays which do not provide the PRDIFLN and NXDIFLN keys. When enabled, it makes the LNUP and LNDN keys skip identical lines.

audio signals (shortcut SND): Toggle audio signals

Default: on. When on, BRLTTY beeps when certain events occur (such as moving beyond the edge of the screen). Beeps also confirm the settings of some toggle options.

st cells style: Set status cell style

The setting is an integer, rather than a toggle. This allows changing the style in which status cells are used. There is roughly a style for each brand of displays, which reflects the preferences of the programmer of the driver for that brand. However it is possible to try out the status cell style intended for another brand. However, not all styles work on all displays, since not all displays have the same number of status cells: if you try a style designed for more status cells than your display has, some information will be missing. Some displays have no status cells at all. The available styles are:

save config: Save configuration on exit

As indicated above, this controls whether or not the configuration should be saved to the configuration file upon exiting the configuration menu.

If save config is off or if you changed some settings by using shortcut keys, you may want to manually save the current settings to the configuration file. To do so, type SAVECONF.

The configuration file is currently a binary file and cannot be edited by hand.

To reload the configurable settings from the configuration file, press RESET.

2.6 Command Line Options

BRLTTY has the following command line options. Use these to start BRLTTY using settings other than the defaults.

-c config-file

Use binary configuration file config-file instead of brlttyconf.dat.

-d serial-device

Use serial-device to access Braille terminal instead of the default (normally /dev/ttyS0)

-t text-trans-file

Use translation table text-trans-file instead of the default. In VErsion 1.0.1 the default is compiled in; in previous versions the file us.tbl was loaded.

-h, --help

Print a brief help message and exit

-l n

Set debugging level for syslog to n (from 0 to 7, default 4)

-q, --quiet

Suppress start-up messages

-v, --version

Print start-up messages and exit

You can, of course, permanently configure the default settings of the first two options (as well as which text translation table to use as the default) at compilation.


Previous Next Table of Contents