Skip to main content

bluetooth_host/
advertise.rs

1//! The broadcaster: advertising sets (legacy, extended, periodic), so the
2//! gateway can send packets as well as hear them.
3//!
4//! A controller with extended advertising is driven only with the extended
5//! commands (it refuses to mix the two generations); legacy PDUs are then a
6//! property of the set. A Bluetooth 4 controller has the one legacy set.
7
8use std::collections::HashMap;
9
10use bt_hci::cmd::le::{
11    LeClearAdvSets, LeRemoveAdvSet, LeSetAdvData, LeSetAdvEnable, LeSetAdvParams,
12    LeSetAdvSetRandomAddr, LeSetExtAdvData, LeSetExtAdvEnable, LeSetExtAdvParams,
13    LeSetExtScanResponseData, LeSetPeriodicAdvData, LeSetPeriodicAdvEnable, LeSetPeriodicAdvParams,
14    LeSetScanResponseData,
15};
16use bt_hci::param::{
17    AddrKind, AdvChannelMap, AdvEventProps, AdvFilterPolicy, AdvHandle, AdvKind, AdvSet, BdAddr,
18    Duration as HciDuration, ExtDuration, Operation, PeriodicAdvProps, PhyKind,
19};
20use serde::{Deserialize, Serialize};
21
22use crate::address::Address;
23use crate::connection::Phy;
24use crate::error::{Error, Result};
25use crate::host::Host;
26
27/// How a set advertises.
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
30#[serde(default)]
31pub struct AdvertisingParams {
32    /// Accept connections.
33    pub connectable: bool,
34    /// Answer scan requests with the scan response.
35    pub scannable: bool,
36    /// Use legacy PDUs (seen by every scanner, 31 octets of data). `None`
37    /// chooses: legacy when the data fits and nothing needs Bluetooth 5.
38    pub legacy: Option<bool>,
39    /// Advertise directed at one device.
40    #[cfg_attr(feature = "schema", schemars(with = "Option<String>"))]
41    pub directed: Option<Address>,
42    /// High duty cycle directed advertising (lasts 1.28 s at most).
43    pub high_duty: bool,
44    /// Omit our address (extended, non-connectable only).
45    pub anonymous: bool,
46    /// Put the TX power in the extended header.
47    pub include_tx_power: bool,
48    /// Minimum interval, ms (20 or more).
49    pub interval_min_ms: u32,
50    /// Maximum interval, ms.
51    pub interval_max_ms: u32,
52    /// Primary PHY: `le1m`, or `le_coded` for long range.
53    pub primary_phy: Phy,
54    /// Secondary PHY (extended).
55    pub secondary_phy: Phy,
56    /// TX power to ask for, dBm; `None` lets the controller choose.
57    pub tx_power: Option<i8>,
58    /// Advertising set id (0 to 15), as scanners see it.
59    pub sid: u8,
60    /// Stop after this long, ms.
61    pub duration_ms: Option<u32>,
62    /// Stop after this many events (extended).
63    pub max_events: Option<u8>,
64    /// Only answer scan and connection requests from the filter accept list.
65    pub filter_accept_list: bool,
66    /// Report scan requests as [`crate::HostEvent::ScanRequest`].
67    pub scan_request_notifications: bool,
68}
69
70impl Default for AdvertisingParams {
71    fn default() -> Self {
72        AdvertisingParams {
73            connectable: false,
74            scannable: false,
75            legacy: None,
76            directed: None,
77            high_duty: false,
78            anonymous: false,
79            include_tx_power: false,
80            interval_min_ms: 100,
81            interval_max_ms: 150,
82            primary_phy: Phy::Le1m,
83            secondary_phy: Phy::Le1m,
84            tx_power: None,
85            sid: 0,
86            duration_ms: None,
87            max_events: None,
88            filter_accept_list: false,
89            scan_request_notifications: false,
90        }
91    }
92}
93
94/// A periodic advertising train on a set.
95#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
96#[serde(default)]
97pub struct PeriodicParams {
98    /// Minimum interval, ms (7.5 or more).
99    pub interval_min_ms: u32,
100    /// Maximum interval, ms.
101    pub interval_max_ms: u32,
102    /// Put the TX power in each packet.
103    pub include_tx_power: bool,
104}
105
106impl Default for PeriodicParams {
107    fn default() -> Self {
108        PeriodicParams {
109            interval_min_ms: 100,
110            interval_max_ms: 200,
111            include_tx_power: false,
112        }
113    }
114}
115
116/// Which sets are running.
117#[derive(Default)]
118pub(crate) struct Advertiser {
119    sets: HashMap<u8, AdvertisingParams>,
120}
121
122fn units_625(ms: u32) -> u32 {
123    (u64::from(ms) * 1000 / 625).clamp(0x20, 0x00ff_ffff) as u32
124}
125
126fn phy_kind(p: Phy) -> PhyKind {
127    match p {
128        Phy::Le1m => PhyKind::Le1M,
129        Phy::Le2m => PhyKind::Le2M,
130        Phy::LeCoded => PhyKind::LeCoded,
131    }
132}
133
134impl Host {
135    /// Starts an advertising set; returns its handle. `scan_response` is
136    /// sent to active scanners when the set is scannable.
137    pub async fn advertise(
138        &self,
139        params: &AdvertisingParams,
140        data: &[u8],
141        scan_response: &[u8],
142    ) -> Result<u8> {
143        if params.interval_min_ms < 20 || params.interval_max_ms < params.interval_min_ms {
144            return Err(Error::InvalidParameter("advertising interval".into()));
145        }
146        if params.connectable && params.anonymous {
147            return Err(Error::InvalidParameter(
148                "an anonymous set cannot be connectable".into(),
149            ));
150        }
151        let caps = self.inner.caps();
152        let mut adv = self.inner.advertiser.lock().await;
153        if !caps.extended_advertising() {
154            return self
155                .advertise_legacy(&mut adv, params, data, scan_response)
156                .await;
157        }
158        let legacy = params.legacy.unwrap_or(
159            data.len() <= 31
160                && scan_response.len() <= 31
161                && params.primary_phy == Phy::Le1m
162                && !params.anonymous
163                && !params.include_tx_power
164                && !(params.connectable && params.scannable && params.directed.is_some()),
165        );
166        if legacy && (data.len() > 31 || scan_response.len() > 31) {
167            return Err(Error::InvalidParameter(
168                "legacy advertising data is 31 octets at most".into(),
169            ));
170        }
171        if !legacy && params.connectable && params.scannable {
172            return Err(Error::InvalidParameter(
173                "an extended set cannot be both connectable and scannable".into(),
174            ));
175        }
176        let max = usize::from(caps.max_adv_data);
177        if data.len() > max || scan_response.len() > max {
178            return Err(Error::InvalidParameter(format!(
179                "this controller takes {max} octets of advertising data"
180            )));
181        }
182        if (params.primary_phy == Phy::LeCoded || params.secondary_phy == Phy::LeCoded)
183            && !caps.coded_phy()
184        {
185            return Err(Error::Unsupported("the coded PHY"));
186        }
187        if params.secondary_phy == Phy::Le2m && !caps.phy_2m() {
188            return Err(Error::Unsupported("the 2M PHY"));
189        }
190        let handle = (0..caps.adv_sets.max(1))
191            .find(|h| !adv.sets.contains_key(h))
192            .ok_or(Error::Unsupported(
193                "another advertising set (all are in use)",
194            ))?;
195        let mut props = AdvEventProps::new()
196            .set_connectable_adv(params.connectable)
197            .set_scannable_adv(
198                params.scannable || (legacy && params.connectable && params.directed.is_none()),
199            )
200            .set_directed_adv(params.directed.is_some())
201            .set_high_duty_cycle_directed_connectable_adv(
202                params.high_duty && params.directed.is_some(),
203            )
204            .set_legacy_adv(legacy)
205            .set_anonymous_adv(params.anonymous)
206            .set_include_tx_power(params.include_tx_power);
207        if legacy && !params.connectable && !params.scannable {
208            props = props.set_scannable_adv(false);
209        }
210        let me = self.address();
211        let (peer_kind, peer) = match params.directed {
212            Some(a) => (AddrKind::new(a.hci_type()), BdAddr::new(a.bytes)),
213            None => (AddrKind::PUBLIC, BdAddr::new([0; 6])),
214        };
215        let filter = if params.filter_accept_list {
216            AdvFilterPolicy::FilterConnAndScan
217        } else {
218            AdvFilterPolicy::Unfiltered
219        };
220        let h = AdvHandle::new(handle);
221        self.inner
222            .hci
223            .exec(&LeSetExtAdvParams::new(
224                h,
225                props,
226                ExtDuration::from_u32(units_625(params.interval_min_ms)),
227                ExtDuration::from_u32(units_625(params.interval_max_ms)),
228                AdvChannelMap::ALL,
229                AddrKind::new(me.hci_type()),
230                peer_kind,
231                peer,
232                filter,
233                params.tx_power.unwrap_or(127),
234                phy_kind(params.primary_phy),
235                0,
236                phy_kind(params.secondary_phy),
237                params.sid & 0x0f,
238                params.scan_request_notifications,
239            ))
240            .await?;
241        if me.kind == crate::address::AddressType::Random {
242            self.inner
243                .hci
244                .exec(&LeSetAdvSetRandomAddr::new(h, BdAddr::new(me.bytes)))
245                .await?;
246        }
247        self.set_ext_data(handle, data, false).await?;
248        if params.scannable || (legacy && !scan_response.is_empty()) {
249            self.set_ext_data(handle, scan_response, true).await?;
250        }
251        let set = AdvSet {
252            adv_handle: h,
253            duration: HciDuration::from_u16(
254                params
255                    .duration_ms
256                    .map(|d| u16::try_from(d / 10).unwrap_or(0xffff))
257                    .unwrap_or(0),
258            ),
259            max_ext_adv_events: params.max_events.unwrap_or(0),
260        };
261        self.inner
262            .hci
263            .exec(&LeSetExtAdvEnable::new(true, &[set]))
264            .await?;
265        adv.sets.insert(handle, params.clone());
266        Ok(handle)
267    }
268
269    async fn set_ext_data(&self, handle: u8, data: &[u8], scan_response: bool) -> Result<()> {
270        let h = AdvHandle::new(handle);
271        let chunks: Vec<&[u8]> = if data.is_empty() {
272            vec![&[]]
273        } else {
274            data.chunks(251).collect()
275        };
276        let n = chunks.len();
277        for (i, c) in chunks.into_iter().enumerate() {
278            let op = match (i, n) {
279                (_, 1) => Operation::Complete,
280                (0, _) => Operation::FirstFragment,
281                (i, n) if i == n - 1 => Operation::LastFragment,
282                _ => Operation::IntermediateFragment,
283            };
284            if scan_response {
285                self.inner
286                    .hci
287                    .exec(&LeSetExtScanResponseData::new(h, op, false, c))
288                    .await?;
289            } else {
290                self.inner
291                    .hci
292                    .exec(&LeSetExtAdvData::new(h, op, false, c))
293                    .await?;
294            }
295        }
296        Ok(())
297    }
298
299    async fn advertise_legacy(
300        &self,
301        adv: &mut Advertiser,
302        params: &AdvertisingParams,
303        data: &[u8],
304        scan_response: &[u8],
305    ) -> Result<u8> {
306        if !adv.sets.is_empty() {
307            return Err(Error::Unsupported(
308                "a second advertising set (Bluetooth 4 controller)",
309            ));
310        }
311        if params.legacy == Some(false)
312            || params.anonymous
313            || params.include_tx_power
314            || params.primary_phy != Phy::Le1m
315        {
316            return Err(Error::Unsupported("extended advertising"));
317        }
318        if data.len() > 31 || scan_response.len() > 31 {
319            return Err(Error::InvalidParameter(
320                "legacy advertising data is 31 octets at most".into(),
321            ));
322        }
323        let kind = match (
324            params.connectable,
325            params.directed.is_some(),
326            params.scannable,
327        ) {
328            (true, true, _) if params.high_duty => AdvKind::AdvDirectIndHigh,
329            (true, true, _) => AdvKind::AdvDirectIndLow,
330            (true, false, _) => AdvKind::AdvInd,
331            (false, _, true) => AdvKind::AdvScanInd,
332            (false, _, false) => AdvKind::AdvNonconnInd,
333        };
334        let (peer_kind, peer) = match params.directed {
335            Some(a) => (AddrKind::new(a.hci_type()), BdAddr::new(a.bytes)),
336            None => (AddrKind::PUBLIC, BdAddr::new([0; 6])),
337        };
338        let to_u16 = |ms: u32| {
339            HciDuration::from_u16(u16::try_from(units_625(ms)).unwrap_or(0x4000).min(0x4000))
340        };
341        self.inner
342            .hci
343            .exec(&LeSetAdvParams::new(
344                to_u16(params.interval_min_ms),
345                to_u16(params.interval_max_ms),
346                kind,
347                AddrKind::new(self.address().hci_type()),
348                peer_kind,
349                peer,
350                AdvChannelMap::ALL,
351                if params.filter_accept_list {
352                    AdvFilterPolicy::FilterConnAndScan
353                } else {
354                    AdvFilterPolicy::Unfiltered
355                },
356            ))
357            .await?;
358        let mut d = [0u8; 31];
359        d[..data.len()].copy_from_slice(data);
360        self.inner
361            .hci
362            .exec(&LeSetAdvData::new(data.len() as u8, d))
363            .await?;
364        let mut s = [0u8; 31];
365        s[..scan_response.len()].copy_from_slice(scan_response);
366        self.inner
367            .hci
368            .exec(&LeSetScanResponseData::new(scan_response.len() as u8, s))
369            .await?;
370        self.inner.hci.exec(&LeSetAdvEnable::new(true)).await?;
371        adv.sets.insert(0, params.clone());
372        Ok(0)
373    }
374
375    /// Replaces a running set's data (and scan response, when given).
376    pub async fn set_advertising_data(
377        &self,
378        handle: u8,
379        data: &[u8],
380        scan_response: Option<&[u8]>,
381    ) -> Result<()> {
382        let adv = self.inner.advertiser.lock().await;
383        if !adv.sets.contains_key(&handle) {
384            return Err(Error::InvalidParameter(format!(
385                "no advertising set {handle}"
386            )));
387        }
388        if !self.inner.caps().extended_advertising() {
389            if data.len() > 31 || scan_response.is_some_and(|s| s.len() > 31) {
390                return Err(Error::InvalidParameter(
391                    "legacy advertising data is 31 octets at most".into(),
392                ));
393            }
394            let mut d = [0u8; 31];
395            d[..data.len()].copy_from_slice(data);
396            self.inner
397                .hci
398                .exec(&LeSetAdvData::new(data.len() as u8, d))
399                .await?;
400            if let Some(sr) = scan_response {
401                let mut s = [0u8; 31];
402                s[..sr.len()].copy_from_slice(sr);
403                self.inner
404                    .hci
405                    .exec(&LeSetScanResponseData::new(sr.len() as u8, s))
406                    .await?;
407            }
408            return Ok(());
409        }
410        self.set_ext_data(handle, data, false).await?;
411        if let Some(sr) = scan_response {
412            self.set_ext_data(handle, sr, true).await?;
413        }
414        Ok(())
415    }
416
417    /// Stops and removes a set.
418    pub async fn stop_advertising(&self, handle: u8) -> Result<()> {
419        let mut adv = self.inner.advertiser.lock().await;
420        if adv.sets.remove(&handle).is_none() {
421            return Ok(());
422        }
423        if !self.inner.caps().extended_advertising() {
424            return self.inner.hci.exec(&LeSetAdvEnable::new(false)).await;
425        }
426        let h = AdvHandle::new(handle);
427        let set = AdvSet {
428            adv_handle: h,
429            duration: HciDuration::from_u16(0),
430            max_ext_adv_events: 0,
431        };
432        // The set may have stopped by itself already.
433        let _ = self
434            .inner
435            .hci
436            .exec(&LeSetExtAdvEnable::new(false, &[set]))
437            .await;
438        self.inner.hci.exec(&LeRemoveAdvSet::new(h)).await
439    }
440
441    /// Stops every set.
442    pub async fn stop_all_advertising(&self) -> Result<()> {
443        let mut adv = self.inner.advertiser.lock().await;
444        adv.sets.clear();
445        if self.inner.caps().extended_advertising() {
446            let _ = self
447                .inner
448                .hci
449                .exec(&LeSetExtAdvEnable::new(false, &[]))
450                .await;
451            self.inner.hci.exec(&LeClearAdvSets::new()).await
452        } else {
453            self.inner.hci.exec(&LeSetAdvEnable::new(false)).await
454        }
455    }
456
457    /// Running sets and their parameters.
458    pub async fn advertising_sets(&self) -> Vec<(u8, AdvertisingParams)> {
459        let mut v: Vec<_> = self
460            .inner
461            .advertiser
462            .lock()
463            .await
464            .sets
465            .iter()
466            .map(|(h, p)| (*h, p.clone()))
467            .collect();
468        v.sort_by_key(|(h, _)| *h);
469        v
470    }
471
472    /// Adds a periodic advertising train to a set (which must be extended,
473    /// non-connectable and non-scannable) and starts it.
474    pub async fn start_periodic(
475        &self,
476        handle: u8,
477        params: &PeriodicParams,
478        data: &[u8],
479    ) -> Result<()> {
480        if !self.inner.caps().periodic_advertising() {
481            return Err(Error::Unsupported("periodic advertising"));
482        }
483        {
484            let adv = self.inner.advertiser.lock().await;
485            let p = adv
486                .sets
487                .get(&handle)
488                .ok_or_else(|| Error::InvalidParameter(format!("no advertising set {handle}")))?;
489            if p.connectable || p.scannable || p.legacy == Some(true) {
490                return Err(Error::InvalidParameter(
491                    "periodic advertising needs a non-connectable, non-scannable extended set"
492                        .into(),
493                ));
494            }
495        }
496        let units = |ms: u32| {
497            HciDuration::from_u16(
498                u16::try_from(u64::from(ms) * 1000 / 1250)
499                    .unwrap_or(0xffff)
500                    .max(6),
501            )
502        };
503        let h = AdvHandle::new(handle);
504        self.inner
505            .hci
506            .exec(&LeSetPeriodicAdvParams::new(
507                h,
508                units(params.interval_min_ms),
509                units(params.interval_max_ms),
510                PeriodicAdvProps::new().include_tx_power(params.include_tx_power),
511            ))
512            .await?;
513        self.set_periodic_data(handle, data).await?;
514        self.inner
515            .hci
516            .exec(&LeSetPeriodicAdvEnable::new(true, h))
517            .await
518    }
519
520    /// Replaces a periodic train's data.
521    pub async fn set_periodic_data(&self, handle: u8, data: &[u8]) -> Result<()> {
522        let h = AdvHandle::new(handle);
523        let chunks: Vec<&[u8]> = if data.is_empty() {
524            vec![&[]]
525        } else {
526            data.chunks(252).collect()
527        };
528        let n = chunks.len();
529        for (i, c) in chunks.into_iter().enumerate() {
530            let op = match (i, n) {
531                (_, 1) => Operation::Complete,
532                (0, _) => Operation::FirstFragment,
533                (i, n) if i == n - 1 => Operation::LastFragment,
534                _ => Operation::IntermediateFragment,
535            };
536            self.inner
537                .hci
538                .exec(&LeSetPeriodicAdvData::new(h, op, c))
539                .await?;
540        }
541        Ok(())
542    }
543
544    /// Stops a set's periodic train.
545    pub async fn stop_periodic(&self, handle: u8) -> Result<()> {
546        self.inner
547            .hci
548            .exec(&LeSetPeriodicAdvEnable::new(false, AdvHandle::new(handle)))
549            .await
550    }
551}
552
553/// A set stopped on its own (duration, event count, or a connection).
554pub(crate) fn on_set_terminated(host: &Host, set: u8, _connection: Option<u16>) {
555    let host = host.clone();
556    tokio::spawn(async move {
557        host.inner.advertiser.lock().await.sets.remove(&set);
558    });
559}