BrlAPI is a service provided by the brltty daemon.
Its purpose is to allow programmers to write applications that take advantage
of a braille terminal in order to deliver a blind user suitable information
for his/her specific needs.
While an application communicates with the braille terminal, everything
brltty sends to the braille terminal in the application's console is
ignored, whereas each piece of data coming from the braille terminal is sent to
the application, rather than to brltty.
All throughout this manual, a few terms will be used which are either
specific to braille terminals, or introduced because of BrlAPI. They are defined
below. Taking a few minutes to go through this glossary will save a lot
of time and questions later.
Authentication key
A file containing arbitrary data, that has to be sent to the server by the
client, to prove it is allowed to establish a connection and then control
the braille terminal.
Braille display
The small screen on the braille terminal that is able to display braille text.
Braille keyboard
The keyboard of the braille terminal.
Braille terminal
A computer designed to display text in braille. In this case, the text is
supposed to come from another computer running Linux or any other Unix system.
Brltty
The background process that gives a blind person access to the console screen
thanks to a braille terminal or speech synthetizer.
Client
An application designed to handle a braille terminal thanks to BrlAPI.
Command
A code returned by the driver, indicating an action to do, for instance
"go to previous line", "go to next line", etc.
Driver
A library that has functions to communicate with a braille terminal.
Basically, a driver has functions to open communication with the
braille terminal, close the communication, write on the braille
display, and read keypresses from the braille keyboard, plus some special
functions that will be described in detail in this manual.
Key
A code that is returned by the driver when a key is pressed. This is
different from a command, because the command concept is driver-independent
(all drivers use the same command codes - those defined by brltty), whereas
codes used for returning keypresses may vary between drivers.
BrlAPI's Library
This library helps clients to connect and use BrlAPI's
server thanks to a series of brlapi_-prefixed functions.
Packet
A sequence of bytes making up the atomic unit in communications, either between
braille drivers and braille terminals or between the server and clients.
Raw mode
Mode in which the client application exchanges packets with the driver.
Normal operations like sending text for display or reading keypresses are
not available in this mode. It lets applications take advantage of advanced
functionalities of the driver's communication protocol.
Server
The part of brltty that controls incoming connections and communication
between clients and braille drivers.
Tty
Synonym for console, terminal, ... Linux' console consist of several Virtual
Ttys (VTs). The screen program's windows also are Ttys. X-window system's
xterms emulate Ttys as well.
Describes more precisely what BrlAPI
is and how it works in collaboration with brltty's core, the braille driver
and clients. In this part, a "connection-use-disconnection" scenario
will be described step by step, explaining for each step what BrlAPI does in
reaction to client instructions. These explanations will take place at a
user level.
This part explains in detail how to install and configure the API. For
instructions on how to install and configure brltty, please report to
the brltty documentation.
This part describes how client applications
can communicate with the server using the BrlAPI library that
comes with brltty. Each function will be briefly described,
classified by categories. More exhaustive descriptions of every
function are available in the corresponding online manual pages.
Chapter
Library description concerns writing
applications that take advantage of braille terminals so as to bring specific
(and more useful) information to blind people.
Chapter
Drivers is for braille driver implementation: either adding a braille driver
to brltty or modifying an existing one so that it can benefit from
BrlAPI's features, this chapter will be of interest, since it describes
exactly what is needed to write a driver for brltty: the core
of drivers interface for instance.
Finally, chapter
Protocol reference is for not using the library, but using the BrlAPI
server directly, when the library might not be sufficient: it describes the
underlying protocol that will have to be used to do so.