The README file for the clicking tty (clicktty) feature.


		OVERVIEW

This software causes your console to produce clicks and chirps
whenever text is sent to the screen.
This tells the blind user when output is being generated,
and conveys the quantity and format of the text.
This capability complements your existing adaptive software,
whatever that may be.

		FILES

README:  This file.
tc_sound.c:  Source code for clicks and chirps at the console.
keysnd.c:  Simple program to make interesting sounds via the toggle speaker.
clicktty.patch:  Patch to upgrade n_tty.c -- inserts calls to tc_sound.c.

		PACKAGE

The sourcefile tc_sound.c
is actually part of a larger package, the Jupiter speech system,
which makes Linux accessible to the blind.
Within that package,
the "tc" prefix on global variables and file names represents
"talking console",
and prevents collisions with other global variables in the Linux kernel.
For more information on this package, visit:
http://eklhad.hispeed.com/linux/jupiter

Unlike the rest of the Jupiter system, tc_sound.c
performs an orthogonal function, and can be grafted
onto almost any other speech or braille package.
It does not render the words on the screen via speech or braille.
Instead, it provides audio feedback for the user as text is being generated.
The user can then read the text, or not, as he sees fit,
using whatever adaptive system he prefers.

		MOTIVATION

This audio channel, which runs through the PC in-built toggle speaker,
effectively provides control information (text is being generated),
as opposed to data (reading the words on the screen).
I find this two-channel paradigm helpful and intuitive.
When clicktty is integrated into the (larger) Jupiter speech system,
additional control signals are sent through this audio channel,
such as reading past end-of-buffer.
But under any adaptive system, clicktty provides
the most important control information:
text is being generated, and here's what it looks like.

After a time, you will recognize the common messages, just by their sonic
patterns.  A sighted person often recognizes a message --
even an entire paragraph -- at a glance;
he doesn't have to read it word for word.
The login sequence is a good example.
The system prints an introductory login message that you've seen so many times,
you just glance at it, recognize the visual pattern,
and then type in your login and password.
After you've logged in you are presented with yet another
familiar message, identifying the machine,
and telling you when you last logged in etc.
Again, you just glance at it, and then move on.
Yet if any of these canned messages changes even slightly, you
detect the visual discrepancy, and read the message to see what happened.

With the clicktty feature, the blind user enjoys the same luxury.
If the pattern "sounds" like the one he's heard at every login prompt
for the past month, there is no need to read it.
Since letters, spaces, and returns generate different sounds,
even slight changes in the text will sound different,
and alert the user to read it via his adaptive system.
Thus the user doesn't miss the "message of the day" (/etc/motd).

		CAPS LOCK

I have often hit the caps lock by accident, or forgotten to turn it off,
whence I have inadvertantly entered an entire paragraph in caps.
The situation is even more frustrating when we leave "insert mode"
and enter "command mode",
where capital X and small x invoke completely different functions.
Therefore this package provide constant,
nonintrusive feedback on the case of the entered letters.
If a character is displayed, and that character is the result of an echo
(stty echo), and that character is upper case,
clicktty issues a short high-frequency beep, rather than a simple click.
Thus the user is constantly aware of the case of the letters being entered.
Again, this feedback can prove useful, regardless of your adaptive software.

Because clicktty is based on output, rather than input,
there is no case feedback when the tty is in no-echo mode.
Thus this feature is not as comprehensive as the locktones program,
written by Dave Nielke, which gave me the idea for case feedback.
(See the blinux web site for this and other programs.)

		ON/OFF

The console audio clicks can be disabled/enabled at run time.
To toggle the feature on and off, echo the string
<escape>{Wa to the console.
This is one of many escape sequences employed by the
Jupiter speech system,
so that running programs can manage speech, as well as keyboard commands.

		YOUR ADAPTIVE SOFTWARE

Clicktty works well with adaptive systems that capture stdout
in a buffer, and read text from that buffer,
rather than accessing screen memory.
This allows the user to monitor two streams simultaneously.
You can start reading a paragraph as soon as you hear the first clicks
(if you wish), and as your adaptive software reads the words,
you can monitor the ongoing output,
assessing its quantity and format.
You can even enter a subsequent command while reading output
from the previous command.
The click patterns will tell you whether the next command
is going well.
I often issue three or four simple commands,
and verify their correct execution via their sound patterns,
while reading the output of an earlier command.

In contrast, clicktty may not work well with screen readers, e.g. brltty,
which tend to couple the reading cursor and the visual cursor.
With the slower display, the visual cursor doesn't simply jump to its new
position.  It takes a while to display the page, and during that time
the visual cursor, and hence the reading cursor, are unstable.
When the two cursors are coupled, clicktty could be an inconvenience.
If you use both linear and screen applications,
you may want to enable (line mode) and disable (screen mode) clicktty,
as described in the last section.

		TEST PROGRAM

Before you hack the kernel, you can test
the software by compiling a small test driver,
built into tc_sound.c.
You can also use this test program to fine-tune the #define constants at
the top of the file.
These constants affect the clicks and chirps.
For instance, you can reduce the time intervals,
thus increasing the effective baud rate of the console display.
However, if the baud rate is too high, you will lose
the ability to distinguish common messages by their sounds.
They will all become high pitched whines.
To build the test program, do the following.

cc -O -s -DTEST tc_sound.c -o clicktty
chown root clicktty
chmod 4755 clicktty

If you're wondering about the -O, check the man page outb(2).
If you're wondering about the setuid root bit, check the man page ioperm(2).

Run `clicktty filename'.
The program generates the clicks and chirps corresponding to the text
in the specified file.
If you install this feature into your kernel, and `cat filename'
at the console, you should hear exactly the same sounds.

		INTERACTIONS

If somebody runs an application that generates sounds via the PC speaker,
while text is running through clicktty,
the results are unpredictable,
since there is no mechanism to grant exclusive access to the toggle speaker.
The console clicks could disrupt the sounds being generated by the application,
or vice versa.
In practice the sounds tend to merge together, without disrupting Linux
or its running processes.

		CLICKTTY IN THE KERNEL

Note that this feature only works on standard PCs,
which have an in-built toggle speaker at port 0x61.
If this is your platform, and you have Linux version 2.2 or above,
you should be able to install this feature.
As always, you should have a backup copy of your working kernel,
accessible from lilo or a boot floppy,
so you can recover your system if something goes wrong.

Go to /usr/src/linux/drivers/char,
copy tc_sound.c into this directory, and patch n_tty.c and the Makefile.
If the patch succeeds, go to /usr/src/linux and rebuild the kernel.
Note that the patch SHOULD succeed, whatever your version;
n_tty.c has been stable for five years.

set -e  #  stop if anything goes wrong
cd /usr/src/linux/drivers/char
cp $HOME/clicktty/tc_sound.c .
	patch -b <$HOME/clicktty/clicktty.patch
cd /usr/src/linux
make bzImage

		TECHNICAL DETAILS

Although it seems crude, the timing of the speaker clicks
is managed by a CPU loop that polls the realtime clock.
(This is necessary to attain sub-millisecond precision.)
In other words, sending text to the console chews up the CPU.
Displaying a full line of text (80 characters) consumes 240ms realtime,
and about 30ms CPU time.
In practice this isn't a serious problem.
Blind users tend to minimize screen output,
and their work stations are rarely placed under load.

The "click" of a character is actually a square pulse, not a toggle,
which would be inaudible in isolation (e.g. single keystroke).
The timing is roughly: wait 3.5ms, toggle, wait 0.5ms, toggle.
After each click is complete, the altered device driver (see n_tty.c)
takes a realtime break, to see if a higher priority process wants to run.
If it returns right away, there is, by assumption,
nothing more important to do, so it generates the next character click.
This begins with a wait loop, until last_toggle + 3.5ms,
but this isn't really a problem, because, as I say,
there is nothing more important to do.
If, in contrast, another task consumed 2ms out of the 3.5ms,
we only run the CPU loop for 1.5ms,
then toggle, then wait 0.5ms, then toggle.
Only the last 0.5ms (out of 4ms) is truly blocked,
to ensure the precise timing of the square wave.
Furthermore, interrupts remain enabled, so we should not lose any
critical incoming data (e.g. serial or ethernet).
The clicks will not degrade the system significantly.

		CONTACT INFORMATION

You can contact the author, Karl Dahlke, at the following address.
mail@eklhad.hispeed.com
http://eklhad.hispeed.com
(USA) 248-524-1004, during regular business hours