From 8a18015c344fd341d80f3345fe3361d1ef7bd7f0 Mon Sep 17 00:00:00 2001 From: Mohamed Mahjoub <75433420+Probler-Yt@users.noreply.github.com> Date: Tue, 22 Sep 2026 17:16:17 +0100 Subject: [PATCH] Themes, actions, text snippets and a key picker --- README.md | 119 ++- docs/images/action.png | Bin 0 -> 320164 bytes docs/images/edit-layout.png | Bin 283792 -> 282504 bytes docs/images/first-launch.png | Bin 256556 -> 255604 bytes docs/images/flat-view.png | Bin 250089 -> 244351 bytes docs/images/hero.png | Bin 250422 -> 253547 bytes docs/images/keyd-note.png | Bin 278064 -> 276891 bytes docs/images/permission.png | Bin 315773 -> 319552 bytes docs/images/read-pad.png | Bin 287353 -> 289740 bytes docs/images/step-media.png | Bin 280654 -> 283599 bytes docs/images/step-nothing.png | Bin 252844 -> 255699 bytes docs/images/step-pending.png | Bin 250368 -> 253383 bytes docs/images/step-record.png | Bin 281796 -> 284054 bytes docs/images/step-type.png | Bin 276939 -> 279574 bytes docs/images/step-written.png | Bin 245037 -> 247154 bytes docs/images/theme-blueprint.png | Bin 0 -> 285182 bytes docs/images/theme-sketch.png | Bin 0 -> 466366 bytes docs/images/themes.png | Bin 0 -> 876123 bytes docs/images/unsupported.png | Bin 369953 -> 367427 bytes docs/make_screenshots.py | 90 +++ install.sh | 21 +- macropad.py | 12 +- macropad_gui/__main__.py | 11 +- macropad_gui/actions.py | 705 ++++++++++++++++++ macropad_gui/app.py | 646 ++++++++++++++-- macropad_gui/core.py | 32 +- .../fonts/ArchitectsDaughter-Regular.ttf | Bin 0 -> 43352 bytes macropad_gui/fonts/OFL.txt | 93 +++ macropad_gui/keymap.py | 2 + macropad_gui/padview.py | 303 ++++++-- macropad_gui/themes.py | 120 +++ packaging/60-macropad.rules | 2 +- tests/test_actions.py | 347 +++++++++ tests/test_core.py | 100 ++- uninstall.sh | 9 + 35 files changed, 2470 insertions(+), 142 deletions(-) create mode 100644 docs/images/action.png create mode 100644 docs/images/theme-blueprint.png create mode 100644 docs/images/theme-sketch.png create mode 100644 docs/images/themes.png create mode 100644 macropad_gui/actions.py create mode 100644 macropad_gui/fonts/ArchitectsDaughter-Regular.ttf create mode 100644 macropad_gui/fonts/OFL.txt create mode 100644 macropad_gui/themes.py create mode 100644 tests/test_actions.py diff --git a/README.md b/README.md index d6b2627..3eca4e0 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,8 @@ The part that matters is **`1189:8840`**. Ignore "Acer": these pads borrow that | π **Reads your pad** | Opens and asks the pad what it's actually holding, so you start from the truth. | | π **Identifies unknown pads** | Asks an unrecognised pad about itself, read only, and refuses to write if it doesn't answer properly. | | π **Layout editor** | Drag the keys around until the drawing matches your pad. | +| π¨ **Themes** | Seven, including an engineering blueprint and a pencil sketch. | +| π **Actions** | Make a key open a web page, launch an app, type a phrase or run a command. Optional. | | π§ **Remembers what it wrote** | Keeps its own notes too, and marks anything it isn't sure about rather than guessing. | | π©Ί **Tells you what's wrong** | Unplugged? No permission? Wrong pad? You get a plain explanation and the exact fix, with a copy button. | | π₯ **Imports from the vendor app** | Set your pad up on Windows before? Bring that setup across. | @@ -129,6 +131,7 @@ Both write straight to the pad's own memory, so you can even use both. Pick whic | Mouse actions, LED modes, extra layers | Not yet | Yes | | Record a shortcut by pressing it | Yes | No | | Read what's on the pad | Yes | No | +| Open web pages, apps, commands, type text | Yes, optional | No | | Install and permissions | One line does both | AUR, a download or `cargo install`; rule by hand | **Short version:** new to Linux, or just want to click things? MacroPad. Want every feature, a different pad, or a config file you can keep in git? ch57x-keyboard-tool. @@ -260,10 +263,39 @@ The bottom bar tells you exactly what happened. Green means it worked. ### 4. Press the key -**Your bindings live on the pad itself**, so they keep working after a reboot, on another computer, even on Windows. Nothing stays running in the background, and you can close the app. +**Your bindings live on the pad itself**, so they keep working after a reboot, on another computer, even on Windows. Nothing stays running in the background, and you can close the app. (The one exception is [actions](#-make-a-key-open-a-web-page-an-app-type-text-or-run-a-command), which are opt in.) --- +## π Make a key open a web page, an app, type text, or run a command + +The pad itself can only ever send key presses. It can't hold "open this website". But your computer can, so an action is split in two: + +- **On the pad**, the key is set to one of **F13 to F24**. No keyboard you own has those, so nothing else reacts to them. +- **On your computer**, a small listener watches for them and does what you asked. + +Click a key, choose **Action**, then pick **Web page**, **App** (from the apps you have installed), **Command**, or **Text**, and write it to the pad. **Test** runs it straight away so you can check it before relying on it. + +
+
+
+
+
+
+
+
+
-### Detecting a pad automatically
+### Start here: ask the pad
-If MacroPad sees a pad it doesn't recognise, it offers to **ask the pad what it is**. That's read only, and it needs the pad to pass two tests before the app will write anything to it:
-
-1. It answers the `0xFB` query with a sensible key and knob count.
-2. It then reports a full layer, describing exactly the control slots that count implies.
-
-A pad from a different family fails one of those, and the app leaves it alone rather than guessing. On the command line:
+Install MacroPad, plug your pad in, and run:
```
macropad detect
```
-The pad reports how many keys and knobs it has, but not how they're arranged, so the app's first guess at rows and columns may be wrong. Check the drawing against the real thing.
+On most pads in this family that's the whole job. It asks the pad how many keys and knobs it has, reads back what's currently bound, and prints a report. Paste that into [an issue](https://github.com/Probler-Yt/MacroPad/issues) and your pad gets added to the known list.
-If your pad passes, please [open an issue](https://github.com/Probler-Yt/MacroPad/issues) with the output so it can be added to the known list and everyone else gets it working first time.
+The app offers the same thing: when it sees a pad it doesn't recognise, the panel has an **Ask the pad what it is** button.
-### Adding one by hand
+### How it decides
-If you'd like your pad in MacroPad too, you're exactly who this project needs. It's the same process used for this one. You'll need the vendor software (`MINI_KEYBOARD.exe`) and Wine.
+Detection is read only, and the pad has to pass two tests before the app will write anything to it:
+
+1. It answers the `0xFB` query with a sensible key and knob count.
+2. It then reports a full layer, describing exactly the control slots that count implies.
+
+A pad from a different family fails one of those, and the app leaves it alone rather than guessing.
+
+The pad reports how many keys and knobs it has, but not how they're arranged, so the first guess at rows and columns may be wrong. Fix it with [Edit layout](#-if-the-drawing-doesnt-match-your-pad) and the drawing will match your hardware.
+
+### If it doesn't answer
+
+Some pads in this family speak an older protocol and won't answer. Working those out needs a capture of the vendor software, the same process used for this one. You'll need `MINI_KEYBOARD.exe` and Wine.
#### Capture what the vendor software sends
@@ -492,6 +578,8 @@ If you'd like your pad in MacroPad too, you're exactly who this project needs. I
Windows already has the vendor app, ugly as it is, and [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) runs there too. **A friendly app on Linux was the gap, so Linux comes first.**
+To be precise about what "Linux only" means here: the window is Qt and runs anywhere, and the protocol module is plain Python. The only Linux specific parts are finding the pad and opening it, which read `/sys/class/hidraw` and `/dev/hidraw`. Swapping those for a cross platform HID library is the whole port. If you run it on Windows today it opens and tells you it can't see any devices.
+
That said, the app is built on Qt, which runs on Windows and macOS too. The only Linux specific parts are the small pieces that talk to USB and check permissions. Swapping it for a cross platform one is on the [roadmap](#-roadmap), and once that's tested on real hardware, one app will work everywhere. If you'd like to help test on Windows, open an issue.
---
@@ -692,6 +780,8 @@ macropad.py the protocol and the command line tool (no dependencies
macropad_gui/
core.py bindings, the app's notes, the permission check, writing
padview.py the drawing of the pad
+ themes.py palettes and drawing styles
+ fonts/ the Sketch theme's handwriting font, with its licence
app.py the window
keymap.py physical key to HID name, for Record
macropad-probe.py read only: what is this device?
@@ -720,6 +810,9 @@ tests/ real captures and the tests that replay them
- [ ] **Windows and macOS** via a cross platform USB layer
- [x] Detecting a pad's key and knob counts by asking it
- [x] A layout editor, since the pad doesn't report how its keys are arranged
+- [x] Actions: open web pages, apps and commands from a key
+- [x] Text snippets: type a phrase from a key
+- [x] Themes, including Blueprint and Sketch
- [ ] **More pads**: every report sent in gets us closer
---
@@ -728,6 +821,8 @@ tests/ real captures and the tests that replay them
- **[kriomant/ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool)**, the MIT licensed command line tool that has supported these pads since 2023. It does more than MacroPad does today (layers, sequences, mouse, LEDs, more pads, every OS), and its source is the best reference there is. Go give it a star.
- **[rOzzy1987/MacroPad](https://github.com/rOzzy1987/MacroPad)**, whose Windows project this app's protocol code started from.
+- **[armas01/macropad](https://github.com/armas01/macropad)**, whose macropad-controller showed the F13 to F24 approach to actions.
+- **[Nord](https://www.nordtheme.com)** and **[Catppuccin](https://catppuccin.com)** for their palettes (both MIT), and Kimberly Geswein for **Architects Daughter**, the Sketch theme's handwriting, under the SIL Open Font License (`macropad_gui/fonts/OFL.txt`).
- Everyone on forums who documented running a whole VM to change a key. Your suffering was noted.
## βοΈ Licence
diff --git a/docs/images/action.png b/docs/images/action.png
new file mode 100644
index 0000000000000000000000000000000000000000..8fe92011b0978c331016ab0bdbc17f35cb1638e3
GIT binary patch
literal 320164
zcmdpdgK>w1t?%b`
zK(bMabQK1_o97r|Th47?vp2e{LYla@- J-=EhYQyqXkTG!UEd 9bL
zJ9qDnFynGY=P!8P5OuiD9}U61!~OjdwY7C|7LpVT_0nevhi`;NofX?TJ_FBYVuUmUA1EF7hRRMv+>f0;)$g}kl{zs-B)7MrDP^qs}hB6U&D&&x-lciuGjF1=O-
z>wSAvW4&wheT&c{%Rp4rG(AZ!qksH2M(etq;Ow@-lrD#t61v3$*(2Gkz4&inZa3Xc
zet~A!vj4Yo1xesD|5zcZ_wqeF6uCG2