From f9c97ecd47e422e696c72a4aa24084c8619aba4f Mon Sep 17 00:00:00 2001 From: HaoboGu Date: Sat, 2 Dec 2023 12:28:00 +0800 Subject: [PATCH] doc(readme): reorganize readme Signed-off-by: HaoboGu --- README.md | 119 +++++++++++++++++++++++++----------------------------- 1 file changed, 56 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 9b71ff2f..970eff0e 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,10 @@ - - -

RMK - -
-

+# RMK [![Crates.io](https://img.shields.io/crates/v/rmk)](https://crates.io/crates/rmk) [![Docs](https://img.shields.io/docsrs/rmk)](https://docs.rs/rmk/latest/rmk/) [![Build](https://github.com/haobogu/rmk/actions/workflows/build.yml/badge.svg)](https://github.com/HaoboGu/rmk/actions) -

-

- - -Keyboard firmware written in Rust. Tested on stm32 and rp2040. - -![IMG_2627](https://github.com/HaoboGu/rmk/assets/8640918/9789dbf7-c974-467e-bbdd-5fa3cc80c66c) - -## Features & TODOs - -A lot of todos at the list, any contributions are welcomed :) - -- [x] support rp2040 -- [x] basic keyboard functions -- [x] layer -- [x] system/media keys -- [x] vial support -- [x] eeprom -- [ ] macro -- [ ] encoder -- [ ] RGB -- [ ] cli tools +Keyboard firmware for cortex-m, with layer/dynamic keymap/vial support, tested on stm32 and rp2040. ## Prerequisites @@ -38,50 +12,69 @@ This crate requires **nightly** Rust. `openocd`(stm32) or `probe-rs`(rp2040) is ## Usage +You can build your own keyboard firmware using RMK or try built-in firmware example for stm32h7 & rp2040. + +### Build your own firmware Example can be found at [`boards`](https://github.com/HaoboGu/rmk/blob/main/boards). The following is a simple step-to-step instruction for creating your own firmware: -1. Create a rust embedded project, Add rmk to your project +1. Create a rust embedded project, Add rmk to your project using `cargo add rmk` 2. Choose your target, use `rustup target add ` to install the target. [Here](https://docs.rust-embedded.org/book/intro/install.html) is the doc for target choosing. For example, - rp2040 is Cortex-M0+, so its corresponding target is `thumbv6m-none-eabi`. + rp2040 is Cortex-M0+, so its target is `thumbv6m-none-eabi`. 3. Create `.cargo/config.toml` in your project's root, specify your target here. See [`boards/stm32h7/.cargo/config.toml`](https://github.com/HaoboGu/rmk/blob/main/boards/stm32h7/.cargo/config.toml) 4. Create `main.rs`, initialize your MCU in rtic's `mod app`, create usb polling task and keyboard task. See [`boards/stm32h7/src/main.rs`](https://github.com/HaoboGu/rmk/blob/main/boards/stm32h7/src/main.rs) -## Compile the firmware - -``` -# Compile stm32 example -cd boards/stm32h7 -cargo build +### Use built-in example + +#### rp2040 + +1. Install `probe-rs` + ```shell + cargo install probe-rs --features cli + ``` +2. Build the firmware + ```shell + cd boards/rp2040 + cargo build + ``` +3. Flash it + ```shell + cd boards/rp2040 + cargo run + ``` + +#### stm32h7 + +1. Install [openocd](https://github.com/openocd-org/openocd) +2. Build the firmware + ```shell + cd boards/stm32h7 + cargo build + ``` +3. Flash + ```shell + openocd -f openocd.cfg -c "program target/thumbv7em-none-eabihf/debug/rmk-stm32h7 preverify verify reset exit" + ``` +4. (Optional) Debug firmware using CMSIS-DAP + + Open the project using VSCode, press `F5`, the firmware will be automatically compiled and flashed. A debug session is started after flashing. + Check [`.vscode/tasks.json`](https://github.com/HaoboGu/rmk/blob/main/.vscode/tasks.json) and [`.vscode/launch.json`](https://github.com/HaoboGu/rmk/blob/main/.vscode/launch.json) for details. + +## Roadmap -# Compile rp2040 example -cd boards/rp2040 -cargo build -``` - -## Flash - -### pi-pico(rp2040) - -Flashing rp2040 is quite simple: - -```shell -cd boards/rp2040 -cargo run -``` - -### stm32 - -Requires `openocd`. - -VSCode: Press `F5`, the firmware will be automatically compiled and flashed. A debug session is started after flashing. -Check `.vscode/tasks.json` for details. - -Or you can do it manually using the following command to flash the firmware after compiling: +A lot of todos at the list, any contributions are welcomed :) -```shell -openocd -f openocd.cfg -c "program target/thumbv7em-none-eabihf/debug/rmk-stm32h7 preverify verify reset exit" -``` +- [x] support rp2040 +- [x] basic keyboard functions +- [x] layer +- [x] system/media keys +- [x] vial support +- [x] eeprom +- [ ] support embassy runtime +- [ ] macro +- [ ] encoder +- [ ] RGB +- [ ] cli tools \ No newline at end of file