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
