README for the Alva Braille Driver

Version 2.2 (March 4, 2004)


Copyright
=========

This driver is copyrighted under the GNU General Public License. It is free 
software.  Visit www.gnu.org for more details.


Supported Hardware
==================

This driver is intended to work with any Alva braille display from the ABT3 
(3nn), Delphi (4nn), Satellite (5nn), and Braille Controller (6nn) series. It 
recognizes the 320, 340, 34d, 380, 382, 38D, 420, 440, 44d, 480, 544, 544t, 
570p, 584p, 620, 632, 640 and 680; other models can be easily added. The 
serial, USB, and Bluetooth protocols are supported; the parallel port is not. 
This driver even supports the old (single byte) protocol for ABT3nn models. 
Keypad and spacepad support are not implemented since I don't have them and 
have no idea regarding their use.

Since I have an ABT340, I've personally tested the driver on that model only, 
with both the old (single byte) and the new (double byte) protocols. The 
instructions provided in this file might, therefore, not necessarily be 
accurate for all supported models.

If you want any information about Alva and its products, you should look at the 
web site [http://www.optelec.com/].


ABT Connection
==============

This driver supports serial, USB, and Bluetooth communication only. Some 
parallel port communication was previously supported, but, since that support 
was based on a non-GPL compatible and binary only library, it has been removed.  
When/if someone can help with providing us with the proper protocol 
information, we'll be pleased to write an open source parallel port driver in 
conformance with BRLTTY's license.

With serial communication, the ABT serial port must be set to alva-mode (the 
default); see the description of 'Local Mode' in the ABT manual. The ABT serial 
port has the same connections as the standard 9-pin serial port of an IBM PC. 
Therefore, a cable connecting the ABT with a PC must have the following wires:

9 pin (ABT)        9 pin (PC)   or    25 pin (PC)

1                  1                  8 (CD)
2                  3                  2 (TD)
3                  2                  3 (RD)
4                  6                  6 (DSR)
5                  5                  7 (GND)
6                  4                  20 (DTR)
7                  8                  5 (CTS)
8                  7                  4 (RTS)
9                  9                  22 (RI)

This kind of cable is called a "null modem" (or "cross over") cable. All 
connectors are female D connectors.

NOTE: I experienced some problems using the serial port while the computer was 
connected to the parallel port on the ABT. If BRLTTY seems to work but exhibits 
strange behaviour, just make sure there's nothing plugged into the parallel 
port connector. At least give it a try ... it might help.


Before Compiling
================

Firmware Version 
---------------- 

Look in the file braille.h for a section identified as "User Settings".  You 
have to define ABT3_OLD_FIRMWARE to 1 (0 by default) if your firmware version 
is older than 010495. To get your firmware version, simply turn your ABT on 
while not connected to your computer. The last digits that will appear on the 
braille display are the firmware version. If the wrong firmware version support 
is compiled in, you won't have access to your ABT control keys. If you have a 
firmware version dated 010495 or later, you normally don't have to edit 
braille.h since support for the new firmware is the default.

ABT Model
---------

Because new firmware is assumed, the terminal model is set to "autodetect" by 
default. Specific model selection is optional with the new firmware version. If 
you have the old firmware version use the line "#define MODEL" with either 
ABT320, ABT340, ABT380, ABT34D or ABT38D.  ABT_AUTO is for autodetection (use 
only with the new firmware version).

Port Specification
------------------

Brltty's default port is usb:. If you need to specify something else please 
follow the suggestions below.

There are a number of ways to specify the port on the PC to which the display 
is connected. Here's a summary, although you should check BRLTTY's manual for 
all of the details.

The default protocol is USB. If you'd like your brltty executable to have its 
own unique default port then use the --with-braille-device= option of the 
configure script in BRLTTY's top-level directory at build-time. If you'd like 
your system to have its own unique default port regardless of which brltty 
executable is being used then use the braille-device directive of BRLTTY's 
configuration file (usually "/etc/brltty.conf"). If you'd like to specify a 
specific port when invoking brltty then use the -d (or --braille-device=) 
command line option.

For a serial port, specify "serial:/path/to/device". The "serial:" qualifier is 
optional (for backward compatibility). If a relative path is given then it's 
anchored at "/dev" (the usual place that devices are found on a Unix-based 
system). The following device specifications all refer to the primary serial 
port on Linux:

   serial:/dev/ttyS0
   serial:ttyS0
   /dev/ttyS0
   ttyS0

For a USB port, specify "usb:". BRLTTY will search for the first USB device 
which matches the braille display driver being used. If this is inadequate, 
e.g. if you have more than one USB braille display which require the same 
driver, then you can refine the device specification by appending the serial 
number of the display to it, e.g. "usb:12345".

Serial Port Settings
--------------------

The serial port configuration is defined in the braille.h header file.

By default, the ABT communicates at 9600 BPS. Although I've run it at a higher 
rate, the possibility of getting communication errors increases. If you change 
the rate in braille.h, you must also change it in the local menu of your ABT.


Running the Driver
==================

Please refer to BRLTTY's documentation for instructions on compiling and 
selecting the Alva driver. To verify which driver is being used (for example, 
if no braille appears on the display) try the following (these commands are 
for Bash):

   clear && killall brltty && brltty -v && brltty

Add any required parameters (such as -bal) to the last two commands. Remember 
that the ABT keys won't work if you have the wrong firmware version set up 
(although some braille should be displayed anyway). You may run BRLTTY even if 
no braille display is plugged into the appropriate port. BRLTTY will wait for 
it.

Key Bindings
============

All the key definitions are listed in the key bindings configuration files 
(usually found in /etc/brltty/brl-al-*). Each file corresponds to an Alva 
model. For more information on the functions listed, see the BRLTTY manual. 
Basic keys are nearly the same as with the DOS software. For a quick start, 
enter the help screen by:

   3nn and 4nn models: press the PROG key.
   5nn models: press the left outer key of the right satellite keypad.
   6nn models: press both rear ETouch keys together.

Enter interactive command learn mode by:

   5nn models: press the right outer key of the right satellite keypad.
   6nn models: press the  left rear and right front ETouch keys together.

Some keys found on the ABT34D, ABT380, and ABT38D are not currently bound to 
any functions (because I don't have those keys). However, it is pretty easy to 
add them in the code. See the function brl_readCommand() and/or send me your 
suggestions.


Status Cells
============

Some models have three hardware status cells to the left of the text display 
area. Some have five hardware status cells, and some have none. As with most 
braille displays, the specific contents of these cells can be specified in the 
Preferences menu. The following describes the default assignments for those 
models with hardware status cells:

The first three cells are used for status information as with the DOS software, 
except for the third one which has the following meanings:

   t = cursor tracking active
   f = screen is frozen
   a = the display is in attribute mode

All three status cells display "hlp" when the help screen is active, "lrn" when 
interactive command learn mode is active, "prf" when the preferences menu is 
active, and "inf" when info mode is active.

Some models have five status cells rather than three. On these, the last two 
cells are currently not used.


Nicolas Pitre <nico@fluxnic.net>
March 4, 2004
