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.
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.
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
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.
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. 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.
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: 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: underline cursor. This function switches the cursor shape: all eight dots (block) or just the bottom two (underline). Choose the one you prefer.
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: 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.
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. 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 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.
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.
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).
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.
BRLTTY has the following command line options. Use these to start BRLTTY using settings other than the defaults.
Use binary configuration file
config-file instead of brlttyconf.dat
.
Use serial-device to access
Braille terminal instead of the default (normally /dev/ttyS0
)
Use translation table
text-trans-file instead of the default of us.tbl
.
Print a brief help message and exit
Suppress start-up messages
Print start-up messages and exit
You can, of course, permanently configure the default settings of the first three options at compilation.