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. [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 operand (which may be either on or off), when applied to an attribute toggling command, forces that attribute to the specified state. 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. [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. The current setting of any of several attributes within the BRLTTY core. These are only sent if "Status Style" is set to "Generic". is the name of any of the STAT_ constants (without the STAT_ prefix) defined within "brldefs.h", e.g. BrlRow. 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 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