{"id":21380797,"url":"https://github.com/frameworkcomputer/qmk_hid","last_synced_at":"2025-10-08T11:36:19.820Z","repository":{"id":177217005,"uuid":"586889141","full_name":"FrameworkComputer/qmk_hid","owner":"FrameworkComputer","description":"Commandline tool for interacting with QMK devices over HID","archived":false,"fork":false,"pushed_at":"2025-07-09T15:41:04.000Z","size":4293,"stargazers_count":71,"open_issues_count":4,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-09T15:45:56.846Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FrameworkComputer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-09T13:24:03.000Z","updated_at":"2025-06-18T09:56:39.000Z","dependencies_parsed_at":"2023-10-25T08:30:13.153Z","dependency_job_id":"288fb23e-5f0a-4fcb-adf6-a734f2f03c67","html_url":"https://github.com/FrameworkComputer/qmk_hid","commit_stats":null,"previous_names":["frameworkcomputer/qmk_hid"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/FrameworkComputer/qmk_hid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameworkComputer%2Fqmk_hid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameworkComputer%2Fqmk_hid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameworkComputer%2Fqmk_hid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameworkComputer%2Fqmk_hid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FrameworkComputer","download_url":"https://codeload.github.com/FrameworkComputer/qmk_hid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameworkComputer%2Fqmk_hid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266161906,"owners_count":23885928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T10:42:48.340Z","updated_at":"2025-10-08T11:36:14.782Z","avatar_url":"https://github.com/FrameworkComputer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QMK HID\n\nCommandline tool to interact with QMK devices via their raw HID interface.\n\nCurrently focusing on the VIA API.\nIt will soon be superceded by QMK XAP, but that isn't ready yet.\n\nTested to work on Windows and Linux, without any drivers or admin privileges.\n\n### GUI\n\nThere is also an easy to use GUI tool that does not require commandline interaction.\n\nSee [GUI README](python/README.md)\n\n![](screenshots/qmk_gui_screenshot.png)\n\n### Supported devices\n\nThe tool is generic and works for any device using [QMK Firmware](https://qmk.fm/).\n\nBut it was built for, and some functionality only works with,\n[Framework 16 keyboard modules](https://frame.work/tw/en/products/laptop16-diy-amd-7040?tab=modules).\nThis includes all keyboard variants, the numpad and macropad.\n\n## Running\n\nDownload the latest binary from the [releases page](https://github.com/FrameworkComputer/qmk_hid/releases).\n\nThe examples call the binary with the name `qmk_hid`, as used on Linux.\nIf you're on Windows, use `qmk_hid.exe`, and when building from source,\nuse `cargo run --`.\n\n###### Show the help\n\n```sh\n\u003e qmk_hid\nRAW HID and VIA commandline for QMK devices\n\nUsage: qmk_hid [OPTIONS] [COMMAND]\n\nCommands:\n  via      Via\n  qmk      QMK\n  help     Print this message or the help of the given subcommand(s)\n\nOptions:\n  -l, --list       List connected HID devices\n  -v, --verbose    Verbose outputs to the console\n      --vid \u003cVID\u003e  VID (Vendor ID) in hex digits\n      --pid \u003cPID\u003e  PID (Product ID) in hex digits\n  -h, --help       Print help information\n  -V, --version    Print version information\n\n\u003e qmk_hid via\nVia\n\nUsage: qmk_hid via [OPTIONS]\n\nOptions:\n      --info\n          Get VIA protocol and config information (most likely NOT what you're looking for)\n      --device-indication\n          Flash device indication (backlight) 3x\n      --rgb-brightness [\u003cRGB_BRIGHTNESS\u003e]\n          Set RGB brightness percentage or get, if no value provided\n      --rgb-effect [\u003cRGB_EFFECT\u003e]\n          Set RGB effect or get, if no value provided\n      --rgb-effect-speed [\u003cRGB_EFFECT_SPEED\u003e]\n          Set RGB effect speed or get, if no value provided (0-255)\n      --rgb-hue [\u003cRGB_HUE\u003e]\n          Set RGB hue or get, if no value provided. (0-255)\n      --rgb-color \u003cRGB_COLOR\u003e\n          Set RGB color [possible values: red, yellow, green, cyan, blue, purple, white]\n      --rgb-saturation [\u003cRGB_SATURATION\u003e]\n          Set RGB saturation or get, if no value provided. (0-255)\n      --backlight [\u003cBACKLIGHT\u003e]\n          Set backlight brightness percentage or get, if no value provided\n      --backlight-breathing [\u003cBACKLIGHT_BREATHING\u003e]\n          Set backlight breathing or get, if no value provided [possible values: true, false]\n      --save\n          Save RGB/backlight value, otherwise it won't persist through keyboard reboot. Can be used by itself or together with other argument\n      --eeprom-reset\n          Reset the EEPROM contents (Not supported by all firmware)\n      --bootloader\n          Jump to the bootloader (Not supported by all firmware)\n  -h, --help\n          Print help information\n\n\u003e qmk_hid qmk\nQMK\n\nUsage: qmk_hid qmk [OPTIONS]\n\nOptions:\n  -c, --console  Listen to the console. Better to use `qmk console` (https://github.com/qmk/qmk_cli)\n  -h, --help     Print help information\n```\n\n###### List available devices\n```sh\n\u003e qmk_hid -l\n32ac:0014\n  Manufacturer: \"Framework Computer Inc\"\n  Product:      \"Framework 16 Numpad\"\n  FW Version:   0.1.3\n  Serial No:    \"FRALDLENA100000000\"\n```\n\n###### Control that device\n\n```sh\n# If there is only one device, no filter needed\n\u003e qmk_hid via --backlight\nBrightness: 0%\n\n# If there are multiple devices, need to filter by either VID, PID or both\n\u003e qmk_hid via --backlight\nMore than 1 device found. Select a specific device with --vid and --pid\n\u003e qmk_hid --vid 3434 via --backlight\nBrightness: 0%\n\n# Get current RGB brightness\n\u003e qmk_hid via --rgb-brightness 50\nBrightness: 50%\n\n# Set new RGB brightness\n\u003e qmk_hid via --rgb-brightness 100\nBrightness: 100%\n```\n\n**NOTE:** By default the settings are not saved. To make them persistent add\nthe `--save` argument. Or run `qmk_hid via --save` by itself. Examples:\n\n```\n# Save directly\n\u003e qmk_hid via --rgb-brightness 100 --save\n\n# Make a couple changes and save everything\n\u003e qmk_hid via --rgb-effect 1\n\u003e qmk_hid via --rgb-color red\n\u003e qmk_hid via --rgb-brightness 100\n\u003e qmk_hid via --save\n```\n\n###### Jumping to the bootloader, to reflash.\n\nNote: This will only work when the QMK firmware has this command enabled. This\nis not the default upstream behavior.\n\n```sh\n\u003e qmk_hid via --bootloader\n```\n\n###### Reset EEPROM contents / Clear VIA config\n\nVIA stores its config in EEPROM (sometimes emulated in flash).\nWhen using a different keyboard with the same controller board you'll want to\nclear it, otherwise the previously stored VIA config overrides the hardcoded\none.\n\nThis becomes obvious when trying to change the hardcoded keymap but the\nbehavior does not change.\n\nThe command only does something when the firmware has `VIA_EEPROM_ALLOW_RESET` defined.\n\n```sh\n\u003e qmk_hid via --eeprom-config\n```\n\n###### Testing the RGB LEDs\n\n```sh\n# Use \"device indication\" to flash backlight 3 times\nqmk_hid via --device-indication\n\n# Turn RGB off\nqmk_hid via --rgb-effect 0\n\n# Turn all LEDs on\nqmk_hid via --rgb-effect 1\n\n# Change color\nqmk_hid via --rgb-color red\nqmk_hid via --rgb-color yellow\nqmk_hid via --rgb-color green\nqmk_hid via --rgb-color cyan\nqmk_hid via --rgb-color blue\nqmk_hid via --rgb-color purple\nqmk_hid via --rgb-color white\n\n# Enable a mode that reacts to keypresses\n# Note that the effect numbers can be different per keyboard\n# On Framework 16 we currently enable all, then 38 is `SOLID_REACTIVE_MULTICROSS`\nqmk_hid via --rgb-effect 38\n```\n\n## Building from source\n\nPre-requisites:\n\n- [Rust](https://rustup.rs/)\n- libudev (`libudev-dev` on Ubuntu, `systemd-devel` on Fedora)\n\n```sh\n# Directly run\ncargo run\n\n# Build and run executable (on Linux)\ncargo build\n./target/debug/qmk_hid\n```\n\n## Running on Linux\n\nTo avoid needing root privileges to access the keyboard please follow the\nofficial [QMK guide](https://docs.qmk.fm/#/faq_build?id=linux-udev-rules) for\nhow to install udev rules. After doing that, you'll be able to interact with\nthe keyboards as a regular user.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframeworkcomputer%2Fqmk_hid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fframeworkcomputer%2Fqmk_hid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframeworkcomputer%2Fqmk_hid/lists"}