From a3928693dc01884e7ef118166db8af7278aa6223 Mon Sep 17 00:00:00 2001 From: Haobo Gu Date: Fri, 26 Jan 2024 16:58:29 +0800 Subject: [PATCH] doc(readme): add rmk-template Signed-off-by: Haobo Gu --- README.md | 49 +++++++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 40465217..98c96594 100644 --- a/README.md +++ b/README.md @@ -4,52 +4,52 @@ [![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 for cortex-m, with layer/dynamic keymap/[vial](https://get.vial.today) support, written in Rust. +Keyboard firmware with layer/dynamic keymap/[vial](https://get.vial.today) support, written in Rust. -RMK is under active development, breaking changes may happen. Please check the latest doc or file an issue if you have any problem. +> RMK is under active development, breaking changes may happen. If you have any problem please check the latest doc or file an issue. ## News -RMK just released version 0.1.0, migrate to [Embassy](https://github.com/embassy-rs/embassy)! By migrating to Embassy, RMK now has better async support, more supported MCUs and much easier usages than before. For examples using Embassy, check [`boards`](https://github.com/HaoboGu/rmk/tree/main/boards) folder! +- [2024.01.26] 🎉[rmk-template](https://github.com/HaoboGu/rmk-template) is released! Now you can create your own keyboard firmware with a single command: `cargo generate --git https://github.com/HaoboGu/rmk-template` + +- [2024.01.18] RMK just released version `0.1.0`! By migrating to [Embassy](https://github.com/embassy-rs/embassy), RMK now has better async support, more supported MCUs and much easier usages than before. For examples using Embassy, check [`boards`](https://github.com/HaoboGu/rmk/tree/main/boards) folder! ## Prerequisites -This crate requires Rust 1.75 and up. `openocd`(stm32) or `probe-rs`(stm32/rp2040) is used for flashing & debugging. +This crate requires stable Rust 1.75 and up. `openocd`(stm32) or `probe-rs`(stm32/rp2040) is used for flashing & debugging. ## Usage -NOTE: RMK -You can build your own keyboard firmware using RMK or try built-in firmware example for stm32h7 & rp2040. +### Initialize from template +You can use [rmk-template](https://github.com/HaoboGu/rmk-template) to initialize your project. -### 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: +``` +cargo install cargo-generate +cargo generate --git https://github.com/HaoboGu/rmk-template +``` -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 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 your own keymap file, see: [`boards/stm32h7/src/keymap.rs`](https://github.com/HaoboGu/rmk/blob/main/boards/stm32h7/src/keymap.rs) -5. Generate the vial config of your keymap, folloing vial's [porting guide](https://get.vial.today/docs/porting-to-via.html) -6. Create `main.rs`, create your `async fn main()`. - See [`boards/stm32h7/src/main.rs`](https://github.com/HaoboGu/rmk/blob/main/boards/stm32h7/src/main.rs) +### Try built-in examples -### Use built-in example +Example can be found at [`boards`](https://github.com/HaoboGu/rmk/blob/main/boards). The following is a simple +step-to-step instruction for rp2040 and stm32h7 #### rp2040 1. Install [probe-rs](https://github.com/probe-rs/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 @@ -58,13 +58,18 @@ step-to-step instruction for creating your own firmware: #### stm32h7 1. Install [openocd](https://github.com/openocd-org/openocd) + 2. Build the firmware + ```shell cd boards/stm32h7 cargo build ``` + 3. Flash + You can use both `probe-rs` and `openocd` to flash the firmware: + ```shell # Use openocd openocd -f openocd.cfg -c "program target/thumbv7em-none-eabihf/debug/rmk-stm32h7 preverify verify reset exit" @@ -83,12 +88,11 @@ step-to-step instruction for creating your own firmware: 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 +- [x] project template - [ ] keyboard macro - [ ] wireless - [ ] encoder @@ -96,6 +100,7 @@ A lot of todos at the list, any contributions are welcomed :) - [ ] cli tools ## License + RMK is licensed under either of - Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)