Drivers/Braille/Virtual/README

The Virtual Braille Display Driver
----------------------------------

This is a virtual braille display driver for BRLTTY.  It uses a simple
text-based protocol over a socket to transmit information to, and to receive
information from, the virtual braille display application (from now on, "the
display"). The intention of this driver is two-fold:
 * Give interested developers the ability to test BRLTTY without requiring
   access to a real braille display.
 * Enable the implementation of a visual braille display based on this driver
   which allows a sighted person to see, and even to experience, how a blind
   person uses a braille display to work with a computer.

This driver supports the following devices:
   client:[address]
      The driver periodically tries to connect to the display at the specified 
      network address.
   server:[address]
      The driver waits on the specified network address for a connection 
      request from the display.

If the network address isn't specified then the driver's default TCP/IP port on
the local host is used. The address may be:
   On Unix systems: /path/to/unix-socket-file
      If the address starts with a slash (/) then it's interpreted as the path 
      to a Unix socket file. If the driver is the client then the socket file 
      must already exist. If the driver is the server then the socket file is 
      created by the driver and must not already exist.
   On Windows NT/2000/XP/2003 systems: \\.\pipe\pipename
      If the address starts with a backslash (\) then it's interpreted as the
      path to a named pipe. If the driver is the client, then the named pipe
      must already exist. If the driver is the server then the named pipe is
      created by the driver and must not already exist. Beware of the shell's
      interpretation of backslashes.
   On all systems: [host][:[port]]
      A TCP/IP address. Both the host and port components of the address are 
      optional. The delimiting colon (:) is only required if the port is being 
      specified. The host may be a name, an alias, or an IPV4 address (in 
      dotted-decimal form); if it's omitted then the local host is assumed. The 
      port may be a service name or a port number; if it's omitted then 35752 
      is assumed.


The Protocol
------------

After the connection between the driver and the display is complete, data is
exchanged between them via command lines. The driver first waits for a "cells"
command in order to determine the dimensions of the braille window. After this
has been taken care of, commands freely flow in both directions without any
restrictions. The braille window dimensions are appropriately reconfigured
whenever another "cells" command is received. The "quit" command, which is also
recognized during the initial wait for the first "cells" command, instructs the
driver to close its end of the connection and to restart.

The command lines are in plain text. Each is terminated by a line-feed [0X0A]
(usually known on Unix systems as a new-line). A carriage-return [0X0D] may
optionally precede the line-feed. Command lines sent to the display contain a
carriage-return if, and only if, the most recent command line received from the
display contained one.

Command lines are composed of space-delimited words, numbers, and strings.
Space consists of one or more blanks and/or tabs. Case is only significant
within a string.

A "number" may be specified as decimal, octal, or hexadecimal. The usual C
syntax is recognized. If the first digit is 0 then the number is octal. If the
first digit isn't 0 then the number is decimal. If the number begins with
either 0X or 0x then the number is hexadecimal. The following three numbers are
the same:
   15   Decimal
   017  Octal
   0XF  Hexadecimal

A "string" is a sequence of characters (including space characters) enclosed
within double quotes ("). Special characters within a string are prefixed with
a backslash (\). The following special characters are supported:
   \\   A literal backslash.
   \"   A literal double quote.
   \Xxx Any character specified via its hexadecimal value.
For example: "A \" (double quote) must be escaped with a \\ (backslash)."

A "dots" is a string which describes a braille character sequence. Space
(blanks and/or tabs) within the string are ignored. The braille characters are
separated from one another by a vertical bar (|). Each braille character
consists of the numbers (1 through 8) of the dots which represent it. For
example, the first three letters of the English alphabet would be "1|12|14".


Commands Recognized by the Driver
---------------------------------

Cells columns [rows]
   The number of columns and rows in the text portion of the display. If the
   number of rows isn't supplied then 1 is assumed. This is the first command
   which the display must send to the driver. It may be sent at any other time
   as well to notify the driver that the dimensions of the text portion of the
   display have changed.

Quit
   Upon receipt of this command, the driver closes its end of the connection
   and then restarts. It's recognized at any time, including during the initial
   wait for the first "cells" command from the display.

<basic-command> [state]
   A basic command for the BRLTTY core. It may be any of the BRL_CMD_ constants
   (without the BRL_CMD_ prefix) defined within "brldefs.h", e.g. LnDn. The
   optional <state> operand (which may be either on or off), when applied to an
   attribute toggling command, forces that attribute to the specified state.

<cell-command> number
   A cell command for the BRLTTY core. It may be any of the BRL_BLK_ constants
   (without the BRL_BLK_ prefix) defined within "brldefs.h", e.g. Route. The cell
   number, starting at 1 for the leftmost cell, must be supplied. If the
   display has more than one row then the cells for the top row are counted
   first, e.g. if the display has 32 columns and 2 rows then 35 refers to the
   third cell on the second row.

<key-command> [number]
   A key command for the BRLTTY core. It may be any of the VPK_ constants
   (without the VPK_ prefix) defined within "brldefs.h", e.g. Return. The
   Function command requires that the function key number, starting at 1, be
   supplied. All the other commands in this set don't accept a number operand.


Commands Sent to the Display
----------------------------

Braille dots
   Cells to be presented on the text portion of the display. Excess cells in
   the data should be ignored. Excess cells on the display should be blank.

Visual string
   Characters to be presented on the visual portion of the display. Excess
   characters in the data should be ignored. Excess characters on the display
   should be blank.

Status dots
   Cells to be presented on the status portion of the display. Excess cells in
   the data should be ignored. Excess cells on the display should be blank.

<attribute> <setting>
   The current setting of any of several attributes within the BRLTTY core.
   These are only sent if "Status Style" is set to "Generic". <attribute> is
   the name of any of the STAT_ constants (without the STAT_ prefix) defined
   within "brldefs.h", e.g. BrlRow. <setting> is a number. Rows and columns
   start at 1. Flags use 0 for "off" and 1 for "on".


Security Implications
---------------------

Please be aware that this driver, when used carelessly, might open severe
security holes. Connections to or from this driver are in no way authenticated
so you yourself need to take care of protecting access to a BRLTTY instance
which uses it. In particular, by sending out information about the currently
active virtual console, this driver might expose valuable information about
your system to a potential attacker. The attacker might also use the
<key-command> family of commands to directly manipulate, possibly even
inputting data to, your current, or even another, virtual console. In effect,
this driver could be used to completely remote-control your system.

Please be aware of these implications when experimenting with this driver. If
you're using TCP/IP, be sure to protect access to the used host and port via
facilities such as firewalls. You should take special precautions on multi-user
systems where untrusted people could use unprotected access to this driver to
gain root access to the machine.


 -- Mario Lang <mlang@delysid.org>