brlapi-sys 0.1.0

#+title: brlapi-rs #+subtitle: Safe, idiomatic Rust bindings for BrlAPI

Safe, idiomatic Rust bindings for [[https://brltty.app/doc/Manual-BrlAPI/][BrlAPI]], the Application Programming Interface for [[https://brltty.app/][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
• Well-documented: Extensive documentation with examples

• Quick Start

Add this to your Cargo.toml: #+begin_src toml [dependencies] brlapi = "0.1" #+end_src

** Simplest Example (Oneshot Message) #+name: simple-example #+begin_src rust use brlapi::util;

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

** Basic Example with Connection Management #+name: connection-management-example #+begin_src rust use brlapi::{Connection, text};

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

// Get display information
let (width, height) = connection.get_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(())

} #+end_src

** Sustained Writing (Most Efficient) #+name: sustained-writing #+begin_src rust use brlapi::{Connection, TtyMode};

fn main() -> Result<(), Box> { 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(())

} #+end_src

• 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 crate consists of two main components:

** brlapi-sys - Low-level FFI bindings

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

** 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

• CI/CD

This project uses Codeberg Actions for continuous integration. The workflows are configured to:

• Use codeberg-small runners for resource efficiency
• Run tests with reduced concurrency in CI environments
• Skip caching (disabled on Codeberg for security)
• Use explicit action URLs as recommended by Codeberg

• Building the Project

In the workspace: #+name: build-debug #+begin_src shell cargo build #+end_src

For release builds: #+name: build-release #+begin_src shell cargo build --release #+end_src

• Running Tests

#+name: run-tests #+begin_src shell cargo test #+end_src

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

Run an example with: #+name: run-simple-example #+begin_src shell cargo run --example simple #+end_src

#+name: run-tutorial-example #+begin_src shell cargo run --example tutorial #+end_src

#+name: run-error-handling-example #+begin_src shell cargo run --example error_handling #+end_src

• Documentation

• [[https://docs.rs/brlapi][API Documentation]] - Complete API reference
• [[https://brltty.app/doc/Manual-BrlAPI/][BrlAPI Manual]] - Official BrlAPI documentation
• [[https://brltty.app/doc/Manual-BRLTTY/][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.