System Requirements =================== The earliest release of Windows which is supported by BRLTTY is Windows 98. Pre-built versions of brltty are available for download on http://mielke.cc/brltty or on http://youpibouh.thefreecat.org/brltty/ In order to build BRLTTY yourself from a supplied tarball, you need either Cygwin (see [http://www.cygwin.com/]) or MinGW (see [http://mingw.sourceforge.net/]). In both cases, you also need the following additional packages: * gcc * make * w32api (version 3.6 or later) If you'd like to build BRLTTY from its source repository rather than from one of the supplied tarballs then you'll also need these additional packages: * autoconf * tcltk If you'd like to prepare the documentation (do make within the Documents/ subdirectory) you'll need these packages: * linuxdoc-tools (not pre-packaged in cygwin unfortunately) * doxygen If you are using MSYS for running configure and make, you should always use Windows paths (like c:/brltty), not MSYS paths (like /c/brltty), because brltty does _not_ understand MSYS paths. ------------------------------------------------------------------------------ Windows 98 and Me Limitation ============================ On Windows versions 2000, XP, 2003, and later, BRLTTY automatically accesses the Windows terminal which you're currently using as you switch between them. This isn't possible on earlier versions. One way to still achieve this functionality, however, is to run one BRLTTY (which directly accesses your braille display) on the root window and another one (which indirectly accesses your braille display via BrlAPI) on each terminal. This scheme may sound complicated, but it can be easily set up to run automatically. The first (or root) BRLTTY should be run as part of Windows startup. It must be given those options which are necessary to access your braille display, e.g. -b, -d, and all other options you'd normally specify. It must also be given the -Xroot=yes option, which attaches it to the root window. An additional BRLTTY should then be run for each new terminal. It should be invoked like this: brltty -bba -N The -bba option tells it to access the root BRLTTY via BrlAPI, and the -N option tells it not to start a BrlAPI server of its own. These BRLTTYs can be started automatically by, for example, adding this line to your .bashrc script. Each of these BRLTTYs takes care of the terminal it's running in, and connects, via BrlAPI, to the root BRLTTY in order to access your braille display. If you're not concerned with security, and would rather not fiddle with the brlapi.key file, then add the -Aauth=none option to the command line which invokes the root BRLTTY. You don't need to worry about unauthorized access over the network since the default is that only locally running programs can connect to BrlAPI. ------------------------------------------------------------------------------ Cygwin Package Management from the Cygwin Command Line ====================================================== A convenient way to manage Cygwin packages from the Cygwin command line is to use the "apt-cyg" tool. It is similar to the "apt-get" command which some Linux distributions use. As of the time of this writing, this is how you can install it: svn --force export http://apt-cyg.googlecode.com/svn/trunk/ /usr/local/bin/ chmod +x /usr/local/bin/apt-cyg If you're using the 64-bit Cygwin platform, then, after installing apt-cyg, you will need to make a couple of simple modifications to it. Using your favourite text editor, and remembering that the actual line numbers within your version may differ from those quoted below, edit /usr/local/bin/apt-cyg and make the following changes: 1) On line 98, change "$mirror/setup.bz2" to "$mirror/x86_64/setup.bz2". 2) On line 105, change "$mirror/setup.ini" to "$mirror/x86_64/setup.ini". To search for a package, you can do: apt-cyg find pattern To install a package, you can do: apt-cyg install name For full details, you can do: apt-cyg help ------------------------------------------------------------------------------ USB Support =========== USB devices are supported thanks to the libusb-win32 or libusb-1.0 packages. If both are installed, preferrence is given to libusb-1.0. Pre-built versions of brltty have USB support compiled in, and the required drivers are shipped, you just need to let the installer set them up. In order to build BRLTTY yourself with USB support enabled, _before_ compiling BRLTTY, you need to install at least one of libusb-win32 or libusb-1.0. At the time of this writing, libusb-win32 binaries can be found on [http://libusb-win32.sourceforge.net/]. The file will be called something like "libusb-win32-bin-.exe", and should be available on [http://sourceforge.net/project/showfiles.php?group_id=78138]. Unpack it in some place. As of the time of this writing, the libusb-1.0 binary snapshots can be found on [http://www.libusb.org/wiki/windows_backend]. The file will be called something like "libusb_.7z". Unpack it in some place. The Cygwin or MinGW toolchain then needs to get aware of the presence of libusb-win32 or libusb1.0-devel. For Cygwin: * Just install the libusb-win32 or libusb1.0-devel package. For MinGW: For libusb-win32: Symlink the header and library files into MinGW installation, run: + ln -s "/path/to/LibUSB-Win32/include/lusb0_usb.h" /mingw/include/usb.h + ln -s "/path/to/LibUSB-Win32/lib/gcc/libusb.a" /mingw/lib/ + ln -s "/path/to/LibUSB-Win32/bin/x86/libusb0_x86.dll" /mingw/bin/libusb0.dll Then you can configure, compile, install, and run BRLTTY as usual. For libusb-1.0: 1) Symlink the header and library files into MinGW installation, run: + ln -s "/path/to/Libusb-1.0/include/libusb-1.0" /mingw/include/ + ln -s "/path/to/Libusb-1.0/MinGW32/dll/libusb-1.0.dll.a" /mingw/lib/ + ln -s "/path/to/Libusb-1.0/MinGW32/dll/libusb-1.0.dll" /mingw/bin/ 2) Create a /mingw/lib/pkgconfig/libusb-1.0.pc file containing prefix=/mingw exec_prefix=${prefix} libdir=${prefix}/lib includedir=${prefix}/include Name: libusb-1.0 Description: C API for USB device access from Windows userspace Version: 1.0 Libs: -L${libdir} -lusb-1.0 Cflags: -I${includedir}/libusb-1.0 Then you can configure, compile, install, and run BRLTTY as usual. To actually be able to use the libusb-win32 driver, you need to copy the runtime files in the brltty source. + cp "/path/to/LibUSB-Win32/bin/x86/libusb0.sys" brltty/hotplug/libusb0.sys + cp "/path/to/LibUSB-Win32/bin/x86/libusb0_x86.dll" brltty/hotplug/libusb0.dll + cp "/path/to/LibUSB-Win32/bin/amd64/libusb0.sys" brltty/hotplug/libusb0_x64.sys + cp "/path/to/LibUSB-Win32/bin/amd64/libusb0.dll" brltty/hotplug/libusb0_x64.dll and then right-click on brltty/hotplug/brltty.inf and select install, or on braille device plug, point at the brltty/hotplug/brltty.inf file. To actually be able to use the libusb-1.0 driver, right-click on brltty/hotplug/brltty-libusb-1.0.inf and select install, or on braille device plug, point at the brltty/hotplug/brltty-libusb-1.0.inf file. ------------------------------------------------------------------------------ Configuring BRLTTY ================== Some of BRLTTY's configure options are of particular interest to users of the Windows platform: --enable-relocatable-install: The default is for BRLTTY to refer to its components via absolute paths. On the Windows platform, however, the convention is for a package to use relative paths so that it can be installed into an arbitrary directory and so that it can be moved around thereafter as well. This option builds BRLTTY such that relative paths are used. ------------------------------------------------------------------------------ Missing Java Class Definitions on Cygwin ======================================== You may get a Java failure which looks like this: Exception in thread "main" java.lang.NoClassDefFoundError: org.eclipse.jdt.internal.compiler.batch.GCCMain at gnu.java.lang.MainThread.run(Unknown Source) Caused by: java.lang.ClassNotFoundException: org.eclipse.jdt.internal.compiler.batch.GCCMain not found in gnu.gcj.runtime.SystemClassLoader {urls=[], parent=gnu.gcj.runtime.ExtensionClassLoader{urls=[], parent=null}} This problem occurs when the java-ecj package isn't installed. It can be obtained from Cygwin Ports. You can also resolve the probem by downloading the file "ftp://sourceware.org/pub/java/ecj-4.5.jar", and installing it into "/usr/share/java/ecj.jar". ------------------------------------------------------------------------------ Sticking to a console ===================== It may be useful to have BRLTTY only review the console it is started in, i.e. for it not to follow the keyboard focus. To achieve this, set the FollowFocus parameter of the Windows screen driver to no. This can be done either on the command line (-XFollowFocus=no) or in brltty.conf (screen-parameter FollowFocus=no). ------------------------------------------------------------------------------ Sharing the Braille Display with Other Screen Readers ===================================================== When you're not on a window which BRLTTY can handle its default action is to retain control of the braille display and to present a brief message explaining the problem. If you have another braille-capable screen reader and would like it to take over instead then both BRLTTY and that other screen reader must be instructed to share the braille display. BRLTTY can be instructed to share the braille display via its --release-device option; the short form of this option is -r. When this option is in effect BRLTTY releases the braille display when you move onto a window which it cannot handle and tries to regain control of the braille display when you move onto a window which it can handle. Note that these actions take a noticeable amount of time so you should only use this option if it's actually needed. ------------------------------------------------------------------------------ Sharing BRLTTY with JAWS ======================== A common case wherein a JAWS user might want BRLTTY to be in control of the braille display is when using Cygwin. There are two phases to configuring JAWS to run in the background while BRLTTY controls the braille display. First, the window title must be established and stable. Second, JAWS braille must be put to sleep. What is a window title? ----------------------- Every window in Windows has a title bar that contains the name of the application which is running in it as well as some controls to do things like move and resize it. BRLTTY does not show this title bar. For a program window, JAWS uses the name of the program's executable as the name of the configuration files to load when that program gains focus. For a console application such as Cygwin, however, it uses the title of the window instead. We must, therefore, tell JAWS within the window title that this is a Cygwin window. Setting the Window Title ------------------------ JAWS uses one of the words in the window title as the name of the configuration files to load. This file set is what tells JAWS the specifics of how to handle the application. It is, therefore, where JAWS must be instructed to put its braille component to sleep. At this writing, it appears that JAWS uses the following algorithm for choosing which word in the title to use as the name of the file set: 1) If there are no slashes (/) or backslashes (\) in the title then JAWS uses the first word. Thus, if the title is "Cygwin Bash Shell" then JAWS will load the Cygwin configuration files. 2) If there is at least one slash (/) or backslash (\) in the title then JAWS uses the last word. Thus, if the title is "$PWD - Cygwin" then JAWS will similarly load the Cygwin configuration files. Setting Cygwin's Window Title ----------------------------- First, it is imperative that you replace, or at least modify, the default PS1 (primary shell prompt) setting. The default for this setting, as distributed by Cygwin, places $PWD (the path to the current working directory) in the window title, thus requiring you to have a separate JAWS configuration for every directory on the system! One possible way to resolve this problem is to uncomment the `settitle' function which can be found near the end of `.bashrc'. This function allows you to place a string of your own choice in the title. You can use this function, therefore, as follows: export PROMPT_COMMAND='settitle "$PWD - Cygwin"' export PS1='$ ' The first of these lines causes the window title to be set just before each shell prompt. Since $PWD always contains at least one slash (/), the operative word is `Cygwin' (the last word), and JAWS will load any Cygwin configuration files that it finds. The second of these lines sets the primary shell prompt to the customary dollar sign ($). More importantly, though, it replaces Cygwin's default PS1 setting which contains escape sequences that overwrite the window title with just $PWD thus not presenting any permanent text for JAWS to recognize. Putting JAWS Braille to Sleep ----------------------------- Now that a stable window title has been established, JAWS braille can finally be put to sleep. While in Cygwin and with BRLTTY not running, do the following: 1) Press Insert+F2 to bring up the Run JAWS Manager dialog. 2) Down-Arrow to Configuration Manager and press Enter. Verify that the title on the top line contains "Cygwin.jcf". 3) Press Alt+S for Set Options. 4) Press B for Braille. 5) Press S for Braille Sleep Mode. 6) Verify that the box is checked (it should look like instead of < >). Press Space to toggle the setting if the x isn't there. 7) Press Enter to leave the menu. 8) Press Control+S to save the file. 9) Press Alt+F4 to exit the configuration manager. Putting JAWS Speech to Sleep ---------------------------- If you want to use JAWS speech in Windows but not in Cygwin, you can do the following: 1) Press Insert+F2 to bring up the Run JAWS Manager dialog. 2) Down-Arrow to Configuration Manager and press Enter. Verify that the title on the top line contains "Cygwin.jcf". 3) Press Alt+S for Set Options. 4) Press A for Advanced. 5) You should be on an item labelled "Sleep Mode Enable" with an empty check box (< >). Press Space to check it (). 6) Press Enter to leave the menu. 7) Press Control+S to save the file. 8) Press Alt+F4 to exit the configuration manager. Performance ----------- You'll always be able to switch to Cygwin, and BRLTTY, if running, will take control of the braille display automatically. Switching back to Windows and JAWS may be a bit more problematic, though ... the degree of success seems to depend on the type of braille display being used. Sometimes it works properly. Sometimes, with a USB display, the cable must be unplugged/replugged to allow JAWS to regain control. In extreme cases you may need to exit BRLTTY before going to Windows. ------------------------------------------------------------------------------