The earliest release of Windows that is supported by BRLTTY is Windows 98.
Pre-built versions of BRLTTY are available for download on BRLTTY's Web Site. Their names begin with brltty-win-. Those with the .zip extension are archives, and those with the .exe extension are installers.
In order to build BRLTTY yourself from a prepared source tarball, you'll need Cygwin (see Cygwin's Web Site) and/or MinGW (see MinGW's Web Site). You'll also need the following additional packages:
If you'd like to build BRLTTY from its source repository (rather than from one of the prepared source tarballs) then you'll also need these packages:
If you'd like to prepare the documentation (by doing make within the Documents/ subdirectory) then you'll need these packages:
If you're using MSYS (the MinGW command shell) for running configure and make, you should always use Windows-like paths (e.g. c:/brltty) rather than MSYS paths (e.g. /c/brltty) because BRLTTY does not understand MSYS paths.
On Windows versions 2000, XP, 2003, and later, BRLTTY automatically accesses the Windows console that you're currently using as you switch between them. This isn't possible on earlier versions. One way to still achieve this functionality, though, is to run one BRLTTY on the root window that directly accesses your braille device, and another one on each console that indirectly accesses your braille device via BrlAPI. This scheme may sound complicated, but it can be set up to run automatically.
The first (or root) BRLTTY should be run as part of Windows startup. It must be run with the options that are necessary for it to access your braille device, e.g. -b (to specify the driver), -d (to specify the device), and (maybe) -B (to specify driver-specific parameters). It must also be given the -Xroot=yes option (which attaches it to the root window).
An additional BRLTTY must then be run for each new console. 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 (non-root) BRLTTYs can be started automatically by, for example, invoking them from your .bashrc script. Each of these BRLTTYs only reviews the console it's running within, and connects, via BrlAPI, to the root BRLTTY in order to access your braille device.
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 that starts 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.
A convenient way to manage Cygwin packages from the command line is to use the apt-cyg command. It's 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'll 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 shown below, edit /usr/local/bin/apt-cyg and make the following changes:
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
A convenient way to manage MinGW packages from the command line is to use the mingw-get command. Be sure to invoke it with arguments because when invoked with no arguments its graphical interface is used.
To list all of the packages, you can do:
mingw-get list
To install a package, you can do:
mingw-get install name
For full details, you can do:
mingw-get -h
USB devices are supported thanks to the LibUSB-Win32 and the 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 Windows drivers are also included, so you just need to let the installer set them up.
In order to build BRLTTY yourself with USB support enabled, you'll need to first install at least one of LibUSB-Win32 or LibUSB-1.0.
At the time of this writing, LibUSB-Win32 binaries can be found on LibUSB-Win32's Web Site. They'll be named something like libusb-win32-bin-<version>.exe, and should be available on http://sourceforge.net/project/showfiles.php?group_id=78138.
On Cygwin:
On MinGW:
Unpack the archive somewhere.
Symlink the header and library files into your MinGW installation:
ln -s LibUSB-Win32/include/lusb0_usb.h /mingw/include/usb.h ln -s LibUSB-Win32/lib/gcc/libusb.a /mingw/lib/ ln -s LibUSB-Win32/bin/x86/libusb0_x86.dll /mingw/bin/libusb0.dll
In order to be able to use the LibUSB-Win32 driver, you'll need to copy its run-time files into BRLTTY's source tree:
cp LibUSB-Win32/bin/x86/libusb0.sys brltty/hotplug/libusb0.sys cp LibUSB-Win32/bin/x86/libusb0_x86.dll brltty/hotplug/libusb0.dll cp LibUSB-Win32/bin/amd64/libusb0.sys brltty/hotplug/libusb0_x64.sys cp LibUSB-Win32/bin/amd64/libusb0.dll brltty/hotplug/libusb0_x64.dll
Then, either right-click on brltty/hotplug/brltty.inf and select install, or, on braille device plug, point at the brltty/hotplug/brltty.inf file.
As of the time of this writing, LibUSB-1.0 binary snapshots can be found on LibUSB-1.0's Web Site. They'll be named something like libusb_<date>.7z.
On Cygwin:
On MinGW:
Unpack the archive somewhere.
Symlink the header and library files into your MinGW installation:
ln -s LibUSB-1.0/include/libusbx-1.0 /mingw/include/libusb-1.0 ln -s LibUSB-1.0/MinGW32/dll/libusb-1.0.dll.a /mingw/lib/ ln -s LibUSB-1.0/MinGW32/dll/libusb-1.0.dll /mingw/bin/
Copy the file libusb-1.0.pc in the Windows/ subdirectory of BRLTTY's source tree into MinGW's /mingw/lib/pkgconfig/ directory. If the pkgconfig/ subdirectory doesn't already exist then create it.
In order to be able to use the LibUSB-1.0 driver, you'll need to either 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.
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's entirely self-contained. This enables it to be installed into an arbitrary directory, and to be moved around thereafter at well. This option builds BRLTTY such that relative paths are used. | |
You may get a Java failure that looks something 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 the Cygwin Ports. You can also resolve the problem by downloading the Cygwin java-ecj jar, and installing it into /usr/share/java/ecj.jar.
These .bat scripts are in the top-level folder where BRLTTY has been installed. They should be run by a user that has administrative privileges.
Manually run BRLTTY with a log level of info. Logs are written to the file brltty.log in the top-level folder where BRLTTY has been installed. All arguments are passed through to BRLTTY.
Manually run BRLTTY, via the run-brltty.bat script, with options that set the log level to debug and enable several useful log categories. All arguments are passed through to the run-brltty.bat script.
Forceably terminate the manually-run BRLTTY process.
Install the BrlAPI service and start it.
Stop the BrlAPI service and uninstall it.
It may be useful to have BRLTTY only review the console that it's started in, i.e. for it not to follow the keyboard focus. To achieve this, set the FollowFocus parameter of BRLTTY's Windows screen driver to no. This can be done:
When you're not on a window that BRLTTY can handle, its default action is to retain control of the braille device and to present a short 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 device.
BRLTTY can be instructed to share the braille device via its --release-device option (the short form of this option is -r). When this option is in effect, BRLTTY releases the braille device when you move onto a window that it can't handle, and then tries to regain control of the braille device when you move onto a window that 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.
A common case wherein a JAWS user might want BRLTTY to be in control of the braille device when on a console window is when using Cygwin.
There are two phases to configuring JAWS to run in the background while BRLTTY controls the braille device. First, a usable 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 that's running in it, as well as some controls to do things like move and resize the window. BRLTTY doesn't 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. You 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 file set 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.
As of 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:
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 in the title will be Cygwin (the last word), and JAWS, therefore, 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, because it contains escape sequences that overwrite the title with $PWD, renders the window unrecognizable by JAWS.
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:
Putting JAWS Speech to Sleep
If you'd like to use JAWS speech in Windows, but not in Cygwin, you can do the following:
Known Problem
You'll always be able to switch to Cygwin, and BRLTTY (if it's running) will take control of the braille device automatically. Switching back to Windows and JAWS, however, may be problematic. The degree of success seems to depend on the type of braille device being used. It usually works properly. Sometimes, however, when using a USB device, the cable needs to be unplugged/replugged to allow JAWS to regain control. In extreme cases, you may need to exit BRLTTY before going to Windows.
The mkwin script, which can be found in the Windows/ subdirectory of BRLTTY's source tree, builds the Windows archive and installer for BRLTTY.
Links to the pages where we found these installers, components, and files are listed. In case any of these links becomes out-of-date, however, copies of some of them have been preserved at http://BRLTTY.app/archive/Windows/.
The following software components should already be installed:
The following MinGW packages may still need to be installed:
The following packages should also be installed:
AutoHotkey (from http://www.autohotkey.com/)
The mkwin script assumes that it has been installed in C:\Program Files (x86)\AutoHotkey. The -A (AutoHotkey) option can be used to specify another location. The installer currently being used is named AutoHotkey104805_Install.exe.
NSIS (from http://nsis.sourceforge.net/)
The mkwin script assumes that it has been installed in C:\Program Files (x86)\NSIS. The -N (NSIS) option can be used to specify another location. The installer currently being used is named nsis-3.0b0-setup.exe.
Python (from http://www.python.org/)
The 32-bit variants are required. Version 2 or 3 may be used. If the python command isn't in your command search path, or if you'd like to use a different version of Python, then use the -P (Python) option to specify the top-level directory of the desired Python version.
Cython (from http://cython.org/)
A corresponding version of Cython must be installed for each version of Python. Each Cython version is installed within the corresponding Python version's hierarchy. Install Cython with the command:
pip install cython
Some systems, either in addition to or in place of the pip command, have the pip2 and/or the pip3 command. As you might have guessed, pip2 corresponds to Python2 and pip3 corresponds to Python3. It's best to use the one with the most explicit version suffix.
If the pip command isn't already included within the version of Python that you're using (usually within its scripts subdirectory) then you can install it from https://pip.pypa.io/en/stable/installing/.
Copies of the files mentioned below are at http://BRLTTY.app/archive/Windows/Cython/:
To force use of MinGW's (rather than Microsoft's) C compiler, add distutils.cfg to the Python/lib/distutils/ directory. It should contain these lines:
[build] compiler = mingw32
If you get a message like "Unknown MS Compiler version 1900" then you'll probably need to apply the patch patch1 (from https://bugs.python.org/file40608/patch.diff) when within the Python/lib/distutils/ directory:
cd Python/lib/distutils patch patch1
If you get a message like "cannot find -lvcruntime140" then you'll need to add the 32-bit version of vcruntime140.dll (from http://www.dll-files.com/) to the Python/libs/ directory. You can verify that you have the 32-bit version with the file command:
file vcruntime140.dll vcruntime140.dll: PE32 executable (DLL) (console) Intel 80386, for MS Windows
A message like "vcruntime140.dll: file not recognized: File format not recognized" probably means that you don't have the 32-bit version of the DLL.
LibUSB-Win32 (from http://libusb-win32.sourceforge.net/)
The mkwin script assumes that it has been installed in C:\LibUSB-Win32. The -U (LibUSB-Win32) option can be used to specify another location. The archive currently being used is named libusb-win32-bin-1.2.6.0.zip. Our copy of this archive has a top-level directory named libusb-win32-bin-1.2.6.0.
LibUSB-1.0 (from http://www.libusb.org/wiki/windows_backend)
The mkwin script assumes that it has been installed in C:\LibUSB-1.0. The -X (libusbx) option can be used to specify another location. The archive currently being used is named libusbx-1.0.18-win.7z. Our copy of this archive doesn't have a top-level directory. We have an alternate copy of this archive named libusbx-1.0.18-win.tar.gz.
WinUSB (from http://www.libusb.org/wiki/windows_backend)
The mkwin script assumes that it has been installed in C:\WinUSB. The -W (WinUSB) option can be used to specify another location. The archive currently being used is named winusb.zip. Our copy of this archive doesn't have a top-level directory.
ICU (from http://icu-project.org/)
The mkwin script assumes that it has been installed in C:\ICU. The -I (ICU) option can be used to specify another location. The archive currently being used is named icu4c-53_1-Win32-msvc10.zip. Our copy of this archive has a top-level directory named icu. Since Windows file systems don't have case sensitive names, renaming it from icu to ICU is optional.
pkg-config (from http://gtk.org/download/win32.php)
The archive currently being used is named pkg-config_0.28-1_win32.zip. Our copy of this archive doesn't have a top-level directory. It should be unpacked when in MinGW's /mingw/ directory.
Glib (from http://gtk.org/download/win32.php)
The archive currently being used is named glib_2.34.3-1_win32.zip. Our copy of this archive doesn't have a top-level directory. It should be unpacked when in MinGW's /mingw/ directory.
gettext-runtime (from http://gtk.org/download/win32.php)
Only install it if your MinGW installation doesn't already have it. Check for the presence of a libintl DLL in MinGW's /mingw/bin/ directory.
The mkwin script uses the lib command, which belongs to MSVC (Microsoft Visual C++). On newer Windows systems, MSVC has become a component of Microsoft Visual Studio. If you don't have it then you'll need to get the following files from someone who does. Copies of them are at http://BRLTTY.app/archive/Windows/MSVC/.
All of them should be placed within the same directory (MinGW's /usr/local/bin/ directory may be a good place). Either add this directory to your command search path or use the -M (MSVC) option to specify its location.
If you'd like to have USB support then create the symbolic links as described within the MinGW instructions for using LibUSB-Win32 and/or LibUSB-1.0. You'll also need to create .pc (pkg-config) files for them within MinGW's /mingw/lib/pkgconfig> directory. The ones we've created are at http://BRLTTY.app/archive/Windows/pkgconfig/.
If you'd like to have Bluetooth support then you'll need to add the files listed below to MinGW's /mingw/include/ directory. Copies of them are at http://BRLTTY.app/archive/Windows/Bluetooth/.
Specify which USB package is to be used. The following USB packages are supported:
The mkwin script accepts two parameters:
The build name is used as:
It has the following form:
brltty-win-buildVersion-buildRevision-usbPackage
For example:
then invoking the following command:
./mkwin .. 4
will create these files within the current working directory:
The winsetup script, which can be found in the Windows/ subdirectory of BRLTTY's source tree, ensures that all needed components are installed on your system so that the mkwin script can successfully build BRLTTY.