Merge pull request #1 from Systemscape/add-content

Add first chapter

Author: joelsa

src/SUMMARY.md

@@ -1,19 +1,14 @@
 # Summary
 
-- [Getting Started With Embedded Rust 📟🦀](./index.md)
-- [Introduction](./introduction.md)
-    - [Setup](./setup.md)
-
+[Getting Started With Embedded Rust 🦀](./index.md)
+- [Introduction](./introduction/introduction.md)
+    - [Who should use this Guide?](./introduction/who_should_use_this_guide.md)
+    - [What you'll need (Prerequisites)](./introduction/what_youll_need_prerequisites.md)
+    - [How to Use This Guide](./introduction/how_to_use_this_guide.md)
+- [Flashing Rust is Easier Than Brewing Coffee. ☕](./flashing/flashing_rust_is_easier_than_brewing_coffee.md)
+    - [Setting Up Your Rust Embedded Toolchain](./flashing/setting-up-your-rust-embedded-toolchain.md)
+        - [RP2350 MCU Flashing Methods](./flashing/rp2350_mcu_flashing_methods.md)
+        - [Install tools for flashing](./flashing/install_tools_for_flashing.md)
+    - [Starting a New Project – Blinky (RP2350 Template)](./flashing/starting_a_new_project_blinky_rp2350_template.md)
 ---
 
-# Exercises
-
-- [First Exercise](./exercise1.md)
-- [Second Exercise](./exercise2.md)
-
----
-
-# Final Words
-
-- [Wrap-up](./wrapup.md)
-

src/chapter_1.md

@@ -0,0 +1,3 @@
+# Flashing Rust is Easier Than Brewing Coffee. ☕
+
+Our first goal is to show that getting Rust code running on a real microcontroller is **surprisingly simple** – often just a few commands. We’ll set up the toolchain for the RP2350, compile a “blinky” program, and flash it to the board. By the end of this chapter, you’ll have an LED blinking on actual hardware, and you’ll see that putting Rust on a microchip is _literally easier than making a cup of coffee._

src/exercise1.md

@@ -0,0 +1,32 @@
+# Install tools for flashing
+
+## Method 1: RP2350-built-in bootloader via drag & drop
+
+As described in the previous chapter, you don't need to install any tools to flash the RP2350 using the RP2350-built-in bootloader if you use our online conversion method at <a href="https://elf2uf2.yrust.de/" target="_blank">elf2uf2.yrust.de</a>. If you prefer to convert it locally though, you will need to install `picotool`, as described in the next paragraph.
+
+## Method 2: RP2350-built-in bootloader with picotool
+
+The RP2040 and RP2350 have a built-in bootloader that presents the device as a USB drive when you plug it in with the BOOTSEL button pressed. You can copy a `.uf2` file to that drive to flash new firmware . For this, it’s helpful to install [picotool](https://github.com/raspberrypi/picotool/), a utility from Raspberry Pi that can convert binaries to UF2 and upload them. You can download a pre-built picotool binary from the [releases page](https://github.com/raspberrypi/picotool/releases) for your OS or build it from source.
+Their docs state that _You cannot just copy the binary into your PATH, else the Pico SDK will not be able to locate it._, however, if you only want to use the RP2350 with Rust code and don't plan on using the SDK, you absolutely can just copy the picotool binary to your PATH.
+
+With picotool installed, you can now flash the RP2350 (given that the bootsel button is pressed when plugging it in) using:
+```bash
+picotool load -u -v -x -t elf your_file.elf
+```
+you can also convert `.elf` files to `.uf2` files using:
+```bash
+picotool uf2 convert your_file.elf your_file.uf2
+```
+
+## Method 3: Probe-based flashing (SWD)
+Using an external debug probe or a second Pico as a probe, you can flash and debug the chip directly via the SWD interface. For this, we use **probe-rs**, a Rust project that replaces OpenOCD/GDB. We recommend installing using the [recommended install scripts](https://probe.rs/docs/getting-started/installation/), which provides the probe-rs CLI and associated tools:
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/latest/download/probe-rs-tools-installer.sh | sh
+```
+This gives you commands like probe-rs flash and also includes probe-run (for running programs with semi-hosted debugging). _(If you’re curious: probe-rs is a pure-Rust implementation of the ARM debugging protocol and works with CMSIS-DAP, J-Link, etc. It makes flashing and even debuggingfirmware straightforward.)_
+
+## (optional) Install cargo-generate
+We will use cargo-generate to quickly bootstrap projects from templates. Install it with:
+```bash
+cargo install cargo-generate
+```

src/exercise2.md

@@ -0,0 +1,60 @@
+# RP2350 MCU Flashing Methods
+
+There are three main ways to flash firmware onto an RP2350 microcontroller, each with different prerequisites and use cases. 
+You can either flash it using the RP2350-built-in bootloader by dragging & dropping the `.uf2` file to the mounted drive, by using the [picotool](https://github.com/raspberrypi/picotool/) tool to talk to the bootloader directly, or by using a hardware debugger or second Pico for programming and debugging over an Serial-Wire-Debug (SWD) connection. The methods are detailed below.
+
+Depending on your preference, you will then learn how to install the tools for these methods in the next chapter. We recommend trying Method 1 first, as it is the easiest to use and doesn't require any installation and setup the other methods later if you need to.
+
+## Method 1: Online Conversion
+
+This method requires no software installation and works entirely through a web browser and your system's file manager.
+
+**Prerequisites:** None
+
+**Steps:**
+1. Take your `.elf` file
+2. Go to [elf2uf2.yrust.de](https://elf2uf2.yrust.de/)[^1]
+3. Upload and convert to `.uf2`
+4. Put RP2350 into boot mode:
+   - Hold **BOOTSEL** button
+   - Power on
+   - Release **BOOTSEL**
+5. Drag & drop the `.uf2` file to the mounted drive
+6. Device will automatically reset and run
+
+## Method 2: Bootloader and picotool
+
+This method uses the official Raspberry Pi tool for direct flashing.
+
+**Prerequisites:** [picotool](https://github.com/raspberrypi/picotool/) installed
+
+**Steps:**
+1. Put RP2350 into boot mode:
+   - Hold **BOOTSEL** button
+   - Power on
+   - Release **BOOTSEL**
+2. Flash directly with picotool:
+   ```bash
+   picotool load -u -v -x -t elf your_file.elf
+   ```
+3. Device will automatically reset and run
+
+## Method 3: Debug Probe
+
+This method uses a hardware debugger or second Pico for programming and debugging.
+
+**Prerequisites:** Debugger or second Pico + [probe-rs](https://probe.rs/) installed
+
+**Steps:**
+1. Connect debugger or second Pico to target RP2350
+2. Flash and run with probe-rs:
+   ```bash
+   probe-rs run --chip RP235x --protocol swd your_file.elf
+   ```
+3. Device will be programmed and start running automatically
+
+## Additional Notes
+
+To erase the flash, you can use `picotool erase` or drag & drop the flash nuke utility: [flash_nuke.uf2](https://datasheets.raspberrypi.com/soft/flash_nuke.uf2) (direct download, 96 kB)
+
+[^1]: Our online tool [elf2uf2.yrust.de](https://elf2uf2.yrust.de/) simply executes `picotool uf2 convert your_file.elf your_file.uf2` - it's equivalent to having picotool installed locally but runs in the browser.

src/flashing/flashing_rust_is_easier_than_brewing_coffee.md

@@ -0,0 +1,19 @@
+# Setting Up Your Rust Embedded Toolchain
+
+Before writing any code, we need to configure our development environment for cross-compiling to the RP2350 microcontroller. The RP2350 is a **dual-core ARM Cortex-M33** microcontroller (with some special features we’ll discuss later). Rust, via `rustup`, can target this architecture easily.
+
+1. **Install Rust (stable)** if you haven’t already, via [rustup](https://rustup.rs/). Ensure you also have Cargo, which comes with Rust.
+2. **Update Rust** to the latest stable version and self-update rustup (to avoid any surprises):
+    ```bash
+    rustup self update  
+    rustup update stable
+    ```
+3. **Add the target for RP2350:** The Cortex-M33 core uses the ARMv8-M architecture with hardware floating-point. The correct Rust target triple is `thumbv8m.main-none-eabihf`. We’ll add that, and for completeness also add the ARMv6-M target used by older Pico (RP2040) and the RISC-V target (the RP2350 has a RISC-V mode, as we’ll mention). Run:
+    ```bash
+    rustup target add thumbv6m-none-eabi # (for RP2040, if needed)
+    rustup target add thumbv8m.main-none-eabihf # RP2350 Arm Cortex-M33
+    rustup target add riscv32imac-unknown-none-elf # (RP2350 RISC-V mode)
+    ```
+    > **Note:** The RP2350 is unique in that each core can actually run as either an ARM Cortex-M33 or a RISC-V core (Hazard3) – a novel feature where the core type can be swapped at runtime . In this guide we’ll focus on the standard Cortex-M (ARM) mode. The RISC-V target is added just in case and for future exploration.
+
+With these tools you will already be able to turn valid Rust code into a `.elf` file, which you can then flash onto the RP2350 using the methods described in the next chapter.

src/flashing/install_tools_for_flashing.md

@@ -0,0 +1,3 @@
+# Starting a New Project – Blinky (RP2350 Template)
+
+Next, we’ll start a new Rust project for the Raspberry Pi Pico 2 board. The community provides ready-to-go templates for Rust on these boards, which set up all the necessary bits (memory layout, linker script, HAL dependencies, and so on). We will use the official **rp-rs project template** for RP2350.

src/flashing/rp2350_mcu_flashing_methods.md

@@ -1 +1,3 @@
 # Getting Started With Embedded Rust 📟🦀
+
+This is a free book about Embedded Rust on the Raspberry Pi Pico 2 (with the RP2350 microcontroller). We primarily use this internally at Systemscape, but we hope it can be useful to others as well and invite you to use it as well and contribute to it.