# Table of Contents
1. [Features](#org5a1ac59)
2. [Quick Start](#org14ba91a)
1. [Simplest Example (Oneshot Message)](#orge41abab)
2. [Basic Example with Connection Management](#org1abd19d)
3. [Sustained Writing (Most Efficient)](#org4f5efe9)
3. [Requirements](#orgb89ef8b)
1. [System Dependencies](#orgbd93a81)
2. [Braille Hardware](#org3c925d5)
4. [Architecture](#org42b39d3)
1. [`brlapi-sys` - Low-level FFI bindings](#orgf50bdd7)
2. [`brlapi` - High-level safe wrapper](#orgc8d7ac7)
5. [Building the Project](#org06f5b22)
6. [Running Tests](#org04ecb0c)
1. [Test Environment Variables](#org57f9e80)
7. [Examples](#org2806899)
8. [Documentation](#org92c4ae9)
9. [License](#org708c75a)
Safe, idiomatic Rust bindings for [BrlAPI](https://brltty.app/doc/Manual-BrlAPI/), the Application Programming Interface for [BRLTTY](https://brltty.app/) (the screen reader for blind people using braille displays).
<a id="org5a1ac59"></a>
# 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
<a id="org14ba91a"></a>
# Quick Start
Add this to your `Cargo.toml`:
[dependencies]
brlapi = "0.4"
<a id="orge41abab"></a>
## 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(())
}
<a id="org1abd19d"></a>
## 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(())
}
<a id="org4f5efe9"></a>
## 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(())
}
<a id="orgb89ef8b"></a>
# Requirements
<a id="orgbd93a81"></a>
## 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`
<a id="org3c925d5"></a>
## 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…
<a id="org42b39d3"></a>
# Architecture
This workspace consists of four main crates:
<a id="orgf50bdd7"></a>
## `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
<a id="orgc8d7ac7"></a>
## `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
<a id="org06f5b22"></a>
# Building the Project
In the workspace:
cargo build
For release builds:
cargo build --release
<a id="org04ecb0c"></a>
# Running Tests
cargo test
Note: Some tests require a running BRLTTY daemon to pass completely.
<a id="org57f9e80"></a>
## 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)
<a id="org2806899"></a>
# 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
<a id="org92c4ae9"></a>
# Documentation
- [API Documentation](https://docs.rs/brlapi) - Complete API reference
- [BrlAPI Manual](https://brltty.app/doc/Manual-BrlAPI/) - Official BrlAPI documentation
- [BRLTTY User Manual](https://brltty.app/doc/Manual-BRLTTY/) - BRLTTY setup and configuration
<a id="org708c75a"></a>
# 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.