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.
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.
Move to top of screen
Move to bottom of screen
Move up several lines
Move down several lines
Move up one line
Move down one line
Skip to the previous different line
Skip to the next different line
Skip to the previous line that contains characters with different attributes from those on the current line. (NEW)
Skip to the next line that contains characters with different attributes from those on the current line. (NEW)
Move to start of line
Move to end of line
Move left half a window
Move right half a window
Move left one character
Move right one character
Move to top left of screen
Move to bottom left of screen
Move window to cursor
Move left one window distance
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.)
In addition to the commands above, BRLTTY offers many other useful features:
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.
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.
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.
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:
t
, space otherwisev
Cursor visible, no blink
B
Cursor is visible and blinking
b
Cursor not visible but blinking is on
Cursor not visible and blinking is off
a
attribute, t
textf
frozen, space liveB
on, space otherwiseWhen in the status screen, all information may be updated by console screen activity or BRLTTY commands. Press INFO to return to normal operation.
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.
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.
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:
move to the previous or next item in the menu;
move to the first item;
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.
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.
Default: off. This function switches the cursor shape: all eight dots (block) or just the bottom two (underline). Choose the one you prefer.
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.
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.
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.
Default: on. This controls whether or not dots superimposed on characters with special attributes will blink or not.
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.
This option works like the cursor blinking rate parameter.
This option works like the cursor blinking rate parameter.
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.
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.
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.
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.
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:
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.
BRLTTY has the following command line options. Use these to start BRLTTY using settings other than the defaults.
-c
config-fileUse binary configuration file
config-file instead of brlttyconf.dat
.
-d
serial-deviceUse serial-device to access
Braille terminal instead of the default (normally /dev/ttyS0
)
-t
text-trans-fileUse 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
nSet 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.