drew-connect 0.1.0

Couche d'I/O et de décodage de télémétrie agnostique et modulaire : transports (série, UDP) et décodeurs (JSON, binaire) interchangeables via traits.
Documentation
// Copyright (C) 2026 Jorge Andre Castro
// GPL-2.0-or-later

//! Décodage d'octets bruts en paquets typés.
//!
//! [`Decoder`] est générique sur son type de sortie : une implémentation de
//! décodage n'a pas besoin de connaître [`TelemetryPacket`] ni aucun autre
//! type spécifique. Ce dernier est fourni comme structure par défaut prête
//! à l'emploi, mais n'importe quel type `Send` peut être produit par un
//! décodeur — y compris un type défini en dehors de ce crate.

/// Trait pour le décodage de formats de trames spécifiques.
///
/// `Output` est le type de paquet produit par ce décodeur ; il doit être
/// `Send` pour pouvoir traverser le canal du [`crate::worker::ConnectionWorker`].
pub trait Decoder: Send {
    /// Type de paquet produit par ce décodeur.
    type Output: Send;

    /// Tente de décoder une trame brute.
    ///
    /// Retourne `None` si la trame est invalide ou incomplète (trame
    /// partielle, format inattendu, etc.) — l'appelant est libre d'ignorer
    /// la trame ou de la journaliser selon son contexte.
    fn decode(&mut self, raw_data: &[u8]) -> Option<Self::Output>;
}

/// Structure de télémétrie standard fournie par défaut.
///
/// Reste indépendante de tout format d'encodage particulier : c'est un
/// simple conteneur de données, réutilisable par n'importe quel [`Decoder`]
/// (y compris un décodeur maison, en dehors de ce crate).
#[derive(Debug, Clone, Default, PartialEq)]
#[cfg_attr(feature = "json", derive(serde::Serialize, serde::Deserialize))]
pub struct TelemetryPacket {
    /// Position \[x, y, z\]
    pub position: [f32; 3],
    /// Rotation \[roll, pitch, yaw\] en radians
    pub rotation: [f32; 3],
    /// Horodatage en millisecondes
    pub timestamp_ms: u64,
}

/// Décodeur JSON ligne par ligne (texte clair, très pratique pour
/// prototyper). Nécessite la feature `json`.
///
/// Exemple de trame attendue :
///
/// ```json
/// {"position":[0.0, 1.2, 0.5], "rotation":[0.1, 0.0, 0.3], "timestamp_ms":1024}
/// ```
#[cfg(feature = "json")]
pub struct JsonDecoder;

#[cfg(feature = "json")]
impl Decoder for JsonDecoder {
    type Output = TelemetryPacket;

    fn decode(&mut self, raw_data: &[u8]) -> Option<TelemetryPacket> {
        serde_json::from_slice(raw_data).ok()
    }
}

/// Décodeur binaire compact (idéal pour microcontrôleurs à faible bande
/// passante/RAM). Aucune dépendance, toujours disponible sans feature.
///
/// Format attendu (28 octets fixes, little-endian) :
/// - 3 x f32 (12 octets) : Position X, Y, Z
/// - 3 x f32 (12 octets) : Rotation Roll, Pitch, Yaw
/// - 1 x u32 (4 octets)  : Timestamp MS
pub struct BinaryDecoder;

impl Decoder for BinaryDecoder {
    type Output = TelemetryPacket;

    fn decode(&mut self, raw_data: &[u8]) -> Option<TelemetryPacket> {
        const LEN: usize = 28;
        if raw_data.len() < LEN {
            return None;
        }

        let read_f32 = |offset: usize| -> f32 {
            let bytes: [u8; 4] = raw_data[offset..offset + 4].try_into().unwrap();
            f32::from_le_bytes(bytes)
        };

        let read_u32 = |offset: usize| -> u32 {
            let bytes: [u8; 4] = raw_data[offset..offset + 4].try_into().unwrap();
            u32::from_le_bytes(bytes)
        };

        Some(TelemetryPacket {
            position: [read_f32(0), read_f32(4), read_f32(8)],
            rotation: [read_f32(12), read_f32(16), read_f32(20)],
            timestamp_ms: read_u32(24) as u64,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn binary_decoder_rejects_short_frames() {
        assert_eq!(BinaryDecoder.decode(&[0u8; 10]), None);
    }

    #[test]
    fn binary_decoder_round_trip() {
        let mut raw = Vec::new();
        for v in [1.0f32, 2.0, 3.0, 0.1, 0.2, 0.3] {
            raw.extend_from_slice(&v.to_le_bytes());
        }
        raw.extend_from_slice(&42u32.to_le_bytes());

        let packet = BinaryDecoder.decode(&raw).expect("trame valide");
        assert_eq!(packet.position, [1.0, 2.0, 3.0]);
        assert_eq!(packet.rotation, [0.1, 0.2, 0.3]);
        assert_eq!(packet.timestamp_ms, 42);
    }
}