mirror of
https://github.com/italicsjenga/rp-hal-boards.git
synced 2024-12-23 20:51:31 +11:00
README updates.
Trying to clarify what is HAL specific and what is RP specific.
This commit is contained in:
Jonathan Pallant (42 Technology)
parent
105dcfddd7
commit
0fa6bf9e0e
|
|
@ -10,3 +10,4 @@ rustflags = [
|
|||
"-C", "no-vectorize-loops",
|
||||
]
|
||||
runner = "elf2uf2-rs -d"
|
||||
# runner = "probe-run-rp --chip RP2040"
|
||||
|
|
|
|||
148
README.md
148
README.md
|
|
@ -8,26 +8,26 @@
|
|||
<h3 align="center">rp-hal</h3>
|
||||
|
||||
<p align="center">
|
||||
A Rust HAL and board support packages for the RP family of microcontrollers from the Raspberry Pi Foundation
|
||||
Rust support for Raspberry Pi Silicon
|
||||
<br />
|
||||
<a href="https://github.com/rp-rs/rp-hal"><strong>Explore the docs »</strong></a>
|
||||
<a href="https://docs.rs/rp2040-hal"><strong>Explore the API docs »</strong></a>
|
||||
<br />
|
||||
<br />
|
||||
<a href="https://github.com/rp-rs/rp-hal">View Demo</a>
|
||||
<a href="https://github.com/rp-rs/rp-hal/tree/main/boards/pico/examples">View Demos</a>
|
||||
·
|
||||
<a href="https://github.com/rp-rs/rp-hal/issues">Report Bug</a>
|
||||
<a href="https://github.com/rp-rs/rp-hal/issues">Report a Bug</a>
|
||||
·
|
||||
<a href="https://github.com/rp-rs/rp-hal/issues">Request Feature</a>
|
||||
<a href="https://matrix.to/#/#rp-rs:matrix.org">Chat on Matrix</a>
|
||||
</p>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
<!-- TABLE OF CONTENTS -->
|
||||
<details open="open">
|
||||
<summary><h2 style="display: inline-block">Table of Contents</h2></summary>
|
||||
<ol>
|
||||
<li><a href="#packages">Packages</a></li>
|
||||
<li><a href="#gettting_started">Getting Started</a></li>
|
||||
<li><a href="#programming">Programming</a></li>
|
||||
<li><a href="#roadmap">Roadmap</a></li>
|
||||
<li><a href="#contributing">Contributing</a></li>
|
||||
<li><a href="#license">License</a></li>
|
||||
|
|
@ -37,6 +37,40 @@
|
|||
</details>
|
||||
|
||||
<!-- GETTING STARTED -->
|
||||
|
||||
## 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 -->
|
||||
## 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 -->
|
||||
## Roadmap
|
||||
|
||||
|
|
|
|||
|
|
@ -8,16 +8,16 @@
|
|||
<h3 align="center">rp-hal</h3>
|
||||
|
||||
<p align="center">
|
||||
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
|
||||
<br />
|
||||
<a href="https://github.com/rp-rs/rp-hal"><strong>Explore the docs »</strong></a>
|
||||
<a href="https://docs.rs/rp2040-hal"><strong>Explore the API docs »</strong></a>
|
||||
<br />
|
||||
<br />
|
||||
<a href="https://github.com/rp-rs/rp-hal">View Demo</a>
|
||||
<a href="https://github.com/rp-rs/rp-hal/tree/main/boards/pico/examples">View Demos</a>
|
||||
·
|
||||
<a href="https://github.com/rp-rs/rp-hal/issues">Report Bug</a>
|
||||
<a href="https://github.com/rp-rs/rp-hal/issues">Report a Bug</a>
|
||||
·
|
||||
<a href="https://github.com/rp-rs/rp-hal/issues">Request Feature</a>
|
||||
<a href="https://matrix.to/#/#rp-rs:matrix.org">Chat on Matrix</a>
|
||||
</p>
|
||||
</p>
|
||||
|
||||
|
|
@ -27,6 +27,7 @@
|
|||
<details open="open">
|
||||
<summary><h2 style="display: inline-block">Table of Contents</h2></summary>
|
||||
<ol>
|
||||
<li><a href="#introduction">Introduction</a></li>
|
||||
<li>
|
||||
<a href="#getting-started">Getting Started</a>
|
||||
<ul>
|
||||
|
|
@ -34,7 +35,6 @@
|
|||
<li><a href="#installation">Installation</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#usage">Usage</a></li>
|
||||
<li><a href="#roadmap">Roadmap</a></li>
|
||||
<li><a href="#contributing">Contributing</a></li>
|
||||
<li><a href="#license">License</a></li>
|
||||
|
|
@ -43,70 +43,60 @@
|
|||
</ol>
|
||||
</details>
|
||||
|
||||
<!-- INTRODUCTION -->
|
||||
## 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 -->
|
||||
## 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 EXAMPLES -->
|
||||
## 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 -->
|
||||
## 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 -->
|
||||
## 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`)
|
||||
|
|
|
|||
Loading…
Reference in a new issue