Merge pull request #4 from FrameworkComputer/first-alpha

README.md

@@ -5,12 +5,17 @@ Commandline (and soon library) to interact with QMK devices via their raw HID in
 Currently focusing on the VIA API.
 It will soon be superceded by QMK XAP, but that isn't ready yet.
 
-I've only tested on Linux so far, but should also work on Windows, FreeBSD and macOS.
+Tested to work on Windows and Linux, without any drivers or admin privileges.
 
 ## Building
 
 Pre-requisites: Rust, libudev
 
+```sh
+cargo build
+ls -l target/debug/qmk_hid
+```
+
 ## Running
 
 The examples call the binary with the name `qmk_hid`. On Windows use
@@ -35,6 +40,7 @@ Options:
       --vid <VID>  VID (Vendor ID) in hex digits
       --pid <PID>  PID (Product ID) in hex digits
   -h, --help       Print help information
+  -V, --version    Print version information
 
 > qmk_hid via
 Via
@@ -143,6 +149,9 @@ The command only does something when the firmware has `VIA_EEPROM_ALLOW_RESET` d
 ###### Factory testing the LEDs
 
 ```sh
+# Use "device indication" to flash backlight 3 times
+qmk_hid via --device-indication
+
 # Turn RGB off
 qmk_hid via --rgb-effect 0
 
@@ -166,7 +175,11 @@ qmk_hid via --rgb-hue 200
 
 
 # Enable a mode that reacts to keypresses
-qmk_hid via --rgb-effect 16
+# Note that the effect numbers can be different per keyboard
+# On Lotus we currently enable all, then 38 is `SOLID_REACTIVE_MULTICROSS`
+qmk_hid via --rgb-effect 38
+
+# Factory commands are not guaranteed to work
 # And simulate keypresses ASDF (see QMK's keycodes.h)
 qmk_hid factory --keycode 4
 qmk_hid factory --keycode 22

src/factory.rs

@@ -3,6 +3,7 @@ use hidapi::HidDevice;
 use crate::raw_hid::send_message;
 use crate::via::ViaCommandId;
 
+/// Send a factory command, currently only supported in Lotus
 pub fn send_factory_command(dev: &HidDevice, command: u8, value: u8) -> Result<(), ()> {
     let msg = vec![command, value];
     let _ = send_message(dev, ViaCommandId::BootloaderJump as u8, Some(&msg), 0)?;

src/keycodes.rs

@@ -1,3 +1,5 @@
+//! QMK basic keycode definitions. Based on quantum/keycodes.h
+
 #![allow(dead_code, unused)]
 pub const KC_NO: u8 = 0x0000;
 pub const KC_TRANSPARENT: u8 = 0x0001;

src/main.rs

@@ -108,7 +108,7 @@ struct ViaSubcommand {
 
 /// RAW HID and VIA commandline for QMK devices
 #[derive(Parser, Debug)]
-#[command(arg_required_else_help = true)]
+#[command(version, arg_required_else_help = true)]
 struct ClapCli {
     #[command(subcommand)]
     command: Option<Commands>,

src/raw_hid.rs

@@ -1,6 +1,11 @@
+//! Interact with the raw HID interface of QMK firmware
+
 use hidapi::HidDevice;
 
-pub const RAW_HID_BUFFER_SIZE: usize = 32; // ChibiOS won't respond with 32. Currently hardcoded to ignore. But in upstream have to send 33 bytes.
+// ChibiOS won't respond if we send 32.
+// Currently I hardcoded it to ignore. But in upstream QMK/ChibiOS we have to send 33 bytes.
+// See raw_hid_send in tmk_core/protocol/chibios/usb_main.c
+pub const RAW_HID_BUFFER_SIZE: usize = 32;
 
 pub const RAW_USAGE_PAGE: u16 = 0xFF60;
 pub const CONSOLE_USAGE_PAGE: u16 = 0xFF31;
@@ -37,7 +42,7 @@ pub fn send_message(
         }
     };
 
-    // Not response expected
+    // No response expected
     if out_len == 0 {
         return Ok(vec![]);
     }

src/via.rs

@@ -1,3 +1,5 @@
+//! Implementing the VIA protocol supported by QMK keyboard firmware
+
 use hidapi::HidDevice;
 
 use crate::raw_hid::*;