From da33e146738642e13dac0c1269ac79b061873364 Mon Sep 17 00:00:00 2001 From: Nikolay Novik Date: Mon, 24 Nov 2025 17:26:07 -0500 Subject: [PATCH] docs: Document commands and resonses strcts. --- src/commands.rs | 26 ++++++++++++++++++++++++++ src/responses.rs | 46 ++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 68 insertions(+), 4 deletions(-) diff --git a/src/commands.rs b/src/commands.rs index f9f6ccf..c3f18d8 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -7,6 +7,8 @@ pub trait SmartAudioCommand { fn to_bytes(&self, buffer: &mut [u8]) -> Result; } +/// Command to get the current settings from the VTX. +/// Corresponds to SmartAudio command `0x01`. #[derive(Default, Debug, Clone, Copy, PartialEq, Eq)] pub struct GetSettingsCommand {} @@ -17,11 +19,17 @@ impl SmartAudioCommand for GetSettingsCommand { } } +/// VTX power setting. #[allow(non_camel_case_types)] #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Power { + /// Power level for SmartAudio V1 and V2. + /// For V1, this is a direct DAC value. + /// For V2, this is an index into a lookup table (e.g., 0 for 25mW, 1 for 200mW). Level(u8), + /// Power in dBm for SmartAudio V2.1. + /// The VTX will set the power to the closest lower supported power level. dBm(u8), } @@ -40,6 +48,8 @@ impl From for u8 { } } +/// Command to set the VTX power. +/// Corresponds to SmartAudio command `0x02`. pub struct SetPowerCommand { pub power: Power, } @@ -51,7 +61,10 @@ impl SmartAudioCommand for SetPowerCommand { } } +/// Command to set the VTX channel. +/// Corresponds to SmartAudio command `0x03`. pub struct SetChannelCommand { + /// Channel index (0-39). pub channel: u8, } @@ -62,7 +75,10 @@ impl SmartAudioCommand for SetChannelCommand { } } +/// Command to set the VTX frequency. +/// Corresponds to SmartAudio command `0x04`. pub struct SetFrequencyCommand { + /// Frequency in MHz (e.g., 5865). pub frequency: u16, } @@ -73,10 +89,20 @@ impl SmartAudioCommand for SetFrequencyCommand { } } +/// Command to set the VTX operation mode (SmartAudio V2+). +/// Corresponds to SmartAudio command `0x05`. pub struct SetModeCommand { + /// Activate "In Range Pit Mode". + /// Reduces output power to a minimum at the current frequency. pub pitmode_in_range_active: bool, + /// Activate "Out Range Pit Mode". + /// Reduces output power to a minimum and sets the frequency to 5584 MHz. + /// Not supported in SmartAudio V2.1 or newer (will default to in-range pit mode). pub pitmode_out_range_active: bool, + /// If `true`, this *deactivates* pit mode. This is counter-intuitive. + /// The flag in the payload (`0x04`) is for "Quit PIT MODE". pub pitmode_enabled: bool, + /// Unlock the VTX. pub unlocked: bool, } diff --git a/src/responses.rs b/src/responses.rs index 0fcb3ab..ab3e24c 100644 --- a/src/responses.rs +++ b/src/responses.rs @@ -4,6 +4,8 @@ use crate::constants::response as resp; use crate::SmartAudioParser; use crate::{parser::SmartAudioError, RawSmartAudioFrame}; +/// The SmartAudio protocol version. +/// This is determined from the command byte of a `GetSettings` response. #[derive(Default, Debug, Clone, Copy, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Version { @@ -31,35 +33,55 @@ pub trait SmartAudioReponse { fn from_raw_frame(raw_frame: &RawSmartAudioFrame<'_>) -> Self; } +/// Detailed power settings, included in `GetSettings` response for SmartAudio V2.1+. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct PowerSettings { + /// The currently selected power in dBm. pub current_power: u8, + /// The number of available power levels. pub num_power_levels: u8, + /// Power level 1 in dBm. pub dbm_level_1: u8, + /// Power level 2 in dBm. pub dbm_level_2: u8, + /// Power level 3 in dBm. pub dbm_level_3: u8, + /// Power level 4 in dBm. pub dbm_level_4: u8, } +/// The VTX settings, returned in response to a `GetSettingsCommand`. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct Settings { + /// SmartAudio protocol version. pub version: Version, + /// Current channel (0-39). pub channel: u8, + /// Current power level index. pub power_level: u8, + /// Current frequency in MHz. pub frequency: u16, + /// VTX is unlocked. pub unlocked: bool, + /// VTX is in user-defined frequency mode. pub user_frequency_mode: bool, + /// Pit mode is currently active. pub pitmode_enabled: bool, + /// In-range pit mode is configured. pub pitmode_in_range_active: bool, + /// Out-of-range pit mode is configured. pub pitmode_out_range_active: bool, + /// Detailed power settings for SmartAudio V2.1+. pub power_settings: Option, } +/// Response to a `SetPowerCommand`. #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct SetPowerResponse { + /// The new power. For V1/V2 this is a level index, for V2.1 it's in dBm. power: u8, } @@ -71,9 +93,11 @@ impl SmartAudioReponse for SetPowerResponse { } } +/// Response to a `SetChannelCommand`. #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct SetChannelResponse { + /// The new channel index (0-39). channel: u8, } @@ -85,9 +109,11 @@ impl SmartAudioReponse for SetChannelResponse { } } +/// Response to a `SetFrequencyCommand`. #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct SetFrequencyResponse { + /// The new frequency in MHz. frequency: u16, } @@ -100,13 +126,18 @@ impl SmartAudioReponse for SetFrequencyResponse { } } +/// Response to a `SetModeCommand`. #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct SetModeResponse { - pitmode_in_range_active: bool, - pitmode_out_range_active: bool, - pitmode_enabled: bool, - unlocked: bool, + /// In-range pit mode is active. + pub pitmode_in_range_active: bool, + /// Out-of-range pit mode is active. + pub pitmode_out_range_active: bool, + /// Pit mode is running. + pub pitmode_enabled: bool, + /// VTX is unlocked. + pub unlocked: bool, } impl SmartAudioReponse for SetModeResponse { @@ -167,14 +198,21 @@ impl SmartAudioReponse for Settings { } } +/// A parsed response from the VTX. #[derive(Debug, Clone)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Response { + /// Current VTX settings (`GetSettingsCommand` response). GetSettings(Settings), + /// Power setting confirmation (`SetPowerCommand` response). SetPower(SetPowerResponse), + /// Channel setting confirmation (`SetChannelCommand` response). SetChannel(SetChannelResponse), + /// Frequency setting confirmation (`SetFrequencyCommand` response). SetFrequency(SetFrequencyResponse), + /// Mode setting confirmation (`SetModeCommand` response). SetMode(SetModeResponse), + /// An unknown or unsupported response. Unknown(u8), }