Add HALs for Framework Input Modules (#92)

* Add HAL for Framework LED Matrix * Add Framework 16 Keyboard HAL * boards/framework16-keyboard: Add capslock example * boards/framework16-keyboard: Add backlight example * boards/framework-ledmatrix: Add ledtest example --------- Signed-off-by: Daniel Schaefer <dhs@frame.work>
rp-rs · Jan 1, 2025 · 451f02c · 451f02c
1 parent ce80657
commit 451f02c
Show file tree

Hide file tree

Showing 16 changed files with 991 additions and 0 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -10,6 +10,8 @@ members = [
     "boards/adafruit-trinkey-qt2040",
     "boards/arduino_nano_connect",
     "boards/boardsource-blok",
+    "boards/framework-ledmatrix",
+    "boards/framework16-keyboard",
     "boards/pimoroni_badger2040",
     "boards/pimoroni-pico-explorer",
     "boards/pimoroni-pico-lipo-16mb",

diff --git a/boards/framework-ledmatrix/.gitignore b/boards/framework-ledmatrix/.gitignore
@@ -0,0 +1,11 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
diff --git a/boards/framework-ledmatrix/CHANGELOG.md b/boards/framework-ledmatrix/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2024-10-21
+
+### Added
+
+- Initial release of Framework LED Matrix HAL
diff --git a/boards/framework-ledmatrix/Cargo.toml b/boards/framework-ledmatrix/Cargo.toml
@@ -0,0 +1,57 @@
+[package]
+name = "framework-ledmatrix"
+version = "0.1.0"
+authors = ["Daniel Schaefer <dhs@frame.work>", "The rp-rs Developers"]
+edition = "2018"
+homepage = "https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework-ledmatrix"
+description = "Board Support Package for the Framework LED Matrix"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/rp-rs/rp-hal-boards.git"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+cortex-m-rt = { workspace = true, optional = true }
+fugit.workspace = true
+rp2040-boot2 = { workspace = true, optional = true }
+rp2040-hal.workspace = true
+
+[dev-dependencies]
+cortex-m.workspace = true
+critical-section.workspace = true
+embedded-graphics.workspace = true
+embedded-hal.workspace = true
+heapless.workspace = true
+nb.workspace = true
+panic-halt.workspace = true
+rp2040-hal = { workspace = true, features = [ "defmt" ] }
+is31fl3741 = { version = "0.4.0", features = [ "framework_ledmatrix" ] }
+
+defmt.workspace = true
+defmt-rtt.workspace = true
+
+[features]
+# This is the set of features we enable by default
+default = ["boot2", "rt", "critical-section-impl", "rom-func-cache"]
+
+# critical section that is safe for multicore use
+critical-section-impl = ["rp2040-hal/critical-section-impl"]
+
+# 2nd stage bootloaders for rp2040
+boot2 = ["rp2040-boot2"]
+
+# Minimal startup / runtime for Cortex-M microcontrollers
+rt = ["cortex-m-rt","rp2040-hal/rt"]
+
+# This enables a fix for USB errata 5: USB device fails to exit RESET state on busy USB bus.
+# Only required for RP2040 B0 and RP2040 B1, but it also works for RP2040 B2 and above
+rp2040-e5 = ["rp2040-hal/rp2040-e5"]
+
+# Memoize(cache) ROM function pointers on first use to improve performance
+rom-func-cache = ["rp2040-hal/rom-func-cache"]
+
+# Disable automatic mapping of language features (like floating point math) to ROM functions
+disable-intrinsics = ["rp2040-hal/disable-intrinsics"]
+
+# This enables ROM functions for f64 math that were not present in the earliest RP2040s
+rom-v2-intrinsics = ["rp2040-hal/rom-v2-intrinsics"]
diff --git a/boards/framework-ledmatrix/README.md b/boards/framework-ledmatrix/README.md
@@ -0,0 +1,124 @@
+# [framework-ledmatrix] - Board Support for the [Framework LED Matrix]
+
+You should include this crate if you are writing code that you want to run on
+a [Frameworkg LED Matrix].
+
+This crate includes the [rp2040-hal], but also configures each pin of the
+RP2040 chip according to how it is connected up on the module.
+
+[Framework LED Matrix]: https://frame.work/tw/en/products/16-led-matrix
+[framework-ledmatrix]: https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework-ledmatrix
+[rp2040-hal]: https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal
+[Raspberry Silicon RP2040]: https://www.raspberrypi.org/products/rp2040/
+
+## Using
+
+To use this crate, your `Cargo.toml` file should contain:
+
+```toml
+framework-ledmatrix = "0.1.0"
+```
+
+In your program, you will need to call `framework_ledmatrix::Pins::new` to create
+a new `Pins` structure. This will set up all the GPIOs for any on-board
+devices. See the [examples](./examples) folder for more details.
+
+## Examples
+
+### General Instructions
+
+To compile an example, clone the _rp-hal-boards_ repository and run:
+
+```console
+rp-hal-boards/boards/framework-ledmatrix $ cargo build --release --example <name>
+```
+
+You will get an ELF file called
+`./target/thumbv6m-none-eabi/release/examples/<name>`, where the `target`
+folder is located at the top of the _rp-hal-boards_ repository checkout. Normally
+you would also need to specify `--target=thumbv6m-none-eabi` but when
+building examples from this git repository, that is set as the default.
+
+If you want to convert the ELF file to a UF2 and automatically copy it to the
+USB drive exported by the RP2040 bootloader, simply boot your board into
+bootloader mode and run:
+
+```console
+rp-hal-boards/boards/framework-ledmatrix $ cargo run --release --example <name>
+```
+
+If you get an error about not being able to find `elf2uf2-rs`, try:
+
+```console
+$ cargo install elf2uf2-rs
+```
+then try repeating the `cargo run` command above.
+
+### From Scratch
+
+To start a basic project from scratch, create a project using `cargo new project-name`. Within the
+project directory, run `cargo add framework-ledmatrix`, `cargo add cortex-m-rt`, and `cargo add panic-halt`. The
+first command will add this HAL (Hardware Abstraction Layer), the second is required for the `#[entry]` macro, and _panic-halt_ creates a simple panic function, which just halts.
+
+You'll also need to copy the cargo config file from the [repo](https://github.com/rp-rs/rp-hal-boards/blob/main/.cargo/config.toml). It specifies the target and optimizing flags to the linker. You'll also need to copy [_memory.x_](https://github.com/rp-rs/rp-hal-boards/blob/main/memory.x) to your project root. This file tells the linker the flash and RAM layout, so it won't clobber the bootloader or write to an out of bounds memory address. 
+
+The simplest working example, which does nothing except loop forever, is:
+
+```ignore
+#![no_std]
+#![no_main]
+use framework_ledmatrix::entry;
+use panic_halt as _;
+#[entry]
+fn see_doesnt_have_to_be_called_main() -> ! {
+  loop {}
+}
+```
+
+It can be placed in _/src/main.rs_. 
+
+You can use `cargo run` to compile and install it. 
+**Note**: You won't see any activity since this program does nothing. You can use the examples provided
+to add more functionality. 
+
+### [ledtest](./examples/ledtest.rs)
+
+Lights up every single LED one after another. It goes back into bootloader mode
+when the system goes to sleep. This makes it easy for you to reflash it to
+other firmware.
+
+## 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**.
+
+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 a [New Pull Request](https://github.com/rp-rs/rp-hal-boards/pulls)
+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!
+
+## Code of Conduct
+
+Contribution to this crate is organized under the terms of the [Rust Code of
+Conduct][CoC], and the maintainer of this crate, the [rp-rs team], promises
+to intervene to uphold that code of conduct.
+
+[CoC]: CODE_OF_CONDUCT.md
+[rp-rs team]: https://github.com/orgs/rp-rs/teams/rp-rs
+
+## 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 `MIT` or `APACHE2.0` for more
+information on each specific license.
+
+Any submissions to this project (e.g. as Pull Requests) must be made available
+under these terms.
diff --git a/boards/framework-ledmatrix/build.rs b/boards/framework-ledmatrix/build.rs
@@ -0,0 +1,6 @@
+//! This build script makes sure the linker flag -Tdefmt.x is added
+//! for the examples.
+
+fn main() {
+    println!("cargo:rustc-link-arg-examples=-Tdefmt.x");
+}
diff --git a/boards/framework-ledmatrix/examples/ledtest.rs b/boards/framework-ledmatrix/examples/ledtest.rs
@@ -0,0 +1,147 @@
+//! # Framework LED Matrix Module LED Test Example
+//!
+//! Lights up every single LED one after another.
+//!
+//! See the `Cargo.toml` file for Copyright and license details.
+
+#![no_std]
+#![no_main]
+#![allow(clippy::needless_range_loop)]
+
+// The macro for our start-up function
+use framework_ledmatrix::entry;
+use framework_ledmatrix::{Pins, XOSC_CRYSTAL_FREQ};
+
+use embedded_hal::digital::{InputPin, OutputPin};
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
+use panic_halt as _;
+
+// Pull in any important traits
+use framework_ledmatrix::hal::prelude::*;
+
+// A shorter alias for the Peripheral Access Crate, which provides low-level
+// register access
+use framework_ledmatrix::hal::pac;
+
+// A shorter alias for the Hardware Abstraction Layer, which provides
+// higher-level drivers.
+use framework_ledmatrix::hal;
+
+use fugit::RateExtU32;
+
+/// Maximum brightness out of 255
+///
+/// 100/255 results in 250mA current draw and is plenty bright.
+///  50/255 results in 160mA current draw and is plenty bright.
+const MAX_BRIGHTNESS: u8 = 50;
+
+use is31fl3741::devices::{LedMatrix, CALC_PIXEL};
+
+#[entry]
+fn main() -> ! {
+    // Grab our singleton objects
+    let mut pac = pac::Peripherals::take().unwrap();
+    let core = pac::CorePeripherals::take().unwrap();
+
+    // Set up the watchdog driver - needed by the clock setup code
+    let mut watchdog = hal::Watchdog::new(pac.WATCHDOG);
+
+    // Configure the clocks
+    //
+    // The default is to generate a 125 MHz system clock
+    let clocks = hal::clocks::init_clocks_and_plls(
+        XOSC_CRYSTAL_FREQ,
+        pac.XOSC,
+        pac.CLOCKS,
+        pac.PLL_SYS,
+        pac.PLL_USB,
+        &mut pac.RESETS,
+        &mut watchdog,
+    )
+    .ok()
+    .unwrap();
+
+    // The single-cycle I/O block controls our GPIO pins
+    let sio = hal::Sio::new(pac.SIO);
+
+    // Set the pins up according to their function on this particular board
+    let pins = Pins::new(
+        pac.IO_BANK0,
+        pac.PADS_BANK0,
+        sio.gpio_bank0,
+        &mut pac.RESETS,
+    );
+
+    // The delay object lets us wait for specified amounts of time (in
+    // milliseconds)
+    let mut delay = cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().to_Hz());
+
+    // Enable LED controller
+    // SDB - Gpio29
+    let mut led_enable = pins.sdb.into_push_pull_output();
+    led_enable.set_high().unwrap();
+    // INTB. Currently ignoring
+    pins.intb.into_floating_input();
+
+    let sda_pin: hal::gpio::Pin<_, hal::gpio::FunctionI2C, _> = pins.gpio26.reconfigure();
+    let scl_pin: hal::gpio::Pin<_, hal::gpio::FunctionI2C, _> = pins.gpio27.reconfigure();
+
+    let i2c = hal::I2C::i2c1(
+        pac.I2C1,
+        sda_pin,
+        scl_pin,
+        1000.kHz(),
+        &mut pac.RESETS,
+        &clocks.peripheral_clock,
+    );
+
+    let mut dip1 = pins.dip1.into_pull_up_input();
+    let _ = dip1.is_high().unwrap();
+
+    // Detect whether the sleep pin is connected
+    // Early revisions of the hardware didn't have it wired up, if that is the
+    // case we have to ignore its state.
+    let mut sleep_present = false;
+    let mut sleep = pins.sleep.into_pull_up_input();
+    if sleep.is_low().unwrap() {
+        sleep_present = true;
+    }
+    let mut sleep = sleep.into_pull_down_input();
+    if sleep.is_high().unwrap() {
+        sleep_present = true;
+    }
+
+    let mut matrix = LedMatrix::new(i2c, CALC_PIXEL);
+    matrix
+        .setup(&mut delay)
+        .expect("failed to setup RGB controller");
+
+    // Enable only the SW pins that we're using.
+    // Otherwise driving the unused pins might result in audible noise.
+    matrix
+        .device
+        .sw_enablement(is31fl3741::SwSetting::Sw1Sw8)
+        .unwrap();
+
+    matrix
+        .set_scaling(MAX_BRIGHTNESS)
+        .expect("failed to set scaling");
+
+    loop {
+        // Light up each LED, one by one
+        for y in 0..matrix.device.height {
+            for x in 0..matrix.device.width {
+                matrix.device.pixel(x, y, 0xFF).expect("couldn't turn on");
+                delay.delay_ms(100);
+                matrix.device.pixel(x, y, 0).expect("couldn't turn off");
+
+                // Reset into bootloader if system asleep
+                if sleep_present && sleep.is_low().unwrap() {
+                    hal::rom_data::reset_to_usb_boot(0, 0);
+                }
+            }
+        }
+    }
+}