RPSP

RP2040 Platform Support Package

Rust library for easy methods to program and design programs for RP2040 devices.

Device Selection

To select the proper pin layout, you must specify the device in the "features" when declaring this crate as a depdency.

Example for the PiPico

rpsp = { version = "0.2.0", features = [ "pico" ] }

Supported Devices

The following device pinouts are supported:

• Pico / PicoW (pico)
• Tiny2040 (tiny2040)
• Seed Studio 2040 (xiao2040)

If your device has no support, you can still use the pico device type, but BE CAREFUL OF THE PINS USED.

I'm open to more devices, I just don't have examples to use ^_^

If you'd like to contribute, pinouts are generated from layout text files in the boards/data directory. These are converted into .rs files via the generate.py python script in boards. This will write board files into the src/pin/boards directory and updates the src/pin/boards/lib.rs with all the tags and modules. The text format is pretty simple, it takes the Pin number and it's capabilities for each line.

Documentation is listed here.

Note

You'll need to make sure you have the flip-link linker installed before compiling. To do this, use the command cargo install flip-link to install it.

Additional Cargo Configuration

For best results, create a .cargo/config.toml file in your project root directory and specify somthing like this:

[target.'cfg(all(target_arch = "arm", target_os = "none"))']
rustflags  = [
    "-C", "linker=flip-link",
    "-C", "link-arg=--nmagic",
    "-C", "link-arg=-Tlink.x",
    "-Z", "trap-unreachable=no",
    "-C", "no-vectorize-loops",
]

[build]
target    = "thumbv6m-none-eabi"

Requires the nightly version of the compiler to use "-Z", "trap-unreachable=no", and can be removed, but will increase binary size slightly.

Extra bonus points if you add:

runner    = "probe-rs run --chip RP2040"

Under the rustflags option. This allows you to flash the firmware on the device directly from cargo run. (Pico debug probe probe and probe-rs required. Can be installed using cargo install probe-rs-tools. Pico probe can be made from another Pico! see here).

Lastly, these are the recommended profile settings for best program results. These go inside the Cargo.toml file in the project root directory.

[profile.dev]
debug            = 2
strip            = false
opt-level        = 3
incremental      = false
codegen-units    = 1
overflow-checks  = true
debug-assertions = true

[profile.release]
lto              = "fat"
panic            = "abort"
debug            = false
strip            = true
opt-level        = 3
incremental      = false
codegen-units    = 1
overflow-checks  = false
debug-assertions = false

Usage

NOTE: The struct Pico has been renamed to Board to properly reflect the multi-device usage. However it still carries the alias type Pico and may be used interchangeably.

To use this library, just import rpsp::Board and call Board::get(). On the first call, the device and it's clocks will be initialized and setup fully.

The configuration is automatic and uses the ROSC as the system clock, disables the XOSC and PLLs and allows for DORMANT sleep, for maximum power savings.

To supply main, you must setup the main function with the #[rpsp::entry] macro, which will setup the locks and properly redirect execution to the selected function.

Basic programs should look something like this:

#![no_std]
#![no_main]

#[rpsp::entry]
fn main() -> ! {
    // do stuff here
}

If you're not using something like defmt, (which is not included by default) you'll need a panic_handler. The example below is a pretty basic one that just loops the CPU:

#[panic_handler]
fn panic(_p: &core::panic::PanicInfo<'_>) -> ! {
    loop {}
}

For the below examples, the panic_handler is omitted, so if you want to use these, you'll need to add it in order for it to compile.

GPIO

Control Pin output:

use rpsp::Board
use rpsp::pin::PinID;

#[rpsp::entry]
fn main() -> ! {
    let p = Board::get();
    let my_pin = p.pin(PinID::Pin5);
    // You could also do..
    // let my_pin = Pin::get(&p, PinID::Pin5);

    // Set High
    my_pin.high();

    // Set Low
    my_pin.low();

    // Need this at the end since it's a '!' function.
    loop {}
}

Read Pin output:

use rpsp::Board
use rpsp::pin::PinID;

#[rpsp::entry]
fn main() -> ! {
    let p = Board::get();
    let my_pin = p.pin(PinID::Pin6).into_input();

    // Set High
    if my_pin.is_high() {
        // Do stuff..
    }

    if my_pin.is_low() {
        // Do other stuff..
    }

    // Need this at the end since it's a '!' function.
    loop {}
}

UART

use rpsp::Board
use rpsp::pin::PinID;
use rpsp::uart::{Uart, UartConfig, UartDev};

#[rpsp::entry]
fn main() -> ! {
    let p = Board::get();

    // DEFAULT_BAUDRATE is 115,200
    let mut u = Uart::new(
        &p,
        UartConfig::DEFAULT_BAUDRATE,
        UartConfig::new(), // Default is NoParity, 8 Bits, 1 Stop Bit.
        UartDev::new(PinID::Pin0, PinID::Pin1).unwrap(),
        // ^ This can error since not all Pinouts are a valid UART set.
        // You can also use..
        // (PinID::Pin0, PinID::Pin1).into()
    ).unwrap();

    let _ = u.write("HEY THERE\n".as_bytes()).unwrap();
    // Returns the amount of bytes written.

    let mut buf = [0u8; 32];
    let n = u.read(&mut buf).unwrap();
    // Read up to 32 bytes.

    // Echo it back.
    let _ = u.write(&buf[0:n]).unwrap();

    // Cleanup
    u.close();

    // Need this at the end since it's a '!' function.
    loop {}
}

Time and Sleep

use rpsp::Board

#[rpsp::entry]
fn main() -> ! {
    let p = Board::get();

    for i in 0..25 {
        p.sleep(5_000); // Wait 5 seconds.

        // Get current RTC time.
        let now = p.rtc().now().unwrap();

        debug!("the time is now {now:?}");
    }

    // Need this at the end since it's a '!' function.
    loop {}
}

Watchdog

use rpsp::Board

#[rpsp::entry]
fn main() -> ! {
    let p = Board::get();
    let dog = p.watchdog();

    dog.start(5_000); // Die if we don't feed the dog every 5 seconds.

    for _ in 0..10 {
        p.sleep(2_500); // ait 2.5 seconds.

        dog.feed(); // Feed da dog.
    }

    p.sleep(10_000); // Device will restart during here.

    // Need this at the end since it's a '!' function.
    loop {}
}

Theres alot of more examples I need to add..

TODO

• CYW Driver
  • Networking??

License for the CYW driver is here