Here is explained what BrlAPI is, and what it precisely does. These explanations should be simple enough to be accessible to every user. For a more technical review of BrlAPI's functionalities, please see chapter Libary description.
Originally, brltty was designed to give access to the Linux console to visually impaired people, through a braille terminal or a speech synthetizer. At that time, applications running in the console were not taking care of the presence of a braille terminal (most applications didn't even know what a braille terminal was).
This situation where applications are not aware of the presence of a special device is elegant of course, since it lets use an unlimited number of applications which don't need to be specially designed for visually impaired people.
However, it appeared that applications specially designed to take advantage of a braille terminal could be wanted, to provide the suitable information to blind users, for instance. The idea of BrlAPI is to propose an efficient communication mechanism, to control the braille display, read keys from the braille keyboard, or to exchange data with the braille terminal at a lower level (e.g. to write file transfer protocols between braille terminals and Linux systems).
Instead of rewriting a whole communication program from scratch, we chose to add communication mechanisms to brltty. This choice has two main justifications.
On the one hand, integration to brltty allows us to use the increasing number of drivers written for brltty, thus handling a large number of braille terminals without having to rewrite any piece of existing code.
On the other hand, if an application chooses to send its own information to the braille display, and to process braille keys, brltty has to be warned, so that it won't try to communicate with the braille terminal while the application already does. To make this synchronzation between brltty and client applications possible, it seemed easier to add the communication mechanisms to brltty's core, instead of writing an external program providing them.
We are now going to describe the steps an application should go through to get control of the braille terminal, and what happens on brltty's side at each step. This step-by-step description will let us introduce more precisely some concepts that are useful for every BrlAPI user.
The first thing any client application has to do is to connect (in the Unix sense of the word) to BrlAPI which is an mere application server. If this is not clear, the only thing to be remembered is that this step allows the client application to let the server know about its presence. At this stage, nothing special is done on brltty's side.
Since Unix is designed to allow many users to work on the same machine, it's quite possible that there are more than one user accounts on the system. Most probably, one doesn't want any user with an account on the machine to be able to communicate with the braille terminal (just imagine what would happen if, while somebody was working with the braille terminal, another user connected to the system began to communicate with it, preventing the first one from doing his job...). That's why BrlAPI has to provide a way to determine whether a user who established a connection is really allowed to communicate with the braille terminal. To achieve this, BrlAPI requires that each application that wants to control a braille terminal sends an authorization key before doing anything else. The control of the braille terminal will only be possible for the client once it has sent the proper authorization key. What is called authorization key is in fact a Unix file containing data (it must be non-empty) on your system. All the things you have to do is to give read permissions on this file to users that are allowed to communicate with the braille terminal, and only to them. This way, only authorized users will have access to the authorization key and then be able to send it to BrlAPI. To see how to do that, please see chapter Installation and configuration.
At the end of this step, the user is authorized to take control of the braille terminal. On brltty's side, some data structures are allocated to store information on the client, but this has no user-level side-effect.
Once the client is properly connected and authorized, there are two possible types of communication with the braille terminal. The chosen type of communication depends on what the client plans to do. If its purpose is to display information on the braille display or to process braille keys, it will have to take control of the Linux tty on which it is running. If its purpose is to exchange data with the braille terminal (e.g. for file transfer), it will enter what is called "raw mode".
If the client wants to display something on the braille display or to process braille keys itself, rather than letting brltty process them, it has to take control of the Linux terminal it is running on.
Once a client has obtained the control of his tty, BrlAPI will completely discard brltty's display on this tty (and only this one), leaving the braille display free for the client.
At the same time, if a key is pressed on the braille keyboard, BrlAPI checks whether the client application is interested in this key or not. If it is, the key is passed to it, either as a key code or as a brltty command. If it is not, the key code is converted into a brltty command and returned to brltty.
Once the client is not interested in displaying text or reading braille keys any more, it has to leave the tty, so that either brltty can continue its job, or another client can take control of it.
Only one client can be in raw mode at the same time. In this mode, data coming from the braille terminal are checked by the driver (to ensure they are valid), but instead of being processed, they are delivered "as-is" to the client that is in raw mode.
In the other direction, packets sent to BrlAPI by the client that is in raw mode are passed to the driver which is expected to deliver them to the braille terminal without any modification.
Only one client can be in suspend mode at the same time. This mode is also exclusive with raw mode. In this mode, the server keeps the device driver closed, and thus the client can open the device directly by itself.
This mode is not recommended, since the client will then have to reimplement device access. Raw mode should really be preferred, since it lets the client take advantage of server's ability to talk with the device (USB/bluetooth support for instance).
Once the client has finished using the braille terminal, it has to disconnect from the API, so that the memory structures allocated for the connection can be freed and eventually used by another client. This step is transparent for the user, in the sense that it involves no change on the braille display.