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

6 files changed, 504 insertions, 2 deletions

diff --git a/examples/stm32l4/.cargo/config.toml b/examples/stm32l4/.cargo/config.toml
index 83fc6d6f8..d71fb1517 100644
--- a/examples/stm32l4/.cargo/config.toml
+++ b/examples/stm32l4/.cargo/config.toml
@@ -2,7 +2,8 @@
 # replace STM32F429ZITx with your chip as listed in `probe-rs chip list`
 #runner = "probe-rs run --chip STM32L475VGT6"
 #runner = "probe-rs run --chip STM32L475VG"
-runner = "probe-rs run --chip STM32L4S5QI"
+#runner = "probe-rs run --chip STM32L4S5QI"
+runner = "probe-rs run --chip STM32L4R5ZITxP"
 
 [build]
 target = "thumbv7em-none-eabi"
diff --git a/examples/stm32l4/Cargo.toml b/examples/stm32l4/Cargo.toml
index b172878c1..512bb8064 100644
--- a/examples/stm32l4/Cargo.toml
+++ b/examples/stm32l4/Cargo.toml
@@ -6,7 +6,7 @@ license = "MIT OR Apache-2.0"
 
 [dependencies]
 # Change stm32l4s5vi to your chip name, if necessary.
-embassy-stm32 = { version = "0.1.0", path = "../../embassy-stm32", features = [ "defmt", "unstable-pac", "stm32l4s5qi", "memory-x", "time-driver-any", "exti", "chrono"]  }
+embassy-stm32 = { version = "0.1.0", path = "../../embassy-stm32", features = [ "defmt", "unstable-pac", "stm32l4r5zi", "memory-x", "time-driver-any", "exti", "chrono"]  }
 embassy-sync = { version = "0.6.1", path = "../../embassy-sync", features = ["defmt"] }
 embassy-executor = { version = "0.6.3", path = "../../embassy-executor", features = ["task-arena-size-32768", "arch-cortex-m", "executor-thread", "defmt", "integrated-timers"] }
 embassy-time = { version = "0.3.2", path = "../../embassy-time", features = ["defmt", "defmt-timestamp-uptime", "tick-hz-32_768", ] }
diff --git a/examples/stm32l4/README.md b/examples/stm32l4/README.md
new file mode 100644
index 000000000..e463c18a0
--- /dev/null
+++ b/examples/stm32l4/README.md
@@ -0,0 +1,24 @@
+# Examples for STM32L4 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 L4R5ZI-P it should be `probe-rs run --chip STM32L4R5ZITxP`. (use `probe-rs chip list` to find your chip)
+* [ ] Update Cargo.toml to have the correct `embassy-stm32` feature. For example for L4R5ZI-P it should be `stm32l4r5zi`. 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/stm32l4/src/bin/tsc_async.rs b/examples/stm32l4/src/bin/tsc_async.rs
new file mode 100644
index 000000000..ada2c468f
--- /dev/null
+++ b/examples/stm32l4/src/bin/tsc_async.rs
@@ -0,0 +1,108 @@
+// Example of async 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 async TSC interface
+// 3. Waiting for acquisition completion using `pend_for_acquisition`
+// 4. Reading touch values and controlling an LED based on the results
+//
+// Suggested physical setup on STM32L4R5ZI-P board:
+// - Connect a 1000pF capacitor between pin PB4 (D25) and GND. This is your sampling capacitor.
+// - Connect one end of a 1K resistor to pin PB5 (D21) 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 2 of the TSC:
+// - PB4 (D25) as the sampling capacitor, TSC group 2 IO1
+// - PB5 (D21) as the channel pin, TSC group 2 IO2
+//
+// The program continuously reads the touch sensor value:
+// - It starts acquisition, waits for completion using `pend_for_acquisition`, and reads the value.
+// - The LED (connected to PB14) is turned on when touch is detected (sensor value < SENSOR_THRESHOLD).
+// - 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.
+
+#![no_std]
+#![no_main]
+
+use defmt::*;
+use embassy_stm32::gpio::{Level, Output, Speed};
+use embassy_stm32::tsc::{self, *};
+use embassy_stm32::{bind_interrupts, peripherals};
+use embassy_time::Timer;
+use {defmt_rtt as _, panic_probe as _};
+
+bind_interrupts!(struct Irqs {
+    TSC => InterruptHandler<embassy_stm32::peripherals::TSC>;
+});
+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 mut pin_group: PinGroupWithRoles<peripherals::TSC, G2> = PinGroupWithRoles::default();
+    // D25
+    pin_group.set_io1::<tsc_pin_roles::Sample>(context.PB4);
+    // D21
+    let tsc_sensor = pin_group.set_io2::<tsc_pin_roles::Channel>(context.PB5);
+
+    let pin_groups: PinGroups<peripherals::TSC> = PinGroups {
+        g2: Some(pin_group.pin_group),
+        ..Default::default()
+    };
+
+    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 touch_controller = tsc::Tsc::new_async(context.TSC, pin_groups, tsc_conf, Irqs).unwrap();
+
+    // Check if TSC is ready
+    if touch_controller.get_state() != State::Ready {
+        info!("TSC not ready!");
+        return;
+    }
+    info!("TSC initialized successfully");
+
+    let mut led = Output::new(context.PB14, Level::High, Speed::Low);
+
+    let discharge_delay = 1; // ms
+
+    info!("Starting touch_controller interface");
+    loop {
+        touch_controller.set_active_channels_mask(tsc_sensor.pin.into());
+        touch_controller.start();
+        touch_controller.pend_for_acquisition().await;
+        touch_controller.discharge_io(true);
+        Timer::after_millis(discharge_delay).await;
+
+        let group_val = touch_controller.group_get_value(tsc_sensor.pin.group());
+        info!("Touch value: {}", group_val);
+
+        if group_val < SENSOR_THRESHOLD {
+            led.set_high();
+        } else {
+            led.set_low();
+        }
+
+        Timer::after_millis(100).await;
+    }
+}
diff --git a/examples/stm32l4/src/bin/tsc_blocking.rs b/examples/stm32l4/src/bin/tsc_blocking.rs
new file mode 100644
index 000000000..76aba55ba
--- /dev/null
+++ b/examples/stm32l4/src/bin/tsc_blocking.rs
@@ -0,0 +1,147 @@
+// # Example of blocking TSC (Touch Sensing Controller) that lights an LED when touch is detected
+//
+// This example demonstrates how to use the Touch Sensing Controller (TSC) in blocking mode on an STM32L4R5ZI-P board.
+//
+// ## 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 STM32L4R5ZI-P board:
+//
+// - Connect a 1000pF capacitor between pin PB4 (D25) and GND. This is your sampling capacitor.
+// - Connect one end of a 1K resistor to pin PB5 (D21) and leave the other end loose.
+//   The loose end will act as the touch sensor which will register your touch.
+//
+// ## Pin Configuration:
+//
+// The example uses two pins from Group 2 of the TSC:
+// - PB4 (D25) as the sampling capacitor, TSC group 2 IO1
+// - PB5 (D21) as the channel pin, TSC group 2 IO2
+//
+// ## Program Behavior:
+//
+// The program continuously reads the touch sensor value:
+// - It starts acquisition, waits for completion using `poll_for_acquisition`, and reads the value.
+// - The LED (connected to PB14) is turned on when touch is detected (sensor value < SENSOR_THRESHOLD).
+// - Touch values are logged to the console.
+//
+// ## Troubleshooting:
+//
+// - If touch is not detected, try adjusting the SENSOR_THRESHOLD value (currently set to 25).
+// - 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.
+// - Be aware that for some boards, there might be overlapping concerns between some pins,
+//   such as UART connections for the programmer. No errors or warnings will be emitted if you
+//   try to use such a pin for TSC, but you may get strange sensor readings.
+//
+// Note: Configuration values and sampling capacitor value have been determined experimentally.
+// Optimal values may vary based on your specific hardware setup. Refer to the official
+// STM32L4R5ZI-P datasheet and user manuals for more information on pin configurations and TSC functionality.
+
+#![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 g2: PinGroupWithRoles<peripherals::TSC, G2> = PinGroupWithRoles::default();
+    // D25
+    g2.set_io1::<tsc_pin_roles::Sample>(context.PB4);
+    // D21
+    let tsc_sensor = g2.set_io2::<tsc_pin_roles::Channel>(context.PB5);
+
+    let pin_groups: PinGroups<peripherals::TSC> = PinGroups {
+        g2: Some(g2.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");
+
+    let mut led = Output::new(context.PB14, 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
+}
diff --git a/examples/stm32l4/src/bin/tsc_multipin.rs b/examples/stm32l4/src/bin/tsc_multipin.rs
new file mode 100644
index 000000000..20a559514
--- /dev/null
+++ b/examples/stm32l4/src/bin/tsc_multipin.rs
@@ -0,0 +1,222 @@
+// # Example of TSC (Touch Sensing Controller) using multiple pins from the same TSC group
+//
+// This example demonstrates how to use the Touch Sensing Controller (TSC) with multiple pins, including pins from the same TSC group, on an STM32L4R5ZI-P board.
+//
+// ## Key Concepts
+//
+// - Only one TSC pin for each TSC group can be acquired and read at a time.
+// - To control which channel pins are acquired and read, we must write a mask before initiating an acquisition.
+// - We organize channel pins into acquisition banks to manage this process efficiently.
+// - Each acquisition bank can contain exactly one channel pin per TSC group and will contain the relevant mask.
+//
+// ## This example demonstrates how to:
+//
+// 1. Configure multiple channel pins within a single TSC group
+// 2. Use the set_active_channels method to switch between different channels
+// 3. Read and interpret touch values from multiple channels in the same group
+//
+// ## Suggested physical setup on STM32L4R5ZI-P board:
+//
+// - Connect a 1000pF capacitor between pin PB12 (D19) and GND. This is the sampling capacitor for TSC group 1.
+// - Connect one end of a 1K resistor to pin PB13 (D18) and leave the other end loose. This will act as a touch sensor.
+// - Connect a 1000pF capacitor between pin PB4 (D25) and GND. This is the sampling capacitor for TSC group 2.
+// - Connect one end of a 1K resistor to pin PB5 (D22) and leave the other end loose. This will act as a touch sensor.
+// - Connect one end of another 1K resistor to pin PB6 (D71) and leave the other end loose. This will act as a touch sensor.
+//
+// ## Pin Configuration:
+//
+// The example uses pins from two TSC groups:
+//
+// - Group 1:
+//   - PB12 (D19) as sampling capacitor (TSC group 1 IO1)
+//   - PB13 (D18) as channel (TSC group 1 IO2)
+// - Group 2:
+//   - PB4 (D25) as sampling capacitor (TSC group 2 IO1)
+//   - PB5 (D22) as channel (TSC group 2 IO2)
+//   - PB6 (D71) as channel (TSC group 2 IO3)
+//
+// The pins have been chosen for their convenient locations on the STM32L4R5ZI-P board, making it easy to add capacitors and resistors directly to the board without special connectors, breadboards, or soldering.
+//
+// ## Program Behavior:
+//
+// The program reads the designated channel pins and adjusts the LED (connected to PB14) blinking pattern based on which sensor(s) are touched:
+//
+// - No touch: LED off
+// - One sensor touched: Slow blinking
+// - Two sensors touched: Fast blinking
+// - Three sensors touched: LED constantly on
+//
+// ## Troubleshooting:
+//
+// - If touch is not detected, try adjusting the SENSOR_THRESHOLD value (currently set to 20).
+// - 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.
+// - Be aware that for some boards there will be overlapping concerns between some pins, for
+//  example UART connection for the programmer to the MCU and a TSC pin. No errors or warning will
+//  be emitted if you try to use such a pin for TSC, but you will get strange sensor readings.
+//
+// Note: Configuration values and sampling capacitor values have been determined experimentally. Optimal values may vary based on your specific hardware setup. Refer to the official STM32L4R5ZI-P datasheet and user manuals for more information on pin configurations and TSC functionality.
+
+#![no_std]
+#![no_main]
+
+use defmt::*;
+use embassy_stm32::gpio::{Level, Output, Speed};
+use embassy_stm32::tsc::{self, *};
+use embassy_stm32::{bind_interrupts, mode, peripherals};
+use embassy_time::Timer;
+use {defmt_rtt as _, panic_probe as _};
+
+bind_interrupts!(struct Irqs {
+    TSC => InterruptHandler<embassy_stm32::peripherals::TSC>;
+});
+
+const MAX_GROUP_STATUS_READ_ATTEMPTS: usize = 10;
+
+async fn read_touch_values(
+    touch_controller: &mut tsc::Tsc<'_, peripherals::TSC, mode::Async>,
+    tsc_acquisition_bank: &TscAcquisitionBank,
+) -> Option<TscAcquisitionBankReadings> {
+    for _ in 0..MAX_GROUP_STATUS_READ_ATTEMPTS {
+        let status = touch_controller.get_acquisition_bank_status(tsc_acquisition_bank);
+        if status.all_complete() {
+            let r = touch_controller.get_acquisition_bank_values(tsc_acquisition_bank);
+            return Some(r);
+        } else {
+            info!("Acquisition still ongoing");
+            Timer::after_millis(1).await;
+        }
+    }
+    info!("Acquisition failed after {} attempts", MAX_GROUP_STATUS_READ_ATTEMPTS);
+    None
+}
+
+const SENSOR_THRESHOLD: u16 = 20;
+
+async fn acquire_sensors(
+    touch_controller: &mut Tsc<'static, peripherals::TSC, mode::Async>,
+    tsc_acquisition_bank: &TscAcquisitionBank,
+) {
+    touch_controller.set_active_channels_mask(tsc_acquisition_bank.mask());
+    touch_controller.start();
+    touch_controller.pend_for_acquisition().await;
+    touch_controller.discharge_io(true);
+    let discharge_delay = 1; // ms
+    Timer::after_millis(discharge_delay).await;
+}
+
+#[embassy_executor::main]
+async fn main(_spawner: embassy_executor::Spawner) {
+    let device_config = embassy_stm32::Config::default();
+    let context = embassy_stm32::init(device_config);
+
+    // ---------- initial configuration of TSC ----------
+    let mut g1: PinGroupWithRoles<peripherals::TSC, G1> = PinGroupWithRoles::default();
+    g1.set_io1::<tsc_pin_roles::Sample>(context.PB12);
+    let sensor0 = g1.set_io2::<tsc_pin_roles::Channel>(context.PB13);
+
+    let mut g2: PinGroupWithRoles<peripherals::TSC, G2> = PinGroupWithRoles::default();
+    g2.set_io1::<tsc_pin_roles::Sample>(context.PB4);
+    let sensor1 = g2.set_io2(context.PB5);
+    let sensor2 = g2.set_io3(context.PB6);
+
+    let config = tsc::Config {
+        ct_pulse_high_length: ChargeTransferPulseCycle::_16,
+        ct_pulse_low_length: ChargeTransferPulseCycle::_16,
+        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 pin_groups: PinGroups<peripherals::TSC> = PinGroups {
+        g1: Some(g1.pin_group),
+        g2: Some(g2.pin_group),
+        ..Default::default()
+    };
+
+    let mut touch_controller = tsc::Tsc::new_async(context.TSC, pin_groups, config, Irqs).unwrap();
+
+    // ---------- setting up acquisition banks ----------
+    // sensor0 and sensor1 belong to different TSC-groups, therefore we can acquire and
+    // read them both in one go.
+    let bank1 = touch_controller.create_acquisition_bank(TscAcquisitionBankPins {
+        g1_pin: Some(sensor0),
+        g2_pin: Some(sensor1),
+        ..Default::default()
+    });
+    // `sensor1` and `sensor2` belongs to the same TSC-group, therefore we must make sure to
+    // acquire them one at the time. We do this by organizing them into different acquisition banks.
+    let bank2 = touch_controller.create_acquisition_bank(TscAcquisitionBankPins {
+        g2_pin: Some(sensor2),
+        ..Default::default()
+    });
+
+    // Check if TSC is ready
+    if touch_controller.get_state() != State::Ready {
+        crate::panic!("TSC not ready!");
+    }
+
+    info!("TSC initialized successfully");
+
+    let mut led = Output::new(context.PB14, Level::High, Speed::Low);
+
+    let mut led_state = false;
+
+    loop {
+        acquire_sensors(&mut touch_controller, &bank1).await;
+        let readings1: TscAcquisitionBankReadings = read_touch_values(&mut touch_controller, &bank1)
+            .await
+            .expect("should be able to read values for bank 1");
+        acquire_sensors(&mut touch_controller, &bank2).await;
+        let readings2: TscAcquisitionBankReadings = read_touch_values(&mut touch_controller, &bank2)
+            .await
+            .expect("should be able to read values for bank 2");
+
+        let mut touched_sensors_count = 0;
+        for reading in readings1.iter().chain(readings2.iter()) {
+            info!("{}", reading);
+            if reading.sensor_value < SENSOR_THRESHOLD {
+                touched_sensors_count += 1;
+            }
+        }
+
+        match touched_sensors_count {
+            0 => {
+                // No sensors touched, turn off the LED
+                led.set_low();
+                led_state = false;
+            }
+            1 => {
+                // One sensor touched, blink slowly
+                led_state = !led_state;
+                if led_state {
+                    led.set_high();
+                } else {
+                    led.set_low();
+                }
+                Timer::after_millis(200).await;
+            }
+            2 => {
+                // Two sensors touched, blink faster
+                led_state = !led_state;
+                if led_state {
+                    led.set_high();
+                } else {
+                    led.set_low();
+                }
+                Timer::after_millis(50).await;
+            }
+            3 => {
+                // All three sensors touched, LED constantly on
+                led.set_high();
+                led_state = true;
+            }
+            _ => crate::unreachable!(), // This case should never occur with 3 sensors
+        }
+    }
+}