### BrlAPI Example: Connect, Get Info, TTY Mode

Source: https://brltty.app/doc/Manual-BrlAPI/English/BrlAPI.txt

A comprehensive example demonstrating connection, retrieving driver name and display size, entering and leaving raw mode, and taking TTY control. Includes error handling with brlapi_perror.

```c
#include <stdio.h>
#include <stdlib.h>
#include <brlapi.h>

int main()
{
 brlapi_keyCode_t key;
 char name[BRLAPI_MAXNAMELENGTH+1];
 unsigned int x, y;

/* Connect to BrlAPI */
 if (brlapi_openConnection(NULL, NULL)==BRLAPI_INVALID_FILE_DESCRIPTOR)
 {
 brlapi_perror("brlapi_openConnection");
 exit(1);
 }

/* Get driver name */
 if (brlapi_getDriverName(name, sizeof(name)) < 0)
 brlapi_perror("brlapi_getDriverName");
 else
 fprintf(stderr, "Driver name: %s\n", name);

/* Get display size */
 if (brlapi_getDisplaySize(&x, &y) < 0)
 brlapi_perror("brlapi_getDisplaySize");
 else
 fprintf(stderr, "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 */
 fprintf(stderr, "Trying to enter in raw mode... ");
 if (brlapi_enterRawMode(name) < 0)
 brlapi_perror("brlapi_enterRawMode");
 else {
 fprintf(stderr, "Ok, leaving raw mode immediately\n");
 brlapi_leaveRawMode();
 }

/* Get tty control */
 fprintf(stderr, "Taking control of the tty... ");
 if (brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT, NULL) >= 0)
 {
 fprintf(stderr, "Ok\n");

/* Write something on the display */

```

--------------------------------

### Start BRLTTY as System Init

Source: https://brltty.app/guidelines.html

This method starts BRLTTY before other system activities by having the kernel launch BRLTTY instead of init. Configure BRLTTY with the init path and then install BRLTTY as init.

```bash
cd brltty-_release_
./configure --with-init-path=/sbin/real_init
make
mv /sbin/init /sbin/real_init
cp Programs/brltty /sbin/init
```

--------------------------------

### Install and Start BrlAPI Service (Windows Batch)

Source: https://brltty.app/doc/Windows.html

This batch script installs and starts the BrlAPI service on Windows.

```batch
@echo off
sc create BrlAPI binPath= "C:\Program Files\BRLTTY\brlapi.exe" start= auto
sc start BrlAPI
```

--------------------------------

### Install BRLTTY from Source

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Commands to navigate to the source directory, configure the build, and install BRLTTY. This process typically requires root privileges.

```bash
cd brltty-_release_
./configure
make install
```

--------------------------------

### BRLTTY Specific Configuration Examples

Source: https://brltty.app/guidelines.html

Provides examples of BRLTTY configurations with specific drivers, devices, and tables.

```shell
brltty=pm,/dev/ttyS0,text.de.tbl
```

```shell
brltty=bl,/dev/tts/1,text.da.tbl
```

```shell
brltty=al,ttyS0,es
```

```shell
brltty=eu,tts/0
```

```shell
brltty=bn,,fr
```

--------------------------------

### Run BRLTTY with Info Logging

Source: https://brltty.app/doc/Windows.html

This batch script manually starts BRLTTY with a log level set to 'info'. Logs are directed to 'brltty.log' in the installation directory. Any additional arguments provided will be passed to the BRLTTY executable.

```batch
@echo off
"%~dp0\run-brltty.bat" --log-level=info %*

```

--------------------------------

### Install BRLTTY

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Completes the compilation and linking phase, then installs the BRLTTY executable, data files, drivers, and help pages to their correct system locations.

```makefile
make install
```

--------------------------------

### Start BRLTTY with inittab (early boot)

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Add this line to /etc/inittab for BRLTTY to start very early in the boot process, before the first ':sysinit:' line. It will not be automatically restarted if it dies.

```inittab
brl::sysinit:/bin/brltty
```

--------------------------------

### Install BRLTTY from Source RPM

Source: https://brltty.app/doc/README.txt

Instructions for building and installing BRLTTY using a source RPM package. This involves installing the source and then building and installing the package.

```bash
rpm -ivh brltty-<release>-<version>.src.rpm
rpm -bi brltty-<release>-<version>
```

--------------------------------

### Install BRLTTY

Source: https://brltty.app/doc/Stow.html

Compiles and installs BRLTTY after configuration. This step places the compiled files into the directory specified by --with-install-root.

```bash
make
make install
```

--------------------------------

### Start BRLTTY with rc.local (Red Hat)

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Use this script to conditionally start BRLTTY if the executable and configuration file exist. This is a common approach for new users.

```bash
if [ -x /bin/brltty -a -f /etc/brltty.conf ]
then
   /bin/brltty
fi
```

```bash
[ -x /bin/brltty -a -f /etc/brltty.conf ] && /bin/brltty
```

--------------------------------

### Install a Cygwin Package

Source: https://brltty.app/doc/Windows.html

Installs a specified package from the Cygwin repository using apt-cyg. Replace '_name_' with the exact name of the package you wish to install.

```bash
apt-cyg install _name_

```

--------------------------------

### Install BRLTTY

Source: https://brltty.app/download.html

Install the compiled BRLTTY components, including binaries, configuration files, man pages, drivers, tables, and startup scripts. The '-s' option silences the output.

```bash
make -s install
```

--------------------------------

### Install apt-cyg using SVN

Source: https://brltty.app/doc/Windows.html

Installs the apt-cyg package manager from its SVN repository. Ensure you have SVN client installed. This command exports the repository to the specified directory and makes the script executable.

```bash
svn --force export http://apt-cyg.googlecode.com/svn/trunk/ /usr/local/bin/
chmod +x /usr/local/bin/apt-cyg

```

--------------------------------

### Install Multiple BRLTTY Versions

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-7.html

Use the --with-execute-root option to install different BRLTTY versions in separate directories. This allows for testing new versions before removing older ones. After installation, create symbolic links to easily switch between versions.

```bash
./configure --with-execute-root=/brltty-3.1
make install
```

```bash
/brltty-3.1/bin/brltty
```

```bash
./configure --with-execute-root=/brltty-3.2
make install
```

```bash
/brltty-3.2/bin/brltty
```

```bash
ln -s /brltty-3.1/bin/brltty /bin/brltty
```

```bash
ln -s /brltty-3.2/bin/brltty /bin/brltty
```

```bash
ln -s /brltty/bin/brltty /bin/brltty
ln -s /brltty/etc/brltty /etc/brltty
ln -s /brltty/lib/brltty /lib/brltty
```

```bash
ln -s /brltty-3.1 /brltty
```

--------------------------------

### Start BRLTTY with inittab (respawn)

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Add this line to /etc/inittab to start BRLTTY with automatic restart capability. Ensure the '-n' option is used with 'respawn' to prevent multiple instances.

```inittab
brl:12345:respawn:/bin/brltty -n
```

--------------------------------

### Install MinGW Package

Source: https://brltty.app/doc/Windows.html

Use this command to install a specific package from the MinGW repository. Replace '_name_' with the actual package name.

```bash
mingw-get install _name_

```

--------------------------------

### Compile and Install BRLTTY on OpenBSD

Source: https://brltty.app/doc/OpenBSD.html

Commands to configure, compile, and install BRLTTY. It's important to use 'gmake' to avoid potential incompatibilities with BSD and GNU Make.

```bash
./configure
gmake
sudo gmake install

```

--------------------------------

### Install BRLTTY File Hierarchy

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Use 'brltty-install' to copy the BRLTTY installed file hierarchy to a new location. The '_to' argument is the destination directory, and '_from' is the optional source directory.

```shell
brltty-install _to_ [_from_]
```

```shell
brltty-install /mnt
```

--------------------------------

### mkdostools Script - Install Directory Option

Source: https://brltty.app/doc/DOS.html

Specify the installation directory for cross-compiler tools using the `-i` option with the `mkdostools` script. The default is 'Tools/'. This directory will be emptied at the start of the build process.

```bash
install | `-i` | Tools/  

```

--------------------------------

### Comprehensive BrlAPI Client Example

Source: https://brltty.app/doc/Manual-BrlAPI/English/BrlAPI-5.html

This example demonstrates the full lifecycle of a BrlAPI client application, including connecting, retrieving driver and display information, handling raw and TTY modes, writing to the display, reading key presses, and disconnecting. It requires linking with -lbrlapi.

```c
#include <stdio.h>
#include <stdlib.h>
#include <brlapi.h>

int main()
{
  brlapi_keyCode_t key;
  char name[BRLAPI_MAXNAMELENGTH+1];
  unsigned int x, y;

/* Connect to BrlAPI */
  if (brlapi_openConnection(NULL, NULL)==BRLAPI_INVALID_FILE_DESCRIPTOR)
  {
    brlapi_perror("brlapi_openConnection");
    exit(1);
  }

/* Get driver name */
  if (brlapi_getDriverName(name, sizeof(name)) < 0)
    brlapi_perror("brlapi_getDriverName");
  else
    fprintf(stderr, "Driver name: %s\n", name);

/* Get display size */
  if (brlapi_getDisplaySize(&x, &y) < 0)
    brlapi_perror("brlapi_getDisplaySize");
  else
    fprintf(stderr, "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 */
  fprintf(stderr, "Trying to enter in raw mode... ");
  if (brlapi_enterRawMode(name) < 0)
    brlapi_perror("brlapi_enterRawMode");
  else {
    fprintf(stderr, "Ok, leaving raw mode immediately\n");
    brlapi_leaveRawMode();
  }

/* Get tty control */
  fprintf(stderr, "Taking control of the tty... ");
  if (brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT, NULL) >= 0)
  {
    fprintf(stderr, "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) {
        brlapi_expandedKeyCode_t ekey;
        brlapi_describedKeyCode_t dkey;
        int i;

        fprintf(stderr, "got it! (code=%%"BRLAPI_PRIxKEYCODE"\n)", key);

        brlapi_expandKeyCode(key, &ekey);
        fprintf(stderr, "type %u, command %u, argument %u, flags %u\n",
          ekey.type, ekey.command, ekey.argument, ekey.flags);

        brlapi_describeKeyCode(key, &dkey);
        fprintf(stderr, "type %s, command %s, argument %u, flags",
          dkey.type, dkey.command, dkey.argument);
        for (i = 0; i < dkey.flags; i++)
          fprintf(stderr, " %s", dkey.flag[i]);
        fprintf(stderr, "\n");
      } else brlapi_perror("brlapi_readKey");

    } else brlapi_perror("brlapi_writeText");

/* Leave tty control */
    fprintf(stderr, "Leaving tty... ");
    if (brlapi_leaveTtyMode() >= 0)
      fprintf(stderr, "Ok\n");
    else brlapi_perror("brlapi_leaveTtyMode");

  } else brlapi_perror("brlapi_enterTtyMode");

/* Disconnect from BrlAPI */
  brlapi_closeConnection();
  return 0;
}
```

--------------------------------

### Get Host Bluetooth Device Address

Source: https://brltty.app/doc/Bluetooth.html

Run this command to find your host's Bluetooth Device Address, typically starting with 'BD Address:'.

```bash
hciconfig hci0
```

--------------------------------

### Install BRLTTY Systemd Files

Source: https://brltty.app/doc/Systemd.html

Run this command in the Autostart/Systemd subdirectory of BRLTTY's build tree to install necessary Systemd service and path units, wrapper scripts, and configuration files.

```bash
make install

```

--------------------------------

### Run BRLTTY with Serial Port

Source: https://brltty.app/doc/OpenBSD.html

Example of how to invoke BRLTTY after it has been installed and configured. This command specifies the 'ts' braille display type and connects to the first serial port (/dev/cua00).

```bash
brltty -b ts -d serial:cua00

```

--------------------------------

### Symlink LibUSB-1.0 Files for MinGW

Source: https://brltty.app/doc/Windows.html

Creates symbolic links for LibUSB-1.0 header and library files into the MinGW installation. This setup is required for building BRLTTY with LibUSB-1.0 support on MinGW.

```bash
ln -s LibUSB-1.0/include/libusbx-1.0 /mingw/include/libusb-1.0
ln -s LibUSB-1.0/MinGW32/dll/libusb-1.0.dll.a /mingw/lib/
ln -s LibUSB-1.0/MinGW32/dll/libusb-1.0.dll /mingw/bin/

```

--------------------------------

### Start BRLTTY with init.d (Automatic Restart)

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY.txt

Add this line to /etc/inittab to start BRLTTY later in the boot process, with automatic restart if it terminates. The '-n' option is crucial to prevent multiple instances.

```inittab
brl:12345:respawn:/bin/brltty ‐n
```

--------------------------------

### Configure BRLTTY for DOS

Source: https://brltty.app/doc/DOS.html

Example configure command for BRLTTY on DOS. It specifies installation prefix, host, and disables various features like API, ICU, X, USB, Bluetooth, and specific drivers while enabling others.

```bash
./configure \
   --prefix=/brltty-dos --host=i586-pc-msdosdjgpp \
   --enable-relocatable-install \
   --disable-api --disable-icu --disable-x \
   --without-usb-package --without-bluetooth-package \
   --without-libbraille --with-braille-driver=-vr,all \
   --without-espeak --without-espeak-ng \
   --without-flite --without-speechd \
   --with-speech-driver=all \
   --with-screen-driver=pb,-all

```

--------------------------------

### winsetup Script Options

Source: https://brltty.app/doc/Windows.html

These options configure the winsetup script, which prepares the system for building BRLTTY. They allow specifying archive locations, performing dry runs, managing temporary directories, and controlling output verbosity.

```bash
winsetup -a http://example.com/brltty.zip
```

```bash
winsetup -d
```

```bash
winsetup -k
```

```bash
winsetup -p C:\Python27
```

```bash
winsetup -t C:\temp\install
```

```bash
winsetup -v
```

```bash
winsetup -q
```

```bash
winsetup -h
```

--------------------------------

### BRLAPI_KEY_CMD_SCR_START

Source: https://brltty.app/doc/BrlAPIref/group__brlapi__keycodes.html

Starts the screen driver.

```APIDOC
## BRLAPI_KEY_CMD_SCR_START
#define BRLAPI_KEY_CMD_SCR_START (BRLAPI_KEY_CMD(0) + 119)

### Description
Start the screen driver.
```

--------------------------------

### Install BRLTTY using Make

Source: https://brltty.app/doc/Android.html

Use the 'make install' command to install BRLTTY on the Android device. This command will fail if BRLTTY is already installed.

```bash
make -s install

```

--------------------------------

### Install BRLTTY Binary RPM

Source: https://brltty.app/doc/README.txt

Instructions for installing a prebuilt BRLTTY binary RPM package for x86 systems. Use `rpm -Uvh` to install or upgrade.

```bash
rpm -Uvh brltty-<release>-<version>.i386.rpm
```

--------------------------------

### Build BRLTTY from Source

Source: https://brltty.app/doc/README.txt

Steps to build BRLTTY from its source code. This process involves setting up the build environment, configuring options, compiling, and installing.

```bash
./autogen
./configure
make
make install
```

--------------------------------

### List Installed BRLTTY Files

Source: https://brltty.app/doc/Stow.html

Lists the files that would have been installed in the main system if Stow were not used. This helps verify the installation structure within the Stow directory.

```bash
ls /usr/local/stow/brltty-3.2/
```

--------------------------------

### Display apt-cyg Help

Source: https://brltty.app/doc/Windows.html

Shows the help documentation for the apt-cyg command, listing all available commands and options.

```bash
apt-cyg help

```

--------------------------------

### Example mkwin Command

Source: https://brltty.app/doc/Windows.html

This command demonstrates how to invoke the mkwin script. It specifies the source directory and a build revision number. The output files will be named based on the BRLTTY version, build revision, and the default USB package.

```bash
./mkwin .. 4
```

--------------------------------

### Configure BRLTTY for Stow Installation

Source: https://brltty.app/doc/Stow.html

Configures BRLTTY during the compilation process to specify the execution root and the installation root within the Stow directory. This ensures Stow can manage the installed files correctly.

```bash
./configure --with-execute-root=/usr/local \
            --with-install-root=/usr/local/stow/brltty-3.2

```

--------------------------------

### Run Specific BRLTTY Version

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY.txt

Executes a specific installed version of BRLTTY from its installation directory.

```bash
/brltty-3.1/bin/brltty
```

--------------------------------

### Initialize and Configure Connection Settings

Source: https://brltty.app/doc/BrlAPIref/structbrlapi__connectionSettings__t.html

Demonstrates how to initialize a brlapi_connectionSettings_t structure and set the authorization key and host. This is useful for establishing a connection to the BrlAPI server.

```c
brlapi_connectionSettings_t settings;
settings.auth="/etc/brlapi.key";
settings.host="foo";
```

--------------------------------

### Install BRLTTY using RPM

Source: https://brltty.app/doc/Manual-BRLTTY/English/BRLTTY-3.html

Use this command to install BRLTTY from an RPM package. Ensure you are running this command as root.

```bash
rpm -Uvh brltty-_release_-_version_._architecture_.rpm
```

--------------------------------

### Display brltty-mkuser help

Source: https://brltty.app/doc/Linux.html

Run this command to display the help information for the brltty-mkuser script.

```bash
brltty-mkuser -h

```

--------------------------------

### BRLTTY Device Examples

Source: https://brltty.app/guidelines.html

Shows how to specify the braille display device, including absolute and relative paths, and devfs usage.

```shell
brltty=,/dev/ttyS0
```

```shell
brltty=,ttyS0
```

```shell
brltty=,/dev/tts/0
```

```shell
brltty=,tts/0
```

--------------------------------

### Check BRLTTY Option Sources

Source: https://brltty.app/guidelines.html

If unsure about BRLTTY option sources when starting manually, check the kernel command line, environment variables, and configuration file in order.

```bash
grep brltty /proc/cmdline
```

```bash
echo $brltty
```

```bash
env | grep "^BRLTTY_"
```

```bash
grep -v "^ *#" /etc/brltty.conf
```

--------------------------------

### Install Android Application using ADB

Source: https://brltty.app/doc/Android.html

The ADB command to install an Android application. Replace '/path/to/file' with the actual path to the APK.

```bash
adb install /path/to/file

```

--------------------------------

### Bind Directive Examples

Source: https://brltty.app/doc/KeyTables.html

Provides practical examples of the bind directive with various commands and modifiers, such as CSRTRK, TOP, GOTOLINE, and CONTEXT.

```plaintext
bind Key1 CSRTRK
bind Key1+Key2 CSRTRK+off
bind Key1+Key3 CSRTRK+on
bind Key4 TOP
bind Key5 TOP+route
bind VerticalSensor GOTOLINE+toleft+scaled
bind Key6 CONTEXT+context1
```

--------------------------------

### BRLAPI_KEY_CMD_GUI_DEV_OPTIONS

Source: https://brltty.app/doc/BrlAPIref/group__brlapi__keycodes.html

Opens the device options window.

```APIDOC
## BRLAPI_KEY_CMD_GUI_DEV_OPTIONS
#define BRLAPI_KEY_CMD_GUI_DEV_OPTIONS (BRLAPI_KEY_CMD(0) + 139)

### Description
Open the device options window
```