bluer

The bluer-tools crate provides several specialized command-line utilities for interacting with Bluetooth on Linux. Each tool supports the --help flag for detailed usage instructions.

Available Tools:

• bluadv: Used to send Bluetooth LE advertisements.
• blumon: A monitoring tool that scans for and monitors Bluetooth devices (similar to the top command).
• gattcat: A comprehensive tool for Bluetooth LE GATT services. It can:
  • Discover devices and services.
  • Handle pairing.
  • Resolve well-known UUIDs and manufacturer IDs.
  • Perform operations on GATT services.
  • Connect to remote GATT services (via notify and write).
  • Serve a local program over a GATT service (via notify and write).
  • Implement the Nordic UART service (NUS) as both client and server.
• l2cat: A netcat-like tool for Bluetooth classic (BR/EDR) and LE L2CAP sockets. It supports connecting to/listening on L2CAP PSMs, serving local programs, and performing speed tests.
• rfcat: A netcat-like tool for Bluetooth RFCOMM sockets. It supports connecting to/listening on RFCOMM channels, serving local programs, resolving/publishing SDP records, and performing speed tests.

If a characteristic is configured with CharacteristicWriteMethod::Io or CharacteristicNotifyMethod::Io, you can handle data transfers via file descriptors instead of callbacks. This provides lower overhead for high-frequency data.

1. Writes: When a client writes to an Io characteristic, a CharacteristicControlEvent::Write(CharacteristicWriteIoRequest) is emitted on the CharacteristicControl stream. Call request.accept() to get a CharacteristicReader for the data.
2. Notifications: When a client starts a notification session on an Io characteristic, a CharacteristicControlEvent::Notify(CharacteristicWriter) is emitted. Use the CharacteristicWriter to send data.

// In your event loop processing CharacteristicControl events:
while let Some(event) = control.next().await {
    match event {
        CharacteristicControlEvent::Write(req) => {
            let mut reader = req.accept().map_err(|e| ...)?;
            // Read from reader.socket...
        }
        CharacteristicControlEvent::Notify(mut writer) => {
            // Write to writer.socket...
        }
    }
}

L2CAP socket addresses (SocketAddr) are used to identify Bluetooth devices and Protocol Service Multiplexors (PSM).

• PSM Requirements:

  • For Bluetooth Classic (BR/EDR), listening on a PSM below PSM_BR_EDR_DYN_START (0x1001) requires CAP_NET_BIND_SERVICE.
  • For Bluetooth LE, listening on a PSM below PSM_LE_DYN_START (0x80) requires CAP_NET_BIND_SERVICE. The maximum PSM for LE is PSM_LE_MAX (0xff).
  • The PSM must be odd and follow the bit pattern xxxxxxx0_xxxxxxx1.
  • Setting PSM to 0 when binding allows the system to assign an available PSM.

• Binding to any local adapter:

  • Use SocketAddr::any_br_edr() for Classic Bluetooth with a dynamic PSM.
  • Use SocketAddr::any_le() for Bluetooth LE with a dynamic PSM.

use bluer::l2cap::{SocketAddr, AddressType};
use bluer::Address;

// Create a specific address
let addr = SocketAddr::new(device_address, AddressType::LePublic, 0x80);

// Create an address for binding to any local adapter (LE)
let bind_addr = SocketAddr::any_le();

A Characteristic defines how a specific GATT characteristic behaves. It includes a UUID, an optional handle, and configuration for:

• Read: Using CharacteristicRead to define the read function and security requirements.
• Write: Using CharacteristicWrite to define write permissions and the method (Fun for a callback or Io for asynchronous socket-based IO).
• Notify/Indicate: Using CharacteristicNotify to define notification/indication behavior and the method (Fun or Io).

To control a characteristic and receive events (like IO requests) after registration, use characteristic_control() to obtain a CharacteristicControl object and a CharacteristicControlHandle. Store the handle in Characteristic::control_handle.

let (control, control_handle) = characteristic_control();

let mut characteristic = Characteristic {
    uuid: Uuid::new_v4(),
    handle: None,
    broadcast: false,
    writable_auxiliaries: false,
    authorize: false,
    descriptors: vec![],
    read: Some(CharacteristicRead {
        read: true,
        ..Default::default()
    }),
    write: Some(CharacteristicWrite {
        write: true,
        method: CharacteristicWriteMethod::Fun(Box::new(|value, options| {
            Box::pin(async move { Ok(()) })
        })),
        ..Default::default()
    }),
    notify: None,
    control_handle,
    _non_exhaustive: (),
};