Skip to main content

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}