PWM

Author: armandas

src/SUMMARY.md

@@ -10,3 +10,5 @@
 - [Interrupts](./interrupt_intro.md)
   - [GPIO Interrupt](./gpio_interrupt.md)
   - [Exercise: toggle LED with interrupt](./led_with_interrupt.md)
+- [PWM](./pwm.md)
+  - [Exercise: LED breathing effect](./pwm_led_breathing.md)

src/pwm.md

@@ -0,0 +1,61 @@
+# PWM
+
+In this chapter, we will learn how to digitally control the brightness of the LED using [Pulse-width modulation][1].
+We will continue using the same `hello_world` project from the previous workshops.
+
+`esp-hal` crate provides a PWM driver in [`mcpwm`][2] module. Let's start by importing the necessary modules and types:
+
+```rust
+use esp_hal::mcpwm::operator::PwmPinConfig;
+use esp_hal::mcpwm::timer::PwmWorkingMode;
+use esp_hal::mcpwm::{McPwm, PeripheralClockConfig};
+use esp_hal::time::Rate;
+```
+
+Next, let set up the PWM peripheral:
+
+```rust
+let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(40)).unwrap();
+let mut mcpwm = McPwm::new(peripherals.MCPWM0, clock_cfg);
+let timer_clock_cfg = clock_cfg
+    .timer_clock_with_frequency(255, PwmWorkingMode::Increase, Rate::from_khz(20))
+    .expect("could not determine parameters for the requested frequency");
+
+mcpwm.operator0.set_timer(&mcpwm.timer0);
+mcpwm.timer0.start(timer_clock_cfg);
+```
+
+> 💡 Note the use of `expect`. `expect` performs the same function as `unwrap`, but allows us to write a helpful
+> error message. In general, use of `unwrap` is discouraged outside of "example" code. Ideally, the errors should be
+> handled gracefully or at least, provide an explanation of what has happened.
+
+We'll change the LED pin to GPIO16, so we can have active-high configuration:
+
+```rust
+let led = Output::new(
+    peripherals.GPIO16,
+    esp_hal::gpio::Level::Low,
+    OutputConfig::default(),
+);
+```
+
+Then, we will transfer GPIO to the PWM instance:
+
+```rust
+let mut led = mcpwm.operator0.with_pin_a(led, PwmPinConfig::UP_ACTIVE_HIGH);
+```
+
+> 💡 Note how we're re-using the name `led`. This is called rebinding and allows us to write cleaner code.
+
+Finally, let's modify our application to cycle through different brightness levels in a loop:
+
+```rust
+let mut sequence = [32, 128, 255].iter().cycle();
+loop {
+    led.set_timestamp(*sequence.next().unwrap());
+    delay.delay_millis(1000);
+}
+```
+
+[1]: https://en.wikipedia.org/wiki/Pulse-width_modulation
+[2]: https://docs.espressif.com/projects/rust/esp-hal/1.0.0-rc.0/esp32c6/esp_hal/mcpwm/index.html

src/pwm_led_breathing.md

@@ -0,0 +1,71 @@
+# Exercise: LED breathing effect
+
+We learnt how to control the LED brightness and make the brightness ramp-up.
+For this exercise, you have to implement a commonly-used breathing effect.
+
+The sequence is roughly as follows:
+
+1. LED brightness should increase gradually until it reaches the maximum.
+1. LED brightness should decrease gradually until it reaches zero.
+1. LED stays off for a couple of seconds.
+1. The sequence repeats.
+
+<details>
+<summary><strong>Solution</strong></summary>
+
+The requirements of this exercise a suited perfectly for a [state machine][1]
+and Rust's `enum`s work great for state machines.
+
+Let's define our enum. We can achieve our goals by using two variants (states):
+one for increasing brightness and one for decreasing.
+The enum variants will hold the actual brightness value.
+
+```rust
+enum LedState {
+    Up(u16),
+    Down(u16),
+}
+```
+
+Let's create the instance of our `LedState`. Declare this variable just above the main loop:
+
+```rust
+let mut led_state = LedState::Up(0);
+```
+
+We will start at zero brightness and increasing direction.
+
+Finally, let's implement our state transitions:
+
+```rust
+loop {
+    match led_state {
+        // We have reached maximum, change state to ramp down.
+        LedState::Up(255) => {
+            led.set_timestamp(255);
+            led_state = LedState::Down(255);
+        }
+        // Ramping up: increment the brightness.
+        LedState::Up(brightness) => {
+            led.set_timestamp(brightness);
+            led_state = LedState::Up(brightness + 1);
+        }
+        // We have reached minimum, wait two seconds then change state to ramp up.
+        LedState::Down(0) => {
+            led.set_timestamp(0);
+            delay.delay_millis(2000);
+            led_state = LedState::Up(0);
+        }
+        // Ramping down: decrement the brightness.
+        LedState::Down(brightness) => {
+            led.set_timestamp(brightness);
+            led_state = LedState::Down(brightness - 1);
+        }
+    }
+    delay.delay_millis(10);
+}
+```
+
+</details>
+
+[1]: https://en.wikipedia.org/wiki/Finite-state_machine