https://github.com/visiuun/vmacropad
Alternative open-source driver for generic 3-Key 1-Knob macropads (VID 0x1189). Features per-app profile auto-switching, system tray support, and a modern dark UI.
https://github.com/visiuun/vmacropad
ch55x ch57x custom-keyboard customtkinter hid macro-keyboard macropad open-source-driver python vid-1189
Last synced: 7 days ago
JSON representation
Alternative open-source driver for generic 3-Key 1-Knob macropads (VID 0x1189). Features per-app profile auto-switching, system tray support, and a modern dark UI.
- Host: GitHub
- URL: https://github.com/visiuun/vmacropad
- Owner: visiuun
- License: mit
- Created: 2026-01-22T12:58:06.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-02-04T13:56:09.000Z (8 days ago)
- Last Synced: 2026-02-05T00:43:24.728Z (8 days ago)
- Topics: ch55x, ch57x, custom-keyboard, customtkinter, hid, macro-keyboard, macropad, open-source-driver, python, vid-1189
- Language: Python
- Homepage:
- Size: 212 KB
- Stars: 12
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# VMacropad
An open-source, modern replacement driver for generic 3-Key / 1-Knob Macropads.
## Why this exists
I bought a cheap "3-key 1-knob" macropad from AliExpress. The hardware is great. The provided software was terrible. It looked like a Windows 98 app, flagged my antivirus, and could not switch profiles automatically based on the active window.
I reverse-engineered the HID protocol and built **VMacropad** to fix these issues. It is written in Python, fully transparent, and includes the features these devices should have had out of the box.
## Supported Hardware
This software is designed for generic macropads using the **CH57x/CH55x** chips.
**Default Hardware IDs:**
* **Vendor ID:** `0x1189`
* **Product ID:** `0x8890`
**Replaces software for:**
* SayoDevice / SimPad (Generic Clones)
* "RSoft" MacroPad
* Generic "3-Key Mini Keyboard" listings on Amazon/AliExpress
* Devices that identify as "Keypad" or "USB Input Device" with the IDs above
*Note: If your device uses different IDs, you can change them directly in the app Settings menu.*
## Features
* **Auto-Profile Switching:** Automatically changes key mappings based on which app you are using. Use Photoshop shortcuts when Photoshop is open, then switch to Media keys when Spotify is focused.
* **App Audio Control:** Bind keys to change the volume of *specific* applications (e.g., lower Discord volume without lowering the game volume). Includes "Fuzzy Matching" so `tidal` finds `TIDALPlayer.exe`.
* **Automatic Updates:** Checks GitHub on startup and notifies you when a new version is available, ensuring you always have the latest features and bug fixes.
* **Smart Fallback:** If the specific app you are trying to control isn't open, the knob automatically falls back to controlling the Master Volume.
* **Modern UI:** Clean, Dark Mode interface using CustomTkinter.
* **System Tray Integration:** Minimizes silently to the background with very low resource usage (~0% CPU).
* **Visual Config:** Interactive visualizer to see exactly what you are programming.
* **Instant Save:** No "Apply" button required. Changes upload to the device memory instantly.
* **Portable:** Single `.exe` file. No installation required.
## Installation
### For Users (Recommended)
1. Go to the [**Releases**](https://github.com/visiuun/VMacropad/releases) page on the right.
2. Download `VMacropad.exe`.
3. Run it.
### For Developers (Running from Source)
If you want to inspect the code or run it via Python:
```bash
# Clone the repository
git clone https://github.com/visiuun/VMacropad.git
# Install dependencies (Updated for v1.0.4)
pip install customtkinter hidapi pywin32 psutil pystray pillow keyboard pycaw comtypes requests
# Run the app
python vmacropad.py
```
## How to use Auto-Switching
1. Create a new preset (e.g. "Photoshop").
2. Click the **"Link to App"** button.
3. You have 3 seconds to click on your target application window.
4. Done. Whenever that app is in focus, the macropad will switch to that preset automatically.
## How to use App Audio Control
1. Select a key or knob direction.
2. Go to the **"App Audio"** tab.
3. Click **"Grab Active App"** and click on the window you want to control (e.g., Spotify), OR manually type the process name (e.g., `spotify`).
4. Select the action (Volume Up, Down, or Mute).
5. Now that key will only change Spotify's volume. If Spotify is closed, it will change the system volume instead.
## Building the EXE
If you want to compile it yourself, use the following PyInstaller command. This ensures the icon, theme files, and new audio libraries are bundled correctly.
```powershell
pyinstaller --noconsole --onefile --icon="vmacropad.ico" --add-data "vmacropad.ico;." --collect-all customtkinter vmacropad.py
```
## Credits
Created by [Visiuun](https://github.com/visiuun).
Licensed under the MIT License.