move cli package to example, add comments to it.

Author: hdoordt

Cargo.toml

@@ -1,5 +1,27 @@
-[workspace]
-members = [
-    "cli",
-    "ppk2"
-]
+[package]
+name = "ppk2"
+version = "0.1.0"
+edition = "2021"
+authors = ["Henk Oordt <[email protected]>"]
+description = "A driver for Nordic's Power Profiler Kit 2"
+readme = "README.md"
+repository = "https://github.com/hdoordt/ppk2-rs"
+license = "MIT"
+keywords = ["PPK2", "Power", "Profiler", "Nordic", "Serial"]
+categories = ["embedded", "development-tools::profiling"]
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+num_enum = "0.5.7"
+serialport = "4.2.0"
+thiserror = "1.0.32"
+tracing = "0.1.36"
+
+[dev-dependencies]
+anyhow = { version = "1.0.60", features = ["backtrace"] }
+ctrlc = "3.2.2"
+tracing-subscriber = "0.3.15"
+clap = { version = "3.2.20", features = ["derive", "env"] }
+
+[badges]
+maintenance = { status = "passively-maintained" }

cli/Cargo.toml

@@ -63,6 +63,7 @@ struct Args {
 }
 
 fn main() -> Result<()> {
+    // Setup stuff
     let args = Args::parse();
 
     let subscriber = FmtSubscriber::builder()
@@ -75,20 +76,28 @@ fn main() -> Result<()> {
         None => try_find_ppk2_port()?,
     };
 
+    // Connect to PPK2 and initialize
     let mut ppk2 = Ppk2::new(ppk2_port, args.mode)?;
-
     ppk2.set_source_voltage(args.voltage)?;
     ppk2.set_device_power(args.power)?;
+
+    // Set up pin pattern for matching
+    // This particular setup will only
+    // match measurements if pin 0 is low.
     let mut levels = [Level::Either; 8];
     levels[0] = Level::Low;
     let pins = LogicPortPins::with_levels(levels);
-    let (rx, kill) = ppk2.start_measuring_while_matches(pins, args.sps)?;
 
-    let mut kill = Some(kill);
+    // Start measuring.
+    let (rx, kill) = ppk2.start_measurement_matching(pins, args.sps)?;
 
+    // Set up sigkill handler.
+    let mut kill = Some(kill);
     ctrlc::set_handler(move || {
         kill.take().unwrap()().unwrap();
     })?;
+
+    // Receive measurements
     let mut count = 0usize;
     let start = Instant::now();
     let r: Result<()> = loop {
@@ -97,10 +106,10 @@ fn main() -> Result<()> {
         use MeasurementMatch::*;
         match rcv_res {
             Ok(Match(m)) => {
-                debug!("Last: {:.4} μA", m.micro_amps);
+                debug!("Last chunk average: {:.4} μA", m.micro_amps);
             }
             Ok(NoMatch) => {
-                debug!("No match");
+                debug!("No match in the last chunk of measurements");
             }
             Err(RecvTimeoutError::Disconnected) => break Ok(()),
             Err(e) => {

cli/src/main.rs examples/cli.rs

@@ -1,7 +1,7 @@
-#![doc = include_str!("../../README.md")]
+#![doc = include_str!("../README.md")]
 #![deny(missing_docs)]
 
-use measurement::{Measurement, MeasurementAccumulator, MeasurementIterExt, MeasurementMatch};
+use measurement::{MeasurementAccumulator, MeasurementIterExt, MeasurementMatch};
 use serialport::{ClearBuffer::Input, FlowControl, SerialPort};
 use std::str::Utf8Error;
 use std::sync::mpsc::{self, Receiver, SendError, TryRecvError};
@@ -105,12 +105,24 @@ impl Ppk2 {
         Ok(())
     }
 
+    /// Start measurements. Returns a tuple of:
+    /// - [Ppk2<Measuring>],
+    /// - [Receiver] of [measurement::MeasurementMatch], and
+    /// - A closure that can be called to stop the measurement parsing pipeline and return the
+    /// device.
+    pub fn start_measurement(
+        self,
+        sps: usize,
+    ) -> Result<(Receiver<MeasurementMatch>, impl FnOnce() -> Result<Self>)> {
+        self.start_measurement_matching(LogicPortPins::default(), sps)
+    }
+
     /// Start measurements. Returns a tuple of:
     /// - [Ppk2<Measuring>],
     /// - [Receiver] of [measurement::Result], and
     /// - A closure that can be called to stop the measurement parsing pipeline and return the
     /// device.
-    pub fn start_measuring_while_matches(
+    pub fn start_measurement_matching(
         mut self,
         pins: LogicPortPins,
         sps: usize,

ppk2/Cargo.toml

@@ -177,10 +177,16 @@ pub enum MeasurementMatch {
 
 /// Extension trait for VecDeque<Measurement>
 pub trait MeasurementIterExt {
-    /// Combine items into a single [Measurement], if there are items.
+    /// Combine items into a single [MeasurementMatch::Match], if there are items.
+    /// If there are none, [MeasurementMatch::NoMatch] is returned.
+    /// Set combined logic port pin high if and only if more than half
+    /// of the measurements indicate the pin was high
     fn combine(self, missed: usize) -> MeasurementMatch;
 
-    /// Combine items with matching logic port pins into a single [Measurement], if any.
+    /// Combine items with matching logic port state into a single [MeasurementMatch::Match],
+    /// if there are items. If there are none, [MeasurementMatch::NoMatch] is returned.
+    /// Set combined logic port pin high if and only if more than half
+    /// of the measurements indicate the pin was high
     fn combine_matching(self, missed: usize, matching_pins: LogicPortPins) -> MeasurementMatch;
 }
 
@@ -205,6 +211,8 @@ impl<I: Iterator<Item = Measurement>> MeasurementIterExt for I {
             return MeasurementMatch::NoMatch;
         }
 
+        // Set combined pin high if and only if more than half
+        // of the measurements indicate the pin was high
         let mut pins = [false; 8];
         pin_high_count
             .into_iter()