IntroductionConcepts All throughout this manual, a few terms will be used which are eitherspecific to braille terminals, or introduced because of How to read this manualThis manual is split in five parts.What should be read probably depends on what should be done by applications withGeneral description of Here is explained what Historical notes.Originally, Why Instead of rewriting a whole communication program fromscratch, we chose to add communicationmechanisms to How it works.We are now going to describe the steps an application shouldgo through to get control of the braille terminal, and whathappens on Connection.The first thing any client application has to do is toconnect (in the Unix sense of the word) to Authentication.Since Unix is designed to allow many users to work on thesame machine, it's quite possible that there are more than oneuser accounts on the system. Most probably, one doesn't wantany user with an account on the machine to be able to communicatewith the braille terminal (just imagine what would happen if,while somebody was working with the braille terminal, another userconnected to the system began to communicate with it,preventing the first one from doing his job...). That's why Real use of the braille terminal.Once the client is properly connected and authenticated,there are two possible types of communication with the brailleterminal. The chosen type of communication depends on what theclient plans to do. If its purpose is to display information onthe braille display or to process braille keys, it will have totake control of the Linux tty on which it is running. If itspurpose is to exchange data with the braille terminal (e.g. forfile transfer), it will enter what is called "raw mode".Braille display and braille key presses processing.If the client wants to display something on the brailledisplay or to process braille keys itself, rather than lettingRaw mode.Only one client can be in raw mode at the same time. Inthis mode, data coming from the braille terminal are checkedby 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 Remarks.- The operations described in the two previoussubsections are not completely mutually exclusive. Anapplication that controls its current tty can enter rawmode, provided that no other application already is in thismode. However, the contrary is not possible: an applicationwhich has entered raw mode cannot take control of its ttybefore having left raw mode. Indeed, it would make no senseto take control of a tty during raw mode since in this mode,braille display and reading of braille keys are impossible.
- Not every braille driver supports raw mode. It hasto be specially (re)written to support it, since it hasto provide special functions to process incoming and outgoingpackets. The same restriction is true (but less strong)concerning the ability to deliver/convert keycodes intocommands: not every driver has this ability, it has to bemodified to get it.
- Operations described in 3.1 and 3.2 can be repeated.You can, for instance, use raw mode to transfer data ontoyour braille terminal, display text in braille, return to rawmode..., all that without having to reconnect to Disconnection.
Once the client has finished using the braille terminal, ithas to disconnect from the API, so that the memory structuresallocated for the connection can be freed and eventually used byanother client. This step is transparent for the user, in thesense that it involves no change on the braille display.Installation and configuration # addgroup brlapi# chgrp brlapi /etc/brlapi.key# chmod g+r /etc/brlapi.key# addgroup user1 brlapi# addgroup user2 brlapi...Library descriptionLet's now see how one can write dedicated applications. Basic notions will beseen, along with a very simple client. Greater details are given as onlinemanual pages.
The historical test program for - connect to get driver id
- get driver name
- get display size
- try entering raw mode, immediately leave raw mode.
- get tty control
- write something on the display
- wait for a key press
- leave tty control
- disconnect from It is here rewritten, its working briefly explained.Connecting to Connection to brlapi_initializeConnection
call. For this, abrlapi_settings_t variable must be filled which will hold thesettings the library needs to connect to the server. Just giving if (brlapi_initializeConnection(NULL,NULL)<0) { brlapi_perror("brlapi_initializeConnection"); exit(1); }The connection might fail, so testing is needed.Getting driver id and nameKnowing the type of the braille device might be useful ( p = brlapi_getDriverId(); if (!p) brlapi_perror("brlapi_getDriverId"); else printf("Driver id: %s\n",p); p = brlapi_getDriverName(); if (!p) brlapi_perror("brlapi_getDriverName"); else printf("Driver name: %s\n",p);This is particularly useful before entering raw mode to achieve filetransfers for instance, just to check that the device is really the oneexpected.Getting display sizeBefore writing on the braille display, the size should be always firstchecked to be sure everything will hold on it: if (brlapi_getDisplaySize(&x, &y)<0) brlapi_perror("brlapi_getDisplaySize"); else printf("Braille display has %d line%s of %d column%s\n",y,y>1?"s":"",x,x>1?"s":"");Entering raw mode, immediately leaving raw mode.Entering raw mode is very simple: fprintf(stderr,"Trying to enter in raw mode... "); if (brlapi_getRaw()<0) brlapi_perror("brlapi_getRaw"); else { fprintf(stderr,"Ok, leaving raw mode immediately\n"); brlapi_leaveRaw(); }Not every driver supports raw mode (actually only one does for the moment ;-),so testing is needed.While in raw mode, brlapi_sendRaw and brlapi_recvRawcan be used to send and get data directly to and from the device.It should be used with care, improper use might completely thrash the device !Getting tty controlLet's now display something on the device. control of the tty must be getfirst: fprintf(stderr,"Taking control of the tty... "); if (brlapi_getTty(0,BRLCOMMANDS)>=0) { printf("Ok\n");The first parameter tells the server the number of the tty to takecontrol of. Setting 0 lets the library determine it for us.
The server is asked to send Getting control might fail if, for instance, another application already tookcontrol of this tty, so testing is needed.From now on, the braille display is detached from the screen.Writing something on the displayThe application can now write things on the braille display withoutaltering the screen display: fprintf(stderr,"Writing to braille display... "); if (brlapi_writeText(0,"Press a braille key to continue...")>=0) { fprintf(stderr,"Ok\n");The cursor is also asked "Writing to braille display... Ok" is now displayed on the screen, and"Press a braille key to continue..." on the braille display.Waiting for a key pressTo have a break for the user to be able to read these messages,a key press (a command here, which is driver-independent) may be waited for: fprintf(stderr,"Waiting until a braille key is pressed to continue... "); if (brlapi_readKey(1,&key)>0) fprintf(stderr,"got it! (code=%d)\n",key);The command code is returned, as described in <brltty/brldefs.h>.It is not transmitted to Leaving tty controlLet's now leave the tty: fprintf(stderr,"Leaving tty... "); if (brlapi_leaveTty()>=0) fprintf(stderr,"Ok\n");But control of another tty can still be get for instance, by callingbrlapi_getTty() again...Disconnecting from Let's disconnect from brlapi_closeConnection();The application can as well still need to connect to another server on anothercomputer for instance, by calling brlapi_initializeConnection()again...Putting everything together...#include #include #include int main(){ brl_keycode_t key; char *p,*c; int x, y;/* Connect to BrlAPI */ if (brlapi_initializeConnection(NULL,NULL)<0) { brlapi_perror("brlapi_initializeConnection"); exit(1); }/* Get driver id & name */ p = brlapi_getDriverId(); if (!p) brlapi_perror("brlapi_getDriverId"); else printf("Driver id: %s\n",p); p = brlapi_getDriverName(); if (!p) brlapi_perror("brlapi_getDriverName"); else printf("Driver name: %s\n",p);/* Get display size */ if (brlapi_getDisplaySize(&x, &y)<0) brlapi_perror("brlapi_getDisplaySize"); else printf("Braille display has %d line%s of %d column%s\n",y,y>1?"s":"",x,x>1?"s":"");/* Try entering raw mode, immediately go out from raw mode */ printf("Trying to enter in raw mode... "); if (brlapi_getRaw()<0) brlapi_perror("brlapi_getRaw"); else { printf("Ok, leaving raw mode immediately\n"); brlapi_leaveRaw(); }/* Get tty control */ printf("Taking control of the tty... "); if (brlapi_getTty(0,BRLCOMMANDS)>=0) { printf("Ok\n");/* Write something on the display */ fprintf(stderr,"Writing to braille display... "); if (brlapi_writeText(0,"Press a braille key to continue...")>=0) { fprintf(stderr,"Ok\n");/* Wait for a key press */ fprintf(stderr,"Waiting until a braille key is pressed to continue... "); if (brlapi_readKey(1,&key)>0) fprintf(stderr,"got it! (code=%d)\n",key); else brlapi_perror("brlapi_readKey"); } else brlapi_perror("brlapi_writeText");/* Leave tty control */ fprintf(stderr,"Leaving tty... "); if (brlapi_leaveTty()>=0) fprintf(stderr,"Ok\n"); else brlapi_perror("brlapi_leaveTty"); } else brlapi_perror("brlapi_getTty");/* Disconnect from BrlAPI */ brlapi_closeConnection(); return 0;}This should compile well thanks togcc apiclient.c -o apiclient -lbrlapiWriting (In this chapter, we will describe in details how to write adriver for Overview of the driver's structureA braille driver is in fact a library that is eitherdynamically loaded by ./configure
script.This library has to provide every function needed by the core,plus some additional functions, that are not mandatory, but whichimprove communication with Basic driver structureEvery must consist in at leasta file called braille.c, located in an appropriate subdirectory ofthe Drivers subdirectory. This braille.c file must have thefollowing layout #ifdef HAVE_CONFIG_H #include "config.h" #endif /* HAVE_CONFIG_H */ /* Include standard C headers */ #include "Programs/brl.h" #include "Programs/misc.h" #include "Programs/scr.h" #include "Programs/message.h" /* Include other files */ static void brl_identify() { } static int brl_open(BrailleDisplay *brl, char **parameters, const char *tty) { ... } static void brl_close(BrailleDisplay *brl) { ... } static void brl_writeWindow(BrailleDisplay *brl) { ... } static void brl_writeStatus(BrailleDisplay *brl) { ... } static int brl_readCommand(BrailleDisplay *brl, DriverCommandContext context) { ... }Before giving a detailed description of what each function issupposed to do, we define the BrailleDisplay structure,since each function has an argument of type BrailleDisplay*. The BrailleDisplay structure is defined like this: typedef struct { int x, y; /* The dimensions of the display */ int helpPage; /* The page number within the help file */ unsigned char *buffer; /* The contents of the display */ unsigned isCoreBuffer:1; /* The core allocated the buffer */ unsigned resizeRequired:1; /* The display size has changed */ unsigned int writeDelay; void (*bufferResized)(int rows, int columns); } BrailleDisplay;We now describe each function's semantics and callingconvention.The Enhancements for To improve the level of service provided to clientapplications communicating with braille drivers through - reading braille terminal specific key codes,
- exchanging raw data packets between the brailleterminal and a client application running on the PC.
For each feature presented below, only a short description of eachconcerned macro and function will be given. For a more complete descriptionof concepts used here, please refer to previous chapters.Reading braille key codesWhen a client takes control of a tty and asks for getting raw key codes, ithas, like in command mode, the possibility to mask some keys. The maskedkeys will then be passed to #define BRL_HAVE_KEY_CODESand the following functions:static int brl_readKey(BrailleDisplay *)int brl_keyToCommand(BrailleDisplay *brl, DriverCommandContext caller, int code)The semantics of brl_readKey() is very similar tobrl_readCommand()'s, with one essential difference: a key codeis not context-dependant, so no context argument needs to be given to thisfunction. Moreover, the code this function returns is driver-specific, andhas to be properly defined by the driver's author so that client applicationscan rely on it.The brl_keyToCommand() function's purpose is to convert a key codeas delivered by brl_readKey() into a RemarksWhen these two functions are present, the only thingbrl_readCommand() has to do is to call brl_readKey() and thencall brl_keyToCommand() with the value returned by the first functionas argument.Exchanging raw data packetsUnder some circ*mstances, an application running on the PCcan be interested in a raw level communication with the brailleterminal. For instance, to implement a file transfer protocol,commands to display braille or to read keys are not enough. Insuch a case, one must have a way to send raw data to theterminal, and to receive them from it.A driver that wants to provide such a mechanism has to definethree functions: one to send packets, another one to receive them,and the last one to reset the communication when problems occur.The macro that declares that a driver is able to transmit packetsis:#define BRL_HAVE_PACKET_IOThe prototypes of the functions the driver should define are:static int brl_writePacket(BrailleDisplay *brl, const unsigned char *packet, int size);static int brl_readPacket(BrailleDisplay *brl, unsigned char *p, int size);static void brl_rescue(BrailleDisplay *brl)brl_writePacket() sends a packet of brl_readPacket() reads a packet of at most brl_rescue() is called by Remarks.- If the driver provides such functions, every otherfunctions should use them, instead of trying to communicatedirectly with the braille terminal. For instance, For the moment, the argument of type BrailleDisplaycan safely be ignored by the functions described here.
Protocol referenceUnder some circ*mstances, it may be preferable to communicate directly withIn all the following, Reliable packet transmission channelThe protocol between To achieve this, - the size in bytes of the packet is transmitted first as an integer,
- then the type of the packet, as an integer,
- and finally the packet data.
The size does not include the { size, type } header, so that packets whichdon't need any data have a size of 0 byte. The type of the packet can beeither of Responses from the serverAs described below, many packets are `acknowledged'. It means that uponreception, the server sends either:- a or a
Some other packets need some information as a response.Upon reception, the server will send either:- a packet of the same type, its data being the response,
- or a
If at some point an ill-formed or non-sense packet is received by the server,and Operating modes
The connection between the client and the server can be in either of the four following modes:- authentication mode: this is the initial mode, when the client hasn'tauthenticated itself to the server yet. Only one normal mode: the client is authenticated, but didn't ask for a ttyor raw mode. The client can send either of these types of packet:
- tty handling mode: the client holds the control of a tty:
- And the server might send raw mode: the client wants to exchange packets directly with the brailleterminal. Only these types of packet will be accepted.
- And the server might send Termination of the connection is initiated by the client in normal mode bysimply closing its side of the socket. The server will then close theconnection.Details for each type of packet
Here is described the semantics of each type of packet. Most of them aredirectly linked to some of This must be the first packet ever transmitted from the client to theserver. It lets the client authenticate itself to the server. Data isfirst an integer indicating a protocol version, then comes the authenticationkey itself.If the protocol version is not the same as the server's, a This should be sent by the client when it needs the 2-char identifier ofthe current This should be sent by the client when it needs the full name ofthe current This should be sent by the client when it needs to know the braille displaysize. The returned data are two integers: width and then height.This should be sent by the client to get control of a tty. Sent data arefirst a series of integers: the numbers of ttys that leads to the tty thatthe application wants to take control of (it can be empty if the tty is one of the machine's VT). Then comes an integer telling the number of the ttyto get control of, and finalyhow key presses should be sent: either As soon as the client gets a tty, it must be prepared to handleFor the server to know which tty is active, one particular client is responsiblefor sending For the server to know which tty is active, one particular client is responsiblefor sending This should be sent to free the tty and masked keys lists.This is acknowledged by the server.If the client doesn't want every key press to be signaled to it, but some ofthem to be given to To display text on the braille terminal and set the position of the cursor,the client can send a - A display number can be given as a integer, in case the brailledisplay has several. If not given, usual display is used.
- A region can be given as two integers indicating the beginning and theend of the part of the braille display which is to be updated (included),the first cell of the display being numberd 1. If not given, the whole displayis considered to be updated (and hence the following three fields should exactlyfit the braille display ie hold The text to display can then be given, one byte per caracter, expected tobe encoded in latin-1 (an extension to the bitfield may set other encodingssome day).
- Then an AND field can be given, one byte per character: the 8-dotrepresentation of the above text will be AND-ed with this field, hence allowingto erase some unwanted parts of characters.
- As well, an OR field may be given, one byte per character: the 8-dotresult of the AND operation above (or the 8-dot representation of the text ifno AND operation was performed) is OR-ed with this field, hence allowingto set some dots, to underline characters for instance.
- Last but not least, a cursor position can be specified. 1 representingthe first character of the display, 0 turning the cursor off. If not given,the cursor (if any) is left unmodified.
To enter raw mode, the client must send a To leave raw mode, the client must send a While in raw mode, only
