Skip to main content

bluetooth_adv/beacon/
eddystone.rs

1//! Eddystone (<https://github.com/google/eddystone>): service data of UUID
2//! 0xFEAA, first byte the frame type.
3
4use super::Reading;
5use crate::reader::Reader;
6
7#[cfg(feature = "serde")]
8use serde::Serialize;
9
10/// Eddystone's service UUID.
11pub const SERVICE_UUID: u16 = 0xfeaa;
12
13/// An Eddystone frame.
14#[derive(Debug, Clone, PartialEq)]
15#[cfg_attr(
16    feature = "serde",
17    derive(Serialize),
18    serde(tag = "frame", rename_all = "snake_case")
19)]
20pub enum Eddystone {
21    /// Eddystone-UID (0x00).
22    Uid {
23        /// Calibrated TX power at 0 m, dBm.
24        tx_power: i8,
25        /// 10-byte namespace.
26        #[cfg_attr(feature = "serde", serde(serialize_with = "crate::ad::ser_hex"))]
27        namespace: [u8; 10],
28        /// 6-byte instance.
29        #[cfg_attr(feature = "serde", serde(serialize_with = "crate::ad::ser_hex"))]
30        instance: [u8; 6],
31    },
32    /// Eddystone-URL (0x10).
33    Url {
34        /// Calibrated TX power at 0 m, dBm.
35        tx_power: i8,
36        /// The URL, expanded.
37        url: String,
38    },
39    /// Eddystone-TLM (0x20), version 0: telemetry in the clear.
40    Tlm {
41        /// Battery voltage, mV; `None` when the beacon does not measure it.
42        battery_mv: Option<u16>,
43        /// Temperature, °C; `None` when not supported (0x8000).
44        temperature: Option<f64>,
45        /// Advertising PDUs sent since power-on or reboot.
46        adv_count: u32,
47        /// Time since power-on or reboot, seconds (0.1 s resolution).
48        uptime: f64,
49    },
50    /// Eddystone-TLM version 1 (encrypted, for EID beacons).
51    EncryptedTlm {
52        /// The encrypted telemetry.
53        #[cfg_attr(feature = "serde", serde(serialize_with = "crate::ad::ser_hex"))]
54        etlm: [u8; 12],
55        /// Salt.
56        salt: u16,
57        /// Message integrity check.
58        mic: u16,
59    },
60    /// Eddystone-EID (0x30): an ephemeral identifier.
61    Eid {
62        /// Calibrated TX power at 0 m, dBm.
63        tx_power: i8,
64        /// The 8-byte ephemeral identifier.
65        #[cfg_attr(feature = "serde", serde(serialize_with = "crate::ad::ser_hex"))]
66        eid: [u8; 8],
67    },
68}
69
70const URL_SCHEMES: [&str; 4] = ["http://www.", "https://www.", "http://", "https://"];
71const URL_EXPANSIONS: [&str; 14] = [
72    ".com/", ".org/", ".edu/", ".net/", ".info/", ".biz/", ".gov/", ".com", ".org", ".edu", ".net",
73    ".info", ".biz", ".gov",
74];
75
76/// Decodes Eddystone service data; `None` for frame types Eddystone does not
77/// define (KKM uses 0x21 and 0x22 under the same UUID).
78pub fn decode(data: &[u8]) -> Option<Eddystone> {
79    let mut r = Reader::new(data);
80    match r.u8()? {
81        0x00 => {
82            let tx_power = r.i8()?;
83            let namespace = r.array()?;
84            let instance = r.array()?;
85            // Two reserved bytes may follow; they carry nothing.
86            Some(Eddystone::Uid {
87                tx_power,
88                namespace,
89                instance,
90            })
91        }
92        0x10 => {
93            let tx_power = r.i8()?;
94            let mut url = String::from(*URL_SCHEMES.get(usize::from(r.u8()?))?);
95            for b in r.rest() {
96                match URL_EXPANSIONS.get(usize::from(*b)) {
97                    Some(e) => url.push_str(e),
98                    None if (0x21..0x7f).contains(b) => url.push(char::from(*b)),
99                    None => return None,
100                }
101            }
102            Some(Eddystone::Url { tx_power, url })
103        }
104        0x20 => match r.u8()? {
105            0x00 => {
106                let vbatt = r.u16_be()?;
107                let temp = r.i16_be()?;
108                Some(Eddystone::Tlm {
109                    battery_mv: (vbatt != 0).then_some(vbatt),
110                    temperature: (temp != i16::MIN).then_some(f64::from(temp) / 256.0),
111                    adv_count: r.u32_be()?,
112                    uptime: f64::from(r.u32_be()?) / 10.0,
113                })
114            }
115            0x01 => Some(Eddystone::EncryptedTlm {
116                etlm: r.array()?,
117                salt: r.u16_be()?,
118                mic: r.u16_be()?,
119            }),
120            _ => None,
121        },
122        0x30 => Some(Eddystone::Eid {
123            tx_power: r.i8()?,
124            eid: r.array()?,
125        }),
126        _ => None,
127    }
128}
129
130impl Eddystone {
131    pub(crate) fn readings(&self) -> Vec<Reading> {
132        match self {
133            Eddystone::Tlm {
134                battery_mv,
135                temperature,
136                adv_count,
137                uptime,
138            } => {
139                let mut v = Vec::new();
140                if let Some(b) = battery_mv {
141                    v.push(Reading::new("voltage", f64::from(*b) / 1000.0, "V"));
142                }
143                if let Some(t) = temperature {
144                    v.push(Reading::new("temperature", *t, "°C"));
145                }
146                v.push(Reading::new("adv_count", f64::from(*adv_count), ""));
147                v.push(Reading::new("uptime", *uptime, "s"));
148                v
149            }
150            _ => Vec::new(),
151        }
152    }
153}
154
155/// Encodes an Eddystone-URL frame's service data. `None` when the URL has no
156/// Eddystone scheme or does not fit in 17 encoded bytes.
157pub fn encode_url(tx_power: i8, url: &str) -> Option<Vec<u8>> {
158    let (scheme, mut rest) = URL_SCHEMES
159        .iter()
160        .enumerate()
161        .rev()
162        .filter_map(|(i, s)| url.strip_prefix(s).map(|r| (i, r)))
163        .max_by_key(|(i, _)| URL_SCHEMES[*i].len())?;
164    let mut v = vec![0x10, tx_power as u8, scheme as u8];
165    while !rest.is_empty() {
166        if let Some((code, e)) = URL_EXPANSIONS
167            .iter()
168            .enumerate()
169            .filter(|(_, e)| rest.starts_with(**e))
170            .max_by_key(|(_, e)| e.len())
171        {
172            v.push(code as u8);
173            rest = &rest[e.len()..];
174        } else {
175            let c = rest.as_bytes()[0];
176            if !(0x21..0x7f).contains(&c) {
177                return None;
178            }
179            v.push(c);
180            rest = &rest[1..];
181        }
182    }
183    (v.len() <= 20).then_some(v)
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    #[test]
191    fn frames() {
192        let uid =
193            decode(&hex::decode("00e8000102030405060708090a0b0c0d0e0f0000").unwrap()).unwrap();
194        assert!(matches!(uid, Eddystone::Uid { tx_power: -24, .. }));
195        let url = decode(&hex::decode("10f303676f6f676c6507").unwrap()).unwrap();
196        assert_eq!(
197            url,
198            Eddystone::Url {
199                tx_power: -13,
200                url: "https://google.com".into()
201            }
202        );
203        let tlm =
204            decode(&hex::decode("2000 0bb8 1980 00000010 00000064".replace(' ', "")).unwrap())
205                .unwrap();
206        assert_eq!(
207            tlm,
208            Eddystone::Tlm {
209                battery_mv: Some(3000),
210                temperature: Some(25.5),
211                adv_count: 16,
212                uptime: 10.0
213            }
214        );
215        let no_temp = decode(&hex::decode("200000008000000000000000000000").unwrap()).unwrap();
216        assert!(matches!(
217            no_temp,
218            Eddystone::Tlm {
219                battery_mv: None,
220                temperature: None,
221                ..
222            }
223        ));
224        assert!(decode(&[0x21, 0, 0]).is_none());
225        assert!(decode(&[0x10]).is_none());
226    }
227
228    #[test]
229    fn url_round_trip() {
230        for u in [
231            "https://www.example.com/a",
232            "http://pulse.example.org",
233            "https://a.b/c.info",
234        ] {
235            let enc = encode_url(-20, u).unwrap();
236            match decode(&enc).unwrap() {
237                Eddystone::Url { url, .. } => assert_eq!(url, u),
238                other => panic!("{other:?}"),
239            }
240        }
241        assert!(encode_url(0, "ftp://x").is_none());
242    }
243}