refactor(core): update arguments of entry function, add docs

Signed-off-by: Haobo Gu <[email protected]>

boards/rp2040/build.rs

@@ -10,12 +10,17 @@
 //!
 //! The build script also sets the linker flags to tell it which link script to use.
 
-use std::env;
+use const_gen::*;
 use std::fs::File;
-use std::io::Write;
-use std::path::PathBuf;
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+use std::{env, fs};
+use xz2::read::XzEncoder;
 
 fn main() {
+    // Generate vial config at the root of project
+    generate_vial_config();
+
     // Put `memory.x` in our output directory and ensure it's
     // on the linker search path.
     let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
@@ -46,3 +51,32 @@ fn main() {
 
     println!("cargo:rustc-linker=flip-link");
 }
+
+fn generate_vial_config() {
+    // Generated vial config file
+    let out_file = Path::new(&env::var_os("OUT_DIR").unwrap()).join("config_generated.rs");
+
+    let p = Path::new("vial.json");
+    let mut content = String::new();
+    match File::open(&p) {
+        Ok(mut file) => {
+            file.read_to_string(&mut content)
+                .expect("Cannot read vial.json");
+        }
+        Err(e) => println!("Cannot find vial.json {:?}: {}", p, e),
+    };
+
+    let vial_cfg = json::stringify(json::parse(&content).unwrap());
+    let mut keyboard_def_compressed: Vec<u8> = Vec::new();
+    XzEncoder::new(vial_cfg.as_bytes(), 6)
+        .read_to_end(&mut keyboard_def_compressed)
+        .unwrap();
+
+    let keyboard_id: Vec<u8> = vec![0xB9, 0xBC, 0x09, 0xB2, 0x9D, 0x37, 0x4C, 0xEA];
+    let const_declarations = vec![
+        const_declaration!(pub VIAL_KEYBOARD_DEF = keyboard_def_compressed),
+        const_declaration!(pub VIAL_KEYBOARD_ID = keyboard_id),
+    ]
+    .join("\n");
+    fs::write(&out_file, const_declarations).unwrap();
+}

boards/rp2040/src/main.rs

@@ -20,7 +20,7 @@ use embassy_rp::{
     usb::{Driver, InterruptHandler},
 };
 use panic_probe as _;
-use rmk::{initialize_keyboard_and_run, keymap::KeyMap};
+use rmk::{config::{RmkConfig, KeyboardUsbConfig, VialConfig}, initialize_keyboard_with_config_and_run, keymap::KeyMap};
 use static_cell::StaticCell;
 use vial::{VIAL_KEYBOARD_DEF, VIAL_KEYBOARD_ID};
 
@@ -63,8 +63,24 @@ async fn main(_spawner: Spawner) {
         None,
     )));
 
-    // Initialize all utilities: keyboard, usb and keymap
-    initialize_keyboard_and_run::<
+    let keyboard_usb_config = KeyboardUsbConfig::new(
+        0x4c4b,
+        0x4643,
+        Some("Haobo"),
+        Some("RMK Keyboard"),
+        Some("00000001"),
+    );
+
+    let vial_config = VialConfig::new(VIAL_KEYBOARD_ID, VIAL_KEYBOARD_DEF);
+
+    let keyboard_config = RmkConfig {
+        usb_config: keyboard_usb_config,
+        vial_config,
+        ..Default::default()
+    };
+
+    // Start serving
+    initialize_keyboard_with_config_and_run::<
         Driver<'_, USB>,
         Input<'_, AnyPin>,
         Output<'_, AnyPin>,
@@ -73,13 +89,6 @@ async fn main(_spawner: Spawner) {
         ROW,
         COL,
         NUM_LAYER,
-    >(
-        driver,
-        input_pins,
-        output_pins,
-        keymap,
-        &VIAL_KEYBOARD_ID,
-        &VIAL_KEYBOARD_DEF,
-    )
+    >(driver, input_pins, output_pins, keymap, keyboard_config)
     .await;
 }

boards/rp2040/src/vial.rs

@@ -1,23 +1,29 @@
-pub const VIAL_KEYBOARD_ID: [u8; 8] = [0xB9, 0xBC, 0x09, 0xB2, 0x9D, 0x37, 0x4C, 0xEA];
-pub const VIAL_KEYBOARD_DEF: [u8; 308] = [
-    0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00, 0x00, 0x04, 0xE6, 0xD6, 0xB4, 0x46, 0x02, 0x00, 0x21, 0x01,
-    0x16, 0x00, 0x00, 0x00, 0x74, 0x2F, 0xE5, 0xA3, 0xE0, 0x01, 0x58, 0x00, 0xF1, 0x5D, 0x00, 0x3D,
-    0x88, 0x89, 0xC6, 0x54, 0x36, 0xC3, 0x17, 0x4F, 0xE4, 0xE2, 0x11, 0x2F, 0x22, 0xB0, 0xBC, 0xC8,
-    0x21, 0x18, 0x12, 0x8B, 0x06, 0x39, 0x42, 0xED, 0x2D, 0x7A, 0x5C, 0xC0, 0x20, 0x95, 0xFA, 0x59,
-    0xBD, 0x04, 0x61, 0xF7, 0xDE, 0x2F, 0xD2, 0xFB, 0x8E, 0xAD, 0x8E, 0xE5, 0x16, 0x4E, 0xEA, 0x09,
-    0xC7, 0x59, 0xDC, 0x04, 0x50, 0xB5, 0x7A, 0x56, 0x03, 0xA4, 0x7C, 0xE2, 0xFE, 0x87, 0x69, 0xA2,
-    0xA1, 0xF1, 0xFC, 0xBB, 0xF8, 0x7D, 0xD8, 0x5F, 0x6A, 0x39, 0xB4, 0xC9, 0x00, 0xE8, 0x52, 0xD3,
-    0xEE, 0x5C, 0x59, 0x88, 0x1E, 0x19, 0x66, 0x17, 0x5D, 0xF6, 0xD2, 0x28, 0x0B, 0xC9, 0xB8, 0x38,
-    0x43, 0x9A, 0x38, 0x26, 0x8C, 0x45, 0xB1, 0x9C, 0xE5, 0x1B, 0x50, 0xF5, 0x71, 0x7F, 0x3A, 0xB4,
-    0xE9, 0xB5, 0x2F, 0xA9, 0xEA, 0xE3, 0xC8, 0xAC, 0x3F, 0x77, 0x37, 0x28, 0xA3, 0x4E, 0xC7, 0x14,
-    0xE4, 0xCF, 0x31, 0xCB, 0x33, 0x11, 0x3F, 0x27, 0x9D, 0xFB, 0x5C, 0x61, 0x96, 0xFE, 0x27, 0x7B,
-    0x04, 0x13, 0x1F, 0xEC, 0xD6, 0x57, 0xD2, 0x32, 0xB8, 0x00, 0x4E, 0x21, 0x32, 0x79, 0xA9, 0x09,
-    0x45, 0xCD, 0x11, 0x6F, 0xF9, 0x37, 0xFB, 0x57, 0xF7, 0x28, 0xC3, 0xAF, 0x00, 0x0F, 0xF3, 0xB2,
-    0x1F, 0xC3, 0x7C, 0x84, 0xA0, 0xF0, 0x09, 0xEE, 0x49, 0x99, 0x39, 0xC2, 0x69, 0x4A, 0xFE, 0x38,
-    0xFE, 0xE7, 0x80, 0xCA, 0x37, 0x46, 0x7B, 0xC9, 0xF4, 0x39, 0x7B, 0x30, 0x0E, 0x22, 0xA6, 0xD3,
-    0x18, 0x1B, 0xA7, 0x70, 0xB9, 0x14, 0x91, 0x13, 0xC2, 0x5F, 0x02, 0xD1, 0x1A, 0x62, 0x6B, 0xC6,
-    0xFC, 0xD3, 0x18, 0xC0, 0x62, 0xA5, 0xEA, 0xD0, 0xDF, 0x18, 0xDD, 0xD3, 0x53, 0x63, 0x11, 0x08,
-    0x00, 0x00, 0x00, 0x00, 0xF5, 0x5B, 0x73, 0xB4, 0xF2, 0x19, 0x3D, 0xF2, 0x00, 0x01, 0x8D, 0x02,
-    0xD9, 0x02, 0x00, 0x00, 0xC6, 0xA2, 0x63, 0x43, 0xB1, 0xC4, 0x67, 0xFB, 0x02, 0x00, 0x00, 0x00,
-    0x00, 0x04, 0x59, 0x5A,
-];
+// Use `build.rs` automatically generate vial config, according to `vial.json`
+// Please put `vial.json` at your project's root
+include!(concat!(env!("OUT_DIR"), "/config_generated.rs"));
+
+// Or you can manually generate vial config then put here
+// pub const VIAL_KEYBOARD_ID: [u8; 8] = [0xB9, 0xBC, 0x09, 0xB2, 0x9D, 0x37, 0x4C, 0xEA];
+// pub const VIAL_KEYBOARD_DEF: [u8; 308] = [
+//     0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00, 0x00, 0x04, 0xE6, 0xD6, 0xB4, 0x46, 0x02, 0x00, 0x21, 0x01,
+//     0x16, 0x00, 0x00, 0x00, 0x74, 0x2F, 0xE5, 0xA3, 0xE0, 0x01, 0x58, 0x00, 0xF1, 0x5D, 0x00, 0x3D,
+//     0x88, 0x89, 0xC6, 0x54, 0x36, 0xC3, 0x17, 0x4F, 0xE4, 0xE2, 0x11, 0x2F, 0x22, 0xB0, 0xBC, 0xC8,
+//     0x21, 0x18, 0x12, 0x8B, 0x06, 0x39, 0x42, 0xED, 0x2D, 0x7A, 0x5C, 0xC0, 0x20, 0x95, 0xFA, 0x59,
+//     0xBD, 0x04, 0x61, 0xF7, 0xDE, 0x2F, 0xD2, 0xFB, 0x8E, 0xAD, 0x8E, 0xE5, 0x16, 0x4E, 0xEA, 0x09,
+//     0xC7, 0x59, 0xDC, 0x04, 0x50, 0xB5, 0x7A, 0x56, 0x03, 0xA4, 0x7C, 0xE2, 0xFE, 0x87, 0x69, 0xA2,
+//     0xA1, 0xF1, 0xFC, 0xBB, 0xF8, 0x7D, 0xD8, 0x5F, 0x6A, 0x39, 0xB4, 0xC9, 0x00, 0xE8, 0x52, 0xD3,
+//     0xEE, 0x5C, 0x59, 0x88, 0x1E, 0x19, 0x66, 0x17, 0x5D, 0xF6, 0xD2, 0x28, 0x0B, 0xC9, 0xB8, 0x38,
+//     0x43, 0x9A, 0x38, 0x26, 0x8C, 0x45, 0xB1, 0x9C, 0xE5, 0x1B, 0x50, 0xF5, 0x71, 0x7F, 0x3A, 0xB4,
+//     0xE9, 0xB5, 0x2F, 0xA9, 0xEA, 0xE3, 0xC8, 0xAC, 0x3F, 0x77, 0x37, 0x28, 0xA3, 0x4E, 0xC7, 0x14,
+//     0xE4, 0xCF, 0x31, 0xCB, 0x33, 0x11, 0x3F, 0x27, 0x9D, 0xFB, 0x5C, 0x61, 0x96, 0xFE, 0x27, 0x7B,
+//     0x04, 0x13, 0x1F, 0xEC, 0xD6, 0x57, 0xD2, 0x32, 0xB8, 0x00, 0x4E, 0x21, 0x32, 0x79, 0xA9, 0x09,
+//     0x45, 0xCD, 0x11, 0x6F, 0xF9, 0x37, 0xFB, 0x57, 0xF7, 0x28, 0xC3, 0xAF, 0x00, 0x0F, 0xF3, 0xB2,
+//     0x1F, 0xC3, 0x7C, 0x84, 0xA0, 0xF0, 0x09, 0xEE, 0x49, 0x99, 0x39, 0xC2, 0x69, 0x4A, 0xFE, 0x38,
+//     0xFE, 0xE7, 0x80, 0xCA, 0x37, 0x46, 0x7B, 0xC9, 0xF4, 0x39, 0x7B, 0x30, 0x0E, 0x22, 0xA6, 0xD3,
+//     0x18, 0x1B, 0xA7, 0x70, 0xB9, 0x14, 0x91, 0x13, 0xC2, 0x5F, 0x02, 0xD1, 0x1A, 0x62, 0x6B, 0xC6,
+//     0xFC, 0xD3, 0x18, 0xC0, 0x62, 0xA5, 0xEA, 0xD0, 0xDF, 0x18, 0xDD, 0xD3, 0x53, 0x63, 0x11, 0x08,
+//     0x00, 0x00, 0x00, 0x00, 0xF5, 0x5B, 0x73, 0xB4, 0xF2, 0x19, 0x3D, 0xF2, 0x00, 0x01, 0x8D, 0x02,
+//     0xD9, 0x02, 0x00, 0x00, 0xC6, 0xA2, 0x63, 0x43, 0xB1, 0xC4, 0x67, 0xFB, 0x02, 0x00, 0x00, 0x00,
+//     0x00, 0x04, 0x59, 0x5A,
+// ];
+

boards/stm32h7/src/main.rs

@@ -24,7 +24,7 @@ use embassy_stm32::{
 };
 use panic_probe as _;
 use rmk::{
-    config::{KeyboardAdvancedConfig, KeyboardUsbConfig},
+    config::{RmkConfig, KeyboardUsbConfig, VialConfig},
     initialize_keyboard_with_config_and_run,
     keymap::KeyMap,
 };
@@ -111,8 +111,11 @@ async fn main(_spawner: Spawner) {
         Some("00000001"),
     );
 
-    let keyboard_config = KeyboardAdvancedConfig {
+    let vial_config = VialConfig::new(VIAL_KEYBOARD_ID, VIAL_KEYBOARD_DEF);
+
+    let keyboard_config = RmkConfig {
         usb_config: keyboard_usb_config,
+        vial_config,
         ..Default::default()
     };
 
@@ -126,14 +129,6 @@ async fn main(_spawner: Spawner) {
         ROW,
         COL,
         NUM_LAYER,
-    >(
-        driver,
-        input_pins,
-        output_pins,
-        keymap,
-        keyboard_config,
-        VIAL_KEYBOARD_ID,
-        VIAL_KEYBOARD_DEF,
-    )
+    >(driver, input_pins, output_pins, keymap, keyboard_config)
     .await;
 }

rmk/src/config.rs

@@ -1,30 +1,50 @@
-// TODO: more configs need to be added, easy configuration
-/// Advanced configurations for keyboard.
+// TODO: more configs need to be added, easy configuration(from config file)
+/// Configurations for RMK keyboard.
 #[derive(Debug, Default)]
-pub struct KeyboardAdvancedConfig<'a> {
+pub struct RmkConfig<'a> {
     pub mouse_config: MouseConfig,
     pub usb_config: KeyboardUsbConfig<'a>,
+    pub vial_config: VialConfig<'a>,
+}
+
+/// Config for [vial](https://get.vial.today/).
+///
+/// You can generate automatically using [`build.rs`](https://github.com/HaoboGu/rmk/blob/main/boards/stm32h7/build.rs).
+#[derive(Debug, Default)]
+pub struct VialConfig<'a> {
+    pub vial_keyboard_id: &'a [u8],
+    pub vial_keyboard_def: &'a [u8],
+}
+
+impl<'a> VialConfig<'a> {
+    pub fn new(vial_keyboard_id: &'a [u8], vial_keyboard_def: &'a [u8]) -> Self {
+        Self {
+            vial_keyboard_id,
+            vial_keyboard_def,
+        }
+    }
 }
 
 /// Configuration for debouncing
 pub struct DebounceConfig {
-    pub debounce_time: u32
+    /// Debounce time in ms
+    pub debounce_time: u32,
 }
 
 /// Configurations for mouse functionalities
 #[derive(Debug)]
 pub struct MouseConfig {
+    /// Time interval in ms of reporting mouse cursor states
     pub mouse_key_interval: u32,
+    /// Time interval in ms of reporting mouse wheel states
     pub mouse_wheel_interval: u32,
-    pub mouse_time_to_max: u32,
 }
 
 impl Default for MouseConfig {
     fn default() -> Self {
         Self {
             mouse_key_interval: 20,
             mouse_wheel_interval: 80,
-            mouse_time_to_max: 80,
         }
     }
 }
@@ -41,10 +61,15 @@ pub struct RGBLightConfig {
 /// Configurations for usb
 #[derive(Debug)]
 pub struct KeyboardUsbConfig<'a> {
+    /// Vender id
     pub vid: u16,
+    /// Product id
     pub pid: u16,
+    /// Manufacturer
     pub manufacturer: Option<&'a str>,
+    /// Product name
     pub product_name: Option<&'a str>,
+    /// Serial number
     pub serial_number: Option<&'a str>,
 }
 

rmk/src/keycode.rs

@@ -3,9 +3,11 @@ use num_enum::FromPrimitive;
 use packed_struct::prelude::*;
 use usbd_hid::descriptor::{MediaKey, SystemControlKey};
 
-/// To represent all combinations of modifiers, at least 5 bits are needed:
+/// To represent all combinations of modifiers, at least 5 bits are needed.
 /// 1 bit for Left/Right, 4 bits for modifier type.
-/// |  x  |  x  |  x  |  x  |  x  |
+///
+/// | bit0 | bit1 | bit2 | bit3 | bit4 |
+/// | --- | --- | --- | --- | --- |  
 /// | L/R | GUI | ALT |SHIFT| CTRL|
 #[derive(PackedStruct, Clone, Copy, Debug, Format, Default, Eq, PartialEq)]
 #[packed_struct(bit_numbering = "lsb0", size_bytes = "1")]