intro

.github/workflows/deploy.yml

@@ -0,0 +1,41 @@
+name: Deploy
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Install mdbook-quiz
+        run: cargo install mdbook-quiz --locked
+      - name: Build Book
+        run: |
+          # This assumes your book is in the root of your repository.
+          # Just add a `cd` here if you need to change to another directory.
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: 'book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

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

book.toml

@@ -0,0 +1,6 @@
+[book]
+title = "Pico Pico - Embedded Programming with Rust"
+authors = []
+language = "en"
+multilingual = false
+src = "src"

src/SUMMARY.md

@@ -0,0 +1,9 @@
+# Summary
+
+- [Intro](./intro/index.md)
+    - [Setup](./intro/setup.md)
+    - [Approach](./intro/approach.md)
+    - [Running the Program](./intro/running.md)
+- [Blink LED](./blinky/index.md)
+    - [With rp-rs](./blinky/rp-rs.md)
+    - [With embassy](./blinky/embassy.md)

src/blinky/embassy.md

@@ -0,0 +1,55 @@
+# Blink LED with Embassy Framework
+
+This example code is taken from rp235x-hal repo (It also includes additional examples beyond just the blink examples):
+
+["https://github.com/rp-rs/rp-hal/tree/main/rp235x-hal-examples"](https://github.com/rp-rs/rp-hal/tree/main/rp235x-hal-examples)
+
+You can clone the blinky project I created and navigate to the `embassy-blinky` folder to run this version of the blink program:
+
+```sh
+git clone https://github.com/ImplFerris/pico2-blinky
+```
+
+## The main code
+```rust
+#![no_std]
+#![no_main]
+
+use embassy_executor::Spawner;
+use embassy_rp::block::ImageDef;
+use embassy_rp::gpio;
+use embassy_time::Timer;
+use gpio::{Level, Output};
+use {defmt_rtt as _, panic_probe as _};
+
+#[link_section = ".start_block"]
+#[used]
+pub static IMAGE_DEF: ImageDef = ImageDef::secure_exe();
+
+// Program metadata for `picotool info`.
+// This isn't needed, but it's recomended to have these minimal entries.
+#[link_section = ".bi_entries"]
+#[used]
+pub static PICOTOOL_ENTRIES: [embassy_rp::binary_info::EntryAddr; 4] = [
+    embassy_rp::binary_info::rp_program_name!(c"Blinky Example"),
+    embassy_rp::binary_info::rp_program_description!(
+        c"This example tests the RP Pico on board LED, connected to gpio 25"
+    ),
+    embassy_rp::binary_info::rp_cargo_version!(),
+    embassy_rp::binary_info::rp_program_build_attribute!(),
+];
+
+#[embassy_executor::main]
+async fn main(_spawner: Spawner) {
+    let p = embassy_rp::init(Default::default());
+    let mut led = Output::new(p.PIN_25, Level::Low);
+
+    loop {
+        led.set_high();
+        Timer::after_millis(500).await;
+
+        led.set_low();
+        Timer::after_millis(500).await;
+    }
+}
+```

src/blinky/index.md

@@ -0,0 +1,6 @@
+# Blink LED
+
+In this section, we'll learn how to blink an LED using the Raspberry Pi Pico 2.
+
+- [With rp-rs](./rp-rs.md)
+- [With embassy](./embassy.md)

src/blinky/rp-rs.md

@@ -0,0 +1,140 @@
+# Blink LED Program with rp-rs HAL
+
+This example code is taken from rp235x-hal repo (It also includes additional examples beyond just the blink examples):
+
+["https://github.com/rp-rs/rp-hal/tree/main/rp235x-hal-examples"](https://github.com/rp-rs/rp-hal/tree/main/rp235x-hal-examples)
+
+You can clone the blinky project I created and navigate to the `rprs-blinky` folder to run this version of the blink program:
+
+```sh
+git clone https://github.com/ImplFerris/pico2-blinky
+```
+
+
+## The main code
+```rust
+//! # PWM Blink Example
+//!
+//! If you have an LED connected to pin 25, it will fade the LED using the PWM
+//! peripheral.
+//!
+//! It may need to be adapted to your particular board layout and/or pin assignment.
+//!
+//! See the `Cargo.toml` file for Copyright and license details.
+
+#![no_std]
+#![no_main]
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
+use panic_halt as _;
+
+// Alias for our HAL crate
+use rp235x_hal as hal;
+
+// Some things we need
+use embedded_hal::delay::DelayNs;
+use embedded_hal::pwm::SetDutyCycle;
+
+/// Tell the Boot ROM about our application
+#[link_section = ".start_block"]
+#[used]
+pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
+/// The minimum PWM value (i.e. LED brightness) we want
+const LOW: u16 = 0;
+
+/// The maximum PWM value (i.e. LED brightness) we want
+const HIGH: u16 = 25000;
+
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
+const XTAL_FREQ_HZ: u32 = 12_000_000u32;
+
+/// Entry point to our bare-metal application.
+///
+/// The `#[hal::entry]` macro ensures the Cortex-M start-up code calls this function
+/// as soon as all global variables and the spinlock are initialised.
+///
+/// The function configures the rp235x peripherals, then fades the LED in an
+/// infinite loop.
+#[hal::entry]
+fn main() -> ! {
+    // Grab our singleton objects
+    let mut pac = hal::pac::Peripherals::take().unwrap();
+
+    // Set up the watchdog driver - needed by the clock setup code
+    let mut watchdog = hal::Watchdog::new(pac.WATCHDOG);
+
+    // Configure the clocks
+    //
+    // The default is to generate a 125 MHz system clock
+    let clocks = hal::clocks::init_clocks_and_plls(
+        XTAL_FREQ_HZ,
+        pac.XOSC,
+        pac.CLOCKS,
+        pac.PLL_SYS,
+        pac.PLL_USB,
+        &mut pac.RESETS,
+        &mut watchdog,
+    )
+    .ok()
+    .unwrap();
+
+    // The single-cycle I/O block controls our GPIO pins
+    let sio = hal::Sio::new(pac.SIO);
+
+    // Set the pins up according to their function on this particular board
+    let pins = hal::gpio::Pins::new(
+        pac.IO_BANK0,
+        pac.PADS_BANK0,
+        sio.gpio_bank0,
+        &mut pac.RESETS,
+    );
+
+    // The delay object lets us wait for specified amounts of time (in
+    // milliseconds)
+    let mut delay = hal::Timer::new_timer0(pac.TIMER0, &mut pac.RESETS, &clocks);
+
+    // Init PWMs
+    let mut pwm_slices = hal::pwm::Slices::new(pac.PWM, &mut pac.RESETS);
+
+    // Configure PWM4
+    let pwm = &mut pwm_slices.pwm4;
+    pwm.set_ph_correct();
+    pwm.enable();
+
+    // Output channel B on PWM4 to GPIO 25
+    let channel = &mut pwm.channel_b;
+    channel.output_to(pins.gpio25);
+
+    // Infinite loop, fading LED up and down
+    loop {
+        // Ramp brightness up
+        for i in LOW..=HIGH {
+            delay.delay_us(8);
+            let _ = channel.set_duty_cycle(i);
+        }
+
+        // Ramp brightness down
+        for i in (LOW..=HIGH).rev() {
+            delay.delay_us(8);
+            let _ = channel.set_duty_cycle(i);
+        }
+
+        delay.delay_ms(500);
+    }
+}
+
+/// Program metadata for `picotool info`
+#[link_section = ".bi_entries"]
+#[used]
+pub static PICOTOOL_ENTRIES: [hal::binary_info::EntryAddr; 5] = [
+    hal::binary_info::rp_cargo_bin_name!(),
+    hal::binary_info::rp_cargo_version!(),
+    hal::binary_info::rp_program_description!(c"PWM Blinky Example"),
+    hal::binary_info::rp_cargo_homepage_url!(),
+    hal::binary_info::rp_program_build_attribute!(),
+];
+
+// End of file
+```

src/intro/approach.md

@@ -0,0 +1,10 @@
+## Approaches for Raspberry Pi Pico 2  
+
+
+### 1. rp-rs  
+[**rp-rs**](https://github.com/rp-rs/rp-hal) is a Rust Embedded Hardware Abstraction Layer (HAL) designed specifically for the RP series microcontrollers. 
+
+### 2. Embassy  
+[**Embassy**](https://github.com/embassy-rs/embassy) is a modern embedded framework that utilizes Rust and asynchronous programming. 
+
+"Embassy is the next-generation framework for embedded applications. Write safe, correct and energy-efficient embedded code faster, using the Rust programming language, its async facilities, and the Embassy libraries."

src/intro/index.md

@@ -0,0 +1,14 @@
+# Pico Pico - Intro
+
+This book is an informal collection of what I explore, tinker with, and learn along the way. The content isn't meant to be professional; Just raw documentation of my journey.
+
+## Meet the hardware  - Pico 2
+We will be using the Raspberry Pi Pico 2.  It features the new RP2350 chip with dual-core flexibility—offering Arm Cortex-M33 cores and optional RISC-V Hazard3 cores. You can operate it as the standard ARM core or switch to the RISC-V architecture.  You find more details from the [official website](https://www.raspberrypi.com/products/raspberry-pi-pico-2/).
+
+<img style="display: block; margin: auto;" alt="pico2" src="images/pico2.png"/>
+
+
+## Datasheets
+For detailed technical information, specifications, and guidelines, refer to the official datasheets:
+* [Pico 2 Datasheet](https://datasheets.raspberrypi.com/pico/pico-2-datasheet.pdf)
+* [RP2350 chip Datasheet](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf)

src/intro/running.md

@@ -0,0 +1,21 @@
+# Running the program
+Before we explore further examples, let’s cover the general steps to build and run any program on the Raspberry Pi Pico 2.
+
+## Build and Run for ARM
+```sh
+# build the program
+cargo build --target=thumbv8m.main-none-eabihf
+
+# Run the program
+cargo run --bin blinky --target=thumbv8m.main-none-eabihf
+```
+
+
+## Build and Run for RISC-V
+```sh
+# build the program
+cargo build --target=riscv32imac-unknown-none-elf
+
+# Run the program
+cargo run --bin blinky --target=riscv32imac-unknown-none-elf
+```

src/intro/setup.md

@@ -0,0 +1,41 @@
+# Setup
+
+## Picotool
+picotool is a tool for working with RP2040/RP2350 binaries, and interacting with RP2040/RP2350 devices when they are in BOOTSEL mode.
+
+[Picotool Repo](https://github.com/raspberrypi/picotool)
+
+Here’s a quick summary of the steps I followed:
+```sh
+mkdir embedded && cd embedded
+
+# Clone the Pico SDK
+git clone https://github.com/raspberrypi/pico-sdk
+# Set the environment variable for the Pico SDK
+PICO_SDK_PATH=/MY_PATH/embedded/pico-sdk
+
+# Clone the Picotool repository
+git clone https://github.com/raspberrypi/picotool
+```
+
+Build and install Picotool
+```sh
+cd picotool
+cmake ../
+make -j8
+sudo make install
+```
+
+On Linux you can add udev rules in order to run picotool without sudo:
+```sh
+sudo cp udev/99-picotool.rules /etc/udev/rules.d/
+```
+
+
+## Rust Targets
+To build and deploy Rust code for the RP2350 chip, you'll need to add the appropriate targets:
+
+```sh
+rustup target add thumbv8m.main-none-eabihf
+rustup target add riscv32imac-unknown-none-elf
+```