drew_connect/decoder.rs
1// Copyright (C) 2026 Jorge Andre Castro
2// GPL-2.0-or-later
3
4//! Décodage d'octets bruts en paquets typés.
5//!
6//! [`Decoder`] est générique sur son type de sortie : une implémentation de
7//! décodage n'a pas besoin de connaître [`TelemetryPacket`] ni aucun autre
8//! type spécifique. Ce dernier est fourni comme structure par défaut prête
9//! à l'emploi, mais n'importe quel type `Send` peut être produit par un
10//! décodeur — y compris un type défini en dehors de ce crate.
11
12/// Trait pour le décodage de formats de trames spécifiques.
13///
14/// `Output` est le type de paquet produit par ce décodeur ; il doit être
15/// `Send` pour pouvoir traverser le canal du [`crate::worker::ConnectionWorker`].
16pub trait Decoder: Send {
17 /// Type de paquet produit par ce décodeur.
18 type Output: Send;
19
20 /// Tente de décoder une trame brute.
21 ///
22 /// Retourne `None` si la trame est invalide ou incomplète (trame
23 /// partielle, format inattendu, etc.) — l'appelant est libre d'ignorer
24 /// la trame ou de la journaliser selon son contexte.
25 fn decode(&mut self, raw_data: &[u8]) -> Option<Self::Output>;
26}
27
28/// Structure de télémétrie standard fournie par défaut.
29///
30/// Reste indépendante de tout format d'encodage particulier : c'est un
31/// simple conteneur de données, réutilisable par n'importe quel [`Decoder`]
32/// (y compris un décodeur maison, en dehors de ce crate).
33#[derive(Debug, Clone, Default, PartialEq)]
34#[cfg_attr(feature = "json", derive(serde::Serialize, serde::Deserialize))]
35pub struct TelemetryPacket {
36 /// Position \[x, y, z\]
37 pub position: [f32; 3],
38 /// Rotation \[roll, pitch, yaw\] en radians
39 pub rotation: [f32; 3],
40 /// Horodatage en millisecondes
41 pub timestamp_ms: u64,
42}
43
44/// Décodeur JSON ligne par ligne (texte clair, très pratique pour
45/// prototyper). Nécessite la feature `json`.
46///
47/// Exemple de trame attendue :
48///
49/// ```json
50/// {"position":[0.0, 1.2, 0.5], "rotation":[0.1, 0.0, 0.3], "timestamp_ms":1024}
51/// ```
52#[cfg(feature = "json")]
53pub struct JsonDecoder;
54
55#[cfg(feature = "json")]
56impl Decoder for JsonDecoder {
57 type Output = TelemetryPacket;
58
59 fn decode(&mut self, raw_data: &[u8]) -> Option<TelemetryPacket> {
60 serde_json::from_slice(raw_data).ok()
61 }
62}
63
64/// Décodeur binaire compact (idéal pour microcontrôleurs à faible bande
65/// passante/RAM). Aucune dépendance, toujours disponible sans feature.
66///
67/// Format attendu (28 octets fixes, little-endian) :
68/// - 3 x f32 (12 octets) : Position X, Y, Z
69/// - 3 x f32 (12 octets) : Rotation Roll, Pitch, Yaw
70/// - 1 x u32 (4 octets) : Timestamp MS
71pub struct BinaryDecoder;
72
73impl Decoder for BinaryDecoder {
74 type Output = TelemetryPacket;
75
76 fn decode(&mut self, raw_data: &[u8]) -> Option<TelemetryPacket> {
77 const LEN: usize = 28;
78 if raw_data.len() < LEN {
79 return None;
80 }
81
82 let read_f32 = |offset: usize| -> f32 {
83 let bytes: [u8; 4] = raw_data[offset..offset + 4].try_into().unwrap();
84 f32::from_le_bytes(bytes)
85 };
86
87 let read_u32 = |offset: usize| -> u32 {
88 let bytes: [u8; 4] = raw_data[offset..offset + 4].try_into().unwrap();
89 u32::from_le_bytes(bytes)
90 };
91
92 Some(TelemetryPacket {
93 position: [read_f32(0), read_f32(4), read_f32(8)],
94 rotation: [read_f32(12), read_f32(16), read_f32(20)],
95 timestamp_ms: read_u32(24) as u64,
96 })
97 }
98}
99
100#[cfg(test)]
101mod tests {
102 use super::*;
103
104 #[test]
105 fn binary_decoder_rejects_short_frames() {
106 assert_eq!(BinaryDecoder.decode(&[0u8; 10]), None);
107 }
108
109 #[test]
110 fn binary_decoder_round_trip() {
111 let mut raw = Vec::new();
112 for v in [1.0f32, 2.0, 3.0, 0.1, 0.2, 0.3] {
113 raw.extend_from_slice(&v.to_le_bytes());
114 }
115 raw.extend_from_slice(&42u32.to_le_bytes());
116
117 let packet = BinaryDecoder.decode(&raw).expect("trame valide");
118 assert_eq!(packet.position, [1.0, 2.0, 3.0]);
119 assert_eq!(packet.rotation, [0.1, 0.2, 0.3]);
120 assert_eq!(packet.timestamp_ms, 42);
121 }
122}