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.
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.
The small screen on the braille terminal that is able to display braille text.
The keyboard of the 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.
The background process that gives a blind person access to the console screen thanks to a braille terminal or speech synthetizer.
An application designed to handle a braille terminal thanks to BrlAPI.
A code returned by the driver, indicating an action to do, for instance "go to previous line", "go to next line", etc.
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.
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.
This library helps clients to connect and use BrlAPI's
server thanks to a series of brlapi_-prefixed functions.
A sequence of bytes making up the atomic unit in communications, either between braille drivers and braille terminals or between the server and clients.
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.
The part of brltty that controls incoming connections and communication between clients and braille drivers.
Mode in which the server keeps the device driver closed, so that the client can connect directly to the device.
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.
This manual is split in five parts.
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 how concurrency between BrlAPI clients is handled thanks to focus tellers.
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.
This part describes how the braille drivers included in brltty should be written in order to take advantage of BrlAPI's services.
This part describes in detail the communication protocol that is used to communicate between server and clients.
What should be read probably depends on what should be done by applications with BrlAPI.
Reading chapters General description, Concurrency management and Installation and configuration is recommended, since they provide useful information and (hopefully) lead to a good understanding of BrlAPI, for an efficient use.
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.