RPPAL - Raspberry Pi外设访问库

RPPAL通过用户友好的接口提供对Raspberry Pi的GPIO、I2C、PWM、SPI和UART外设的访问。除了外设访问外，RPPAL还提供对USB到串行适配器的支持。该库可以通过其embedded-hal特征实现与各种平台无关的驱动程序一起使用。

RPPAL需要Raspbian或任何类似的、较新的Linux发行版。支持gnu和musl的libc目标。RPPAL与Raspberry Pi A、A+、B、B+、2B、3A+、3B、3B+、4B、CM、CM 3、CM 3+、Zero和Zero W兼容。直到v1.0.0版本，不会保证向后兼容小版本。

此库在GitHub存储库的master分支上处于积极开发状态。如果您正在寻找最新发布版或任何早期发布版的README.md或examples目录，请访问crates.io，从GitHub releases页面下载存档发布版，或克隆并检出相关发布标签。

目录

• 文档
• 使用方法
• 示例
• 可选功能
• 支持的外设
  • GPIO
  • I2C
  • PWM
  • SPI
  • UART
• 交叉编译
  • Cargo
  • RLS
• 注意
• 版权和许可

文档

在线文档适用于最新发布版、旧发布版以及当前开发版。

• 最新发布版：docs.golemparts.com/rppal
• 旧发布版：docs.rs/rppal
• 开发中：docs.golemparts.com/rppal-dev

使用方法

将rppal作为依赖项添加到您的Cargo.toml中。

[dependencies]
rppal = "0.11.3"

如果您的项目需要embedded-hal特征实现，在依赖声明中指定hal或hal-unproven功能标志。

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

在任何外设上调用 new() 来构建一个新的实例。

use rppal::gpio::Gpio;
use rppal::i2c::I2c;
use rppal::pwm::{Channel, Pwm};
use rppal::spi::{Bus, Mode, SlaveSelect, Spi};
use rppal::uart::{Parity, Uart};

let gpio = Gpio::new()?;
let i2c = I2c::new()?;
let pwm = Pwm::new(Channel::Pwm0)?;
let spi = Spi::new(Bus::Spi0, SlaveSelect::Ss0, 16_000_000, Mode::Mode0)?;
let uart = Uart::new(115_200, Parity::None, 8, 1)?;

访问某些外设可能需要先通过 sudo raspi-config 或编辑 /boot/config.txt 来启用。请参考相关模块的文档了解所需步骤。

示例

以下示例演示了如何闪烁连接到GPIO引脚的LED。请记住添加适当值的电阻，以防止超过GPIO引脚和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(())
}

更多示例可以在 examples 目录中找到。

可选功能

默认情况下，所有可选功能都未启用。您可以通过在您的 Cargo.toml 中为 rppal 指定相关的功能标志来启用功能。

• hal - 启用所有支持外设的 embedded-hal 特性实现。这不包括 unproven 特性。
• hal-unproven - 启用所有支持外设的 embedded-hal 特性实现，包括标记为 unproven 的特性。请注意，embedded-hal 的 unproven 特性不遵循semver规则。补丁版本可能会引入破坏性更改。

支持的外设

GPIO

为了确保快速性能，RPPAL 通过直接访问寄存器来控制GPIO外设，通过 /dev/gpiomem 或 /dev/mem。使用 gpiochip 字符设备配置GPIO中断。

功能

• 设置/获取引脚模式和逻辑电平
• 配置内置的上拉/下拉电阻
• 同步和异步中断处理程序
• 基于软件的PWM实现
• 可选的 embedded-hal 特性实现（《digital::{InputPin, OutputPin, StatefulOutputPin, ToggleableOutputPin}，Pwm，PwmPin）

• 单主站，7位从站地址，传输速率高达400 kbit/s（快速模式）
• I2C基本读写，块读写，组合写+读
• SMBus协议：快速命令，发送/接收字节，读取/写入字节/字，进程调用，块写，PEC
• 可选的 embedded-hal 特性实现（《blocking::i2c::{Read, Write, WriteRead}）

PWM

RPPAL通过 pwm sysfs接口控制树莓派的PWM外设。

功能

• 多达两个硬件PWM通道
• 可配置频率、占空比和极性
• 可选的 embedded-hal 特性实现（《Pwm》，《PwmPin》）

SPI

RPPAL通过 spidev 字符设备控制树莓派的主和辅助SPI外设。

功能

• SPI主站，模式0-3，从选通低/高有效，每字8位，可配置时钟速度
• 半双工读写，多段传输
• 全双工传输和多段传输
• 可自定义多段传输中每个段的可配置选项（时钟速度、延迟、SS改变）
• 反转位顺序辅助函数
• 可选的 embedded-hal 特性实现（blocking::spi::{Transfer, Write}，spi::FullDuplex）

UART

RPPAL 通过 ttyAMA0（PL011）和 ttyS0（mini UART）字符设备控制 Raspberry Pi 的 UART 外设。使用 ttyUSBx 和 ttyACMx 字符设备控制 USB 转串行适配器。

功能

• 支持 UART 外设（PL011、mini UART）和 USB 转串行适配器
• 无/偶/奇/标记/空校验位，5-8 位数据位，1-2 位停止位
• 传输速率高达 4 Mbit/s（设备相关）
• XON/XOFF 软件流控制
• RTS/CTS 硬件流控制，带自动引脚配置
• 可选的 embedded-hal 特性实现（blocking::serial::Write，serial::{Read, Write}）

交叉编译

如果您不是直接在 Raspberry Pi 上工作，您必须为适当的 ARM 架构交叉编译您的代码。查看此指南以获取更多信息，或尝试cross项目以进行“零设置”交叉编译。

Cargo

虽然可能需要在您的平台上执行额外的步骤以交叉编译二进制文件，但使用cargo check检查您的代码只需安装适当的目标。大多数 Raspberry Pi 型号需要armv7-unknown-linux-gnueabihf目标。对于某些型号，例如 Raspberry Pi Zero，需要不同的目标三元组。

使用 rustup 安装相关目标。

rustup target install armv7-unknown-linux-gnueabihf

在项目的根目录中创建一个 .cargo 子目录，然后将以下片段保存到 .cargo/config。

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

RLS

RLS 需要通过设置 rust.target 配置选项来了解目标平台。此选项的位置是 IDE 特定的。

Visual Studio Code

在项目的根目录中创建一个 .vscode 子目录，然后将以下片段保存到 .vscode/settings.json。

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

注意

在处理 Raspberry Pi 的外设时始终要小心，尤其是如果您将任何外部组件连接到 GPIO 引脚。不当使用可能导致永久损坏。

版权和许可

版权（c）2017-2020 Rene van der Meer。在MIT 许可证下发布。