Krolyxon
Commit 65fed26

Branches

Refs →

budctlcratesbudctl-coresrcdevicesrealme_t310codec.rs

1409 lines · 56.0 KB · Rust

Raw Blame History Download
1//! realme Buds T310 commands, tables and pure decoders. No I/O here, so every function can be
2//! tested with bytes from the spec. Each constant cites docs/protocol/realme_t310.md.
3
4use crate::bt::BdAddr;
5use crate::error::{Error, Result};
6use crate::reader::Reader;
7use crate::status::{
8 AncLevel, Battery, Charge, DualDevice, EqBand, EqPreset, Gesture, GestureChoice, NoiseControl, NoiseMode, Switch,
9};
10
11/// Spec: realme_t310.md#bitmap
12pub(super) const HANDSHAKE: u16 = 0x0100;
13/// Spec: realme_t310.md#identity
14pub(super) const PRODUCT_ID: u16 = 0x0103;
15/// Spec: realme_t310.md#firmware
16pub(super) const FIRMWARE: u16 = 0x0105;
17/// Spec: realme_t310.md#battery
18pub(super) const BATTERY: u16 = 0x0106;
19/// Spec: realme_t310.md#gestures
20pub(super) const GESTURES: u16 = 0x0108;
21/// Spec: realme_t310.md#anc-read
22pub(super) const NOISE_CONTROL: u16 = 0x010C;
23/// Spec: realme_t310.md#switches
24pub(super) const SWITCHES: u16 = 0x010D;
25/// Spec: realme_t310.md#anc-write
26pub(super) const NOISE_CONTROL_WRITE: u16 = 0x0404;
27/// Spec: realme_t310.md#switch-write
28pub(super) const SWITCH_WRITE: u16 = 0x0403;
29/// Spec: realme_t310.md#eq-write
30pub(super) const EQ_SELECT: u16 = 0x0406;
31/// Spec: realme_t310.md#find
32pub(super) const FIND: u16 = 0x0400;
33/// Spec: realme_t310.md#bass-write
34pub(super) const BASS_LEVEL_WRITE: u16 = 0x041B;
35/// The bass-level range. Spec: realme_t310.md#bass-write
36pub(super) const BASS_RANGE: (i8, i8) = (-5, 5);
37
38/// `FB 05 <level s8>`: the range bytes, then the level. Spec: realme_t310.md#bass-write
39pub(super) fn bass_write_payload(level: i8) -> Result<[u8; 3]> {
40 let (min, max) = BASS_RANGE;
41 if !(min..=max).contains(&level) {
42 return Err(Error::Usage(format!(
43 "the bass level goes from {min} to +{max}; {level} is outside"
44 )));
45 }
46 let [min, max, level] = [min, max, level].map(|v| v.to_le_bytes()[0]);
47 Ok([min, max, level])
48}
49/// Spec: realme_t310.md#gesture-write
50pub(super) const GESTURE_WRITE: u16 = 0x0401;
51
52/// `01` starts ringing, `00` stops it. Spec: realme_t310.md#find
53pub(super) fn find_payload(ring: bool) -> [u8; 1] {
54 [u8::from(ring)]
55}
56/// Spec: realme_t310.md#eq-read
57pub(super) const EQ_PRESET: u16 = 0x010F;
58/// Spec: realme_t310.md#codec
59pub(super) const CODEC: u16 = 0x0114;
60/// Spec: realme_t310.md#dual-devices
61pub(super) const DUAL_DEVICES: u16 = 0x0112;
62/// The state of a connected device. Spec: realme_t310.md#dual-devices
63const DUAL_CONNECTED: u8 = 0x02;
64/// Flag bits: the device that asked, the main audio device, playing. Spec: realme_t310.md#dual-devices
65const DUAL_THIS: u8 = 0x01;
66/// Spec: realme_t310.md#dual-devices
67const DUAL_MAIN_AUDIO: u8 = 0x02;
68/// Spec: realme_t310.md#dual-devices
69const DUAL_PLAYING: u8 = 0x04;
70/// Spec: realme_t310.md#custom-eq
71pub(super) const CUSTOM_EQ_LIST: u16 = 0x0122;
72/// Spec: realme_t310.md#custom-eq
73pub(super) const CUSTOM_EQ_WRITE: u16 = 0x0418;
74/// The `0x0418` action that saves a whole preset and selects it. Spec: realme_t310.md#custom-eq
75const CUSTOM_EQ_SAVE: u8 = 0x02;
76/// The `0x0418` action that creates a preset; the buds give it an id. Spec: realme_t310.md#custom-eq
77const CUSTOM_EQ_CREATE: u8 = 0x01;
78/// The `0x0418` action that deletes a preset. Spec: realme_t310.md#custom-eq
79const CUSTOM_EQ_DELETE: u8 = 0x03;
80/// The range and bands of the owner's T310's custom presets: what a new preset gets when there is
81/// none to copy. Spec: realme_t310.md#custom-eq-create
82const T310_CUSTOM_RANGE: (i8, i8) = (-6, 6);
83/// Spec: realme_t310.md#custom-eq-create
84const T310_CUSTOM_BANDS: [u16; 6] = [50, 250, 1000, 4000, 8000, 16000];
85/// The most custom presets the buds keep. Spec: realme_t310.md#custom-eq
86pub(super) const CUSTOM_EQ_MAX: usize = 3;
87/// The longest preset name budctl writes, in bytes. budctl's own limit: the name's length is one
88/// byte, and the vendor's limit is unknown. Spec: realme_t310.md#custom-eq-create
89const CUSTOM_EQ_NAME_MAX: usize = 16;
90/// Spec: realme_t310.md#events-offered
91pub(super) const EVENTS_OFFERED: u16 = 0x0200;
92/// Spec: realme_t310.md#subscribe
93pub(super) const SUBSCRIBE: u16 = 0x0205;
94/// Spec: realme_t310.md#fit-test
95pub(super) const FIT_TEST: u16 = 0x0405;
96
97/// Spec: realme_t310.md#identity
98pub(super) const T310_PRODUCT_ID: u32 = 0x06_3C_12;
99
100/// Payload asking for the current noise-control mode. Spec: realme_t310.md#anc-read
101pub(super) const NOISE_MODE_QUERY: [u8; 2] = [0x01, 0x01];
102/// Payload asking for the hold's noise-control cycle (one setting for both buds).
103/// Spec: realme_t310.md#hold-cycle
104pub(super) const HOLD_CYCLE_QUERY: [u8; 2] = [0x02, 0x01];
105/// Count, then the T310's switch ids: `05 06 11 1A 1B 1D`. Spec: realme_t310.md#switches
106pub(super) const SWITCH_QUERY: [u8; 7] = [6, 0x05, 0x06, 0x11, 0x1A, 0x1B, 0x1D];
107
108/// Event codes to subscribe to; the optional ones only when their command is allowed.
109/// Spec: realme_t310.md#subscribe
110const EVENTS: [(u8, Option<u16>); 4] = [(0x01, None), (0x02, None), (0x03, None), (0x04, Some(FIT_TEST))];
111
112/// Spec: realme_t310.md#switches
113const SWITCH_NAMES: [(u8, &str, &str); 5] = [
114 (0x06, "game", "Game mode"),
115 (0x11, "dual", "Dual connection"),
116 (0x1A, "wind", "Wind-noise reduction"),
117 (0x1B, "spatial", "3D sound"),
118 (0x1D, "bass-boost", "Bass boost"),
119];
120
121/// Noise-control masks: mode and level. Spec: realme_t310.md#anc-read
122const NOISE_MODES: [(u32, &str, Option<&str>); 5] = [
123 (0x01, "off", None),
124 (0x02, "transparency", None),
125 (0x04, "anc", Some("light")),
126 (0x08, "anc", Some("deep")),
127 (0x10, "anc", Some("medium")),
128];
129
130/// Bits of the hold cycle. Spec: realme_t310.md#hold-cycle
131const CYCLE_MODES: [(u32, &str); 3] = [(0x01, "off"), (0x02, "transparency"), (0x08, "anc")];
132
133/// Built-in EQ presets by id. Spec: realme_t310.md#eq-read
134const EQ_PRESETS: [(u8, &str); 4] = [
135 (0x00, "pure-raw"),
136 (0x01, "deep-bass"),
137 (0x02, "pure-vocals"),
138 (0x03, "pure-bass"),
139];
140
141/// Spec: realme_t310.md#codec
142const CODECS: [(u8, &str); 8] = [
143 (0x01, "SBC"),
144 (0x02, "AAC"),
145 (0x03, "LDAC"),
146 (0x04, "aptX"),
147 (0x05, "aptX HD"),
148 (0x06, "aptX Adaptive"),
149 (0x07, "LHDC"),
150 (0x08, "LHDC V5"),
151];
152
153/// Gesture-table names. Spec: realme_t310.md#gestures
154const SIDES: [(u8, &str); 3] = [(0x01, "left"), (0x02, "right"), (0x04, "both")];
155/// Spec: realme_t310.md#gestures
156const MAIN_GROUP: u8 = 0x01;
157/// Spec: realme_t310.md#gestures
158const ACTS: [(u8, &str); 6] = [
159 (0x01, "single-tap"),
160 (0x02, "double-tap"),
161 (0x03, "triple-tap"),
162 (0x04, "hold"),
163 (0x05, "slide"),
164 (0x06, "long-hold"),
165];
166/// Spec: realme_t310.md#gestures
167const FUNCTIONS: [(u8, &str); 15] = [
168 (0x00, "none"),
169 (0x01, "play-pause"),
170 (0x03, "voice-assistant"),
171 (0x05, "previous"),
172 (0x06, "next"),
173 (0x07, "volume"),
174 (0x08, "noise-cycle"),
175 (0x09, "favourite-music"),
176 (0x0A, "switch-track"),
177 (0x0B, "volume-up"),
178 (0x0C, "volume-down"),
179 (0x0D, "switch-devices"),
180 (0x11, "game-mode"),
181 (0x1C, "decline-call"),
182 (0x1D, "answer-call"),
183];
184
185fn name_of<K: PartialEq + Copy>(table: &[(K, &'static str)], key: K) -> Option<&'static str> {
186 table.iter().find(|(k, _)| *k == key).map(|(_, name)| *name)
187}
188
189/// When a command may be sent. Spec: realme_t310.md#bitmap
190enum Gate {
191 Always,
192 Bit(u8),
193}
194
195/// The gate of every command budctl uses. An unlisted command is never sent.
196/// Spec: realme_t310.md#bitmap
197fn gate(cmd: u16) -> Option<Gate> {
198 Some(match cmd {
199 0x0100..=0x0104 | 0x0106 | 0x010B | 0x010D | 0x0200 => Gate::Always,
200 0x0105 => Gate::Bit(0),
201 0x0108 | 0x0401 => Gate::Bit(3),
202 0x0109 => Gate::Bit(4),
203 0x0400 => Gate::Bit(5),
204 0x0403 => Gate::Bit(7),
205 0x010C | 0x0404 => Gate::Bit(8),
206 0x0405 => Gate::Bit(9),
207 0x010F | 0x0406 => Gate::Bit(10),
208 0x0114 => Gate::Bit(17),
209 0x0205 => Gate::Bit(22),
210 0x0112 => Gate::Bit(29),
211 0x0122 | 0x0418 => Gate::Bit(34),
212 0x0124 | 0x041B => Gate::Bit(38),
213 _ => return None,
214 })
215}
216
217/// The commands these buds accept, from the handshake reply. Spec: realme_t310.md#bitmap
218#[derive(Debug)]
219pub(super) struct Commands {
220 bitmap: Vec<u8>,
221}
222
223impl Commands {
224 pub(super) fn parse(reply: &[u8]) -> Result<Self> {
225 let mut r = ok_reply(reply, "the handshake")?;
226 Ok(Self {
227 bitmap: r.rest().to_vec(),
228 })
229 }
230
231 pub(super) fn allows(&self, cmd: u16) -> bool {
232 match gate(cmd) {
233 Some(Gate::Always) => true,
234 Some(Gate::Bit(n)) => self
235 .bitmap
236 .get(usize::from(n / 8))
237 .is_some_and(|byte| byte & (1 << (n % 8)) != 0),
238 None => false,
239 }
240 }
241}
242
243/// A reply whose status byte is `00`, positioned after it. Spec: realme_t310.md#seq
244fn ok_reply<'a>(reply: &'a [u8], what: &'static str) -> Result<Reader<'a>> {
245 let mut r = Reader::new(reply, what);
246 match r.u8()? {
247 0x00 => Ok(r),
248 status => Err(Error::Rejected {
249 what: what.to_owned(),
250 status,
251 }),
252 }
253}
254
255/// Spec: realme_t310.md#identity
256pub(super) fn decode_product_id(reply: &[u8]) -> Result<u32> {
257 let mut r = ok_reply(reply, "the product id query")?;
258 let [low, middle, high] = [r.u8()?, r.u8()?, r.u8()?];
259 Ok(u32::from_le_bytes([low, middle, high, 0]))
260}
261
262/// Spec: realme_t310.md#events-offered
263pub(super) fn decode_events_offered(reply: &[u8]) -> Result<Vec<u8>> {
264 let mut r = ok_reply(reply, "the event list")?;
265 let count = r.u8()?;
266 Ok(r.take(usize::from(count))?.to_vec())
267}
268
269/// The subscribe payload: count, then the wanted codes the buds offer.
270/// Spec: realme_t310.md#subscribe
271pub(super) fn subscribe_payload(offered: &[u8], commands: &Commands) -> Vec<u8> {
272 let codes: Vec<u8> = EVENTS
273 .iter()
274 .filter(|(code, needs)| offered.contains(code) && needs.is_none_or(|cmd| commands.allows(cmd)))
275 .map(|(code, _)| *code)
276 .collect();
277 let mut payload = vec![u8::try_from(codes.len()).unwrap_or_default()];
278 payload.extend(codes);
279 payload
280}
281
282/// Spec: realme_t310.md#battery
283pub(super) fn decode_battery(reply: &[u8]) -> Result<Battery> {
284 let mut r = ok_reply(reply, "the battery reply")?;
285 let mut battery = Battery::default();
286 for _ in 0..r.u8()? {
287 let part = r.u8()?;
288 let raw = r.u8()?;
289 let level = raw & 0x7F;
290 if level == 0 {
291 continue; // not known
292 }
293 let charge = Some(Charge {
294 level,
295 charging: raw & 0x80 != 0,
296 });
297 match part {
298 0x01 => battery.left = charge,
299 0x02 => battery.right = charge,
300 0x03 => battery.case = charge,
301 _ => {}
302 }
303 }
304 Ok(battery)
305}
306
307/// The versions of kind 2: plain numbers are joined with dots; full dotted versions (the T310's)
308/// are shown once each, joined with ` / `. The raw text when there are none.
309/// Spec: realme_t310.md#firmware
310pub(super) fn decode_firmware(reply: &[u8]) -> Result<String> {
311 let mut r = ok_reply(reply, "the firmware reply")?;
312 let _count = r.u8()?;
313 let text = String::from_utf8_lossy(r.rest()).into_owned();
314 let fields: Vec<&str> = text.split(',').map(str::trim).collect();
315 let mut versions: Vec<&str> = fields
316 .chunks(3)
317 .filter_map(|triple| match triple {
318 [_device, "2", version] => Some(*version),
319 _ => None,
320 })
321 .collect();
322 if versions.is_empty() {
323 return Ok(text);
324 }
325 if !versions.iter().any(|v| v.contains('.')) {
326 return Ok(versions.join("."));
327 }
328 let mut seen = Vec::new();
329 versions.retain(|v| {
330 let new = !seen.contains(v);
331 seen.push(*v);
332 new
333 });
334 Ok(versions.join(" / "))
335}
336
337/// Spec: realme_t310.md#codec
338pub(super) fn decode_codec(reply: &[u8]) -> Result<String> {
339 let codec = ok_reply(reply, "the codec reply")?.u8()?;
340 Ok(name_of(&CODECS, codec).map_or_else(|| format!("unknown (0x{codec:02X})"), str::to_owned))
341}
342
343/// Each entry: the address last byte first, `len`, then `len` bytes: state, flags, the name's
344/// length and the name. Spec: realme_t310.md#dual-devices
345pub(super) fn decode_dual_devices(reply: &[u8]) -> Result<Vec<DualDevice>> {
346 let mut r = ok_reply(reply, "the dual-connection list")?;
347 let count = r.u8()?;
348 let mut devices = Vec::new();
349 for _ in 0..count {
350 let address = r.array()?;
351 let len = r.u8()?;
352 let mut entry = Reader::new(r.take(usize::from(len))?, "a dual-connection entry");
353 let state = entry.u8()?;
354 let flags = entry.u8()?;
355 let name_len = entry.u8()?;
356 let name = String::from_utf8_lossy(entry.take(usize::from(name_len))?).into_owned();
357 devices.push(DualDevice {
358 address: BdAddr::from_reversed(address),
359 name,
360 connected: state == DUAL_CONNECTED,
361 this_computer: flags & DUAL_THIS != 0,
362 main_audio: flags & DUAL_MAIN_AUDIO != 0,
363 playing: flags & DUAL_PLAYING != 0,
364 });
365 }
366 Ok(devices)
367}
368
369/// Spec: realme_t310.md#anc-read
370pub(super) fn decode_noise_mode(reply: &[u8]) -> Result<NoiseControl> {
371 let mask = noise_mask(reply, NOISE_MODE_QUERY, "the noise-control reply")?;
372 Ok(match NOISE_MODES.iter().find(|(m, _, _)| *m == mask) {
373 Some((_, mode, level)) => NoiseControl {
374 mode: (*mode).to_owned(),
375 level: level.map(str::to_owned),
376 },
377 None => NoiseControl {
378 mode: format!("unknown (0x{mask:02X})"),
379 level: None,
380 },
381 })
382}
383
384/// The mask that selects `mode`, as written and as read back. Spec: realme_t310.md#anc-write
385pub(super) fn noise_write_mask(mode: NoiseMode) -> u32 {
386 match mode {
387 NoiseMode::Off => 0x01,
388 NoiseMode::Transparency => 0x02,
389 NoiseMode::Anc(AncLevel::Light) => 0x04,
390 NoiseMode::Anc(AncLevel::Medium) => 0x10,
391 // Also plain "noise cancelling on".
392 NoiseMode::Anc(AncLevel::Deep) => 0x08,
393 }
394}
395
396/// `01 01 <mask>`: the noise-mode kind, then the mask in the fewest bytes (all fit in one).
397/// Spec: realme_t310.md#anc-write
398pub(super) fn noise_write_payload(mode: NoiseMode) -> Vec<u8> {
399 let mut payload = NOISE_MODE_QUERY.to_vec();
400 payload.extend(fewest_bytes(noise_write_mask(mode)));
401 payload
402}
403
404/// A mask in the fewest little-endian bytes that hold it, at least one.
405/// Spec: realme_t310.md#anc-write, #hold-cycle-write
406fn fewest_bytes(mask: u32) -> Vec<u8> {
407 let bytes = mask.to_le_bytes();
408 let used = bytes.iter().rposition(|&b| b != 0).map_or(1, |last| last + 1);
409 bytes.iter().take(used).copied().collect()
410}
411
412/// The mask in a noise-control read reply. Spec: realme_t310.md#anc-read
413pub(super) fn decode_noise_mask(reply: &[u8]) -> Result<u32> {
414 noise_mask(reply, NOISE_MODE_QUERY, "the noise-control reply")
415}
416
417/// A write reply: `00` means accepted. Spec: realme_t310.md#writes
418pub(super) fn check_write_reply(reply: &[u8], what: &'static str) -> Result<()> {
419 ok_reply(reply, what).map(|_| ())
420}
421
422/// Spec: realme_t310.md#hold-cycle
423pub(super) fn decode_hold_cycle(reply: &[u8]) -> Result<Vec<String>> {
424 let mask = decode_hold_cycle_mask(reply)?;
425 let mut modes: Vec<String> = CYCLE_MODES
426 .iter()
427 .filter(|(bit, _)| mask & bit != 0)
428 .map(|(_, name)| (*name).to_owned())
429 .collect();
430 let known = CYCLE_MODES.iter().fold(0, |all, (bit, _)| all | bit);
431 if mask & !known != 0 {
432 modes.push(format!("unknown (0x{:02X})", mask & !known));
433 }
434 Ok(modes)
435}
436
437/// The mask for a hold cycle through `modes` (`off`, `transparency`, `anc`): at least two,
438/// none twice. The buds keep their own order, so the order given does not matter.
439/// Spec: realme_t310.md#hold-cycle-write
440pub(super) fn hold_cycle_mask(modes: &[&str]) -> Result<u32> {
441 let mut mask = 0;
442 for &mode in modes {
443 let Some(&(bit, _)) = CYCLE_MODES.iter().find(|(_, name)| *name == mode) else {
444 let names: Vec<&str> = CYCLE_MODES.iter().map(|(_, name)| *name).collect();
445 return Err(Error::Usage(format!(
446 "no mode called {mode} in the hold cycle; use: {}",
447 names.join(", ")
448 )));
449 };
450 if mask & bit != 0 {
451 return Err(Error::Usage(format!("{mode} is in the hold cycle twice")));
452 }
453 mask |= bit;
454 }
455 if mask.count_ones() < 2 {
456 return Err(Error::Usage("the hold cycle needs at least two modes".to_owned()));
457 }
458 Ok(mask)
459}
460
461/// `02 01 <mask>`, the mask in the fewest bytes. Spec: realme_t310.md#hold-cycle-write
462pub(super) fn hold_cycle_write_payload(mask: u32) -> Vec<u8> {
463 let mut payload = HOLD_CYCLE_QUERY.to_vec();
464 payload.extend(fewest_bytes(mask));
465 payload
466}
467
468/// The mask in a hold-cycle read reply. Spec: realme_t310.md#hold-cycle
469pub(super) fn decode_hold_cycle_mask(reply: &[u8]) -> Result<u32> {
470 noise_mask(reply, HOLD_CYCLE_QUERY, "the hold-cycle reply")
471}
472
473/// `00 <echo of the query> <mask, 1-4 bytes LE>`. Spec: realme_t310.md#anc-read
474fn noise_mask(reply: &[u8], query: [u8; 2], what: &'static str) -> Result<u32> {
475 let mut r = ok_reply(reply, what)?;
476 if [r.u8()?, r.u8()?] != query {
477 return Err(Error::Protocol(format!("{what} answers a different question")));
478 }
479 let bytes = r.rest();
480 if bytes.is_empty() || bytes.len() > 4 {
481 return Err(Error::Protocol(format!("{what} has a {} byte value", bytes.len())));
482 }
483 Ok(bytes.iter().rev().fold(0, |mask, &b| (mask << 8) | u32::from(b)))
484}
485
486/// Spec: realme_t310.md#switches
487pub(super) fn decode_switches(reply: &[u8]) -> Result<Vec<Switch>> {
488 let mut r = ok_reply(reply, "the switch reply")?;
489 let mut switches = Vec::new();
490 for _ in 0..r.u8()? {
491 let id = r.u8()?;
492 let value = r.u8()?;
493 if let Some((_, key, label)) = SWITCH_NAMES.iter().find(|(known, _, _)| *known == id) {
494 switches.push(Switch {
495 key,
496 label,
497 on: value == 0x01,
498 });
499 }
500 }
501 Ok(switches)
502}
503
504/// The id of a switch, by its key (`game`…). Spec: realme_t310.md#switches
505pub(super) fn switch_id(key: &str) -> Option<u8> {
506 SWITCH_NAMES.iter().find(|(_, k, _)| *k == key).map(|(id, _, _)| *id)
507}
508
509/// `<id> <01|00>`. Spec: realme_t310.md#switch-write
510pub(super) fn switch_write_payload(id: u8, on: bool) -> [u8; 2] {
511 [id, u8::from(on)]
512}
513
514/// The id of a built-in EQ preset, by name. Spec: realme_t310.md#eq-read
515pub(super) fn eq_id(name: &str) -> Option<u8> {
516 EQ_PRESETS.iter().find(|(_, n)| *n == name).map(|(id, _)| *id)
517}
518
519/// The built-in EQ presets' names, in id order. Spec: realme_t310.md#eq-read
520pub(super) fn eq_names() -> Vec<&'static str> {
521 EQ_PRESETS.iter().map(|(_, name)| *name).collect()
522}
523
524/// Spec: realme_t310.md#eq-read
525pub(super) fn decode_eq(reply: &[u8]) -> Result<String> {
526 let id = ok_reply(reply, "the EQ reply")?.u8()?;
527 Ok(name_of(&EQ_PRESETS, id).map_or_else(|| format!("custom-{id}"), str::to_owned))
528}
529
530/// The built-in EQ presets, in id order. Spec: realme_t310.md#eq-read
531pub(super) fn builtin_eqs() -> Vec<EqPreset> {
532 EQ_PRESETS
533 .iter()
534 .map(|&(id, name)| EqPreset {
535 name: name.to_owned(),
536 id,
537 custom: false,
538 bands: Vec::new(),
539 range: None,
540 })
541 .collect()
542}
543
544/// One custom preset as the list holds it. Spec: realme_t310.md#custom-eq
545#[derive(Debug, Clone, PartialEq, Eq)]
546pub(super) struct CustomEq {
547 pub(super) selected: bool,
548 /// Gain range, dB.
549 pub(super) min: i8,
550 pub(super) max: i8,
551 pub(super) id: u8,
552 /// The stored name, byte for byte, so a save writes it back unchanged.
553 pub(super) name: Vec<u8>,
554 pub(super) bands: Vec<EqBand>,
555}
556
557impl CustomEq {
558 pub(super) fn preset(&self) -> EqPreset {
559 EqPreset {
560 name: String::from_utf8_lossy(&self.name).into_owned(),
561 id: self.id,
562 custom: true,
563 bands: self.bands.clone(),
564 range: Some((self.min, self.max)),
565 }
566 }
567}
568
569/// `00 <count>`, then per preset `<selected> <min> <max> <id> <nameLen> <name> <bands>
570/// (<freq u16 LE> <gain s8>)…`. Spec: realme_t310.md#custom-eq
571pub(super) fn decode_custom_eq_list(reply: &[u8]) -> Result<Vec<CustomEq>> {
572 let mut r = ok_reply(reply, "the custom EQ list")?;
573 let mut presets = Vec::new();
574 for _ in 0..r.u8()? {
575 let selected = r.u8()? == 0x01;
576 let (min, max, id) = (r.i8()?, r.i8()?, r.u8()?);
577 let name_len = r.u8()?;
578 let name = r.take(usize::from(name_len))?.to_vec();
579 let mut bands = Vec::new();
580 for _ in 0..r.u8()? {
581 bands.push(EqBand {
582 hz: r.u16_le()?,
583 gain: r.i8()?,
584 });
585 }
586 presets.push(CustomEq {
587 selected,
588 min,
589 max,
590 id,
591 name,
592 bands,
593 });
594 }
595 Ok(presets)
596}
597
598/// Spec: realme_t310.md#custom-eq
599pub(super) fn decode_custom_eqs(reply: &[u8]) -> Result<Vec<EqPreset>> {
600 Ok(decode_custom_eq_list(reply)?.iter().map(CustomEq::preset).collect())
601}
602
603/// The id in `custom-<id>`, the name [`decode_eq`] gives a custom preset.
604/// Spec: realme_t310.md#eq-read
605pub(super) fn custom_eq_id(name: &str) -> Option<u8> {
606 name.strip_prefix("custom-")?.parse().ok()
607}
608
609/// The preset with the given bands' gains changed, and nothing else. Every band must be one the
610/// preset has, at most once, with a gain inside the preset's range.
611/// Spec: realme_t310.md#custom-eq
612pub(super) fn retune(preset: &CustomEq, changes: &[EqBand]) -> Result<CustomEq> {
613 let mut tuned = preset.clone();
614 for (i, change) in changes.iter().enumerate() {
615 if changes.iter().take(i).any(|earlier| earlier.hz == change.hz) {
616 return Err(Error::Usage(format!("the {} Hz band is given twice", change.hz)));
617 }
618 let Some(band) = tuned.bands.iter_mut().find(|b| b.hz == change.hz) else {
619 let have: Vec<String> = preset.bands.iter().map(|b| b.hz.to_string()).collect();
620 return Err(Error::Usage(format!(
621 "custom-{} has no {} Hz band; its bands are {} Hz",
622 preset.id,
623 change.hz,
624 have.join(", ")
625 )));
626 };
627 if !(preset.min..=preset.max).contains(&change.gain) {
628 return Err(Error::Usage(format!(
629 "a gain of {:+} dB is outside {:+}..{:+} dB",
630 change.gain, preset.min, preset.max
631 )));
632 }
633 band.gain = change.gain;
634 }
635 Ok(tuned)
636}
637
638/// `02 <min> <max> <id> <nameLen> <name> <bands> (<freq u16 LE> <gain s8>)…`: save the whole
639/// preset and select it. Spec: realme_t310.md#custom-eq
640pub(super) fn custom_eq_save_payload(preset: &CustomEq) -> Result<Vec<u8>> {
641 custom_eq_payload(CUSTOM_EQ_SAVE, preset)
642}
643
644/// `01 <min> <max> 00 <nameLen> <name> <bands> …`: create a preset, as [`new_custom_eq`] makes
645/// it. Spec: realme_t310.md#custom-eq-create
646pub(super) fn custom_eq_create_payload(preset: &CustomEq) -> Result<Vec<u8>> {
647 custom_eq_payload(CUSTOM_EQ_CREATE, preset)
648}
649
650/// A preset name as budctl writes it: 1 to [`CUSTOM_EQ_NAME_MAX`] bytes of UTF-8, no control
651/// characters, no spaces around it. Spec: realme_t310.md#custom-eq-create
652pub(super) fn custom_eq_name(name: &str) -> Result<Vec<u8>> {
653 if name.is_empty() || name.trim() != name {
654 return Err(Error::Usage(
655 "a preset name cannot be empty, or start or end with a space".to_owned(),
656 ));
657 }
658 if name.chars().any(char::is_control) {
659 return Err(Error::Usage("a preset name cannot hold control characters".to_owned()));
660 }
661 if name.len() > CUSTOM_EQ_NAME_MAX {
662 return Err(Error::Usage(format!(
663 "a preset name can be at most {CUSTOM_EQ_NAME_MAX} bytes; \"{name}\" has {}",
664 name.len()
665 )));
666 }
667 Ok(name.as_bytes().to_vec())
668}
669
670/// A new preset called `name`: the range and the bands of `model`, a preset the buds have, else
671/// the T310's own, with every gain at 0, and id `00` for the buds to replace.
672/// Spec: realme_t310.md#custom-eq-create
673pub(super) fn new_custom_eq(name: &str, model: Option<&CustomEq>) -> Result<CustomEq> {
674 let ((min, max), bands): ((i8, i8), Vec<u16>) = match model {
675 Some(model) => ((model.min, model.max), model.bands.iter().map(|b| b.hz).collect()),
676 None => (T310_CUSTOM_RANGE, T310_CUSTOM_BANDS.to_vec()),
677 };
678 Ok(CustomEq {
679 selected: false,
680 min,
681 max,
682 id: 0x00,
683 name: custom_eq_name(name)?,
684 bands: bands.into_iter().map(|hz| EqBand { hz, gain: 0 }).collect(),
685 })
686}
687
688/// `03 <min> <max> <id> <nameLen> <name> <bands> …`: delete the preset, sent as the list holds it.
689/// Spec: realme_t310.md#custom-eq-delete
690pub(super) fn custom_eq_delete_payload(preset: &CustomEq) -> Result<Vec<u8>> {
691 custom_eq_payload(CUSTOM_EQ_DELETE, preset)
692}
693
694/// Whether a list read after deleting `gone` from `before` shows it gone: one preset fewer, and
695/// none left with its name and bands. Ids can change, so they prove nothing.
696/// Spec: realme_t310.md#custom-eq-delete
697pub(super) fn deleted(before: &[CustomEq], gone: &CustomEq, now: &[CustomEq]) -> bool {
698 let same = |p: &CustomEq| p.name == gone.name && p.bands == gone.bands;
699 let left_before = before.iter().filter(|p| same(p)).count().saturating_sub(1);
700 now.len() + 1 == before.len() && now.iter().filter(|p| same(p)).count() == left_before
701}
702
703/// The preset under a new name, and nothing else changed: saved with [`custom_eq_save_payload`],
704/// it is renamed. Spec: realme_t310.md#custom-eq-rename
705pub(super) fn renamed(preset: &CustomEq, name: &str) -> Result<CustomEq> {
706 Ok(CustomEq {
707 name: custom_eq_name(name)?,
708 ..preset.clone()
709 })
710}
711
712/// The id in a `0x0418` reply: `00 <id>`. Spec: realme_t310.md#custom-eq
713pub(super) fn decode_custom_eq_write_reply(reply: &[u8]) -> Result<u8> {
714 let mut r = ok_reply(reply, "the custom EQ write")?;
715 r.u8()
716}
717
718/// The preset a create made, in the list read after it: the one with that name and the id the
719/// buds answered, else the only one with that name. Spec: realme_t310.md#custom-eq-create
720pub(super) fn find_created<'a>(list: &'a [CustomEq], name: &[u8], id: u8) -> Option<&'a CustomEq> {
721 let mut named = list.iter().filter(|p| p.name == name);
722 list.iter()
723 .find(|p| p.name == name && p.id == id)
724 .or_else(|| match (named.next(), named.next()) {
725 (Some(only), None) => Some(only),
726 _ => None,
727 })
728}
729
730fn custom_eq_payload(action: u8, preset: &CustomEq) -> Result<Vec<u8>> {
731 let too_long = |what: &str| Error::Protocol(format!("the preset's {what} does not fit in a byte"));
732 let mut payload = vec![action];
733 payload.extend([preset.min.to_le_bytes()[0], preset.max.to_le_bytes()[0], preset.id]);
734 payload.push(u8::try_from(preset.name.len()).map_err(|_| too_long("name"))?);
735 payload.extend(&preset.name);
736 payload.push(u8::try_from(preset.bands.len()).map_err(|_| too_long("band count"))?);
737 for band in &preset.bands {
738 payload.extend(band.hz.to_le_bytes());
739 payload.push(band.gain.to_le_bytes()[0]);
740 }
741 Ok(payload)
742}
743
744/// One gesture-table entry: `<dev> <btn> <act> <fn>`. Spec: realme_t310.md#gestures
745pub(super) type GestureEntry = [u8; 4];
746
747/// The entries of a gesture-table reply, in the order the buds sent them.
748/// Spec: realme_t310.md#gestures
749pub(super) fn decode_gesture_entries(reply: &[u8]) -> Result<Vec<GestureEntry>> {
750 let mut r = ok_reply(reply, "the gesture table")?;
751 let mut entries = Vec::new();
752 for _ in 0..r.u8()? {
753 entries.push([r.u8()?, r.u8()?, r.u8()?, r.u8()?]);
754 }
755 Ok(entries)
756}
757
758/// Spec: realme_t310.md#gestures
759pub(super) fn name_gesture(&[side, group, act, function]: &GestureEntry) -> Gesture {
760 Gesture {
761 side: name_of(&SIDES, side).map_or_else(|| format!("device-0x{side:02X}"), str::to_owned),
762 gesture: name_of(&ACTS, act).map_or_else(|| format!("act-0x{act:02X}"), str::to_owned),
763 action: name_of(&FUNCTIONS, function).map_or_else(|| format!("fn-0x{function:02X}"), str::to_owned),
764 group: (group != MAIN_GROUP).then_some(group),
765 }
766}
767
768/// Spec: realme_t310.md#gestures
769pub(super) fn decode_gestures(reply: &[u8]) -> Result<Vec<Gesture>> {
770 Ok(decode_gesture_entries(reply)?.iter().map(name_gesture).collect())
771}
772
773/// What `touch <side>` changes: `both` is the left and the right bud's entry.
774/// Spec: realme_t310.md#gesture-choices
775const TOUCH_SIDES: [(&str, &[u8]); 3] = [("left", &[0x01]), ("right", &[0x02]), ("both", &[0x01, 0x02])];
776
777/// The actions realme Link offers per gesture on the T310, in its order. budctl offers no
778/// others. Spec: realme_t310.md#gesture-choices
779const TOUCH_CHOICES: [(u8, &[u8]); 3] = [
780 // double tap: none, play/pause, next, voice assistant
781 (0x02, &[0x00, 0x01, 0x06, 0x03]),
782 // triple tap: none, previous, next, voice assistant, volume up, volume down, game mode
783 (0x03, &[0x00, 0x05, 0x06, 0x03, 0x0B, 0x0C, 0x11]),
784 // hold: none, noise-control cycle, voice assistant, game mode
785 (0x04, &[0x00, 0x08, 0x03, 0x11]),
786];
787
788/// The actions each gesture can be given, by name, in realme Link's order.
789/// Spec: realme_t310.md#gesture-choices
790pub(super) fn touch_choices() -> Vec<GestureChoice> {
791 TOUCH_CHOICES
792 .iter()
793 .filter_map(|&(act, functions)| {
794 Some(GestureChoice {
795 gesture: name_of(&ACTS, act)?.to_owned(),
796 actions: functions
797 .iter()
798 .filter_map(|&f| name_of(&FUNCTIONS, f).map(str::to_owned))
799 .collect(),
800 })
801 })
802 .collect()
803}
804
805/// The modes a hold cycle can include, by name. Spec: realme_t310.md#hold-cycle-write
806pub(super) fn cycle_modes() -> Vec<String> {
807 CYCLE_MODES.iter().map(|&(_, name)| name.to_owned()).collect()
808}
809
810/// A checked `touch <side> <gesture> <action>`: the bud ids, the act and the fn to write.
811#[derive(Debug, PartialEq, Eq)]
812pub(super) struct TouchTarget {
813 pub(super) devices: &'static [u8],
814 pub(super) act: u8,
815 pub(super) function: u8,
816}
817
818/// Check the names against what the T310 offers. Every failure is a usage error that lists
819/// the valid names. Spec: realme_t310.md#gesture-choices
820pub(super) fn touch_target(side: &str, gesture: &str, action: &str) -> Result<TouchTarget> {
821 let list = |names: Vec<&str>| names.join(", ");
822 let Some(&(_, devices)) = TOUCH_SIDES.iter().find(|(name, _)| *name == side) else {
823 return Err(Error::Usage(format!(
824 "no side called {side}; use one of: {}",
825 list(TOUCH_SIDES.iter().map(|(name, _)| *name).collect())
826 )));
827 };
828 let gesture_names = || {
829 list(
830 TOUCH_CHOICES
831 .iter()
832 .filter_map(|(act, _)| name_of(&ACTS, *act))
833 .collect(),
834 )
835 };
836 let Some(&(act, choices)) = TOUCH_CHOICES
837 .iter()
838 .find(|(act, _)| name_of(&ACTS, *act) == Some(gesture))
839 else {
840 return Err(Error::Usage(format!(
841 "these buds have no {gesture} gesture to set; use one of: {}",
842 gesture_names()
843 )));
844 };
845 let Some(&function) = choices.iter().find(|f| name_of(&FUNCTIONS, **f) == Some(action)) else {
846 return Err(Error::Usage(format!(
847 "{gesture} cannot be set to {action} on these buds; use one of: {}",
848 list(choices.iter().filter_map(|f| name_of(&FUNCTIONS, *f)).collect())
849 )));
850 };
851 Ok(TouchTarget { devices, act, function })
852}
853
854/// The table with the target's entries changed, and nothing else. Every targeted entry must
855/// already be in the table: budctl never adds entries. Spec: realme_t310.md#gesture-write
856pub(super) fn retarget_gestures(table: &[GestureEntry], target: &TouchTarget) -> Result<Vec<GestureEntry>> {
857 for &device in target.devices {
858 if !table
859 .iter()
860 .any(|&[d, group, act, _]| d == device && group == MAIN_GROUP && act == target.act)
861 {
862 let entry = name_gesture(&[device, MAIN_GROUP, target.act, 0]);
863 return Err(Error::Unsupported(format!(
864 "the buds report no {} {} entry, so budctl will not write one",
865 entry.side, entry.gesture
866 )));
867 }
868 }
869 Ok(table
870 .iter()
871 .map(|&[device, group, act, function]| {
872 if target.devices.contains(&device) && group == MAIN_GROUP && act == target.act {
873 [device, group, act, target.function]
874 } else {
875 [device, group, act, function]
876 }
877 })
878 .collect())
879}
880
881/// `<count> (<dev> <btn> <act> <fn>)…`: the whole table. Spec: realme_t310.md#gesture-write
882pub(super) fn gesture_write_payload(table: &[GestureEntry]) -> Result<Vec<u8>> {
883 let count = u8::try_from(table.len())
884 .map_err(|_| Error::Protocol(format!("a gesture table of {} entries does not fit", table.len())))?;
885 let mut payload = vec![count];
886 payload.extend(table.iter().flatten());
887 Ok(payload)
888}
889
890/// The handshake reply of the owner's T310 (HW1). Spec: realme_t310.md#bitmap-t310
891#[cfg(test)]
892pub(super) const T310_BITMAP_REPLY: &str = "00 BF 1F 5A 20 45 04 40 00";
893
894#[cfg(test)]
895mod tests {
896 use super::*;
897 use crate::transport::mock::hex;
898
899 #[test]
900 fn t310_bitmap_allows_its_commands_and_nothing_else() {
901 let commands = Commands::parse(&hex(T310_BITMAP_REPLY)).unwrap();
902 // Every gated command in the T310's logged command set (realme_t310.md#bitmap-t310).
903 for cmd in [
904 0x0100, 0x0103, 0x0105, 0x0106, 0x0108, 0x0109, 0x010C, 0x010D, 0x010F, 0x0112, 0x0114, 0x0122, 0x0124,
905 0x0205, 0x0400, 0x0401, 0x0403, 0x0404, 0x0405, 0x0406, 0x0418, 0x041B, 0x0200,
906 ] {
907 assert!(commands.allows(cmd), "0x{cmd:04X} should be allowed");
908 }
909 // Commands the T310 lacks (the dual-connection device manager among them), and commands
910 // budctl has no gate for.
911 for cmd in [
912 0x012F, 0x041E, 0x0413, 0x0130, 0x0427, 0x0423, 0x012A, 0x0422, 0x0429, 0x0132, 0x9999,
913 ] {
914 assert!(!commands.allows(cmd), "0x{cmd:04X} should be refused");
915 }
916 }
917
918 #[test]
919 fn a_short_bitmap_allows_only_the_always_commands() {
920 let commands = Commands::parse(&hex("00")).unwrap();
921 assert!(commands.allows(BATTERY) && commands.allows(SWITCHES) && commands.allows(HANDSHAKE));
922 assert!(!commands.allows(FIRMWARE) && !commands.allows(NOISE_CONTROL));
923 assert!(matches!(
924 Commands::parse(&hex("01 FF")),
925 Err(Error::Rejected { status: 1, .. })
926 ));
927 }
928
929 #[test]
930 fn product_id_is_three_bytes_little_endian() {
931 assert_eq!(decode_product_id(&hex("00 12 3C 06")).unwrap(), T310_PRODUCT_ID);
932 assert_eq!(decode_product_id(&hex("00 14 54 06")).unwrap(), 0x06_54_14);
933 assert!(decode_product_id(&hex("00 12 3C")).is_err());
934 }
935
936 #[test]
937 fn subscribes_to_offered_events_only() {
938 let commands = Commands::parse(&hex(T310_BITMAP_REPLY)).unwrap();
939 let buds4_offer = hex("00 09 01 02 03 04 08 0B F1 F2 F3");
940 let offered = decode_events_offered(&buds4_offer).unwrap();
941 assert_eq!(subscribe_payload(&offered, &commands), hex("04 01 02 03 04"));
942 assert_eq!(subscribe_payload(&[0x02, 0x01], &commands), hex("02 01 02"));
943 let no_fit_test = Commands::parse(&hex("00 BD 0D")).unwrap();
944 assert_eq!(subscribe_payload(&offered, &no_fit_test), hex("03 01 02 03"));
945 }
946
947 #[test]
948 fn battery_levels_charging_and_unknown_parts() {
949 let battery = decode_battery(&hex("00 03 01 64 02 E4 03 00")).unwrap();
950 assert_eq!(
951 battery.left,
952 Some(Charge {
953 level: 100,
954 charging: false
955 })
956 );
957 assert_eq!(
958 battery.right,
959 Some(Charge {
960 level: 100,
961 charging: true
962 })
963 );
964 assert_eq!(battery.case, None);
965 assert_eq!(decode_battery(&hex("00 00")).unwrap(), Battery::default());
966 assert!(decode_battery(&hex("00 03 01 64")).is_err());
967 }
968
969 #[test]
970 fn firmware_shows_kind_two_versions() {
971 let mut reply = hex("00 04");
972 reply.extend(b"1,2,138,2,2,138,3,1,01,3,2,105");
973 assert_eq!(decode_firmware(&reply).unwrap(), "138.138.105");
974 // The owner's T310 (HW1): both buds report the same full version.
975 let mut t310 = hex("00 02");
976 t310.extend(b"1,2,1.1.0.43,2,2,1.1.0.43");
977 assert_eq!(decode_firmware(&t310).unwrap(), "1.1.0.43");
978 let mut differ = hex("00 02");
979 differ.extend(b"1,2,1.1.0.43,2,2,1.1.0.44");
980 assert_eq!(decode_firmware(&differ).unwrap(), "1.1.0.43 / 1.1.0.44");
981 let mut odd = hex("00 01");
982 odd.extend(b"V1.0.2");
983 assert_eq!(decode_firmware(&odd).unwrap(), "V1.0.2");
984 }
985
986 #[test]
987 fn noise_control_modes() {
988 let mode = |reply: &str| decode_noise_mode(&hex(reply)).unwrap();
989 assert_eq!(mode("00 01 01 01").mode, "off");
990 assert_eq!(mode("00 01 01 02 00").mode, "transparency");
991 let deep = mode("00 01 01 08");
992 assert_eq!((deep.mode.as_str(), deep.level.as_deref()), ("anc", Some("deep")));
993 assert_eq!(mode("00 01 01 10").level.as_deref(), Some("medium"));
994 assert_eq!(mode("00 01 01 00 08").mode, "unknown (0x800)");
995 assert!(decode_noise_mode(&hex("00 02 01 08")).is_err());
996 assert!(decode_noise_mode(&hex("00 01 01")).is_err());
997 assert!(matches!(
998 decode_noise_mode(&hex("0E 01 01 08")),
999 Err(Error::Rejected { status: 0x0E, .. })
1000 ));
1001 }
1002
1003 #[test]
1004 fn noise_control_write_payloads() {
1005 assert_eq!(noise_write_payload(NoiseMode::Off), hex("01 01 01"));
1006 assert_eq!(noise_write_payload(NoiseMode::Transparency), hex("01 01 02"));
1007 assert_eq!(noise_write_payload(NoiseMode::Anc(AncLevel::Light)), hex("01 01 04"));
1008 assert_eq!(noise_write_payload(NoiseMode::Anc(AncLevel::Medium)), hex("01 01 10"));
1009 assert_eq!(noise_write_payload(NoiseMode::Anc(AncLevel::Deep)), hex("01 01 08"));
1010 // What is written is what a read reports: every write mask decodes to its own mode.
1011 for level in [AncLevel::Light, AncLevel::Medium, AncLevel::Deep] {
1012 let mut reply = hex("00 01 01");
1013 reply.extend(noise_write_payload(NoiseMode::Anc(level)).iter().skip(2));
1014 let read = decode_noise_mode(&reply).unwrap();
1015 assert_eq!((read.mode.as_str(), read.level.as_deref()), ("anc", Some(level.name())));
1016 }
1017 // The family's documented frame for "off" (realme_t310.md#frame-whole).
1018 let frame =
1019 crate::devices::realme_t310::frame::encode(NOISE_CONTROL_WRITE, 0x06, &noise_write_payload(NoiseMode::Off))
1020 .unwrap();
1021 assert_eq!(frame, hex("AA 0A 00 00 04 04 06 03 00 01 01 01"));
1022 }
1023
1024 #[test]
1025 fn switch_writes() {
1026 assert_eq!(switch_id("game"), Some(0x06));
1027 assert_eq!(switch_id("dual"), Some(0x11));
1028 assert_eq!(switch_id("turbo"), None);
1029 assert_eq!(switch_write_payload(0x06, true), [0x06, 0x01]);
1030 assert_eq!(switch_write_payload(0x06, false), [0x06, 0x00]);
1031 }
1032
1033 #[test]
1034 fn eq_presets_by_name() {
1035 assert_eq!(eq_id("pure-raw"), Some(0x00));
1036 assert_eq!(eq_id("pure-bass"), Some(0x03));
1037 assert_eq!(eq_id("custom-7"), None);
1038 assert_eq!(eq_names(), ["pure-raw", "deep-bass", "pure-vocals", "pure-bass"]);
1039 // Every preset reads back under the name it was selected by.
1040 for name in eq_names() {
1041 let reply = [0x00, eq_id(name).unwrap()];
1042 assert_eq!(decode_eq(&reply).unwrap(), name);
1043 }
1044 }
1045
1046 #[test]
1047 fn find_payloads() {
1048 assert_eq!(find_payload(true), [0x01]);
1049 assert_eq!(find_payload(false), [0x00]);
1050 }
1051
1052 #[test]
1053 fn write_replies() {
1054 assert!(check_write_reply(&hex("00"), "the write").is_ok());
1055 assert!(matches!(
1056 check_write_reply(&hex("0E"), "the write"),
1057 Err(Error::Rejected { status: 0x0E, .. })
1058 ));
1059 assert!(check_write_reply(&[], "the write").is_err());
1060 }
1061
1062 #[test]
1063 fn hold_cycle_lists_modes() {
1064 assert_eq!(decode_hold_cycle(&hex("00 02 01 0A")).unwrap(), ["transparency", "anc"]);
1065 assert_eq!(
1066 decode_hold_cycle(&hex("00 02 01 0B 00")).unwrap(),
1067 ["off", "transparency", "anc"]
1068 );
1069 assert_eq!(decode_hold_cycle(&hex("00 02 01 14")).unwrap(), ["unknown (0x14)"]);
1070 }
1071
1072 #[test]
1073 fn switches_from_report_22_values() {
1074 let switches = decode_switches(&hex("00 06 05 00 06 00 11 01 1A 00 1B 01 1D 01")).unwrap();
1075 let on: Vec<(&str, bool)> = switches.iter().map(|s| (s.key, s.on)).collect();
1076 assert_eq!(
1077 on,
1078 [
1079 ("game", false),
1080 ("dual", true),
1081 ("wind", false),
1082 ("spatial", true),
1083 ("bass-boost", true)
1084 ]
1085 );
1086 assert!(decode_switches(&hex("00 02 06 01")).is_err());
1087 }
1088
1089 #[test]
1090 fn eq_and_codec() {
1091 assert_eq!(decode_eq(&hex("00 00")).unwrap(), "pure-raw");
1092 assert_eq!(decode_eq(&hex("00 03")).unwrap(), "pure-bass");
1093 assert_eq!(decode_eq(&hex("00 05")).unwrap(), "custom-5");
1094 assert_eq!(decode_codec(&hex("00 02")).unwrap(), "AAC");
1095 assert_eq!(decode_codec(&hex("00 09")).unwrap(), "unknown (0x09)");
1096 }
1097
1098 #[test]
1099 fn dual_devices_from_the_spec_example() {
1100 let devices = decode_dual_devices(&hex(
1101 "00 02 66 55 44 33 22 11 0A 02 06 07 50 69 78 65 6C 20 38 CC BB AA 00 1A 2B 07 02 01 04 61 72 63 68",
1102 ))
1103 .unwrap();
1104 let [phone, computer] = devices.as_slice() else {
1105 panic!("two devices expected: {devices:?}");
1106 };
1107 assert_eq!(phone.address.to_string(), "11:22:33:44:55:66");
1108 assert_eq!(phone.name, "Pixel 8");
1109 assert!(phone.connected && phone.main_audio && phone.playing && !phone.this_computer);
1110 assert_eq!(computer.address.to_string(), "2B:1A:00:AA:BB:CC");
1111 assert_eq!(computer.name, "arch");
1112 assert!(computer.connected && computer.this_computer && !computer.main_audio && !computer.playing);
1113 }
1114
1115 #[test]
1116 fn dual_devices_skip_by_len_and_keep_disconnected_ones() {
1117 // A device that left (state 00) with two bytes after its name, then an empty list.
1118 let devices = decode_dual_devices(&hex("00 01 01 02 03 04 05 06 06 00 00 01 41 FF FF")).unwrap();
1119 let [gone] = devices.as_slice() else {
1120 panic!("one device expected: {devices:?}");
1121 };
1122 assert_eq!(gone.address.to_string(), "06:05:04:03:02:01");
1123 assert_eq!(gone.name, "A");
1124 assert!(!gone.connected && !gone.this_computer);
1125 assert!(decode_dual_devices(&hex("00 00")).unwrap().is_empty());
1126 // A name longer than its entry, an entry cut short, a refusal.
1127 assert!(decode_dual_devices(&hex("00 01 01 02 03 04 05 06 04 02 00 05 41")).is_err());
1128 assert!(decode_dual_devices(&hex("00 01 01 02 03 04 05 06 07 02 00 04 61")).is_err());
1129 assert!(decode_dual_devices(&hex("01")).is_err());
1130 }
1131
1132 #[test]
1133 fn gesture_table_names_known_values() {
1134 let gestures = decode_gestures(&hex("00 03 01 01 02 01 02 01 04 08 04 06 02 1D")).unwrap();
1135 let rows: Vec<(&str, &str, &str, Option<u8>)> = gestures
1136 .iter()
1137 .map(|g| (g.side.as_str(), g.gesture.as_str(), g.action.as_str(), g.group))
1138 .collect();
1139 assert_eq!(
1140 rows,
1141 [
1142 ("left", "double-tap", "play-pause", None),
1143 ("right", "hold", "noise-cycle", None),
1144 ("both", "double-tap", "answer-call", Some(6)),
1145 ]
1146 );
1147 let odd = decode_gestures(&hex("00 01 09 01 07 42")).unwrap();
1148 assert_eq!(odd.first().map(|g| g.action.as_str()), Some("fn-0x42"));
1149 assert!(decode_gestures(&hex("00 02 01 01 02 01")).is_err());
1150 }
1151
1152 /// The owner's table (HW1): per bud, double tap play/pause, triple tap next, hold cycle.
1153 const HW1_GESTURES: &str = "00 06 01 01 02 01 01 01 03 06 01 01 04 08 02 01 02 01 02 01 03 06 02 01 04 08";
1154
1155 #[test]
1156 fn touch_targets_follow_the_t310_choices() {
1157 assert_eq!(
1158 touch_target("left", "triple-tap", "volume-up").unwrap(),
1159 TouchTarget {
1160 devices: &[0x01],
1161 act: 0x03,
1162 function: 0x0B
1163 }
1164 );
1165 assert_eq!(touch_target("both", "hold", "none").unwrap().devices, [0x01, 0x02]);
1166 let usage = |side, gesture, action| match touch_target(side, gesture, action) {
1167 Err(Error::Usage(message)) => message,
1168 other => panic!("expected a usage error, got {other:?}"),
1169 };
1170 assert!(usage("middle", "hold", "none").contains("left, right, both"));
1171 assert!(usage("left", "single-tap", "none").contains("double-tap, triple-tap, hold"));
1172 // Offered by the family, but not by realme Link for this gesture.
1173 assert!(usage("left", "double-tap", "volume-up").contains("none, play-pause, next, voice-assistant"));
1174 assert!(usage("left", "hold", "previous").contains("none, noise-cycle, voice-assistant, game-mode"));
1175 }
1176
1177 #[test]
1178 fn retargeting_changes_only_the_targeted_entries() {
1179 let table = decode_gesture_entries(&hex(HW1_GESTURES)).unwrap();
1180 let left = touch_target("left", "triple-tap", "volume-up").unwrap();
1181 let payload = gesture_write_payload(&retarget_gestures(&table, &left).unwrap()).unwrap();
1182 assert_eq!(
1183 payload,
1184 hex("06 01 01 02 01 01 01 03 0B 01 01 04 08 02 01 02 01 02 01 03 06 02 01 04 08")
1185 );
1186 // The frame the spec gives for this change (realme_t310.md#gesture-write).
1187 let frame = crate::devices::realme_t310::frame::encode(GESTURE_WRITE, 0x06, &payload).unwrap();
1188 assert_eq!(
1189 crate::debug::hex(&frame),
1190 "AA 20 00 00 01 04 06 19 00 06 01 01 02 01 01 01 03 0B 01 01 04 08 02 01 02 01 02 01 03 06 02 01 04 08"
1191 );
1192 let both = touch_target("both", "hold", "game-mode").unwrap();
1193 let payload = gesture_write_payload(&retarget_gestures(&table, &both).unwrap()).unwrap();
1194 assert_eq!(
1195 payload,
1196 hex("06 01 01 02 01 01 01 03 06 01 01 04 11 02 01 02 01 02 01 03 06 02 01 04 11")
1197 );
1198 // Unchanged, the payload is the reply without its status byte.
1199 let same = touch_target("right", "double-tap", "play-pause").unwrap();
1200 let payload = gesture_write_payload(&retarget_gestures(&table, &same).unwrap()).unwrap();
1201 assert_eq!(payload, hex(HW1_GESTURES).get(1..).unwrap());
1202 }
1203
1204 #[test]
1205 fn entries_the_buds_did_not_report_are_never_written() {
1206 // Only the left bud's entries.
1207 let table = decode_gesture_entries(&hex("00 03 01 01 02 01 01 01 03 06 01 01 04 08")).unwrap();
1208 let both = touch_target("both", "hold", "none").unwrap();
1209 assert!(matches!(retarget_gestures(&table, &both), Err(Error::Unsupported(_))));
1210 // An on-call row (group 06) is not a main-group entry.
1211 let table = decode_gesture_entries(&hex("00 01 01 06 02 1D")).unwrap();
1212 let left = touch_target("left", "double-tap", "none").unwrap();
1213 assert!(matches!(retarget_gestures(&table, &left), Err(Error::Unsupported(_))));
1214 }
1215
1216 #[test]
1217 fn hold_cycle_writes() {
1218 assert_eq!(hold_cycle_mask(&["transparency", "anc"]).unwrap(), 0x0A);
1219 assert_eq!(hold_cycle_mask(&["anc", "off", "transparency"]).unwrap(), 0x0B);
1220 assert_eq!(hold_cycle_write_payload(0x0B), hex("02 01 0B"));
1221 assert_eq!(hold_cycle_write_payload(0x09), hex("02 01 09"));
1222 let usage = |modes: &[&str]| matches!(hold_cycle_mask(modes), Err(Error::Usage(_)));
1223 assert!(usage(&["anc"]));
1224 assert!(usage(&[]));
1225 assert!(usage(&["anc", "anc"]));
1226 assert!(usage(&["anc", "deep"]));
1227 // What is written reads back as the same modes.
1228 let mut reply = hex("00");
1229 reply.extend(hold_cycle_write_payload(0x0B));
1230 assert_eq!(decode_hold_cycle_mask(&reply).unwrap(), 0x0B);
1231 assert_eq!(decode_hold_cycle(&reply).unwrap(), ["off", "transparency", "anc"]);
1232 // The frame the spec gives (realme_t310.md#hold-cycle-write).
1233 let frame =
1234 crate::devices::realme_t310::frame::encode(NOISE_CONTROL_WRITE, 0x06, &hold_cycle_write_payload(0x0B))
1235 .unwrap();
1236 assert_eq!(crate::debug::hex(&frame), "AA 0A 00 00 04 04 06 03 00 02 01 0B");
1237 }
1238
1239 #[test]
1240 fn custom_eq_list() {
1241 assert!(decode_custom_eqs(&hex("00 00")).unwrap().is_empty());
1242 // One preset "Me", selected, range FA 06, two bands: 62 Hz +3, 16 kHz -2.
1243 let reply = hex("00 01 01 FA 06 04 02 4D 65 02 3E 00 03 80 3E FE");
1244 let presets = decode_custom_eqs(&reply).unwrap();
1245 assert_eq!(
1246 presets,
1247 [EqPreset {
1248 name: "Me".to_owned(),
1249 id: 0x04,
1250 custom: true,
1251 bands: vec![EqBand { hz: 62, gain: 3 }, EqBand { hz: 16000, gain: -2 }],
1252 range: Some((-6, 6)),
1253 }]
1254 );
1255 // Cut short inside the bands.
1256 assert!(decode_custom_eqs(&hex("00 01 01 FA 06 04 02 4D 65 02 3E 00")).is_err());
1257 assert_eq!(builtin_eqs().len(), 4);
1258 }
1259
1260 #[test]
1261 fn bass_level_payloads() {
1262 assert_eq!(bass_write_payload(0).unwrap(), [0xFB, 0x05, 0x00]);
1263 assert_eq!(bass_write_payload(5).unwrap(), [0xFB, 0x05, 0x05]);
1264 assert_eq!(bass_write_payload(-2).unwrap(), [0xFB, 0x05, 0xFE]);
1265 assert_eq!(bass_write_payload(-5).unwrap(), [0xFB, 0x05, 0xFB]);
1266 assert!(matches!(bass_write_payload(6), Err(Error::Usage(_))));
1267 assert!(matches!(bass_write_payload(-6), Err(Error::Usage(_))));
1268 // The frame the spec gives (realme_t310.md#bass-write).
1269 let frame = crate::devices::realme_t310::frame::encode(BASS_LEVEL_WRITE, 0x05, &bass_write_payload(3).unwrap())
1270 .unwrap();
1271 assert_eq!(crate::debug::hex(&frame), "AA 0A 00 00 1B 04 05 03 00 FB 05 03");
1272 }
1273
1274 /// The owner's custom EQ list (W11a): "Custom1", id 04, 6 flat bands from 50 Hz.
1275 const OWNER_CUSTOM_EQS: &str =
1276 "00 01 01 FA 06 04 07 43 75 73 74 6F 6D 31 06 32 00 00 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E 00";
1277
1278 #[test]
1279 fn retunes_the_owners_custom_preset() {
1280 let list = decode_custom_eq_list(&hex(OWNER_CUSTOM_EQS)).unwrap();
1281 let custom1 = list.first().unwrap();
1282 assert!(custom1.selected);
1283 assert_eq!((custom1.min, custom1.max, custom1.id), (-6, 6, 4));
1284 assert_eq!(custom_eq_id("custom-4"), Some(4));
1285 assert_eq!(custom_eq_id("pure-bass"), None);
1286 assert_eq!(custom_eq_id("custom-x"), None);
1287
1288 // Unchanged, the save carries the preset as listed.
1289 assert_eq!(
1290 custom_eq_save_payload(&retune(custom1, &[]).unwrap()).unwrap(),
1291 hex("02 FA 06 04 07 43 75 73 74 6F 6D 31 06 32 00 00 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E 00")
1292 );
1293 let tuned = retune(custom1, &[EqBand { hz: 50, gain: 3 }, EqBand { hz: 16000, gain: -2 }]).unwrap();
1294 let payload = custom_eq_save_payload(&tuned).unwrap();
1295 assert_eq!(
1296 payload,
1297 hex("02 FA 06 04 07 43 75 73 74 6F 6D 31 06 32 00 03 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E FE")
1298 );
1299 // The frame the spec gives (realme_t310.md#custom-eq).
1300 let frame = crate::devices::realme_t310::frame::encode(CUSTOM_EQ_WRITE, 0x06, &payload).unwrap();
1301 assert_eq!(
1302 crate::debug::hex(&frame),
1303 "AA 26 00 00 18 04 06 1F 00 02 FA 06 04 07 43 75 73 74 6F 6D 31 06 32 00 03 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E FE"
1304 );
1305
1306 let usage = |changes: &[EqBand]| matches!(retune(custom1, changes), Err(Error::Usage(_)));
1307 assert!(usage(&[EqBand { hz: 62, gain: 1 }]));
1308 assert!(usage(&[EqBand { hz: 50, gain: 7 }]));
1309 assert!(usage(&[EqBand { hz: 50, gain: -7 }]));
1310 assert!(usage(&[EqBand { hz: 50, gain: 1 }, EqBand { hz: 50, gain: 2 }]));
1311 }
1312
1313 #[test]
1314 fn creates_a_flat_copy_of_the_owners_preset() {
1315 let list = decode_custom_eq_list(&hex(OWNER_CUSTOM_EQS)).unwrap();
1316 let new = new_custom_eq("Test", list.first()).unwrap();
1317 // With no preset to copy, the T310's own layout: the same, here.
1318 assert_eq!(new_custom_eq("Test", None).unwrap(), new);
1319 assert_eq!((new.id, new.min, new.max), (0x00, -6, 6));
1320 assert!(new.bands.iter().all(|b| b.gain == 0));
1321 let hz: Vec<u16> = new.bands.iter().map(|b| b.hz).collect();
1322 assert_eq!(hz, [50, 250, 1000, 4000, 8000, 16000]);
1323 // Spec: realme_t310.md#custom-eq-create (the expected frame, with seq 06)
1324 let frame =
1325 crate::devices::realme_t310::frame::encode(CUSTOM_EQ_WRITE, 0x06, &custom_eq_create_payload(&new).unwrap())
1326 .unwrap();
1327 assert_eq!(
1328 frame,
1329 hex("AA 23 00 00 18 04 06 1C 00 01 FA 06 00 04 54 65 73 74 06 \
1330 32 00 00 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E 00")
1331 );
1332 }
1333
1334 /// The owner's list after W11c: Custom1 (id 04) and Test (id 05, flat, selected).
1335 const OWNER_AFTER_W11C: &str = "00 02 00 FA 06 04 07 43 75 73 74 6F 6D 31 06 32 00 06 FA 00 03 E8 03 03 A0 0F 04 40 1F 06 80 3E 06 \
1336 01 FA 06 05 04 54 65 73 74 06 32 00 00 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E 00";
1337
1338 #[test]
1339 fn renames_the_owners_new_preset() {
1340 let list = decode_custom_eq_list(&hex(OWNER_AFTER_W11C)).unwrap();
1341 let test = list.iter().find(|p| p.id == 0x05).unwrap();
1342 let gym = renamed(test, "Gym").unwrap();
1343 assert_eq!(
1344 (gym.id, gym.bands.clone(), gym.name.clone()),
1345 (0x05, test.bands.clone(), b"Gym".to_vec())
1346 );
1347 // Spec: realme_t310.md#custom-eq-rename (the expected frame, with seq 06)
1348 let frame =
1349 crate::devices::realme_t310::frame::encode(CUSTOM_EQ_WRITE, 0x06, &custom_eq_save_payload(&gym).unwrap())
1350 .unwrap();
1351 assert_eq!(
1352 frame,
1353 hex("AA 22 00 00 18 04 06 1B 00 02 FA 06 05 03 47 79 6D 06 \
1354 32 00 00 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E 00")
1355 );
1356 assert!(renamed(test, "").is_err());
1357 }
1358
1359 #[test]
1360 fn deletes_the_owners_preset_as_listed() {
1361 let list = decode_custom_eq_list(&hex(OWNER_AFTER_W11C)).unwrap();
1362 let mut gym = list.iter().find(|p| p.id == 0x05).unwrap().clone();
1363 gym.name = b"Gym".to_vec();
1364 // Spec: realme_t310.md#custom-eq-delete (the expected frame, with seq 06)
1365 let frame =
1366 crate::devices::realme_t310::frame::encode(CUSTOM_EQ_WRITE, 0x06, &custom_eq_delete_payload(&gym).unwrap())
1367 .unwrap();
1368 assert_eq!(
1369 frame,
1370 hex("AA 22 00 00 18 04 06 1B 00 03 FA 06 05 03 47 79 6D 06 \
1371 32 00 00 FA 00 00 E8 03 00 A0 0F 00 40 1F 00 80 3E 00")
1372 );
1373 let before = vec![list[0].clone(), gym.clone()];
1374 assert!(deleted(&before, &gym, &before[..1]));
1375 assert!(!deleted(&before, &gym, &before));
1376 assert!(!deleted(&before, &gym, &before[1..]), "the wrong one went");
1377 }
1378
1379 #[test]
1380 fn preset_names() {
1381 assert_eq!(custom_eq_name("Gym").unwrap(), b"Gym");
1382 assert_eq!(custom_eq_name("Bass é").unwrap().len(), 7);
1383 for bad in ["", " Gym", "Gym ", "a\tb", "seventeen bytes!!"] {
1384 assert!(matches!(custom_eq_name(bad), Err(Error::Usage(_))), "{bad:?}");
1385 }
1386 }
1387
1388 #[test]
1389 fn finds_the_created_preset() {
1390 let preset = |id, name: &str| CustomEq {
1391 selected: false,
1392 min: -6,
1393 max: 6,
1394 id,
1395 name: name.as_bytes().to_vec(),
1396 bands: Vec::new(),
1397 };
1398 let list = [preset(4, "Custom1"), preset(5, "Test")];
1399 assert_eq!(find_created(&list, b"Test", 5).map(|p| p.id), Some(5));
1400 // Renumbered after the reply: the name still finds it.
1401 assert_eq!(find_created(&list, b"Test", 9).map(|p| p.id), Some(5));
1402 assert!(find_created(&list, b"Other", 5).is_none());
1403 let twins = [preset(4, "Test"), preset(5, "Test")];
1404 assert_eq!(find_created(&twins, b"Test", 5).map(|p| p.id), Some(5));
1405 assert!(find_created(&twins, b"Test", 9).is_none());
1406 assert_eq!(decode_custom_eq_write_reply(&hex("00 05")).unwrap(), 5);
1407 assert!(decode_custom_eq_write_reply(&hex("01 05")).is_err());
1408 }
1409}