diff --git a/.cargo/config b/.cargo/config index 55974e3..6486a00 100644 --- a/.cargo/config +++ b/.cargo/config @@ -10,3 +10,4 @@ rustflags = [ "-C", "no-vectorize-loops", ] runner = "elf2uf2-rs -d" +# runner = "probe-run-rp --chip RP2040" diff --git a/README.md b/README.md index 808656a..6f08aaf 100644 --- a/README.md +++ b/README.md @@ -8,26 +8,26 @@

rp-hal

- A Rust HAL and board support packages for the RP family of microcontrollers from the Raspberry Pi Foundation + Rust support for Raspberry Pi Silicon
- Explore the docs » + Explore the API docs »

- View Demo + View Demos · - Report Bug + Report a Bug · - Request Feature + Chat on Matrix

-

Table of Contents
    -
  1. Packages
    2. +
  2. Getting Started
    3. +
  3. Programming
  4. Roadmap
  5. Contributing
  6. License
    7. @@ -37,6 +37,40 @@
+ +## Getting Started + +So, you want to program your Raspberry Pi Silicon, using the Rust programming +language. You've come to the right place! + +This repository is `rp-hal` - a collection of high-level drivers for the RP2040 +and various associated boards, like the Raspberry Pi Pico and the Adafruit +Feather RP2040. + +If you want to try out some examples on one of our supported boards, check out +the list of *Board Support Packages* below, and click through to see the various +examples for each board. + +If you want to write an application for Raspberry Pi Silicon, check out our +[RP2040 Project Template](https://github.com/rp-rs/rp2040-project-template). + +Before trying any of the examples, please ensure you have the latest stable version of Rust installed, along with the right target support: + +```console +$ rustup self update +$ rustup update stable +$ rustup target add thumbv6m-none-eabi +``` + +You may also want to install these helpful tools: + +```sh +# Useful to creating UF2 images for the RP2040 USB Bootloader +cargo install elf2uf2-rs +# Useful for flashing over the SWD pins using a supported JTAG probe +cargo install --git https://github.com/rp-rs/probe-run.git --branch rp2040-support +``` + ## Packages This git repository is organised as a [Cargo Workspace]. @@ -147,6 +181,106 @@ RP2040 chip according to how it is connected up on the Pro Micro RP2040. [Sparkfun Pro Micro RP2040]: https://www.sparkfun.com/products/18288 [pro_micro_rp2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/pro_micro_rp2040 + +## Programming + +Rust generates standard Arm ELF files, which you can load onto your Raspberry Pi +Silicon device with your favourite Arm flashing/debugging tool. In addition, the +RP2040 contains a ROM bootloader which appears as a Mass Storage Device over USB +that accepts UF2 format images. You can use the `elf2uf2-rs` package to convert +the Arm ELF file to a UF2 format image. + +For boards with USB Device support like the Raspberry Pi Pico, we recommend you +use the UF2 process. + +The RP2040 contains a Cortex-M0+ processor, which implements the Thumb-2 format +of the ARMv6-M instruction set. For compatibilty with other Arm code (e.g. as +produced by GCC), Rust uses the *Arm Embedded-Application Binary Interface* +standard or EABI. Therefore, any Rust code for the RP2040 should be compiled +with the target `thumbv6m-none-eabi`. + +More details can be found in the [Project Template](https://github.com/rp-rs/rp2040-project-template). + +### Loading a UF2 over USB + +*Step 1* - Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs): + +```console +$ cargo install elf2uf2-rs +``` + +*Step 2* - Make sure your .cargo/config contains the following (it should by +default if you are working in this repository): + +```toml +[target.thumbv6m-none-eabi] +runner = "elf2uf2-rs -d" +``` + +The `thumbv6m-none-eabi` target may be replaced by the all-Arm wildcard +`'cfg(all(target_arch = "arm", target_os = "none"))'`. + +*Step 3* - Boot your RP2040 into "USB Bootloder mode", typically by rebooting +whilst holding some kind of "Boot Select" button. On Linux, you will also need +to 'mount' the device, like you would a USB Thumb Drive. + +*Step 4* - Use `cargo run`, which will compile the code and started the +specified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2 +file and copy it to your RP2040. + +```console +$ cargo run --release --example pico_pwm_blink +``` + +### Loading with probe-run + +The Knurling project has a tool called +[probe-run](https://github.com/knurling-rs/probe-run). This is a command-line +tool which can flash a wide variety of microcontrollers using a wide variety of +debug/JTAG probes. It is based on a library called +[probe-rs](https://github.com/probe-rs/probe-rs). + +Currently, probe-rs supports the slightly unusual debug hardware in the RP2040, +but the last released probe-run tool (v0.2.6, as of September 2021), does not. +However, there is a special version of probe-run for the RP2040 called +[probe-run-rs]. + +*Step 1* - Install `probe-run-rp`: + +```console +$ cargo install --git https://github.com/rp-rs/probe-run.git --branch rp2040-support +``` + +*Step 2* - Make sure your .cargo/config contains the following: + +```toml +[target.thumbv6m-none-eabi] +runner = "probe-run-rp --chip RP2040" +``` + +*Step 3* - Connect your USB JTAG/debug probe (such as a Raspberry Pi Pico +running [this firmware](https://github.com/majbthrd/DapperMime)) to the SWD +programming pins on your RP2040 board. Check the probe has been found by +running: + +```console +$ probe-run-rp --chip RP2040 --list-probes +The following devices were found: +[0]: J-Link (J-Link) (VID: 1366, PID: 0101, Serial: 000099999999, JLink) +``` + +There is a SEGGER J-Link connected in the example above - the mesage you see +will reflect the probe you have connected. + +*Step 4* - Use `cargo run`, which will compile the code and start the specified +'runner'. As the 'runner' is the `probe-run-rp` tool, it will connect to the +RP2040 via the first probe it finds, and install your firmware into the Flash +connected to the RP2040. + +```console +$ cargo run --release --example pico_pwm_blink +``` + ## Roadmap diff --git a/rp2040-hal/README.md b/rp2040-hal/README.md index b5d1a0b..fef8602 100644 --- a/rp2040-hal/README.md +++ b/rp2040-hal/README.md @@ -8,16 +8,16 @@

rp-hal

- A Rust HAL impl for the RP family of microcontrollers from the Raspberry Pi Foundation + High-level Rust drivers for the Raspberry Pi Silicon RP2040 Microcontroller
- Explore the docs » + Explore the API docs »

- View Demo + View Demos · - Report Bug + Report a Bug · - Request Feature + Chat on Matrix

@@ -27,6 +27,7 @@

Table of Contents
    +
  1. Introduction
  2. Getting Started
    3. -
  3. Usage
  4. Roadmap
  5. Contributing
  6. License
    7. @@ -43,70 +43,60 @@
+ +## Introduction + +This is the `rp2040-hal` package - a library crate of high-level Rust drivers +for the Raspberry Pi Silicon RP2040 microcontroller, along with a collection of +non-board specific example programs for you to study. You should use this crate +in your application if you want to write code for the RP2040 microcontroller. +The *HAL* in the name standards for *Hardware Abstraction Layer*, and comes from +the fact that many of the drivers included implement the generic +hardware-abstraction interfaces defined in the Rust Embedded Working Group's +[embedded-hal](https://github.com/rust-embedded/embedded-hal) crate. + +We also provide a series of *Board Support Package* (BSP) crates, which take +this HAL crate and pre-configure the pins according to a specific PCB design. If +you are using on of the supported boards, you should use one of those crates in +preference, and return here to see documentation about specific peripherals on +the RP2040 and how to use them. See the `boards` folder in +https://github.com/rp-rs/rp-hal/ for more details. + ## Getting Started -To get a local copy up and running follow these simple steps. - -### Prerequisites - -* A [Rust](https://www.rust-lang.org/tools/install) toolchain - -### Installation - -1. Clone the repo or use the crate - - ```sh - git clone https://github.com/rp-rs/rp-hal - ``` - - or - - ```sh - cargo install rp2040-hal - ``` - - -## Usage - -Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. - -For more examples, please refer to the [Documentation](https://github.com/rp-rs/rp-hal) - -### Run examples - -#### UF2 - -For boards with uf2 flashloaders like the raspberry pi pico. Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs): - -```sh -cargo install elf2uf2-rs -``` - -Make sure .cargo/config contains the following (it should by default): +To include this crate in your project, amend your `Cargo.toml` file to include ```toml -runner = "elf2uf2-rs -d" +rp2040-hal = "0.3" ``` -**IMPORTANT: Make sure you've put your device into bootloader mode and the drive is showing as mounted before executing the next command.** +To obtain a copy of the source code (e.g. if you want to propose a bug-fix or +new feature, or simply to study the code), run: -```sh -cargo run --example pico_pwm_blink # Run `cargo run --example` for more examples +```console +$ git clone https://github.com/rp-rs/rp-hal.git ``` +For details on how to program an RP2040 microcontroller, see the [top-level +rp-hal README](https://github.com/rp-rs/rp-hal/). + ## Roadmap -NOTE This HAL is under active development. As such, it is likely to remain volatile until a 1.0.0 release. +NOTE This HAL is under active development. As such, it is likely to remain +volatile until a 1.0.0 release. -See the [open issues](https://github.com/rp-rs/rp-hal/issues) for a list of proposed features (and known issues). +See the [open issues](https://github.com/rp-rs/rp-hal/issues) for a list of +proposed features (and known issues). ## Contributing -Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**. +Contributions are what make the open source community such an amazing place to +be learn, inspire, and create. Any contributions you make are **greatly +appreciated**. 1. Fork the Project 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)