BrlAPI Reference manual: Introduction

Next Previous Contents

## 1. Introduction

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.

## 1.1 Concepts

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.

Authorization 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.

Suspend mode

  Mode in which the server keeps the device driver closed, so that the client can connect directly to the device.

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.

## 1.2 How to read this manual

This manual is split in five parts.

General description

  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.

Concurrency management

  This part explains how concurrency between BrlAPI clients is handled thanks to focus tellers.

Installation and configuration

  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.

Library description

  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.

Writing braille drivers

  This part describes how the braille drivers included in brltty should be written in order to take advantage of BrlAPI's services.

Protocol reference

  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.

Next Previous Contents