Repository files navigation

Rust support for boards based on the "Raspberry Silicon" family of microcontrollers

rp2040-hal ·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!

These board support packages are based onrp-hal - a collection of high-leveldrivers for the Raspberry Silicon RP2040 microcontroller and variousassociated boards, like the Raspberry Pi Pico and the Adafruit FeatherRP2040.

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

If you want to try out some examples on one of our supported boards, check outthe list ofBoard Support Packages below, 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 --locked elf2uf2-rs# Useful for flashing over the SWD pins using a supported JTAG probecargo install --locked probe-rs-tools

This git repository is organised as aCargo Workspace.

If you are writing code that should work on any RP2040 device, usetheHAL crate. If you are running code on a specific board, usethe appropriateBSP crate (which will include theHAL crate foryou). Please note, you cannot depend on multipleBSP crates; you haveto pick one, or useCargo Features to select one at build time.

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

You should include this crate if you are writing code that you want to run onaRaspberry Pi Pico - the original launch PCB for the RP2040 chip.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Pico.

You should include this crate if you are writing code that you want to run onanAdafruit Feather RP2040 - a Feather form-factor RP2040 board from Adafruit.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Feather RP2040.

You should include this crate if you are writing code that you want to run onanAdafruit ItsyBitsy RP2040 - an RP2040 board in the ItsyBitsy family.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the ItsyBitsy RP2040.

You should include this crate if you are writing code that you want to run onanAdafruit KB2040 - an Arduino Pro Micro-shaped board for keyboards.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the KB2040.

You should include this crate if you are writing code that you want to run onanAdafruit Macropad - a 3x4 keyboard and OLED combo board from Adafruit.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Macropad.

You should include this crate if you are writing code that you want to run onanAdafruit Metro RP2040 - an RP2040 board in the Metro family.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Metro RP2040.

You should include this crate if you are writing code that you want to run onanAdafruit QT Py RP2040 - an extremely small form-factor RP2040 board from Adafruit.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Feather RP2040.

You should include this crate if you are writing code that you want to run onanAdafruit Trinkey QT2040 - a 3x4 keyboard and OLED combo board from Adafruit.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Trinkey.

You should include this crate if you are writing code that you want to run onaBlok - an RP2040 based controller, made byBoardsource,built for the keyboard community.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Blok.

You should include this crate if you are writing code that you want to run onaPimoroni Badger2040 - a conference-style badge built around an e-paperdisplay and an rp2040

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Badger2040.

You should include this crate if you are writing code that you want to run onaPimoroni Pico Explorer - a breakout board for theRaspberry Pi Pico featuring a small LCD screen, abreadboard and some breakout headers.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Pico Explorer.

You should include this crate if you are writing code that you want to run onaPimoroni Pico Lipo 16MB - a board with USB-C, STEMMA QT/Qwiic connectors,plus a Li-Po battery charging circuit.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Pico Lipo.

Note that if you use this crate the compiler will expect the full 16MB flashspace, and so it may not work if you only have the 4MB variant.

You should include this crate if you are writing code that you want to run onaPimoroni Plasma 2040 - Swathe everything in rainbows with this all-in-one, USB-C powered controllerfor WS2812/Neopixel and APA102/Dotstar addressable LED strip.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Pimoroni Plasma 2040.

You should include this crate if you are writing code that you want to run onaPimoroni Servo2040 - a standalone servo motor controller for up to 18 servosand 6 sensors.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Servo2040.

You should include this crate if you are writing code that you want to run onaPimoroni Tiny2040 - one of the first third party RP2040 boards available, with 8MB flash and a 3 colour LED.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Tiny2040.

You should include this crate if you are writing code that you want to run onaSolderParty RP2040 Stamp - a square RP2040 board with castellated edges.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Stamp.

You should include this crate if you are writing code that you want to run onaSparkFun MicroMod RP2040 - the RP2040 processor board for theSparkFun MicroMod ecosystem.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the MicroMod RP2040.

You should include this crate if you are writing code that you want to run onaSparkfun Pro Micro RP2040 - a smaller RP2040 board with USB-C and a WS2812B addressable LED.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Pro Micro RP2040.

You should include this crate if you are writing code that you want to run onaSparkfun Thing Plus RP2040 - an RP2040 board with a Feather form factor, USB-C, and a WS2812B addressable LED.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the Thing Plus RP2040.

You should include this crate if you are writing code that you want to run onanArduino Nano RP2040 Connect - a development pcb with shortwave communication, IMU, and BLE package.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the nano connect.

You should include this crate if you are writing code that you want to run onaSeeeduino XIAO RP2040 - a tiny board for wearable devices and smallprojects.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the XIAO RP2040.

You should include this crate if you are writing code that you want to run onaVCC-GND Studio YD-RP2040 - a PCB for the RP2040 chip with USB-C port, WS2812 RGB LED on GPIO23, user key on GPIO24 and built-in blue LED.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the YD-RP2040.

You should include this crate if you are writing code that you want to run onanWaveshare RP2040 Zero - a very small RP2040 breakout board with USB-C and a RGB led from Waveshare.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the board.

You should include this crate if you are writing code that you want to run onanWaveshare RP2040 LCD 0.96" - a very small RP2040 breakout board with USB-C,a 65K IPS LCD 160x80, 16MBit Flash and 1A battery charger from Waveshare.

This crate includes therp2040-hal, but also configures each pin of theRP2040 chip according to how it is connected up on the board.

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 compatibilty 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.

Step 1 - Installelf2uf2-rs:

$cargo install elf2uf2-rs --locked

Step 2 - Make sure your .cargo/config.toml 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 --example pico_pwm_blink

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.toml 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 mesage 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 pico_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 Apache2.0 License. That means you can choose either the MIT license or theApache-2.0 license when you re-use this code. SeeMIT orAPACHE2.0 for moreinformation on each specific license.

Any submissions to this project (e.g. as Pull Requests) must be made availableunder these terms.

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

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