WIP

Author: Bergmann89

README.md

@@ -1,12 +1,10 @@
-# HighFlowNext
-
-HighFlowNext is a Rust library for communicating with the [Aquacomputer high flow NEXT](https://shop.aquacomputer.de/Monitoring-and-Controlling/Sensors/Flow-sensor-high-flow-NEXT-G1-4::3953.html) device. It provides strongly typed access to the device’s binary protocol, allowing you to interact with sensor values, settings, and configuration in a safe and structured way. The primary goal of this project is to enable clean integration of the high flow NEXT into [OpenRGB](https://openrgb.org/), so that device data and lighting controls can be accessed and managed alongside other RGB hardware.
+`HighFlowNext` is a Rust library for communicating with the [Aquacomputer high flow NEXT](https://shop.aquacomputer.de/Monitoring-and-Controlling/Sensors/Flow-sensor-high-flow-NEXT-G1-4::3953.html) device. It provides strongly typed access to the device’s binary protocol, allowing you to interact with sensor values, settings, and configuration in a safe and structured way. The primary goal of this project is to enable clean integration of the high flow NEXT into [OpenRGB](https://openrgb.org/), so that device data and lighting controls can be accessed and managed alongside other RGB hardware.
 
 > **Notice**: This is **not an official implementation** from Aquacomputer.
 
 > **Warning**: No guarantees are given regarding correctness, completeness, or stability of the protocol description. Use it at your own risk.
 
-## Features
+# Features
 
 - Reading the settings frame (**done**)
 - Writing the settings frame (**planned**)
@@ -15,20 +13,20 @@ HighFlowNext is a Rust library for communicating with the [Aquacomputer high flo
 - Writing ambient color data (**planned**)
 - Writing sound data (**planned**)
 
-## Use Cases
+# Use Cases
 
-HighFlowNext is intended as a building block for an OpenRGB integration. By decoding the device’s settings and sensor values, it becomes straightforward to surface flow rate, temperatures, and conductivity within the OpenRGB UI or its plugins.
+`HighFlowNext` is intended as a building block for an `OpenRGB` integration. By decoding the device’s settings and sensor values, it becomes straightforward to surface flow rate, temperatures, and conductivity within the `OpenRGB` UI or its plugins.
 
-Planned write-paths for ambient color and sound data aim to let OpenRGB drive RGBpx lighting effects on the high flow NEXT directly, coordinating lighting with the rest of a system’s devices.
+Planned write-paths for ambient color and sound data aim to let `OpenRGB` drive `RGBpx` lighting effects on the high flow NEXT directly, coordinating lighting with the rest of a system’s devices.
 
-Beyond OpenRGB, the crate can also support monitoring, logging, and automation workflows where you want to read configuration, calibrations, and live telemetry and then act on it in your own services or dashboards.
+Beyond `OpenRGB`, the crate can also support monitoring, logging, and automation workflows where you want to read configuration, calibrations, and live telemetry and then act on it in your own services or dashboards.
 
-## Protocol Specification
+# Protocol Specification
 
 If you are only interested in the details of the communication protocol itself,
 please have a look at the included [specification file](https://github.com/Bergmann89/HighFlowNext/blob/master/protocol/SPECIFICATION). It describes the binary
 layout of settings, frames, effects, colors, and source control mappings.
 
-## License
+# License
 
 This crate is licensed under the MIT License.

src/misc/crc.rs

@@ -5,19 +5,27 @@ use crc::{Crc, Digest, Table, CRC_16_USB};
 
 use crate::misc::{IoError, Reader};
 
+/// A writer wrapper that calculates a CRC checksum while writing data.
+///
+/// The checksum is updated automatically as bytes are written.
+/// Once writing is finished, [`finalize`](CrcWriter::finalize) can be used
+/// to obtain both the inner writer and the computed CRC value.
 pub struct CrcWriter<W> {
     writer: W,
     digest: Digest<'static, u16, Table<1>>,
 }
 
 impl<W> CrcWriter<W> {
+    /// Creates a new [`CrcWriter`] wrapping the given writer.
     pub fn new(writer: W) -> Self {
         Self {
             writer,
             digest: CRC.digest(),
         }
     }
 
+    /// Finalizes the CRC calculation and returns the inner writer along with
+    /// the computed CRC value.
     pub fn finalize(self) -> (W, u16) {
         let Self { writer, digest } = self;
 
@@ -42,30 +50,38 @@ impl<W> Write for CrcWriter<W>
 where
     W: Write,
 {
+    /// Writes data to the underlying writer and updates the CRC checksum.
     fn write(&mut self, buf: &[u8]) -> IoResult<usize> {
         self.digest.update(buf);
 
         self.writer.write(buf)
     }
 
+    /// Flushes the underlying writer.
     fn flush(&mut self) -> IoResult<()> {
         self.writer.flush()
     }
 }
 
+/// A reader wrapper that calculates a CRC checksum while reading data.
+///
+/// The checksum is updated automatically as bytes are read. After finishing
+/// reading, [`finalize`](CrcReader::finalize) returns the computed CRC value.
 pub struct CrcReader<'a, R> {
     reader: &'a mut R,
     digest: Digest<'static, u16, Table<1>>,
 }
 
 impl<'a, R> CrcReader<'a, R> {
+    /// Creates a new [`CrcReader`] wrapping the given reader.
     pub fn new(reader: &'a mut R) -> Self {
         Self {
             reader,
             digest: CRC.digest(),
         }
     }
 
+    /// Finalizes the CRC calculation and returns the computed value.
     #[must_use]
     pub fn finalize(self) -> u16 {
         self.digest.finalize()
@@ -89,13 +105,16 @@ where
 {
     type Guard = R::Guard;
 
+    /// Reads exactly `buf.len()` bytes from the underlying reader, updating
+    /// the CRC checksum with the data.
     fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), IoError> {
         self.reader.read_exact(buf)?;
         self.digest.update(buf);
 
         Ok(())
     }
 
+    /// Delegates guard creation to the inner reader’s guard.
     fn guard<F, T>(f: F) -> <Self::Guard as super::Guard>::Output<T>
     where
         F: FnOnce(Self::Guard) -> T,
@@ -104,4 +123,5 @@ where
     }
 }
 
+/// Constant CRC definition using the USB CRC-16 polynomial.
 const CRC: Crc<u16> = Crc::<u16>::new(&CRC_16_USB);

src/misc/io/mod.rs

@@ -4,4 +4,4 @@ mod reader;
 
 pub use self::decode::Decode;
 pub use self::error::Error;
-pub use self::reader::{Guard, GuardOutput, Reader};
+pub use self::reader::{Guard, GuardOutput, Reader, SkipGuard, SkipReader, ValueGuard};

src/misc/io/reader.rs

@@ -103,7 +103,8 @@ where
 /// A wrapper around a [`Reader`] that discards values instead of keeping them.
 ///
 /// Used by [`Decode::skip_bytes`](super::Decode::skip_bytes).
-pub(super) struct SkipReader<'a, R: Reader>(pub(super) &'a mut R);
+#[derive(Debug)]
+pub struct SkipReader<'a, R: Reader>(pub(super) &'a mut R);
 
 impl<R> Reader for SkipReader<'_, R>
 where
@@ -156,7 +157,7 @@ impl Guard for ValueGuard {
 /// A [`Guard`] implementation for **skip mode**.
 /// Values are replaced with [`PhantomData`] and cannot be accessed.
 #[derive(Debug)]
-pub(super) struct SkipGuard;
+pub struct SkipGuard;
 
 impl Guard for SkipGuard {
     type Output<T> = PhantomData<T>;

src/misc/mod.rs

@@ -1,28 +1,12 @@
 //! Miscellaneous utilities for binary I/O, checksums, and typed wrappers.
 //!
 //! This module collects helper traits and types that are reused across
-//! different parts of the codebase. It consists of three main areas:
-//!
-//! - [`io`] – Core traits and helpers for working with binary readers,
-//!   decoding values, and guarding against unwanted allocations.
-//!   Includes [`Reader`], [`Guard`], and [`Decode`], with errors reported
-//!   via [`IoError`].
-//! - [`crc`] – Readers and writers with CRC (checksum) calculation built-in,
-//!   allowing integrity verification of binary streams (`CrcReader`, `CrcWriter`).
-//! - [`wrapped`] – Strongly typed wrappers around primitive values, providing
-//!   validation and range enforcement. Useful for ensuring effect parameters
-//!   like brightness, delays, and widths remain within valid bounds
-//!   (`Wrapped`, `Ranged`, `ValueVerifier`).
-//!
-//! The most important items are re-exported at the top level so you can simply write:
-//!
-//! This keeps protocol code concise while still enforcing correctness
-//! and data integrity.
+//! different parts of the codebase.
 
 mod crc;
 mod io;
 mod wrapped;
 
 pub use self::crc::{CrcReader, CrcWriter};
-pub use self::io::{Decode, Error as IoError, Guard, GuardOutput, Reader};
-pub use self::wrapped::{Ranged, ValueVerifier, Wrapped};
+pub use self::io::{Decode, Error as IoError, Guard, GuardOutput, Reader, SkipGuard, SkipReader, ValueGuard};
+pub use self::wrapped::{Ranged, ValueVerifier, Wrapped, RangeError};

src/misc/wrapped.rs

@@ -6,6 +6,15 @@ use thiserror::Error;
 
 use crate::misc::{Decode, Guard, GuardOutput, IoError, Reader};
 
+/// Macro to define a new typed wrapper around a primitive value.
+///
+/// Example:
+/// ```rust,ignore
+/// define_wrapped! {
+///     /// Brightness level (0..255).
+///     pub type Brightness<u8, BrightnessTag>;
+/// }
+/// ```
 #[macro_export]
 macro_rules! define_wrapped {
     ($(#[$meta:meta])* $pub:vis type $name:ident<$base:ty, $tag:ident> ;) => {
@@ -18,6 +27,9 @@ macro_rules! define_wrapped {
     };
 }
 
+/// Macro to implement a trivial verifier that accepts all values.
+///
+/// Use this when no validation is needed for the type.
 #[macro_export]
 macro_rules! impl_verify_simple {
     ($value_type:ident<$base:ty, $tag:ident>) => {
@@ -31,6 +43,9 @@ macro_rules! impl_verify_simple {
     };
 }
 
+/// Macro to implement a ranged verifier for a wrapper type.
+///
+/// The type will only accept values within the inclusive range [`min`, `max`].
 #[macro_export]
 macro_rules! impl_ranged {
     ($value_type:ident<$base:ty, $tag:ident>, $min:expr, $max:expr) => {
@@ -48,6 +63,11 @@ macro_rules! impl_ranged {
     };
 }
 
+/// A strongly typed wrapper around a primitive value with validation.
+///
+/// Wrappers are parameterized by a phantom `tag` type which implements
+/// either [`Ranged`] or [`ValueVerifier`]. This allows creating distinct
+/// types from the same base primitive while enforcing domain-specific rules.
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd)]
 pub struct Wrapped<T, X> {
     value: T,
@@ -59,11 +79,13 @@ where
     T: Ord,
     X: Ranged<T>,
 {
+    /// Returns the minimum allowed value.
     #[must_use]
     pub fn min_inclusive() -> T {
         X::min_inclusive()
     }
 
+    /// Returns the maximum allowed value.
     #[must_use]
     pub fn max_inclusive() -> T {
         X::max_inclusive()
@@ -74,6 +96,8 @@ impl<T, X> Wrapped<T, X>
 where
     X: ValueVerifier<T>,
 {
+    /// Creates a new wrapper from a primitive value,
+    /// validating it with the associated verifier.
     pub fn from_value(val: T) -> Result<Self, X::Error> {
         let val = X::verify(val)?;
 
@@ -92,6 +116,7 @@ impl<T, X> Deref for Wrapped<T, X> {
     }
 }
 
+/// Implements [`Decode`] for `Wrapped<u8, X>`.
 impl<X> Decode for Wrapped<u8, X>
 where
     X: ValueVerifier<u8>,
@@ -105,6 +130,7 @@ where
     }
 }
 
+/// Implements [`Decode`] for `Wrapped<u16, X>`.
 impl<X> Decode for Wrapped<u16, X>
 where
     X: ValueVerifier<u16>,
@@ -118,6 +144,7 @@ where
     }
 }
 
+/// Implements [`Decode`] for `Wrapped<i16, X>`.
 impl<X> Decode for Wrapped<i16, X>
 where
     X: ValueVerifier<i16>,
@@ -131,17 +158,31 @@ where
     }
 }
 
+/// Trait for types that define inclusive minimum and maximum bounds.
 pub trait Ranged<T> {
+    /// Return the minimum inclusive value for this range.
     fn min_inclusive() -> T;
+
+    /// Return the maximum inclusive value for this range.
     fn max_inclusive() -> T;
 }
 
+/// Trait for types that verify whether a value is valid.
+///
+/// Custom verifiers can reject values outside ranges, apply additional
+/// constraints, or simply accept all values.
 pub trait ValueVerifier<T> {
+    /// Error returned by the verifier.
     type Error;
 
-    fn verify(val: T) -> Result<T, Self::Error>;
+    /// Verify if the given `value` is valid, returning either the valid value
+    /// `Ok(value)` or a suitable error `Err(error)`.
+    fn verify(value: T) -> Result<T, Self::Error>;
 }
 
+/// Default implementation of [`ValueVerifier`] for any [`Ranged`] type.
+///
+/// Rejects values outside the inclusive min/max bounds.
 impl<T, X> ValueVerifier<T> for X
 where
     X: Ranged<T>,
@@ -161,18 +202,26 @@ where
     }
 }
 
+/// Error returned when a value lies outside the allowed range.
 #[derive(Debug, Error)]
 #[error("Value out of range (min={min}, max={max}, val={val})!")]
 pub struct RangeError<T> {
+    /// Minimum inclusive value of the range.
     pub min: T,
+
+    /// Maximum inclusive value of the range.
     pub max: T,
+
+    /// Actual value (not in range).
     pub val: T,
 }
 
 impl<T> RangeError<T>
 where
     T: Display,
 {
+    /// Converts this error into an owned `RangeError<String>`,
+    /// useful for error reporting where `T` is not `Clone`.
     pub fn to_owned(&self) -> RangeError<String> {
         RangeError {
             min: self.min.to_string(),

src/protocol/mod.rs

@@ -9,25 +9,36 @@ use crate::misc::{CrcReader, Decode, Guard, GuardOutput, IoError, Reader};
 
 pub use self::settings::Settings;
 
+/// A top-level protocol frame received from or sent to the device.
+///
+/// Each frame starts with an operation code (`OpCode`), followed by a
+/// payload and a trailing CRC checksum. The `Frame` enum provides typed
+/// variants for the supported op codes.
+///
+/// Currently supported:
+/// - `0x03` → [`Frame::Settings`]
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum Frame {
+    /// Frame carrying the full device settings (decoded into [`Settings`]).
     Settings(Settings),
 }
 
 impl Decode for Frame {
     fn decode<R: Reader>(reader: &mut R) -> Result<GuardOutput<R, Self>, IoError> {
+        // Read the operation code
         let op_code = reader.read_u8()?;
         let mut crc = CrcReader::new(reader);
 
+        // Dispatch based on op code
         let ret = match op_code {
             0x03 => {
                 let ret = Settings::decode(&mut crc)?;
-
                 R::guard(|x| Self::Settings(x.extract(ret)))
             }
             op_code => Err(IoError::InvalidValue("OpCode", op_code.into()))?,
         };
 
+        // Verify CRC
         let crc_actual = crc.finalize();
         let crc_expceted = reader.read_u16be()?;
 

src/protocol/settings/mod.rs

@@ -2,13 +2,7 @@
 //!
 //! This module contains all types and decoding logic related to device
 //! configuration and runtime settings. The `Settings` struct is the top-
-//! level container, which aggregates the following areas:
-//!
-//! - [`system`]   – System-level settings (e.g. `AquaBus` address, standby flags).
-//! - [`sensor`]   – Sensor-related calibration and correction values.
-//! - [`alarm`]    – Alarm configuration (thresholds, delays, behaviors).
-//! - [`display`]  – Display settings for the onboard screen.
-//! - [`lighting`] – Lighting / `RGBpx` settings.
+//! level container.
 
 mod alarm;
 mod display;