in progress for esp rust...

content/_index.md

@@ -4,8 +4,6 @@ toc: false
 ---
 
 {{< cards >}}
-  {{< card link="about" title="About" icon="information-circle" >}}
-  {{< card link="projects" title="Projects" icon="code" >}}
   {{< card link="assignments" title="Assignments" icon="book-open" >}}
   {{< card link="additional-resources" title="Resources" icon="external-link" >}}
 {{< /cards >}}

content/additional-resources/_index.md

@@ -7,5 +7,6 @@ Some useful external resources.
 
 {{< cards >}}
   {{< card link="arduino" title="Arduino" >}}
+  {{< card link="rust" title="Rust" >}}
   {{< card link="swiftui" title="SwiftUI" subtitle="Developing idiomatic SwiftUI apps and using BLE.">}}
 {{< /cards >}}

content/additional-resources/rust.md

@@ -0,0 +1,14 @@
+---
+title: Rust
+type: docs
+---
+
+The Rust Foundation provides a multitude of educational tools for learning Rust.
+
+- [The Rust Book](https://doc.rust-lang.org/beta/book/) A book that covers the entirety of the language.
+- [Rustlings](https://github.com/rust-lang/rustlings) An interactive experience with challenges and quizzes.
+- [Rust By Example](https://doc.rust-lang.org/rust-by-example/) A supplement to the Rust Book.
+
+## Embedded
+
+- [Embassy Book](https://embassy.dev/book/) Embassy's high level documentation.

content/assignments/ControlWithPython/_index.md

@@ -1,15 +1,9 @@
 ---
 title: ControlWIthPython
 type: docs
-prev: assignments/VUMeter/
+prev: assignments/SpinningAndBlinking/
 next: assignments/ControlWithPython/tutorial
-weight: 4
+weight: 5
 ---
 
-In this assignment you will learn to create a **G**raphical **U**ser **I**nterface (GUI) to interact with a microcontroller.
-
-We will be migrating from CircuitPython to the Arduino C ecosystem.
-
-Download the Arduino software [here](https://www.arduino.cc/en/software).
-
-If you are unfamiliar with Arduino, the official [Arduino website](https://www.arduino.cc/reference/en/) contains great resources for learning about embedded development. You may also want to take a look at the [reference page](https://www.arduino.cc/reference/en/) for help with Arduino's syntax and language.
+In this assignment you will extend your knowledge by learning to create a **G**raphical **U**ser **I**nterface (GUI) to interact with a microcontroller.

content/assignments/SpinningAndBlinking/Arduino/_index.md

@@ -0,0 +1,10 @@
+---
+title: Arduino
+type: docs
+prev: assignments/SpinningAndBlinking/
+weight: 1
+---
+
+Download the Arduino software [here](https://www.arduino.cc/en/software).
+
+If you are unfamiliar with Arduino, the official [Arduino website](https://www.arduino.cc/reference/en/) contains great resources for learning about embedded development. You may also want to take a look at the [reference page](https://www.arduino.cc/reference/en/) for help with Arduino's syntax and language.

content/assignments/SpinningAndBlinking/Rust/_index.md

@@ -0,0 +1,54 @@
+---
+title: Rust
+type: docs
+prev: assignments/SpinningAndBlinking/
+next: assignments/SpinningAndBlinking/Rust/setup
+weight: 2
+---
+
+Rust is an esoteric[^1] multiparadigm[^2] systems programming language with an emphasis on safety.
+It leverages what we have learned from the past 50 years of advancement in the field of software engineering
+to create a consistent, performant, vibrant, reliable, and most importantly *safe* development environment.
+
+When coming from C++, Python, Java, etc. learning Rust can be tricky because you will have to shake the
+habit of using anti-patterns[^3] without any consequences. This learning curve can be steep, but over time you
+will come to realize that as you endeavor to learn Rust, you *also* become a better developer in other
+languages! The ideals Rust holds dear are simply the good design practices of the past half-century all combined
+in one programming language.
+
+{{< callout type="info" >}}
+  To help you on your journey, refer to the [resources](/additional-resources/rust) page.
+{{< /callout >}}
+
+## Some Background
+
+So why exactly is Rust on embedded so cool? What does it provide?
+Well, in addition to the language's passive benefits, i.e. static analysis[^4], RAII adherence[^5], fantastic build tools[^6], etc.
+Rust also provides us with first class[^7] async[^8]!
+
+You may have heard of RTOS before, it stands for **R**eal **T**ime **O**perating **S**ystem. For complex embedded systems, it can be
+really useful to compartmentalize various responsibilities of the system as tasks that run side by side. Of course, the CPU can only
+execute one instruction at a time, but by interleaving the instructions, the illusion of parallelism is created. This is called **concurrency**.
+
+In addition to this, microcontrollers are comprised of more than just a CPU, there are many peripherals[^9] the CPU uses to interact with the world.
+These peripherals can do work while the CPU is handling other things, and use **D**irect **M**emory **A**ccess (DMA) to read, store, or exchange
+information as it is served. A very special Rust crate called **Embassy** utilizes these very principles to provide a high level async interface
+for us to use.
+
+{{< callout type="info" >}}
+  More information on Embassy can be found on the [resources](/additional-resources/rust/#embedded) page.
+{{< /callout >}}
+
+[^1]: Languages that push the boundaries of programming with radical new archetypes.
+[^2]: Languages that employ multiple programming paradigms, i.e. functional, OOP, etc.
+[^3]: Design patterns ubiquitous for resulting in low-quality code.
+[^4]: Programs can be represented with FSTs, control flow can be encoded as types, a strong type system henceforth allows
+a program's behavior to be bounded and thus analyzable at compile-time.
+[^5]: **R**esource **A**cquisition **I**s **I**nitialization (RAII). We bind resources to symbols, access to the resource
+is the same as accesss to the binding. Now symbolic access control represents resource access control.
+[^6]: Cargo -- Rust's build tool -- is renowned for ease of use, performance, and reliability.
+[^7]: A first class citizen is a feature a language provides directly.
+A third class citizen is a feature *derived* from other primitives of the language.
+[^8]: A modern language feature that fascilitates concurrency.
+[^9]: The core of microcontrollers is the concept of peripherals. The other "entities" that coexist with the CPU.
+UART, Timers, ADC, etc.

content/assignments/SpinningAndBlinking/Rust/blinking.md

@@ -0,0 +1,39 @@
+---
+title: Blinking
+type: docs
+prev: assignments/SpinningAndBlinking/Setup
+weight: 2
+---
+
+Well... this is awkward. The board is already blinking!
+
+*But how?*
+
+Let's look line by line to understand how this is working.
+
+Navigate to `firmware/src/main.rs`. This is the main file for our firmware.
+
+```rust
+#![no_std]
+#![no_main]
+```
+
+At the top of the file you will find ^ these directives.
+
+`#![no_std]` indicates that our program will *not* have acces to the Rust
+standard library. This is because embedded systems are resource constrained
+environments with no operating system, so simple things like allocation are
+suddenly not so simple. This directive informs the Rust compiler that the
+standard library is unavailable, which permits us to target the microcontroller.
+
+`#![no_main]` indicates that the entry-point[^1] to our program is non-trivial.
+The Rust compiler typically expects the entry-point to be defined as a top-level[^2]
+function named `main`, however as we will soon see, the entry-point will not be
+defined by us, and will be generated by Embassy to begin async operation and start
+the executor[^3].
+
+[^1]: All binaries have an entry-point, which is the symbol to start execution on.
+[^2]: A top-level item is defined above all hierarchy of a file. Think of global
+variable definitions, free-standing functions or type definitions.
+[^3]: The *executor* is the "entity" provided by Embassy that fascilitates the
+routing of execution between tasks.

content/assignments/SpinningAndBlinking/Rust/setup.md

@@ -0,0 +1,104 @@
+---
+title: Setup
+type: docs
+prev: assignments/SpinningAndBlinking/Rust
+weight: 1
+---
+
+## Install Rust
+
+To install rust, follow the instructions [here](https://www.rust-lang.org/tools/install).
+
+## Embedded Tools
+
+For ESP32s, we need to install ESP's tools.
+
+Execute:
+
+```sh
+cargo install espup espflash
+espup install
+```
+
+{{% details title="macOS/Linux" closed="true" %}}
+  Execute...
+
+  ```
+  . $HOME/export-esp.sh
+  ```
+
+  ...in every terminal session, or append it to your shell profile.
+{{% /details %}}
+
+Now we need to install `cargo-embassy`, a tool for generating Embassy projects.
+
+Execute:
+
+```sh
+cargo install cargo-embassy
+```
+
+## Project
+
+It's time to create our Rust project in the assignment repository. Make sure you are in the
+root directory of your assignment repo, and invoke cargo-embassy like so:
+
+```sh
+cd {your assignment root directory} # change directory to the assignment repo
+cargo embassy init firmware --chip esp32s3 # create rust project in a subdirectory named "firmware"
+```
+
+The resulting file structure should look something like:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="assignment-directory" >}}
+    {{< filetree/folder name="firmware" >}}
+      {{< filetree/folder name=".cargo" state="closed" >}}
+          {{< filetree/file name="config.toml" >}}
+      {{< /filetree/folder >}}
+      {{< filetree/folder name="src" >}}
+        {{< filetree/file name="main.rs" >}}
+      {{< /filetree/folder >}}
+        {{< filetree/file name="Cargo.toml" >}}
+        {{< filetree/file name="build.rs" >}}
+        {{< filetree/file name="rust-toolchain.toml" >}}
+    {{< /filetree/folder >}}
+    {{< filetree/file name="README.md" >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+{{< callout type="info" >}}
+  You can learn more about this structure [here](https://embassy.dev/book/#_project_structure).
+{{< /callout >}}
+
+{{< callout type="info" >}}
+  If you so desire: Inside `firmware/Cargo.toml`, you can rename your project by finding and replacing all occurances of `"devboard-rs-template"`.
+{{< /callout >}}
+
+## Checkpoint
+
+Let's make sure all we've done so far is working properly.
+
+In the `firmware` directory, execute:
+
+```sh
+cargo build --release
+```
+
+> What does `--release` mean? Rust has multiple build profiles for different contexts.
+> By default, the `debug` profile is used, this includes debug symbols in the resulting
+> binary, and significantly reduces the optimizations done. `release` contains no debug
+symbols and is optimized (as specified in `Cargo.toml`).
+
+If this succeeds, plug your DevBoard into your computer and execute:
+
+```sh
+cargo run --release
+```
+
+> It will ask you to select the port the DevBoard is connected to.
+
+If you see the builtin LED blinking, and `Hello, World!` printing on each blink, you have
+successfully deployed Rust code to an ESP32!
+
+Give yourself a pat on the back :)

content/assignments/SpinningAndBlinking/_index.md

@@ -0,0 +1,30 @@
+---
+title: SpinningAndBlinking
+type: docs
+prev: assignments/VUMeter/
+next: assignments/SpinningAndBlinking/getting-started
+weight: 4
+---
+
+In this assignment you will learn to create a **G**raphical **U**ser **I**nterface (GUI) to interact with a microcontroller.
+
+---
+
+**You are faced with an important decision.**
+
+We will be leaving CircuitPython in the pursuit of better understanding how good -- production ready -- firmware is written.
+
+For this assignment, you have **two** options for how to proceed:
+
+{{< cards >}}
+  {{< card link="Arduino" title="Arduino" image="images/arduino.png" >}}
+  {{< card link="Rust" title="Rust" image="images/ferris.png" subtitle="This little guy is named Ferris :)" >}}
+{{< /cards >}}
+
+You may already be familiar with Arduino, as it is a very popular educational platform for introducing students to embedded systems. If
+you don't want these assignments to be any more challenging than they already are, or you aren't particularly passionate about/interested in
+embedded systems, you should select this option.
+
+You may have *heard* of Rust, or even tried it! Rust as an embedded systems language is a brand new field on the bleeding edge of industry.
+As such, there are less resources, it is incomplete, and it is ever changing. If you want a challenge, to get a *much* better understanding of
+how microcontrollers actually work, and a taste of the future, we recommend this option.

hugo.yaml

@@ -18,24 +18,18 @@ markup:
 
 menu:
   main:
-    - name: About
-      pageRef: /about
-      weight: 1
-    - name: Projects
-      pageRef: /projects
-      weight: 2
     - name: Assignments
       pageRef: /assignments
-      weight: 3
+      weight: 1
     - name: Resources
       pageRef: /additional-resources
-      weight: 4
+      weight: 2
     - name: Search
-      weight: 5
+      weight: 3
       params:
         type: search
     - name: GitHub
-      weight: 6
+      weight: 4
       url: "https://github.com/ece-196"
       params:
         icon: github