bt_gatt/
central.rs

1// Copyright 2023 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Contains traits that are used to find and connect to Low Energy Peers, i.e.
6//! the GAP Central and Observer roles role defined in the Bluetooth Core
7//! Specification (5.4, Volume 3 Part C Section 2.2.2)
8//!
9//! These traits should be implemented outside this crate, conforming to the
10//! types and structs here when necessary.
11
12use bt_common::{PeerId, Uuid};
13
14#[derive(Debug, Clone)]
15pub enum AdvertisingDatum {
16    Services(Vec<Uuid>),
17    ServiceData(Uuid, Vec<u8>),
18    ManufacturerData(u16, Vec<u8>),
19    // TODO: Update to a more structured Appearance
20    Appearance(u16),
21    TxPowerLevel(i8),
22    Uri(String),
23}
24
25/// Matches a single advertised attribute or condition from a Bluetooth Low
26/// Energy peer.
27#[derive(Clone, Debug)]
28pub enum Filter {
29    /// Advertised Service UUID
30    ServiceUuid(Uuid),
31    /// ServiceData is included which is associated with the UUID
32    HasServiceData(Uuid),
33    /// ManufacturerData is provided with the Company Identifier Code given
34    HasManufacturerData(u16),
35    /// Connectable flag is set
36    IsConnectable,
37    /// String provided is included in the peer's name
38    MatchesName(String),
39    /// Path loss from the peer (RSSI - Advertised TX Power) is below the given
40    /// dB value
41    MaxPathLoss(i8),
42}
43
44/// A ScanFilter must match all of its combined filters and conditions to
45/// provide a result. Currently can only include zero or more Filters.
46/// The Default ScanFilter will match everything and should be avoided.
47#[derive(Default, Clone, Debug)]
48pub struct ScanFilter {
49    pub filters: Vec<Filter>,
50}
51
52impl From<Filter> for ScanFilter {
53    fn from(value: Filter) -> Self {
54        ScanFilter { filters: vec![value] }
55    }
56}
57
58impl ScanFilter {
59    pub fn add(&mut self, filter: Filter) -> &mut Self {
60        self.filters.push(filter);
61        self
62    }
63}
64
65#[derive(Debug, Clone)]
66pub enum PeerName {
67    Unknown,
68    PartialName(String),
69    CompleteName(String),
70}
71
72#[derive(Debug, Clone)]
73pub struct ScanResult {
74    pub id: PeerId,
75    pub connectable: bool,
76    pub name: PeerName,
77    pub advertised: Vec<AdvertisingDatum>,
78    pub advertising_sid: u8,
79}
80
81pub trait Central<T: crate::GattTypes> {
82    /// Scan for peers.
83    /// If any of the filters match, the results will be returned in the Stream.
84    fn scan(&self, filters: &[ScanFilter]) -> T::ScanResultStream;
85
86    /// Connect to a specific peer.
87    fn connect(&self, peer_id: PeerId) -> T::ConnectFuture;
88
89    /// Get API for periodic advertising.
90    fn periodic_advertising(&self) -> crate::Result<T::PeriodicAdvertising>;
91}
bt_gatt/central.rs

bt_gatt/
central.rs
