Skip to main content

bluetooth_host/
controller.rs

1//! What the controller can do, read once at start, so every feature can
2//! check before it asks and degrade cleanly on an old chip (a Pi 3's
3//! Bluetooth 4.1 controller has no extended advertising, no 2M or coded PHY
4//! and no data length extension).
5
6use bt_hci::param::CmdMask;
7use serde::Serialize;
8
9/// LE feature bits, Core Vol 6, Part B, 4.6.
10pub mod le_feature {
11    /// LE Encryption.
12    pub const ENCRYPTION: u32 = 0;
13    /// Connection Parameters Request procedure.
14    pub const CONN_PARAMS_REQUEST: u32 = 1;
15    /// LE Ping.
16    pub const PING: u32 = 4;
17    /// LE Data Packet Length Extension.
18    pub const DATA_LENGTH_EXTENSION: u32 = 5;
19    /// LL Privacy.
20    pub const LL_PRIVACY: u32 = 6;
21    /// Extended Scanner Filter Policies.
22    pub const EXT_SCANNER_FILTER_POLICIES: u32 = 7;
23    /// LE 2M PHY.
24    pub const PHY_2M: u32 = 8;
25    /// LE Coded PHY.
26    pub const PHY_CODED: u32 = 11;
27    /// LE Extended Advertising.
28    pub const EXTENDED_ADVERTISING: u32 = 12;
29    /// LE Periodic Advertising.
30    pub const PERIODIC_ADVERTISING: u32 = 13;
31    /// Channel Selection Algorithm #2.
32    pub const CSA2: u32 = 14;
33    /// Connection CTE Request.
34    pub const CONN_CTE_REQUEST: u32 = 17;
35    /// Connection CTE Response.
36    pub const CONN_CTE_RESPONSE: u32 = 18;
37    /// Connectionless CTE Transmitter.
38    pub const CONNLESS_CTE_TX: u32 = 19;
39    /// Connectionless CTE Receiver.
40    pub const CONNLESS_CTE_RX: u32 = 20;
41    /// Antenna switching during CTE transmission (AoD).
42    pub const AOD: u32 = 21;
43    /// Antenna switching during CTE reception (AoA).
44    pub const AOA: u32 = 22;
45    /// Receiving Constant Tone Extensions.
46    pub const CTE_RX: u32 = 23;
47    /// Periodic Advertising Sync Transfer, recipient.
48    pub const PAST_RECIPIENT: u32 = 25;
49    /// Isochronous Broadcaster.
50    pub const ISO_BROADCASTER: u32 = 30;
51    /// Synchronized Receiver.
52    pub const SYNC_RECEIVER: u32 = 31;
53    /// LE Power Control Request.
54    pub const POWER_CONTROL: u32 = 33;
55    /// Connection Subrating.
56    pub const SUBRATING: u32 = 37;
57    /// Channel Sounding.
58    pub const CHANNEL_SOUNDING: u32 = 46;
59
60    /// Every named bit, for reports.
61    pub const NAMES: &[(u32, &str)] = &[
62        (0, "le_encryption"),
63        (1, "connection_parameters_request"),
64        (2, "extended_reject_indication"),
65        (3, "peripheral_initiated_features_exchange"),
66        (4, "le_ping"),
67        (5, "data_length_extension"),
68        (6, "ll_privacy"),
69        (7, "extended_scanner_filter_policies"),
70        (8, "le_2m_phy"),
71        (9, "stable_modulation_index_tx"),
72        (10, "stable_modulation_index_rx"),
73        (11, "le_coded_phy"),
74        (12, "extended_advertising"),
75        (13, "periodic_advertising"),
76        (14, "channel_selection_algorithm_2"),
77        (15, "power_class_1"),
78        (16, "minimum_number_of_used_channels"),
79        (17, "connection_cte_request"),
80        (18, "connection_cte_response"),
81        (19, "connectionless_cte_transmitter"),
82        (20, "connectionless_cte_receiver"),
83        (21, "antenna_switching_aod"),
84        (22, "antenna_switching_aoa"),
85        (23, "receiving_cte"),
86        (24, "periodic_advertising_sync_transfer_sender"),
87        (25, "periodic_advertising_sync_transfer_recipient"),
88        (26, "sleep_clock_accuracy_updates"),
89        (27, "remote_public_key_validation"),
90        (28, "cis_central"),
91        (29, "cis_peripheral"),
92        (30, "isochronous_broadcaster"),
93        (31, "synchronized_receiver"),
94        (32, "cis_host_support"),
95        (33, "power_control_request"),
96        (34, "power_control_request_2"),
97        (35, "path_loss_monitoring"),
98        (36, "periodic_advertising_adi"),
99        (37, "connection_subrating"),
100        (38, "connection_subrating_host_support"),
101        (39, "channel_classification"),
102        (40, "advertising_coding_selection"),
103        (41, "advertising_coding_selection_host_support"),
104        (43, "periodic_advertising_with_responses_advertiser"),
105        (44, "periodic_advertising_with_responses_scanner"),
106        (46, "channel_sounding"),
107        (47, "channel_sounding_host_support"),
108    ];
109}
110
111/// The controller's identity and capabilities.
112#[derive(Debug, Clone, Serialize)]
113pub struct Capabilities {
114    /// The public address, least significant byte first; all zeros when the
115    /// controller has none.
116    #[serde(serialize_with = "ser_addr")]
117    pub public_address: [u8; 6],
118    /// HCI version (a Core Specification version number).
119    pub hci_version: u8,
120    /// HCI subversion.
121    pub hci_subversion: u16,
122    /// LMP/LL version.
123    pub lmp_version: u8,
124    /// LMP/LL subversion.
125    pub lmp_subversion: u16,
126    /// Manufacturer (a company identifier).
127    pub manufacturer: u16,
128    /// Supported commands, the 64-octet mask.
129    #[serde(skip)]
130    pub commands: [u8; 64],
131    /// LMP features, page 0.
132    pub lmp_features: u64,
133    /// LE features.
134    pub le_features: u64,
135    /// LE supported states.
136    pub le_states: u64,
137    /// Maximum LE ACL data length per packet, and how many the controller buffers.
138    pub le_acl: (u16, u16),
139    /// Maximum ISO data length and buffer count (0 when ISO is not supported).
140    pub iso: (u16, u8),
141    /// Maximum extended advertising data length (31 for legacy only).
142    pub max_adv_data: u16,
143    /// Number of advertising sets (1 for legacy only).
144    pub adv_sets: u8,
145    /// Filter Accept List size.
146    pub filter_accept_list_size: u8,
147    /// Resolving List size (0 without LL privacy).
148    pub resolving_list_size: u8,
149    /// Maximum data length: (tx octets, tx time, rx octets, rx time).
150    pub max_data_length: (u16, u16, u16, u16),
151}
152
153fn ser_addr<S: serde::Serializer>(a: &[u8; 6], s: S) -> Result<S::Ok, S::Error> {
154    s.collect_str(&crate::Address::public(*a))
155}
156
157impl Capabilities {
158    /// The supported-commands mask, with a getter per command.
159    pub fn cmds(&self) -> CmdMask {
160        // CmdMask is a transparent 64-byte bit field; rebuild it from the bytes.
161        use bt_hci::FromHciBytes;
162        <&CmdMask>::from_hci_bytes(&self.commands)
163            .map(|(m, _)| *m)
164            .unwrap_or_default()
165    }
166
167    /// Whether an LE feature bit is set.
168    pub fn le(&self, bit: u32) -> bool {
169        bit < 64 && self.le_features & (1 << bit) != 0
170    }
171
172    /// Extended advertising, scanning and connecting (Bluetooth 5). The
173    /// feature bit makes those commands mandatory (Core Vol 4, Part E, 3),
174    /// so it alone decides: some controllers leave them out of their
175    /// supported-commands mask.
176    pub fn extended_advertising(&self) -> bool {
177        self.le(le_feature::EXTENDED_ADVERTISING)
178    }
179
180    /// Extended scanning commands (the same feature bit).
181    pub fn extended_scanning(&self) -> bool {
182        self.extended_advertising()
183    }
184
185    /// Periodic advertising.
186    pub fn periodic_advertising(&self) -> bool {
187        self.le(le_feature::PERIODIC_ADVERTISING)
188    }
189
190    /// The coded PHY (long range).
191    pub fn coded_phy(&self) -> bool {
192        self.le(le_feature::PHY_CODED)
193    }
194
195    /// The 2M PHY.
196    pub fn phy_2m(&self) -> bool {
197        self.le(le_feature::PHY_2M)
198    }
199
200    /// Data length extension.
201    pub fn data_length_extension(&self) -> bool {
202        self.le(le_feature::DATA_LENGTH_EXTENSION) && self.cmds().le_set_data_length()
203    }
204
205    /// Changing PHY on a connection.
206    pub fn phy_update(&self) -> bool {
207        (self.phy_2m() || self.coded_phy()) && self.cmds().le_set_phy()
208    }
209
210    /// Names of the LE features the controller has.
211    pub fn le_feature_names(&self) -> Vec<&'static str> {
212        le_feature::NAMES
213            .iter()
214            .filter(|(b, _)| self.le(*b))
215            .map(|(_, n)| *n)
216            .collect()
217    }
218
219    /// The manufacturer's name, from the assigned numbers.
220    pub fn manufacturer_name(&self) -> Option<&'static str> {
221        bluetooth_numbers::company(self.manufacturer)
222    }
223
224    /// The Core Specification version the controller implements.
225    pub fn version_name(&self) -> Option<&'static str> {
226        bluetooth_numbers::core_version(self.hci_version)
227    }
228}