This is the BRLTTY driver for TSI braille displays,
Version 2.74 April 2004

Author and maintainer:
        Stéphane Doyon
E-Mail: s.doyon@videotron.ca

This driver contains the code to support most of Telesensory Systems' braille
displays. It is a part of the source code for BRLTTY. The information here
pertains only to the support of the TSI displays. You must also read the
documentation of the main module of BRLTTY.

There is only a handful of BRLTTY users. If you are trying out my driver,
please let me know! I am willing to help and I am open to suggestions.

See the headers of brl.c for history notes.

Supported braille displays
==========================
  Navigator 20 / 40 / 80 (latest firmware version only?)
  PowerBraille 40 / 65 / 80

Unsupported displays:
  Older firmware versions of the navigator models may not work.

I have used older versions of this driver every day for over two years with a
Navigator 40, so I can say that BRLTTY and this driver are pretty stable.
Since version 2.0 of this driver, I have integrated support for PB80
displays. I have used a PowerBraille 80 for nearly a year now, and a
PowerBraille 40 for a few months. I have had success reports from about 10
other people (most of them use a PowerBraille 40). Navigator 40 has not been
tested since version 2.1 of this driver (I changed my Navigator 40 for a
PowerBraille 40). Navigator 20 and 80 should work but has never been tested.

I am currently trying to debug support for two emulators of the
PowerBraille 40. 
- BAUM displays (Vario?): This display emulates a PowerBraille 40. However,
    it cannot operate at 19200baud as PowerBraille models can. The driver
    now detects this and falls back to 9600baud. I don't know much about
    BAUM display models. I have had two success reports but also one failure
    report.
- mdv mb408s: This display also emulates a PowerBraille 40 and it too is
    capable of operating only at 9600baud. However it also has additional
    timing constraints. Please uncomment the FORCE_FULL_SEND_DELAY option 
    in braille.h before compiling. This has been tested by only one person.
However with both these emulators, there is another limitation: the key
configurations are not the same as that of any TSI model and some key
combinations for certain commands may be difficult or impossible to
reproduce. Specific drivers need to be written for these models, and efforts
are under way. Until then, the driver remains useful and at least partly
functional even with this limitation.

For impatients
==============

If you really want to go ahead right now without further reading, well then
go for it: no special configuration is really necessary. All you have to know
is the key to bring up the help screen:
  - For navigator users: press the "cursor left" and "cursor right" keys
    together.
  - For PB40 users: press the first and the last cursor routing keys
    together (cursor routing keys 1 and 40).
  - For PB65/80 users: Press cursor routing keys 1 and 80 together, or press
    the two small square buttons on top and to the left of the display.

Connecting the display
===========================

Navigator users should connect their displays the same way as they do
for use under DOS. PowerBraille users however might require additional
instructions.

This driver only supports the serial interface to the PowerBraille: you
cannot use its parallel port. You will therefore need a serial cable to
connect your PowerBraille to your computer. The cable must be "straight
through" (not "null-modem"). Connect one end to one of the COM ports of
your computer and the other to the DCE port (the 9-pin female connector)
on the PowerBraille.

Configuration of the driver
===========================

The file braille.h contains some few parameters specific to this driver
which you can modify, but you really don't have to. No adjustments are
necessary: everything will be autodetected by the driver when you start BRLTTY.

PowerBraille displays can operate at 19200 baud. If you don't trust your serial 
port to operate at that speed (for example, if you're using DOS), you can 
disable this feature with the HighBaud=no driver parameter, and crawl at 9600 
baud.

The HighBaud= driver parameter specifies whether or not the driver is permitted 
to use 19200 baud. It can be set to either yes (the default) or no. Note that 
if this parameter is set to no but the display has been configured to operate 
at 19200 baud then it won't be autodetected.

The SetBaud= driver parameter specifies which baud is to be used. It can be set 
to 4800, 9600, or 19200. The default is to use 19200 baud if the display 
supports it or to use the baud at which the display was autodetected if it 
doesn't.

You usually won't need to specify any of these driver parameters. A case where 
you would, though, is if you're using a PowerBraille on DOS because DOS 
doesn't support higher than 9600 baud. In this situation, you'll want to 
specify the HighBaud=no driver parameter. You'll still have a problem, though, 
if the PowerBraille is currently configured to use 19200 baud. If this is the 
case, first connect it to a system that does support 19200 baud and specify the 
SetBaud=9600 driver parameter. So, for example:

   on Linux: -B SetBaud=9600
   on DOS: -B HighBaud=no

Note that braille driver parameters can be specified either via the -B 
(uppercase) command line option or via the braille-parameters brltty.conf 
directive. The format is name=value. So, for example:

   on the command line: -B HighBaud=no
   in brltty.conf: braille-parameters HighBaud=no

Initialization and reset
========================

When BRLTTY is started, it will call a function within this driver to detect
and initialize a braille display. If none is connected, then the whole
BRLTTY process will sleep until a braille display is connected and turned on.
Immediately, it will be detected, identified, initialized, and updated with
a welcome message, and then with some text from the screen. It will then be
ready for use.

This means that your braille display need not be active when your machine
boots (when BRLTTY starts up).

Furthermore, you may also turn off your display at any time while BRLTTY is
running, take it away for the day while your computer is still running, and
connect it back later. After 2 or 3 seconds, BRLTTY will realize that the
display is off or disconnected. It will then go back to waiting for you to
connect it and turn it on, at which point it will reinitialize it.

Key bindings
============

The online help describes the key bindings: for each available function, the
display key or combination of keys that activates it is listed. For details
on the functions themselves, see the documentation of the main module of
BRLTTY. Here again is how to bring up the help screen:
  - For navigator users: press the "cursor left" and "cursor right" keys
    together.
  - For PB40 users: press the first and the last cursor routing keys
    together (cursor routing keys 1 and 40).
  - For PB65/80 users: Press cursor routing keys 1 and 80 together, or press
    the two small square buttons on top and to the left of the display.

I am open to suggestions. If you don't like the help screen, if you find the
names of the keys confusing, if you find an inconsistency or if you just don't
like the bindings I have chosen, send me your comments. It is not very hard to
change which keys trigger which function. I have tried to come up with the
best arrangement but you might have a better idea.

If any of the keys mentioned in the help screen do not work or are somehow
inconsistent, please let me know.

In general the key bindings are the same for all the displays, Navigator
and PowerBraille models alike. The Navigator 80 and the PoewrBraille 40 simply
have some added key bindings to take advantage of their routing keys.
Furthermore, certain key combinations that can conveniently be pressed on
the Navigator 20/40 cannot be entered on a PowerBraille since it does not
have the cursor left/right keys and since it uses rockers instead of button
pairs.

But you do not have to worry, since the help screen that is provided will
vary according to the model of the display that is detected. In fact, the
first line of the help screen identifies the display model that was detected.
If this is incorrect, then you're in trouble and you should contact me!

I've tried to keep key bindings similar to what is used under DOS, but there
are several differences. Basic movement of the braille display is the
same, but several bindings have been added for more elaborate
functionalities. You also have those keys that are mapped to the keyboard
arrow keys, but I did not think it was really relevant to have a key act as the
RETURN key. Also the link/unlink button does not exactly work the same: the
rightmost of the front middle buttons simply jumps to the cursor; it is not
a toggle. The left button toggles the link/unlink (whether or not the braille
display should follow the cursor if it moves), but unlinking the braille
display from the cursor can be done without bringing the braille window back
to the cursor beforehand.

Also note that there is no function to combine lines and wrap words...
There is however a function to skip identical lines.

For Navigator 20/40 users:
    You will find one interesting addition to cursor routing: now you do not
only have a function that routes the cursor to the beginning of the display,
you also have another function that brings it somewhere towards the end of
the display. I find it quite useful. BRLTTY also supports a cut-and-paste
functionality that can be triggered from the braille display. This has
forced me to add a very strange twist to the interface. Users of braille
displays with cursor routing keys normally will mark text to be cut/copied
by using some combination of these routing keys. Since we don't have them,
I've added a key binding that brings you into a special mode in which a
"virtual" cursor appears. By moving that special cursor around you can mark up
the start of the text to cut. As soon as this mark is made, you are returned
to the normal mode of operation. You can then move to the end of the
text to mark, reactivate the special cursor mode, and mark the end of the
text. At that point the text will by copied in a buffer, and you'll be able to
paste it wherever you want. Note that there also are two shortcut keys to do
cut & paste: one combination states that the block of text to be copied starts
at the beginning of the display and the other states that the block of text
ends at the end of the braille display. Just experiment with it in an editor.
you'll see it's great! Mail me if you're mixed up.

For Navigator 80 / PowerBraile users:
    You will find that several key bindings use combinations of cursor
routing keys. You may not be used to that. In particular the cut-and-paste
functions, used to mark the start and the end of a block of text to be
copied, uses combinations of three keys. One more thing so that you don't get
confused: it is impossible to mark the beginning of a block of text to
cut/copy in the last two cells of the braille display, and it is impossible
to mark the end of a block in the first two cells. There is a function that
allows movement of the braille window by only a few characters left or
right: this usually suffices to get around this limitation. Again if you
have suggestions as to what would be most convenient, do not hesitate to
contact me.

Credits
=======

Thanks to Jason Fayre (I don't have his current address) for his patient help
in getting PowerBraille 40 support working: he tested each version of the
PowerBraile support until it worked. I myself did not have access to a PB40.
We worked over E-mail.

Thanks to Nicolas Pitre <nico@fluxnic.net> for extensive help writing the very
first version of this driver. Initially, this code was derived from that of
the driver for the Alva ABT40. Surprising how little they have in common now.

-------------------------------------------------------------------------------
Well that's about it! Try it out and do let me know how it goes PLEASE!

Hope this is of use to you!
