Repository files navigation

Rust support for the "Raspberry Silicon" family of microcontrollers
Explore the API docs »

View Demos ·Report a Bug ·Chat on Matrix

So, you want to program your new Raspberry Silicon microcontroller, using theRust programming language. You've come to the right place!

This repository isrp-hal - a collection of high-level drivers for theRaspberry Silicon RP2040 microcontroller and various associated boards, likethe Raspberry Pi Pico and the Adafruit Feather RP2040.

If you want to write an application for Raspberry Silicon, check out ourRP2040 Project Template.

If you want to write code that uses the Raspberry Silicon PIO State Machines,check outpio-rs. You can even compile PIOprograms at run-time, on the RP2040 itself!

If you want to try out some examples on one of our supported boards, check outthe list ofBoard Support Packages, and click through to see the variousexamples for each board.

Before trying any of the examples, please ensure you have the latest stableversion of Rust installed, along with the right target support:

rustup self updaterustup update stablerustup target add thumbv6m-none-eabi

You may also want to install these helpful tools:

# Useful to creating UF2 images for the RP2040 USB Bootloadercargo install elf2uf2-rs --locked# Useful for flashing over the SWD pins using a supported JTAG probecargo install --locked probe-rs-tools

There is aHardware Abstraction Layer (or HAL) crate for the RP2040 chip,andBoard Support Package crates for a number of RP2040 based PCBs. If youare writing code that should run on any microcontroller, consider using thegeneric Rust Embedded Working Group'sEmbedded HAL.

If you are writing code that should work on any RP2040 device, use theHALcrate. If you are running code on a specific board, use the appropriateBSPcrate (which will include theHAL crate for you). Please note, you cannotdepend on multipleBSP crates; you have to pick one, or useCargo Featuresto select one at build time.

Each BSP includes some examples to show off the features of that particular board.

You should include this crate in your project if you want to write a driver orlibrary that runs on theRaspberry Silicon RP2040, or if you are writing a BoardSupport Package (see later on).

The crate provides high-level drivers for the RP2040's internal peripherals,such as the SPI Controller and the I²C Controller. It doesn't know anythingabout how your particular board is wired up (such as what each IO pin of theRP2040 is connected to).

There are examples in this crate to show how to use various peripherals(GPIO, I²C, SPI, UART, etc) but note that the pin-outs may not match anyparticular board.

There are BSPs for various boards based on the RP2040 available inaseparate repository.

Rust generates standard Arm ELF files, which you can load onto your Raspberry PiSilicon device with your favourite Arm flashing/debugging tool. In addition, theRP2040 contains a ROM bootloader which appears as a Mass Storage Device over USBthat accepts UF2 format images. You can use theelf2uf2-rs package to convertthe Arm ELF file to a UF2 format image.

For boards with USB Device support like the Raspberry Pi Pico, we recommend youuse the UF2 process.

The RP2040 contains two Cortex-M0+ processors, which execute Thumb-2 encodedARMv6-M instructions. There are no operating-specific features in the binariesproduced - they are for 'bare-metal' systems. For compatibility with other Armcode (e.g. as produced by GCC), Rust uses theArm Embedded-Application BinaryInterface standard or EABI. Therefore, any Rust code for the RP2040 should becompiled with the targetthumbv6m-none-eabi.

More details can be found in theProject Template.

Besides the correct target, which mainly defines the instruction set,it's also necessary to use a certain memory layout compatible withthe rp2040. To achieve that, rustc must be called with appropriatelinker flags. In theProject Template, those flags are defined in.cargo/config.toml.Another necessary file ismemory.x.

More detailed information on how the linker flags work can be found inthe cortex_m_rt docs.

In most cases, it should be sufficient to use the example files from theProject Template.

Step 1 - Installelf2uf2-rs:

$cargo install elf2uf2-rs --locked

Step 2 - Make sure your .cargo/config contains the following (it should bydefault if you are working in this repository):

[target.thumbv6m-none-eabi]runner ="elf2uf2-rs -d"

Thethumbv6m-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 Bootloader mode", typically by rebootingwhilst holding some kind of "Boot Select" button. On Linux, you will also needto 'mount' the device, like you would a USB Thumb Drive.

Step 4 - Usecargo run, which will compile the code and started thespecified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2file and copy it to your RP2040.

$cargo run --release --features"critical-section-impl,rt,defmt" --example pwm_blink

(Thepwm_blink example doesn't need all these feature flags. They are listed hereso you can use the same command for all examples.)

probe-rs is a library and acommand-line tool which can flash a wide variety of microcontrollersusing a wide variety of debug/JTAG probes. Unlike using, say, OpenOCD,probe-rs can autodetect your debug probe, which can make it easier to use.

Step 1 - Installprobe-rs:

$cargo install --locked probe-rs-tools

Alternatively, follow the installation instructions onhttps://probe.rs/.

Step 2 - Make sure your .cargo/config contains the following:

[target.thumbv6m-none-eabi]runner ="probe-rs run --chip RP2040"

Step 3 - Connect your USB JTAG/debug probe (such as a Raspberry Pi Picorunningthis firmware) to the SWDprogramming pins on your RP2040 board. Check the probe has been found byrunning:

$probe-rs listThe following debug probes 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 message you seewill reflect the probe you have connected.

Step 4 - Usecargo run, which will compile the code and start the specified'runner'. As the 'runner' is theprobe-rs tool, it will connect to theRP2040 via the first probe it finds, and install your firmware into the Flashconnected to the RP2040.

$cargo run --release --example pwm_blink

As ELF files produced by compiling Rust code are completely compatible with ELFfiles produced by compiling C or C++ code, you can also use the Raspberry Pitoolpicotool. The only thing to beaware of is that picotool expects your ELF files to have a.elf extension, andby default Rust does not give the ELF files any extension. You can fix this bysimply renaming the file.

Also of note is that the specialpico-sdk macros which hideinformation in the ELF file in a way thatpicotool info can read it out, arenot supported in Rust. An alternative is TBC.

NOTE These packages are under active development. As such, it is likely toremain volatile until a 1.0.0 release.

See theopen issues for a list ofproposed features (and known issues).

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make aregreatly appreciated.

The steps are:

1. Fork the Project by clicking the 'Fork' button at the top of the page.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Make some changes to the code or documentation.
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Feature Branch (git push origin feature/AmazingFeature)
6. Create aNew Pull Request
7. An admin will review the Pull Request and discuss any changes that may be required.
8. Once everyone is happy, the Pull Request can be merged by an admin, and your work is part of our project!

Contribution to this crate is organized under the terms of theRust Code ofConduct, and the maintainer of this crate, therp-rs team, promisesto intervene to uphold that code of conduct.

The contents of this repository are dual-licensed under theMIT OR Apache 2.0License. That means you can choose either the MIT license or the Apache 2.0license when you re-use this code. SeeLICENSE-MIT orLICENSE-APACHE for more information on each specificlicense. Our Apache 2.0 notices can be found inNOTICE.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shall bedual licensed as above, without any additional terms or conditions.

Raise an issue:https://github.com/rp-rs/rp-hal/issuesChat to us on Matrix:#rp-rs:matrix.org

• Othneil Drew's README template
• Rust Embedded Working Group
• Raspberry Pi and thePico SDK