From 98d88f261b009444d978e5f661b0c2da4238200c Mon Sep 17 00:00:00 2001 From: Haobo Gu Date: Sun, 18 Feb 2024 00:27:23 +0800 Subject: [PATCH] docs: add the last part of RMK guide, add docs to readme Signed-off-by: Haobo Gu --- README.md | 10 +++ docs/src/README.md | 111 +--------------------------------- docs/src/compile_and_flash.md | 12 +++- 3 files changed, 22 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index dd8f127e..33657aac 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,18 @@ Keyboard firmware with layer/dynamic keymap/[vial](https://get.vial.today) suppo - [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` +
+ +Click to checkout more news + - [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! +
+ +## [User Documentation](https://haobogu.github.io/rmk/guide_overview.html) + +## [API Reference](https://docs.rs/rmk/latest/rmk/) + ## Prerequisites This crate requires stable Rust 1.75 and up. `openocd`(stm32) or `probe-rs`(stm32/rp2040) is used for flashing & debugging. diff --git a/docs/src/README.md b/docs/src/README.md index 8d1089ec..89f9d5de 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -4,113 +4,4 @@ [![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) -RMK is a Rust keyboard firmware crate with layer/dynamic keymap/[vial](https://get.vial.today) support. - -
-RMK is under active development, breaking changes may happen. If you have any problem please check the latest doc or file an issue. -
- -## News - -- [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 stable Rust 1.75 and up. `openocd`(stm32) or `probe-rs`(stm32/rp2040) is used for flashing & debugging. - -## Usage - -### Option 1: Initialize from template -You can use [rmk-template](https://github.com/HaoboGu/rmk-template) to initialize your project. - -``` -cargo install cargo-generate -cargo generate --git https://github.com/HaoboGu/rmk-template -``` - -### Option 2: Try built-in examples - -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 - ``` - -#### 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" - - # Use probe-rs - cd boards/stm32h7 - cargo run - ``` - -4. (Optional) Debug firmware using CMSIS-DAP - - Open the project using VSCode, choose `Cortex-Debug - stm32h7` debug profile, then 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 - -A lot of todos at the list, any contributions are welcomed :) - -- [x] layer support -- [x] system/media keys -- [x] mouse keys -- [x] vial support -- [x] eeprom -- [x] project template -- [ ] easy keyboard configuration with good default -- [ ] LED -- [ ] RGB -- [ ] better documentation -- [ ] keyboard macro -- [ ] encoder -- [ ] wireless -- [ ] default bootloader/DFU -- [ ] a good gui configurator - -## License - -RMK is licensed under either of - -- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) -- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) - -at your option. +RMK is a Rust keyboard firmware crate with lots of features, like layer support, dynamic keymap, vial support, etc, making firmware customization easy and accessible. \ No newline at end of file diff --git a/docs/src/compile_and_flash.md b/docs/src/compile_and_flash.md index 28b0777b..86cc3d02 100644 --- a/docs/src/compile_and_flash.md +++ b/docs/src/compile_and_flash.md @@ -12,4 +12,14 @@ cargo build --release If you've done all the previous steps correctly, you can find your compiled firmware at `target//release` folder. -If you encountered any problems when compiling the firmware, please report it at [https://github.com/HaoboGu/rmk](https://github.com/HaoboGu/rmk) \ No newline at end of file +If you encountered any problems when compiling the firmware, please report it [here](https://github.com/HaoboGu/rmk/issues). + +## 2. Flash the firmware + +The last step is to flash compiled firmware to your microcontroller. This needs a debug probe like [daplink](https://daplink.io/), [jlink](https://www.segger.com/products/debug-probes/j-link/) or stlink(stm32 only). If you've get your debug probe, connect it with your board and host, make sure you have installed [probe-rs](https://probe.rs/), then just run + +```shell +cargo run --release +``` + +The firmware will be flashed to your microcontroller and the firmware will run automatically, yay!