rmk 0.1.3

Keyboard firmware written in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# 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 for cortex-m, 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.

## 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!

## Prerequisites

This crate requires 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.

### 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 using `cargo add rmk`
2. Choose your target, use `rustup target add <your-target-name>` 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)

### Use built-in example

#### 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] support rp2040
- [x] basic keyboard functions
- [x] layer
- [x] system/media keys
- [x] vial support
- [x] eeprom
- [ ] keyboard macro
- [ ] wireless
- [ ] encoder
- [ ] RGB
- [ ] 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)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.