API Reference

This page provides a reference for the core traits, structs, and enums that make up the btleplug public API. These are defined in the btleplug::api module.

Core Traits

Manager

The entry point to the library. It is responsible for finding and providing access to the system's Bluetooth adapters.

  • async fn adapters(&self) -> Result<Vec<Self::Adapter>>: Retrieves a list of all available Bluetooth adapters on the system. Each adapter implements the Central trait.

Central

Represents a physical Bluetooth adapter and acts as the central client in BLE communication.

  • async fn events(&self) -> Result<Pin<Box<dyn Stream<Item = CentralEvent> + Send>>>: Returns a stream of CentralEvents for real-time notifications about device discovery, connections, etc.
  • async fn start_scan(&self, filter: ScanFilter) -> Result<()>: Starts scanning for nearby BLE peripherals.
  • async fn stop_scan(&self) -> Result<()>: Stops the BLE scan.
  • async fn peripherals(&self) -> Result<Vec<Self::Peripheral>>: Returns a list of all peripherals that have been discovered so far.
  • async fn peripheral(&self, id: &PeripheralId) -> Result<Self::Peripheral>: Retrieves a specific Peripheral object by its unique ID.
  • async fn adapter_info(&self) -> Result<String>: Returns a string with information about the adapter.

Peripheral

Represents a remote BLE device.

  • fn id(&self) -> PeripheralId: Returns the unique, platform-specific identifier for the peripheral.
  • fn address(&self) -> BDAddr: Returns the Bluetooth device address (MAC address) of the peripheral.
  • async fn properties(&self) -> Result<Option<PeripheralProperties>>: Returns the latest known properties of the peripheral, such as its name, RSSI, and advertisement data.
  • async fn is_connected(&self) -> Result<bool>: Checks if a connection is currently active.
  • async fn connect(&self) -> Result<()>: Establishes a GATT connection.
  • async fn disconnect(&self) -> Result<()>: Terminates the GATT connection.
  • async fn discover_services(&self) -> Result<()>: Queries the peripheral to discover its available services and characteristics.
  • fn services(&self) -> BTreeSet<Service>: Returns the set of services discovered by discover_services.
  • fn characteristics(&self) -> BTreeSet<Characteristic>: Returns a flattened set of all discovered characteristics across all services.
  • async fn read(&self, characteristic: &Characteristic) -> Result<Vec<u8>>: Reads the value of a characteristic.
  • async fn write(&self, characteristic: &Characteristic, data: &[u8], write_type: WriteType) -> Result<()>: Writes data to a characteristic.
  • async fn subscribe(&self, characteristic: &Characteristic) -> Result<()>: Subscribes to notifications or indications for a characteristic.
  • async fn unsubscribe(&self, characteristic: &Characteristic) -> Result<()>: Unsubscribes from notifications or indications.
  • async fn notifications(&self) -> Result<Pin<Box<dyn Stream<Item = ValueNotification> + Send>>>: Returns a stream that yields ValueNotifications when the peripheral sends them.
  • async fn read_descriptor(&self, descriptor: &Descriptor) -> Result<Vec<u8>>: Reads the value of a descriptor.
  • async fn write_descriptor(&self, descriptor: &Descriptor, data: &[u8]) -> Result<()>: Writes data to a descriptor.

Key Data Structures

PeripheralProperties

Contains information about a peripheral, gathered from its advertisement packets.

  • address: BDAddr: The Bluetooth device address.
  • local_name: Option<String>: The advertised local name.
  • rssi: Option<i16>: The most recent Received Signal Strength Indicator.
  • tx_power_level: Option<i16>: The transmission power level.
  • manufacturer_data: HashMap<u16, Vec<u8>>: Manufacturer-specific data.
  • service_data: HashMap<Uuid, Vec<u8>>: Data associated with an advertised service UUID.
  • services: Vec<Uuid>: A list of advertised service UUIDs.

Service

Represents a GATT service, which is a collection of characteristics.

  • uuid: Uuid: The unique identifier for the service.
  • primary: bool: Whether this is a primary service.
  • characteristics: BTreeSet<Characteristic>: The set of characteristics belonging to this service.

Characteristic

Represents a GATT characteristic, the primary conduit for data transfer.

  • uuid: Uuid: The unique identifier for the characteristic.
  • service_uuid: Uuid: The UUID of the parent service.
  • properties: CharPropFlags: A bitfield indicating the supported operations (Read, Write, Notify, etc.).
  • descriptors: BTreeSet<Descriptor>: A set of descriptors that provide metadata for this characteristic.

Descriptor

Represents a GATT descriptor, which provides additional information about a characteristic's value.

  • uuid: Uuid: The UUID of the descriptor.
  • service_uuid: Uuid: The UUID of the parent service.
  • characteristic_uuid: Uuid: The UUID of the parent characteristic.

ValueNotification

An event struct delivered through the notifications stream.

  • uuid: Uuid: The UUID of the characteristic that sent the notification.
  • value: Vec<u8>: The data payload of the notification.