rp-hal/rp235x-hal-examples at main · rp-rs/rp-hal

Name	Name	Last commit message	Last commit date
parent directory ..
.cargo	.cargo
src/bin	src/bin
.gitignore	.gitignore
Cargo.toml	Cargo.toml
LICENSE-APACHE	LICENSE-APACHE
LICENSE-MIT	LICENSE-MIT
NOTICE	NOTICE
README.md	README.md
build.rs	build.rs
memory.x	memory.x
riscv_examples.txt	riscv_examples.txt
rp235x_riscv.x	rp235x_riscv.x

rp-hal

Rust Examples for the Raspberry Silicon RP235x family Microcontrollers
View the examples »

Explore the API docs · Report a Bug · Chat on Matrix

Introduction
Getting Started
Roadmap
Contributing
License
Contact
Acknowledgements

Introduction

The rp235x-hal package is a library crate of high-level Rust drivers for the Raspberry Silicon RP235x family of microcontrollers. This folder contains a collection of non-board specific example programs for you to study.

We also provide a series of Board Support Package (BSP) crates, which take the HAL crate and pre-configure the pins according to a specific PCB design. If you are using one of the supported boards, you should use one of those crates in preference, and return here to see documentation about specific peripherals on the RP235x and how to use them. See the boards folder in https://github.com/rp-rs/rp-hal-boards/ for more details.

Getting Started

To build the examples, first grab a copy of the source code:

$ git clone https://github.com/rp-rs/rp-hal.git

Then use rustup to grab the Rust Standard Library for the appropriate targets. RP2350 has two possible targets: thumbv8m.main-none-eabihf for the Arm mode, and riscv32imac-unknown-none-elf for the RISC-V mode.

$ rustup target add thumbv8m.main-none-eabihf
$ rustup target add riscv32imac-unknown-none-elf

Note: all examples assume the current directory is <repo root>/rp235x-hal-examples.

cd rp235x-hal-examples

The most basic method is to use cargo build with the --bin flag to specify the example you want to build. For example, to build the blinky example:

$ cargo build --bin blinky
   Compiling proc-macro2 v1.0.89
   Compiling unicode-ident v1.0.13
   Compiling syn v1.0.109
...
   Compiling pio-parser v0.2.2
   Compiling rp235x-hal v0.2.0
   Compiling pio-proc v0.2.2
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 14.97s

This builds the default target, which is Arm mode and the ELF file is located at ./target/thumbv8m.main-none-eabihf/debug/blinky:

$ file ./target/thumbv8m.main-none-eabihf/debug/blinky
./target/thumbv8m.main-none-eabihf/debug/blinky: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, with debug_info, not stripped

If you want to build a binary that runs in RISC-V mode, then you must specify the RISC-V target to override the default:

$ cargo build --target=riscv32imac-unknown-none-elf --bin blinky
   Compiling nb v1.1.0
   Compiling byteorder v1.5.0
   Compiling stable_deref_trait v1.2.0
..
   Compiling futures v0.3.31
   Compiling frunk v0.4.3
   Compiling rp235x-hal v0.2.0
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.23s```

And we see that the RISC-V mode ELF file is now present at ./target/riscv32imac-unknown-none-elf/debug/blinky:

$ file ./target/riscv32imac-unknown-none-elf/debug/blinky
./target/riscv32imac-unknown-none-elf/debug/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, with debug_info, not stripped

You can also specify the Arm mode target directly by using --target thumbv8m.main-none-eabihf instead of --target riscv32imac-unknown-none-elf.

To build, flash and start the application on the RP235x you use cargo run with one of the following commands. Note: be sure the RP235x is in BOOTSEL mode before using the run command because we use picotool to flash and run the binary:

$ cargo run --target thumbv8m.main-none-eabihf --bin blinky
$ cargo run --target riscv32imac-unknown-none-elf --bin blinky

For the release profile build pass --release to the cargo build or cargo run commands. This will build the example with optimizations enabled:

$ cargo run --target thumbv8m.main-none-eabihf --release --bin blinky
$ cargo run --target riscv32imac-unknown-none-elf --release --bin blinky

For the Arm mode target all of the examples are built if no --bin is specified:

$ cargo clean
     Removed 1488 files, 398.6MiB total
$ cargo build --target thumbv8m.main-none-eabihf
   Compiling proc-macro2 v1.0.89
   Compiling unicode-ident v1.0.13
..
   Compiling rp235x-hal v0.2.0
   Compiling pio-proc v0.2.2
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 16.08s
$ find target/thumbv8m.main-none-eabihf/debug/ -maxdepth 1 -type f -executable | sort
target/thumbv8m.main-none-eabihf/debug/adc
target/thumbv8m.main-none-eabihf/debug/adc_fifo_dma
..
target/thumbv8m.main-none-eabihf/debug/blinky
..
target/thumbv8m.main-none-eabihf/debug/vector_table
target/thumbv8m.main-none-eabihf/debug/watchdog

For the RISC-V mode it is currently possible to build only some of the examples. See riscv_examples.txt for a list of known working examples. The missing ones probably rely on interrupts, or some other thing we haven't ported to work in RISC-V mode yet.

Here is an example using the blinky example in RISC-V mode. We'll build and run it first using the default dev profile, emulating the development cycle Note: be sure the RP235x is in BOOTSEL mode before using the run command because we use picotool to flash and run the binary:

$ cargo build --bin blinky --target=riscv32imac-unknown-none-elf
   Compiling rp235x-hal-examples v0.1.0
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.15s
$ cargo run --bin blinky --target=riscv32imac-unknown-none-elf
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.07s
     Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/debug/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
  00000000->02000000
Loading into Flash: [==============================]  100%
Verifying Flash:    [==============================]  100%
  OK

The device was rebooted to start the application.

At this point the development version is running on the RP2350 and the LED is blinking. When we look at blinky using file we see we have generated a RISC-V mode ELF file:

$ file ./target/riscv32imac-unknown-none-elf/debug/blinky
./target/riscv32imac-unknown-none-elf/debug/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, with debug_info, not stripped

Next we'll build and run it using the release profile for "final" testing, again be sure the RP235x is in BOOTSEL mode:

$ cargo run --bin blinky --target=riscv32imac-unknown-none-elf --release
   Compiling proc-macro2 v1.0.89
   Compiling unicode-ident v1.0.13
..
   Compiling pio-parser v0.2.2
   Compiling pio-proc v0.2.2
    Finished `release` profile [optimized] target(s) in 17.05s
     Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/release/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
  00000000->02000000
Loading into Flash: [==============================]  100%
Verifying Flash:    [==============================]  100%
  OK

The device was rebooted to start the application.

The LED should be blinking as we are now running this binary:

$ file ./target/riscv32imac-unknown-none-elf/release/blinky
./target/riscv32imac-unknown-none-elf/release/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, not stripped

The above commands work well, but the commands are somewhat verbose. To make building and running commands more succinct an [alias] section has been added to .cargo/config.toml that define:

Command Alias	Description
build-arm	build for ARM
build-riscv	build for RISC-V
run-arm	run on ARM
run-riscv	run on RISC-V
rrr-blinky	run release on RISC-V blinky

When using these aliases your build and run commands are much shorter. Below we see the development cycle using build-riscv and run-riscv:

$ cargo build-riscv --bin blinky
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s
$ cargo run-riscv --bin blinky
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s
     Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/debug/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
  00000000->02000000
Loading into Flash: [==============================]  100%
Verifying Flash:    [==============================]  100%
  OK

The device was rebooted to start the application.

And for the run command in --release profile and a RISC-V mode we added the rrr-blinky alias as an example of customization. You might want to add others as you see fit:

$ cargo rrr-blinky
    Finished `release` profile [optimized] target(s) in 0.05s
     Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/release/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
  00000000->02000000
Loading into Flash: [==============================]  100%
Verifying Flash:    [==============================]  100%
  OK

The device was rebooted to start the application.

Roadmap

NOTE The HAL is under active development, and so are these examples. As such, it is likely to remain volatile until a 1.0.0 release.

See the open 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.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

The contents of this repository are dual-licensed under the MIT OR Apache 2.0 License. That means you can choose either the MIT license or the Apache 2.0 license when you re-use this code. See LICENSE-MIT or LICENSE-APACHE for more information on each specific license. Our Apache 2.0 notices can be found in NOTICE.

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

Contact

Project Link: https://github.com/rp-rs/rp-hal/issues
Matrix: #rp-rs:matrix.org

Acknowledgements

Othneil Drew's README template

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rp235x-hal-examples

rp235x-hal-examples

README.md

rp-hal

Table of Contents

Introduction

Getting Started

Roadmap

Contributing

License

Contact

Acknowledgements

Files

rp235x-hal-examples

Directory actions

More options

Directory actions

More options

Latest commit

History

rp235x-hal-examples

Folders and files

parent directory

README.md

rp-hal

Table of Contents

Introduction

Getting Started

Roadmap

Contributing

License

Contact

Acknowledgements