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

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.

2.2 Other Controls

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.

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 proportion of the time. When the cursor is off, you will be able to view the character beneath the cursor.

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.

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.

CSRSIZE: Toggle cursor shape

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

BRLDOTS: 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.

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.

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.

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 does not work well on heavily loaded systems (see config.h for further details).

Once you give a cursor routing command, BRLTTY will spend a pre-defined amount of time attempting to carry out your instruction, before finally giving up if unsuccessful. The default timeout is 4 seconds. At present, any further commands you issue will only be carried out after the timeout has elapsed---we may implement a `quit' command to abort cursor routing in a future release.

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. It is particularly useful for items such as long filenames or complicated commands.

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

BRLTTY has a simple menu from which you can change some of the settings. The menu is activated by pressing CONFMENU. The display will briefly display the menu title and then display the current parameter.

To move around in the menu, use the normal window movement keys as follows: LNUP and LNDN move up and down the menu; TOP and HOME move to the start; BOT moves to the end. To adjust the setting of a parameter use FWINLT and FWINRT. To undo all the changes made since entering the menu use RESET.

Many of the parameters available through the menu can also be set using single key strokes to toggle them (see above). In addition, the menu allows you to configure the speeds of the blinking features.

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

2.6 Storing the Current Configuration

When you load BRLTTY, a configuration file is loaded to determine the settings of the features available through the configuration menu. You can save the current settings back to the configuration file using SAVECONF; this automatically happens when you exit the menu if the save config option is on. The configuration file is currently a binary file.

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

2.7 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 of us.tbl.

-h, --help

Print a brief help message and exit

-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 three options at compilation.


Previous Next Table of Contents