Workshop 1 materials

Author: armandas

.gitignore

@@ -0,0 +1 @@
+book

book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["Armandas Jarušauskas"]
+language = "en"
+src = "src"
+title = "Rust Workshop"

src/SUMMARY.md

@@ -0,0 +1,8 @@
+# Summary
+
+- [Setup](./setup/README.md)
+  - [Software setup](./setup/software.md)
+  - [Hardware information](./setup/hardware.md)
+- [Hello World](./hello_world.md)
+- [Blinky](./blinky.md)
+- [Exercise: working with inputs](./button.md)

src/blinky.md

@@ -0,0 +1,48 @@
+# Blinky
+
+We have created a typical "hello world" application, but in embedded systems,
+the equivalent of "hello world" is blinky: simply blinking an LED.
+
+We will continue working in the `hello_world` project.
+
+## Change the program
+
+In order to blink an LED, we need to define an output pin and make a couple of other changes.
+
+Firstly, let's rename the `_peripherals` variable to `peripherals`.
+
+> 💡 In Rust, a variable can be prefixed with an underscore (`_`) to indicate that it is unused.
+> Since we'll be using it, let's remove the leading underscore.
+
+Next, we will define our LED:
+
+```rust
+let mut led = Output::new(
+    peripherals.GPIO19,
+    Level::Low,
+    OutputConfig::default().with_drive_mode(DriveMode::OpenDrain),
+);
+```
+
+The code above will not compile as is, since the compiler won't know where `Output` and other types are coming from. To fix that, import the required types like so:
+
+```rust
+use esp_hal::gpio::{DriveMode, Level, Output, OutputConfig};
+```
+
+> 💡 Whenever a you have a missing declaration error, you can use `rust-analyzer` to help you fix it.
+>
+> Place the cursor on the missing type name and press `Ctrl` + `.` on the keyboard.
+> In the context menu, select `Import <Type>` or `Qualify <Type>`.
+>
+> "Import" will add the required `use` declaration, while "Qualify" will prefix the module path in-place.
+
+Finally, add the following line to the body of the `loop` to toggle the LED every cycle:
+
+```rust
+led.toggle();
+```
+
+## Experiment
+
+`Output` has other methods than `toggle`. Try using `set_high` and `set_low` methods to change the LED blinking pattern.

src/button.md

@@ -0,0 +1,32 @@
+# Working with inputs
+
+We have worked through an example of driving a GPIO output.
+Now it's time for you to try and extend the program to read the GPIO input state.
+
+- Use the `esp_hal` crate documentation to create and initialize a GPIO [`Input`][1].
+- The button is connected to `GPIO9`.
+- Write a program that turns the LED on only while the button is pressed.
+
+<details>
+<summary><strong>Solution</strong></summary>
+
+1. Add new imports:
+   ```rust
+   use esp_hal::gpio::{Input, InputConfig};
+   ```
+2. Declare the button:
+   ```rust
+   let button = Input::new(peripherals.GPIO9, InputConfig::default());
+   ```
+3. Modify the loop code:
+   ```rust
+    if button.is_high() {
+        led.set_high();
+    } else {
+        led.set_low();
+    }
+   ```
+
+</details>
+
+[1]: https://docs.espressif.com/projects/rust/esp-hal/1.0.0-rc.0/esp32c6/esp_hal/gpio/struct.Input.html

src/files/ESP32-C6-Touch-LCD-1.47-Schematic.pdf

@@ -0,0 +1 @@
+# Hardware

src/files/ESP32-C6_Series_Datasheet.pdf

@@ -0,0 +1,63 @@
+# Hello World
+
+## Create the project
+
+Let's create our first embedded Rust project. For this, we will be using `esp-generate` tool installed earlier.
+
+To begin with, run the following command:
+
+```text
+esp-generate --headless --chip=esp32c6 -o log -o unstable-hal hello_world
+```
+
+This will create a new project in `hello_world` directory. Go ahead and open it with: `code hello_world`.
+
+> 💡 You can run `esp-generate --chip=esp32c6` to open the tool in interactive mode and explore the available options.
+
+## Run
+
+With the ESP board plugged into your computer, you should be able to run the firmware with:
+
+```text
+cargo run
+```
+
+You may have to select the appropriate device. If this is the case, the tool will prompt for it.
+
+If everything goes well, your device will boot and start printing the "hello world" message:
+
+```text
+INFO - Hello world!
+INFO - Hello world!
+INFO - Hello world!
+INFO - Hello world!
+INFO - Hello world!
+```
+
+## Experiment
+
+Experiment with this example a little bit.
+
+- Change the message to print something else.
+- Change the log level (e.g. to `warn`).
+- Change the printing frequency by adjusting the sleep duration.
+
+## Bonus
+
+The way the delay is currently written is a bit verbose.
+We can simplify the code by using [`Delay`][1] from the `esp_hal` crate.
+
+1. Add the following line next to the existing `use` declarations:
+   ```rust
+   use esp_hal::delay::Delay;
+   ```
+2. Create a delay variable:
+   ```rust
+   let delay = Delay::new();
+   ```
+3. Replace the two lines using `delay_start` with the following one line:
+   ```rust
+   delay.delay_millis(1000);
+   ```
+
+[1]: https://docs.espressif.com/projects/rust/esp-hal/1.0.0-rc.0/esp32c6/esp_hal/delay/struct.Delay.html