Complete, native control software for the Cooler Master ControlPad (VID 0x2516 / PID 0x007B, Cherry MX switch variant) on macOS.
The official Cooler Master software (MasterPlus+) is strictly Windows-only, resource-intensive, and prone to crashes. This project liberates the hardware on Mac, providing an ultra-responsive native SwiftUI (Liquid Glass) user interface backed by a reverse-engineered low-level USB HID communication engine.
- ⚡ Native & Fluid macOS Experience: Built with modern SwiftUI and Apple's Liquid Glass design system, full dark/light mode support, runtime multi-language switching (English & Italian), and zero heavy runtime dependencies.
- 🎯 Multi-Disciplinary Professional Versatility:
- Video & Audio Post-Production: Precise frame-by-frame scrubbing and timeline navigation using the dual precision dials for DaVinci Resolve, Final Cut Pro, Logic Pro, and Premiere.
- 3D Modeling & Graphic Design: Rapid shortcut triggering and custom macros for Blender, Photoshop, Illustrator, and CAD.
- Software Engineering & Terminal Power Users: One-touch Git commands, terminal navigation, snippet insertion, and window tiling shortcuts.
- macOS Gaming: Custom input mapping with ultra-low latency response.
- 💾 Firmware Flash Persistence (On-Board Memory):
- Macros, 24-key remappings, special functions, and profile selections are written directly to the device's hardware flash memory. Once configured, they work autonomously on any computer without background software.
- 🌈 Complete RGB Lighting Control:
- 14 lighting effect modes (Static, Rainbow Wave, Crosshair, Reactive Fade, Custom Per-Key, Stars, Snow, Color Cycle, Blink, Reactive Punch, Circular Spectrum, Reactive Tornado, Water Ripple, Off).
- Custom per-key RGB coloring and reaction tint customization.
- 💡 4 Profile Indicator LEDs Animation Engine:
- Full addressability and frame-by-frame live animation engine for the top 4 status LEDs (the last written state persists even across USB disconnects).
- 🛡️ Robust & Resilient Architecture:
- Over 130 automated unit tests across the Python engine and Swift GUI.
- Automatic draft state preservation (
draft.json) with.baksafety fallbacks to prevent configuration loss.
| Directory | Description |
|---|---|
ControlPadEngine/ |
The Engine: Low-level USB HID driver, hardware session manager, macro and lighting effect encoders, JSON IPC bridge subprocess. |
ControlPadGUI/ |
macOS App: Native SwiftUI interface (Liquid Glass) with Lighting, Key Mapping, Macros, Profiles, and Settings tabs. |
ControlPAD - CATTURA/ |
Reverse Engineering: Raw Wireshark .pcapng USB packet captures and comprehensive protocol specifications in PROTOCOL.md. |
Come_usare_manipolare_i_4_led/ |
LED Manipulation: Primitive animation algorithms, time/space transforms, and persistence tests for the 4 top LEDs. |
- macOS 14+ (with optimal support for macOS 26 Liquid Glass SDK).
- Python 3.11+ with the
hidapipackage.
# 1. Clone the repository
git clone https://github.com/NsPowEr/ControlPAD-Controller.git
cd ControlPAD-Controller
# 2. Install the single Python dependency
pip3 install hidapi
# 3. Verify engine tests (runs offline without hardware connected)
python3 -m unittest discover ControlPadEngine/tests
# 4. Launch the SwiftUI application in development mode
cd ControlPadGUI
swift runTo build and package a standalone macOS .app bundle into ~/Applications:
cd ControlPadGUI
./scripts/make_app_bundle.shBefore extending communication logic, review the reverse engineering specifications:
- 📖
ControlPAD - CATTURA/PROTOCOL.md— Byte-by-byte breakdown of USB HID packets (0x04OUT /0x83IN endpoints,56 83color headers, column-major matrix indexing, macro micro-event structure). ⚠️ ControlPAD - CATTURA/README.md— Hardware quirks uncovered during capture analysis (the 3 distinct numbering schemes for the 24 keys, flash write delays, ACK queue draining rules).
Contributions from the community are warmly welcomed! Please check CONTRIBUTING.md for development guidelines and CHANGES.md for version history.
This project is licensed under the MIT License.
All product and brand names (Cooler Master, ControlPad, MasterPlus+, Aimpad, Cherry MX) are trademarks of their respective owners.