Crate core_bluetooth

Safe wrapper around Core Bluetooth framework used to communicate with Bluetooth-equipped low energy (LE) and Basic Rate / Enhanced Data Rate (BR/EDR) wireless technology.

The API closely resembles to the native API with some changes for consistency sake. The main difference is that this API lacks most of the functions for accessing retained state, for thread-safety reasons. If needed users can maintain the retained state via information from events.

Central role

Central role is when application acts as “central” and initiates discovery of and connections to peripherals. The central package contains all the needed objects for central role.

Example

The following example shows how to discover peripherals, services and characteristics, connect to peripherals and subscribe to characteristics.

use core_bluetooth::*;
use core_bluetooth::central::*;

let (central, receiver) = CentralManager::new();

let handle_event = |event| {
    match event {
        CentralEvent::ManagerStateChanged { new_state } => {
            match new_state {
                // Must be in PoweredOn state.
                ManagerState::PoweredOn => central.scan(),
                _ => panic!("no bluetooth available"),
            }
        }
        CentralEvent::PeripheralDiscovered { peripheral, advertisement_data, .. } => {
            if advertisement_data.is_connectable() != Some(false) {
                central.connect(&peripheral);
            }
        }
        CentralEvent::PeripheralConnected { peripheral } => {
            peripheral.discover_services_with_uuids(&[
                "ebe0ccb0-7a0a-4b0c-8a1a-6ff2997da3a6".parse().unwrap()]);
        }
        CentralEvent::ServicesDiscovered { peripheral, services } => {
            if let Ok(services) = services {
                for service in services {
                    peripheral.discover_characteristics_with_uuids(&service, &[
                        "ebe0ccc1-7a0a-4b0c-8a1a-6ff2997da3a6".parse().unwrap()]);
                }
            }
        }
        CentralEvent::CharacteristicsDiscovered { peripheral, characteristics, .. } => {
            if let Ok(chars) = characteristics {
                peripheral.subscribe(&chars[0]);
            }
        }
        CentralEvent::CharacteristicValue { peripheral, value, .. } => {
            if let Ok(value) = value {
                // Decode the value.
                // In this example the value comes from a Xiaomi temperature sensor.
                let t = i16::from_le_bytes([value[0], value[1]]) as f64 / 100.0;
                let rh = value[2];
                println!("t = {} C, rh = {}%", t, rh);
            }
        }
        _ => {}
    }
};
while let Ok(event) = receiver.recv() {
    handle_event(event);
}

You can find more examples in the examples directory.

Modules

central

error

uuid

Enums

ManagerState

The possible states of a Core Bluetooth manager.

Type Aliases

Receiver

Receiving end of channel.

Tag

Arbitrary data to associate with asynchronous API call.