Using kvm with a virtual, visual braille output

Mon, 13 Jan 2014 12:09:30 GMT

As I find that there is a lack of documentation on how to configure and test the braille output of programs, I will give a short overview on how I set up qemu and a virtual braille line for sighted people. This information is probably not relevant for visually impaired people who use a real braille line anyway.

As for all tutorials about software that is not widely used, it will probably not work for you, but hopefully give you useful hints on how to make it work. If you find some mistake or something that could be more clear or something outdated, send me an E-Mail.

I use XUbuntu 12.04 LTS. Even though it is still supported, it is slightly outdated, even for today, but I guess that similar things can be done for newer releases. I will maybe give some update here for the linux system I will use after the support of 12.04 ends. Just feel free to send me an E-Mail in case I forget to do so.

A warning: This is a guide for advanced users! Think before you do anything, and do not do it if you are not sure about it. It is also likely that I have installed some tools that do not belong to the default installation of Xubuntu, but should be easily installable.

One main problem is that qemu changes its commandline arguments from time to time. So this information might be outdated. The other one is that Ubuntu is good at removing features of software without warning or providing alternatives. I had to recompile kvm myself with brlapi-support.

Of course, as a first step, you need brltty to be installed. Furthermore, you need to install libbrlapi-dev. And you need the source repositories in your /etc/apt/sources.lst, which Ubuntu usually omits for ... whatever reason. These are the lines beginning with deb-src instead of just deb, but otherwise look similar.

Now create some directory (the process of recompiling is "dirty" and creates a lot of files in this directory, this is why you want an own directory for that) and run

apt-get source kvm

It should download some stuff and create a subdirectory that is called like qemu-kvm-1.0+noroms or something. In this directory, there is a configure script. When you run

./configure --help

you should find an option --enable-brlapi. This is the option we will use. There is a debian subdirectory, with a file called rules. Open this file in an editor. This file tells what has to be done to build the package, and we have to add this option to the part that runs the configure-script. Now, there are probably many better ways to do this, but here is what I did: I went to the part that starts with

config-host.mak: $(QUILT_STAMPFN)

and added the option:

config-host.mak: $(QUILT_STAMPFN)
        dh_testdir
        ./configure \
            --target-list="x86_64-softmmu i386-softmmu x86_64-linux-user i386-linux-user" \
            --prefix=/usr \
            --interp-prefix=/etc/qemu-binfmt/%M \
            --disable-blobs \
            --disable-strip \
            --enable-brlapi \
            --sysconfdir=/etc \
        --enable-rbd \
            $(conf_arch)

Back to the qemu-kvm-1.0+noroms directory (or whatever it is called for you), run

dpkg-buildpackage -rfakeroot

It will complain about some build-dependencies that are not installed. Install them and run it again. Then wait and pray. There will occur a few warnings that the stuff could not be authenticated because you do not have the maintainer's key, but we just ignore that.

If everything goes right, the parent directory should now contain a few .deb files. Make sure that you uninstalled everything related to qemu and qemu-kvm and kvm before, and install these packages using

dpkg --install *.deb

Hopefully, the software runs now. At least it did for me.

Now grab some linux cd (I used debian-7.3.0-amd64-netinst.iso) and create, as usual, a hard disk image (I called it debian.qcow2). At another shell, run

sudo brltty -n -b xw -B model=vs -x no -A auth=none,host=127.0.0.1:1

You should hear an audible signal, and a window resembling a braille line should appear on your desktop. Furthermore, run

BRLAPI_HOST=127.0.0.1:1 kvm -usbdevice braille -cdrom debian-7.3.0-amd64-netinst.iso -hda debian.qcow2

to start the virtual machine. The stdout of brltty should tell you something like

BRLTTY 4.3 rev 5477 [http://mielke.cc/brltty/]
brltty: NoScreen Screen Driver:
brltty: BrlAPI Server: release 0.5.6
brltty: XWindow Braille Driver: version 0.1, 2004
brltty: NoSpeech Speech Driver:
brltty: BrlAPI connection fd=7 accepted: inet 127.0.0.1:47172

If that is the case, it should be connected. The debian installation without looking at the screen is ... hilarious. If I didn't already know it by heart, I wouldn't have had a chance to install it.

Anyway, back to topic: Ubuntu now tries to convince me that the package I created can be updated by the default package from Ubuntu. I hope that it is sufficient to set this package on "hold", which can be done under aptitude by selecting it and pressing =. A better solution would probably be to rename the package and make it collide with the original kvm, or use apt-pinning, but I am currently too lazy to do so.

Consider reading DebianInstaller Accessibility which gives some of this information. I also found Testing accessibility of text applications, but did not try it. Here is some thread in some mailing list that also describes a bit of that stuff.