rppal

To use RPPAL in your Rust project, add it to your Cargo.toml dependencies. You can do this using cargo add rppal or by manually adding the dependency line.

Note: RPPAL is no longer maintained as of July 1, 2025. It is compatible with all Raspberry Pi models released before that date, including Raspberry Pi 5.

[dependencies]
rppal = "0.22.1"

If you are developing on a non-Raspberry Pi machine, you must cross-compile for the target ARM architecture.

1. Install the target

For 32-bit Linux, use armv7-unknown-linux-gnueabihf. For 64-bit, use aarch64-unknown-linux-gnu.

rustup target install armv7-unknown-linux-gnueabihf

2. Configure Cargo

Create a .cargo/config.toml file in your project root to set the default target:

[build]
target = "armv7-unknown-linux-gnueabihf"

3. Configure VS Code

To ensure rust-analyzer works correctly, create a .vscode/settings.json file in your project root:

{
    "rust-analyzer.cargo.target": "armv7-unknown-linux-gnueabihf"
}

RPPAL provides a user-friendly interface to access Raspberry Pi peripherals including GPIO, I2C, PWM, SPI, and UART. It also supports USB to serial adapters.

Key integration features:

• embedded-hal support: RPPAL implements embedded-hal traits, allowing it to be used with a wide variety of platform-agnostic drivers. It supports both embedded-hal v0.2.7 and v1.
• Platform Support: Compatible with Raspberry Pi A, A+, B, B+, 2B, 3A+, 3B, 3B+, 4B, 5, CM, CM 3, CM 3+, CM 4, CM 5, 400, Zero, Zero W, and Zero 2 W.
• OS Requirements: Requires a recent release of Raspberry Pi OS. Other Linux distributions are unsupported.
• Toolchain Support: Supports both gnu and musl libc targets.

If your project requires embedded-hal trait implementations, you must specify either the hal or hal-unproven feature flag in your Cargo.toml.

• hal: Enables embedded-hal trait implementations for all supported peripherals (excludes unproven traits).
• hal-unproven: Enables all embedded-hal trait implementations, including those marked as unproven. Note that unproven traits do not follow semver rules and may introduce breaking changes in patch releases.

[dependencies]
rppal = { version = "0.22.1", features = ["hal"] }

When performing a multi-segment transfer via Spi::transfer_segments, each Segment allows you to fine-tune the SPI protocol parameters for that specific chunk of data.

Key behaviors to keep in mind:

1. Buffer Lengths: If you provide both a read and write buffer in a single segment, the transfer length is automatically determined by the shortest of the two buffers. You can check this length using segment.len().
2. Slave Select (SS) Toggling: By setting ss_change to true, you can force the Slave Select line to toggle between segments. This is useful for protocols that require a chip-select pulse between different command/data phases.
3. Inheritance: If you do not explicitly set a parameter (like clock_speed or bits_per_word) on a segment, it defaults to 0, which instructs the driver to use the global configuration of the Spi instance.

PWM channel availability depends on the Raspberry Pi model being used:

Raspberry Pi 5 and later

Supports 4 hardware PWM channels:

• Channel::Pwm0 = GPIO12
• Channel::Pwm1 = GPIO13
• Channel::Pwm2 = GPIO18
• Channel::Pwm3 = GPIO19

Older models (pre-Raspberry Pi 5)

Supports 2 hardware PWM channels:

• Channel::Pwm0 = GPIO12 or GPIO18
• Channel::Pwm1 = GPIO13 or GPIO19

Note: Using analog audio output consumes both PWM channels on older models, which may cause conflicts if you attempt to access PWM simultaneously.

RPPAL can be used as a hardware abstraction layer for the Rust ecosystem by enabling specific features. This allows you to use RPPAL-compatible hardware with any driver that implements the embedded-hal traits.

To use these traits, you must enable one of the following features in your Cargo.toml:

• embedded-hal-0 (for embedded-hal v0.2.7)
• embedded-hal (for embedded-hal v1)
• embedded-hal-nb (for non-blocking embedded-hal support)

The following examples demonstrate communication with other peripherals and hardware modules:

• I2C (Real-Time Clock): i2c_ds3231.rs shows how to set and retrieve time on a Maxim Integrated DS3231 RTC via the I2C bus.
• Hardware PWM:
  • pwm_blinkled.rs blinks an LED using the Raspberry Pi's dedicated hardware PWM.
  • pwm_servo.rs rotates a servo motor using hardware PWM.
• SPI (EEPROM): spi_25aa1024.rs demonstrates data transfers to a Microchip 25AA1024 serial EEPROM using the SPI bus.
• UART (Serial): uart_blocking_read.rs demonstrates how to perform blocking reads while waiting for incoming serial data.

This example demonstrates how to control a GPIO pin to blink an LED. This code uses BCM pin numbering (e.g., BCM 23 corresponds to physical pin 16).

Caution: Always use an appropriate resistor in series with an LED to prevent damage to the GPIO pin or the LED.

use std::error::Error;
use std::thread;
use std::time::Duration;

use rppal::gpio::Gpio;
use rppal::system::DeviceInfo;

// Gpio uses BCM pin numbering. BCM GPIO 23 is tied to physical pin 16.
const GPIO_LED: u8 = 23;

fn main() -> Result<(), Box<dyn Error>> {
    println!("Blinking an LED on a {}.", DeviceInfo::new()?.model());

    let mut pin = Gpio::new()?.get(GPIO_LED)?.into_output();

    // Blink the LED by setting the pin's logic level high for 500 ms.
    pin.set_high();
    thread::sleep(Duration::from_millis(500));
    pin.set_low();

    Ok()
}