Table of Contents

1. Features
2. Quick Start
   1. Simplest Example (Oneshot Message)
   2. Basic Example with Connection Management
   3. Sustained Writing (Most Efficient)
3. Requirements
   1. System Dependencies
   2. Braille Hardware
4. Architecture
   1. brlapi-sys - Low-level FFI bindings
   2. brlapi - High-level safe wrapper
5. Building the Project
6. Running Tests
   1. Test Environment Variables
7. Examples
8. Documentation
9. License

Safe, idiomatic Rust bindings for BrlAPI, the Application Programming Interface for BRLTTY (the screen reader for blind people using braille displays).

Features

• Safe and idiomatic: Memory-safe Rust wrappers around the C BrlAPI library

• Automatic resource management: Connections and TTY modes are cleaned up automatically

• Thread-safe: Uses BrlAPI's handle-based API for thread safety

• Cross-platform: Works on Linux, macOS, and other Unix-like systems

• Comprehensive: Covers all major BrlAPI functionality including:

  • Text and Unicode writing with cursor control
  • Raw braille dot pattern output
  • Interactive key reading with timeout support
  • Key filtering (accept/ignore specific keys)
  • Path-based TTY management
  • Focus management for window managers
  • Parameter reading for display information and user preferences
  • Braille contraction via integrated liblouis support
  • Dynamic contraction table detection from BRLTTY preferences
  • Simple time-based cooperative display sharing
  • Raw mode for direct hardware communication (feature-gated)
  • Suspend mode for direct braille driver control (feature-gated)
  • Full key constant definitions and utilities

• Well-documented: Extensive documentation with examples

Quick Start

Add this to your Cargo.toml:

[dependencies]
brlapi = "0.4"

Simplest Example (Oneshot Message)

use brlapi::util;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Send a quick message - handles everything automatically
    util::send_message("Hello from Rust!")?;
    Ok(())
}

Basic Example with Connection Management

use brlapi::{Connection, text};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to BrlAPI
    let connection = Connection::open()?;

    // Get display information
    let (width, height) = connection.display_size()?;
    println!("Braille display: {width}×{height} cells");

    // Send multiple oneshot messages
    text::oneshot::write_message(&connection, "First message")?;
    text::oneshot::write_message(&connection, "Second message")?;

    // Connection automatically closed when dropped
    Ok(())
}

Sustained Writing (Most Efficient)

use brlapi::{Connection, TtyMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let connection = Connection::open()?;

    // TTY mode with automatic cleanup when dropped
    let (tty_mode, tty_num) = TtyMode::enter_auto(&connection)?;
    println!("Using virtual console {tty_num}");

    // Use convenience methods on TtyMode for efficient multiple writes
    tty_mode.write_text("First line")?;
    tty_mode.write_text("Second line")?;
    tty_mode.write_notification("Notification without cursor")?;

    // TTY mode automatically exited here when tty_mode goes out of scope
    Ok(())
}

Braille Contraction (New in 0.4.0)

use brlapi::{Connection, text};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let connection = Connection::open()?;

    // Get user's preferred contraction table from BRLTTY
    let user_table = connection.user_contraction_table()?;
    println!("Using contraction table: {}", user_table);

    // Send contracted text using user preferences
    text::oneshot::write_contracted_message(&connection, "Hello world")?;

    // Or use specific table if needed
    text::oneshot::write_contracted_message_with_table(
        &connection, "Hello world", "en-us-g2.ctb")?;

    Ok(())
}

Requirements

System Dependencies

• BrlAPI development libraries: Required for building

  • Ubuntu/Debian: sudo apt install libbrlapi-dev
  • Fedora: sudo dnf install brlapi-devel
  • Arch Linux: sudo pacman -S brltty

• BRLTTY daemon: Required for runtime

  • Most distributions: sudo systemctl start brltty

Braille Hardware

This library works with any braille display supported by BRLTTY, including:

• HIMS: BrailleSense, BrailleEdge, SyncBraille

• Freedom Scientific: Focus, PAC Mate

• HumanWare: Brailliant, BrailleNote

• Baum: VarioConnect, SuperVario, EcoVario

• HandyTech: Braille Star, Active Braille

• Alva: Satellite, BC series

• And many more…

Architecture

This workspace consists of four main crates:

brlapi-sys - Low-level BrlAPI FFI bindings

• Raw C bindings generated with bindgen
• Direct mapping of BrlAPI C functions
• Unsafe but comprehensive API coverage

louis-sys - Low-level liblouis FFI bindings

• Raw C bindings for liblouis braille contraction library
• Generated with bindgen from liblouis headers
• Provides access to grade 1/grade 2 braille translation

louis - Safe liblouis wrapper

• Safe Rust abstractions over louis-sys

• Thread-safe braille contraction and translation

• Table resolution and locale handling

• Integrated with brlapi for seamless contraction

brlapi - High-level safe wrapper

• Safe Rust abstractions over brlapi-sys

• Automatic resource management with RAII

• Idiomatic error handling with Result<T, BrlApiError>

• Thread-safe operations using handle-based API

• Integrated liblouis support for braille contraction

Building the Project

In the workspace:

cargo build

For release builds:

cargo build --release

Running Tests

cargo test

Note: Some tests require a running BRLTTY daemon to pass completely.

Test Environment Variables

For CI environments or resource-constrained systems, you can control test behavior:

• CI=1 - Automatically reduces concurrency levels

• BRLAPI_TEST_THREADS - Number of threads for concurrent tests (default: 5, CI: 2)

• BRLAPI_TEST_CONNECTIONS - Number of connections for multi-connection tests (default: 3, CI: 2)

Examples

See the examples/ directory for more examples:

• simple.rs - Basic usage with automatic TTY detection
• tutorial.rs - Comprehensive tutorial with all features
• error_handling.rs - Demonstrates proper error handling patterns
• cooperative_notifications.rs - Simple cooperative braille notifications
• integration_test.rs - Complete liblouis integration testing
• raw_mode_demo.rs - Safe raw mode demonstration (requires --features dangerous-raw-mode)
• raw_mode_firmware_pattern.rs - Advanced firmware simulation (requires --features dangerous-raw-mode)
• suspend_mode_demo.rs - Suspend mode demonstration (requires --features dangerous-suspend-mode)

Run an example with:

cargo run --example simple

cargo run --example tutorial

cargo run --example integration_test

cargo run --example cooperative_notifications

cargo run --example raw_mode_demo --features dangerous-raw-mode

Documentation

• API Documentation - Complete API reference

• BrlAPI Manual - Official BrlAPI documentation

• BRLTTY User Manual - BRLTTY setup and configuration

License

This project is licensed under the GNU Lesser General Public License v2.1 or later - see the LICENSE file for details.

This is the same license as BrlAPI and BRLTTY, ensuring compatibility with the broader ecosystem.