STM32-TSC: enable discriminating between pins within same TSC group and improve TSC library in general

3 files changed, 162 insertions, 98 deletions

diff --git a/examples/stm32f3/README.md b/examples/stm32f3/README.md
new file mode 100644
index 000000000..0a85c4858
--- /dev/null
+++ b/examples/stm32f3/README.md
@@ -0,0 +1,24 @@
+# Examples for STM32F3 family
+Run individual examples with
+```
+cargo run --bin <module-name>
+```
+for example
+```
+cargo run --bin blinky
+```
+
+## Checklist before running examples
+You might need to adjust `.cargo/config.toml`, `Cargo.toml` and possibly update pin numbers or peripherals to match the specific MCU or board you are using.
+
+* [ ] Update .cargo/config.toml with the correct probe-rs command to use your specific MCU. For example for F303ZE it should be `probe-rs run --chip STM32F303ZETx`. (use `probe-rs chip list` to find your chip)
+* [ ] Update Cargo.toml to have the correct `embassy-stm32` feature. For example for F303ZE it should be `stm32f303ze`. Look in the `Cargo.toml` file of the `embassy-stm32` project to find the correct feature flag for your chip.
+* [ ] If your board has a special clock or power configuration, make sure that it is set up appropriately.
+* [ ] If your board has different pin mapping, update any pin numbers or peripherals in the given example code to match your schematic
+
+If you are unsure, please drop by the Embassy Matrix chat for support, and let us know:
+
+* Which example you are trying to run
+* Which chip and board you are using
+
+Embassy Chat: https://matrix.to/#/#embassy-rs:matrix.org
diff --git a/examples/stm32f3/src/bin/blocking-tsc.rs b/examples/stm32f3/src/bin/blocking-tsc.rs
deleted file mode 100644
index 5c8dac94f..000000000
--- a/examples/stm32f3/src/bin/blocking-tsc.rs
+++ /dev/null
@@ -1,98 +0,0 @@
-// Example of polling TSC (Touch Sensing Controller) that lights an LED when touch is detected.
-//
-// Suggested physical setup on STM32F303ZE Nucleo board:
-// - Connect a 1000pF capacitor between pin A0 and GND. This is your sampling capacitor.
-// - Connect one end of a 1K resistor to pin A1 and leave the other end loose.
-//   The loose end will act as touch sensor which will register your touch.
-//
-// Troubleshooting the setup:
-// - If no touch seems to be registered, then try to disconnect the sampling capacitor from GND momentarily,
-//   now the led should light up. Next try using a different value for the sampling capacitor.
-//   Also experiment with increasing the values for `ct_pulse_high_length`, `ct_pulse_low_length`, `pulse_generator_prescaler`, `max_count_value` and `discharge_delay`.
-//
-// All configuration values and sampling capacitor value have been determined experimentally.
-// Suitable configuration and discharge delay values are highly dependent on the value of the sample capacitor. For example, a shorter discharge delay can be used with smaller capacitor values.
-//
-#![no_std]
-#![no_main]
-
-use defmt::*;
-use embassy_stm32::gpio::{Level, Output, Speed};
-use embassy_stm32::tsc::{self, *};
-use embassy_time::Timer;
-use {defmt_rtt as _, panic_probe as _};
-
-/// This example is written for the nucleo-stm32f303ze, with a stm32f303ze chip.
-///
-/// Make sure you check/update the following (whether you use the F303ZE or another board):
-///
-/// * [ ] Update .cargo/config.toml with the correct `probe-rs run --chip STM32F303ZETx`chip name.
-/// * [ ] Update Cargo.toml to have the correct `embassy-stm32` feature, for F303ZE it should be `stm32f303ze`.
-/// * [ ] If your board has a special clock or power configuration, make sure that it is
-///       set up appropriately.
-/// * [ ] If your board has different pin mapping, update any pin numbers or peripherals
-///       to match your schematic
-///
-/// If you are unsure, please drop by the Embassy Matrix chat for support, and let us know:
-///
-/// * Which example you are trying to run
-/// * Which chip and board you are using
-///
-/// Embassy Chat: https://matrix.to/#/#embassy-rs:matrix.org
-#[embassy_executor::main]
-async fn main(_spawner: embassy_executor::Spawner) {
-    let device_config = embassy_stm32::Config::default();
-    let context = embassy_stm32::init(device_config);
-
-    let tsc_conf = Config {
-        ct_pulse_high_length: ChargeTransferPulseCycle::_8,
-        ct_pulse_low_length: ChargeTransferPulseCycle::_8,
-        spread_spectrum: false,
-        spread_spectrum_deviation: SSDeviation::new(2).unwrap(),
-        spread_spectrum_prescaler: false,
-        pulse_generator_prescaler: PGPrescalerDivider::_32,
-        max_count_value: MaxCount::_255,
-        io_default_mode: false,
-        synchro_pin_polarity: false,
-        acquisition_mode: false,
-        max_count_interrupt: false,
-        channel_ios: TscIOPin::Group1Io1.into(),
-        shield_ios: 0, // no shield
-        sampling_ios: TscIOPin::Group1Io2.into(),
-    };
-
-    let mut g1: PinGroup<embassy_stm32::peripherals::TSC, G1> = PinGroup::new();
-    g1.set_io1(context.PA0, PinType::Sample);
-    g1.set_io2(context.PA1, PinType::Channel);
-
-    let mut touch_controller = tsc::Tsc::new_blocking(context.TSC, Some(g1), None, None, None, None, None, tsc_conf);
-
-    // LED2 on the STM32F303ZE nucleo-board
-    let mut led = Output::new(context.PB7, Level::High, Speed::Low);
-
-    // smaller sample capacitor discharge faster and can be used with shorter delay.
-    let discharge_delay = 5; // ms
-
-    // the interval at which the loop polls for new touch sensor values
-    let polling_interval = 100; // ms
-
-    info!("polling for touch");
-    loop {
-        touch_controller.start();
-        touch_controller.poll_for_acquisition();
-        touch_controller.discharge_io(true);
-        Timer::after_millis(discharge_delay).await;
-
-        let grp1_status = touch_controller.group_get_status(Group::One);
-        match grp1_status {
-            GroupStatus::Complete => {
-                let group_one_val = touch_controller.group_get_value(Group::One);
-                info!("{}", group_one_val);
-                led.set_high();
-            }
-            GroupStatus::Ongoing => led.set_low(),
-        }
-
-        Timer::after_millis(polling_interval).await;
-    }
-}
diff --git a/examples/stm32f3/src/bin/tsc_blocking.rs b/examples/stm32f3/src/bin/tsc_blocking.rs
new file mode 100644
index 000000000..fa7f718e6
--- /dev/null
+++ b/examples/stm32f3/src/bin/tsc_blocking.rs
@@ -0,0 +1,138 @@
+// Example of blocking TSC (Touch Sensing Controller) that lights an LED when touch is detected.
+//
+// This example demonstrates:
+// 1. Configuring a single TSC channel pin
+// 2. Using the blocking TSC interface with polling
+// 3. Waiting for acquisition completion using `poll_for_acquisition`
+// 4. Reading touch values and controlling an LED based on the results
+//
+// Suggested physical setup on STM32F303ZE Nucleo board:
+// - Connect a 1000pF capacitor between pin PA10 and GND. This is your sampling capacitor.
+// - Connect one end of a 1K resistor to pin PA9 and leave the other end loose.
+//   The loose end will act as the touch sensor which will register your touch.
+//
+// The example uses two pins from Group 4 of the TSC:
+// - PA10 as the sampling capacitor, TSC group 4 IO2 (D68 on the STM32F303ZE nucleo-board)
+// - PA9 as the channel pin, TSC group 4 IO1 (D69 on the STM32F303ZE nucleo-board)
+//
+// The program continuously reads the touch sensor value:
+// - It starts acquisition, waits for completion using `poll_for_acquisition`, and reads the value.
+// - The LED is turned on when touch is detected (sensor value < 40).
+// - Touch values are logged to the console.
+//
+// Troubleshooting:
+// - If touch is not detected, try adjusting the SENSOR_THRESHOLD value.
+// - Experiment with different values for ct_pulse_high_length, ct_pulse_low_length,
+//   pulse_generator_prescaler, max_count_value, and discharge_delay to optimize sensitivity.
+//
+// Note: Configuration values and sampling capacitor value have been determined experimentally.
+// Optimal values may vary based on your specific hardware setup.
+// Pins have been chosen for their convenient locations on the STM32F303ZE board. Refer to the
+// official relevant STM32 datasheets and user nucleo-board user manuals to find suitable
+// alternative pins.
+
+#![no_std]
+#![no_main]
+
+use defmt::*;
+use embassy_stm32::gpio::{Level, Output, Speed};
+use embassy_stm32::tsc::{self, *};
+use embassy_stm32::{mode, peripherals};
+use embassy_time::Timer;
+use {defmt_rtt as _, panic_probe as _};
+
+const SENSOR_THRESHOLD: u16 = 25; // Adjust this value based on your setup
+
+#[embassy_executor::main]
+async fn main(_spawner: embassy_executor::Spawner) {
+    let device_config = embassy_stm32::Config::default();
+    let context = embassy_stm32::init(device_config);
+
+    let tsc_conf = Config {
+        ct_pulse_high_length: ChargeTransferPulseCycle::_4,
+        ct_pulse_low_length: ChargeTransferPulseCycle::_4,
+        spread_spectrum: false,
+        spread_spectrum_deviation: SSDeviation::new(2).unwrap(),
+        spread_spectrum_prescaler: false,
+        pulse_generator_prescaler: PGPrescalerDivider::_16,
+        max_count_value: MaxCount::_255,
+        io_default_mode: false,
+        synchro_pin_polarity: false,
+        acquisition_mode: false,
+        max_count_interrupt: false,
+    };
+
+    let mut g: PinGroupWithRoles<peripherals::TSC, G4> = PinGroupWithRoles::default();
+    // D68 on the STM32F303ZE nucleo-board
+    g.set_io2::<tsc_pin_roles::Sample>(context.PA10);
+    // D69 on the STM32F303ZE nucleo-board
+    let tsc_sensor = g.set_io1::<tsc_pin_roles::Channel>(context.PA9);
+
+    let pin_groups: PinGroups<peripherals::TSC> = PinGroups {
+        g4: Some(g.pin_group),
+        ..Default::default()
+    };
+
+    let mut touch_controller = tsc::Tsc::new_blocking(context.TSC, pin_groups, tsc_conf).unwrap();
+
+    // Check if TSC is ready
+    if touch_controller.get_state() != State::Ready {
+        crate::panic!("TSC not ready!");
+    }
+    info!("TSC initialized successfully");
+
+    // LED2 on the STM32F303ZE nucleo-board
+    let mut led = Output::new(context.PB7, Level::High, Speed::Low);
+
+    // smaller sample capacitor discharge faster and can be used with shorter delay.
+    let discharge_delay = 5; // ms
+
+    // the interval at which the loop polls for new touch sensor values
+    let polling_interval = 100; // ms
+
+    info!("polling for touch");
+    loop {
+        touch_controller.set_active_channels_mask(tsc_sensor.pin.into());
+        touch_controller.start();
+        touch_controller.poll_for_acquisition();
+        touch_controller.discharge_io(true);
+        Timer::after_millis(discharge_delay).await;
+
+        match read_touch_value(&mut touch_controller, tsc_sensor.pin).await {
+            Some(v) => {
+                info!("sensor value {}", v);
+                if v < SENSOR_THRESHOLD {
+                    led.set_high();
+                } else {
+                    led.set_low();
+                }
+            }
+            None => led.set_low(),
+        }
+
+        Timer::after_millis(polling_interval).await;
+    }
+}
+
+const MAX_GROUP_STATUS_READ_ATTEMPTS: usize = 10;
+
+// attempt to read group status and delay when still ongoing
+async fn read_touch_value(
+    touch_controller: &mut tsc::Tsc<'_, peripherals::TSC, mode::Blocking>,
+    sensor_pin: TscIOPin,
+) -> Option<u16> {
+    for _ in 0..MAX_GROUP_STATUS_READ_ATTEMPTS {
+        match touch_controller.group_get_status(sensor_pin.group()) {
+            GroupStatus::Complete => {
+                return Some(touch_controller.group_get_value(sensor_pin.group()));
+            }
+            GroupStatus::Ongoing => {
+                // if you end up here a lot, then you prob need to increase discharge_delay
+                // or consider changing the code to adjust the discharge_delay dynamically
+                info!("Acquisition still ongoing");
+                Timer::after_millis(1).await;
+            }
+        }
+    }
+    None
+}