Instructions for setting up

N.B. These install instructions are a work in progress and have not been vigorously tested by BBT.

Installing the right version of BRLTTY

Canute is supported on BRLTTY version 6.1 and above. Your distribution’s repos may have a version of BRLTTY that is new enough, so for less experienced Linux users we suggest using that version. However support has been improved since version 6.1 so for technically confident users we suggest downloading and compiling Canute from source.

Be aware that these processes will change BRLTTY across your system, so if you use it for other purposes, or other programs use BRLTTY, then you should consider this before making changes.

Downloading BRLTTY from the distro repos

Check if you have BRLTTY installed and its version:

$ brltty -v

If BRLTTY is not installed:

$ sudo apt install brltty

Check version again:

$ brltty -v

If your version number is less than 6.1 then uninstall:

$ sudo apt remove brltty

And follow the instructions below to compile from source.

Compiling BRLTTY from source

Download the repository:

$ cd ~/
$ git clone https://github.com/brltty/brltty.git
$ cd ~/brltty

Optional but recommended (where 6.4.1 is the latest release, or no lower than 6.1, when Canute was first supported):

$ git checkout BRLTTY-6.4.1

Configure and make:

$ ./autogen

You may get the following:

/usr/bin/env: ‘tclsh’: No such file or directory

In which case:

$ $ sudo apt-get install tclsh
$ ./autogen

Then:

$ ./configure
$ make

If the make command fails with errors something like:

"Variables of the format BRLAPI_KEY_FLG_<some word> are undeclared" 

… Then you must be using a distro which is using mawk instead of gask. The solution:

$ sudo apt-get install gawk
$ ./autogen
$ ./configure
$ make

Install BRLTTY

You don’t need to actually install brltty as you can also just use the run-brltty script in the top-level directory of brltty’s source tree. It takes the very same options, etc, but sets things up so that what’s run is what you just built (with make).

However if you do want to install then:

$ make install

If you regret doing that…

$ make uninstall

You may have to run ‘make install’ as root by starting the command with ‘sudo’.

Start running BRLTTY with Canute

First plug your Canute it to the mains (but not the PC yet) and turn it on.

Next whilst you are waiting, on your PC, run BRLTTY either as a script…

$ cd ~/brltty
$ ./run-brltty -b cn -L log.txt -n

… Or, if you installed it, like so…

$ brltty -b cn -L log.txt -n

If either of those commands brings up an error like…

brltty: USBFS open error: /dev/bus/usb/002/002: Permission denied

… Then you may have to run it as root by starting the command with ‘sudo’.

Here’s what that command means…

Braille device = Canute:

-b cn

Save log output to ~/brltty/log.txt (optional):

-L log.txt

Run in the foreground, not as a daemon (optional, useful for being able to cancel it with ctrl-c):

-n

When your Canute has finished starting up take a USB-A to USB-B cable (a typical printer cable), plug the USB-B connexion (the larger end) into the left side of the Canute, and the USB-A connexion into your PC.

If at this stage you see the Braille message on you Canute display like…

screen not in text mode

… Then you’re using a graphical console. Switch to a text console (ctrl-alt-F2) and it should work.

Setting up the text-mode console

Assuming you are in the text mode console (without GUI, via ctrl+F2):

Maximise resolution

Optional 1st step for sighted and low-vision users:

$ sudo dpkg-reconfigure console-setup

Choose your encoding, for e.g. UTF-8 and Latin 1.

Then choose the font. For clearest text choose:

TerminusBold 16x32

Configure terminal output to match the Canute 360 display

$ stty cols 40
$ stty rows 9

At this point Canute will only be show one line of text. Help BRLTTY out by restarting your session

$ exit

Then log in again and BRLTTY will be outputting nine lines to the Canute (if there are nine lines to output).

Running BRLTTY within GUI terminal windows

This is answered on the BRLTTY documentation, at the bottom of the page under ‘Reading the Screen’: https://brltty.app/doc/X11.html

In short, you can run a second instance of BRLTTY to act as a screen-reader for the GUI terminal.


All mistakes are BBT’s, otherwise thanks goes to Dave Mielke.

See BRLTTY