brasse/macropad-itprotech
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source 
Condensed some information and removed unneeded words. An overhauled readme combined with the creation of a wiki page on the github maybe a better option.
This commit is contained in:
Oaken
2026-10-08 17:45:28 +01:00
parent 2c12f53c6a
commit 1966122f5c
1 changed files with 153 additions and 344 deletions
Download Patch File Download Diff File Expand all files Collapse all files

497
README.md
View File

@@ -5,8 +5,8 @@
<h1 align="center">MacroPad</h1> <h1 align="center">MacroPad</h1>
<p align="center"> <p align="center">
<b>Set up your cheap 12 key, 2 knob USB macro pad on Linux.</b><br> <b>Set up your macro pad on Linux, natively.</b><br>
No Windows. No virtual machine. No Wine. Just click a key and tell it what to do. No Windows, virtual machine, or Wine.
</p> </p>
<p align="center"> <p align="center">
@@ -23,46 +23,23 @@
</p> </p>
<p align="center"> <p align="center">
<a href="#-install">Install</a> &nbsp;|&nbsp; <a href="#-installing-and-first-use">Installing</a> &nbsp;|&nbsp;
<a href="#-your-first-binding">First binding</a> &nbsp;|&nbsp; <a href="#-your-first-bindings">Quick Start</a> &nbsp;|&nbsp;
<a href="#-when-something-goes-wrong">Help</a> &nbsp;|&nbsp; <a href="#-troubleshooting">Help/Troubleshooting</a> &nbsp;|&nbsp;
<a href="#-other-pads-in-this-family">Other pads</a> &nbsp;|&nbsp; <a href="#-other-pads-in-this-family">Other Pads</a> &nbsp;|&nbsp; <!-- Supported Pads -->
<a href="#-for-the-nerds">For the nerds</a> <a href="#-for-the-nerds">For the Nerds</a>
</p> </p>
--- ---
> [!TIP] > [!NOTE]
> **In a hurry?** Open a terminal and paste this. It does everything, asks before changing anything, and is safe to run again. > **Just want to install MacroPad?** Paste the following into your terminal to get started.
> ``` > ```
> curl -fsSL https://raw.githubusercontent.com/Probler-Yt/MacroPad/main/install.sh | bash > curl -fsSL https://raw.githubusercontent.com/Probler-Yt/MacroPad/main/install.sh | bash
> ``` > ```
> Never used a terminal? Perfect. [The step by step guide](#-install) was written for you.
--- ---
## 📜 Why this exists
I left Windows.
It went fine. Games ran. My editor ran. Everything I cared about had a Linux version or a good replacement. Then I picked up the little AliExpress macro pad on my desk, the one with twelve keys and two knobs, and remembered that the software it came with is a Windows program called `MINI_KEYBOARD.exe` that looks like it was designed during a power cut.
People online were running **entire Windows virtual machines** just to change one key. Others kept a Windows partition alive for it. That is a lot of Windows for a thing that costs less than a pizza.
So I sat down with the vendor's software, the Linux kernel's USB sniffer, and a lot of stubbornness, and worked out exactly what bytes that program sends to the pad.
Once it worked, I found out I wasn't the first. **[ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool)** has handled these pads from the command line since 2023, on Linux, macOS and Windows, and it's excellent. If you're happy editing a YAML file and running a command, go and use it.
But I wanted something a friend on their first week of Linux could use without ever seeing a config file. So this is the other half, the program I actually wanted:
- **It looks like your pad.** You click on a drawing of the real thing, not a settings list.
- **It's honest.** The pad can't tell anyone what's on it, so the app never pretends to know.
- **It's small, quick, and gets out of your way.** Open it, change a key, close it. The pad remembers the rest.
- **It's free, forever.** GPL-3.0. Fork it, fix it, add your pad.
If you've ever thought "I'd switch to Linux, but...", I hope this is one less "but".
---
## 🔍 Is this my pad? ## 🔍 Is this my pad?
@@ -73,49 +50,43 @@ Probably, if yours looks like this:
- Came with software called **`MINI_KEYBOARD.exe`**, or a download link to it. - Came with software called **`MINI_KEYBOARD.exe`**, or a download link to it.
- Plugs in with USB and works as a keyboard straight away. - Plugs in with USB and works as a keyboard straight away.
To check, run `lsusb` in a terminal and look for a line like: To be sure, open a terminal ([how?](#step-1-open-a-terminal)), type `lsusb` and press Enter. Look for this line:
``` ```
Bus 001 Device 011: ID 1189:8840 Acer Communications & Multimedia USB Composite Device Bus 001 Device 011: ID 1189:8840 Acer Communications & Multimedia USB Composite Device
``` ```
The part that matters is **`1189:8840`**. Ignore "Acer": these pads borrow that ID and have nothing to do with Acer. The important bit is **`1189:8840`**. Don't worry about the "Acer" part: it isn't made by Acer, these pads just borrow that ID.
> [!NOTE] > [!NOTE]
> **Different number, like `1189:8890` or `1189:8842`?** That's a sibling of this pad with a different layout. MacroPad will spot it and tell you it isn't supported yet, rather than risk sending it the wrong thing. [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) supports several of them today, and [you can help add yours here](#-other-pads-in-this-family). > **Different number, like `1189:8890` or `1189:8842`?** That's a sibling of this pad with a different layout. MacroPad will spot it and tell you it isn't supported yet, rather than risk sending it the wrong thing. [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) supports several of them today, and [you can help add yours here](#-other-pads-in-this-family).
---
## ✨ What it does ## ✨ Overview
| | | <!--| | |
|---|---| |---|---|
| 🎹 **Click the drawing** | The window shows your pad as it really is. Click a key, or any part of a knob (turn left, press, turn right). | | 🎹 **Click the drawing** | The window shows your pad as it really is. Click a key, or any part of a knob (turn left, press, turn right). |
| ⌨️ **Keyboard shortcuts** | Anything like `Ctrl+C`, `Ctrl+Shift+T`, `Meta+Ctrl+Right`, `F5`. Type it or press **Record** and just do the combo. | | ⌨️ **Keyboard shortcuts** | Anything like `Ctrl+C`, `Ctrl+Shift+T`, `Meta+Ctrl+Right`, `F5`. Type it or press **Record** and just do the combo. |
| 🎵 **Media keys** | Play/pause, next, previous, stop, volume, mute, **screen brightness**, calculator, email, browser, my computer. | | 🎵 **Media keys** | Play/pause, next, previous, stop, volume, mute, **screen brightness**, calculator, email, browser, my computer. |
| 🚫 **Nothing** | Switch a key off completely, so a stray press does nothing. | | 🚫 **Nothing** | Switch a key off completely, so a stray press does nothing. |
| 🔄 **Rotate view** | Stand your pad up or lay it flat. The drawing turns to match. | | 🔄 **Rotate view** | Stand your pad up or lay it flat. The drawing turns to match. |
| 📖 **Reads your pad** | Opens and asks the pad what it's actually holding, so you start from the truth. | | 🧠 **Remembers what it wrote** | The pad can't be read back, so the app keeps its own notes and marks anything it doesn't know. |
| 🔎 **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. | | 🩺 **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. | | 📥 **Imports from the vendor app** | Set your pad up on Windows before? Bring that setup across. |-->
### Reading the drawing ### Reading the UI
<p align="center"> <p align="center">
<img src="docs/images/legend.png" width="700" alt="The four states a key can be drawn in: written, unknown, changed and selected"> <img src="docs/images/legend.png" width="700" alt="The four states a key can be drawn in: written, unknown, changed and selected">
</p> </p>
- **Written**: the app put this on the pad, so it knows exactly what's there. - **Written**: An action has been written to this key.
- **Unknown**: stripes mean the app has no idea what this key does right now. It hasn't written it, and the pad can't be asked. Not broken, just a mystery. - **Unknown**: MacroPad does not know what this key does (this is most common on first usage).
- **Changed**: the orange tape means you've changed it here but haven't sent it to the pad yet. - **Changed**: An action has been written to this key, but not yet sent to the pad.
- **Selected**: the orange outline is the one you're editing. - **Selected**: The currently selected key you are editing.
The tiny `0x04` in each corner is that key's **action byte**, the number the pad uses for it internally. You can ignore it forever. It's there for anyone [adding support for another pad](#-other-pads-in-this-family). Each key's top-left corner shows that key's **action byte**, the number the pad uses for it internally. You can ignore it if you just want to use the app, otherwise it's there for anyone [adding support for another pad](#-other-pads-in-this-family).
### MacroPad or ch57x-keyboard-tool? ### MacroPad or ch57x-keyboard-tool?
@@ -123,209 +94,186 @@ Both write straight to the pad's own memory, so you can even use both. Pick whic
| | MacroPad | [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) | | | MacroPad | [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) |
|---|---|---| |---|---|---|
| How you use it | Click a drawing of your pad | Write a YAML file, run a command | | How you use it | Click on the UI of your pad | Write a YAML file, run a command |
| Pads | `1189:8840` (12 keys, 2 knobs) | `1189:8840`, `8842`, `8890`, several layouts | | Supported Pads | `1189:8840` (12 keys, 2 knobs) | `1189:8840`, `8842`, `8890`, several layouts |
| Systems | Linux | Linux, macOS, Windows | | Operating Systems | Linux | Linux, macOS, Windows |
| Shortcuts and media keys | Yes | Yes | | Shortcuts | Yes | Yes |
| Key sequences with delays | Not yet | Yes | | Media Keys | Yes | Yes |
| Mouse actions, LED modes, extra layers | Not yet | Yes | | Key Sequences/Macros with Delays | Not Yet | Yes |
| Mouse actions, LED modes, Extra Layers | Not Yet | Yes |
| Record a shortcut by pressing it | Yes | No | | Record a shortcut by pressing it | Yes | No |
| Read what's on the pad | Yes | No | | Install and permissions | <a href="#-install-it-the-whole-world-is-counting-on-you">Via Terminal</a> &nbsp; | AUR, Installer, building with `cargo install`|
| 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. Other GUIs for these pads exist too (mostly for the smaller 3 and 6 key models) including one that runs in a web browser. You'll find them under the [ch57x topic on GitHub](https://github.com/topics/ch57x).
Other people have built GUIs for these pads too, mostly for the smaller 3 and 6 key models, including one that runs in a web browser. You'll find them under the [ch57x topic on GitHub](https://github.com/topics/ch57x). The more of these there are, the fewer people are stuck running Windows for a macro pad.
--- ## 🚀 Installing and First Use
## 🚀 Install In a terminal, run the following:
One command does everything: the app, the Qt libraries if you need them, the menu entry, and the USB permission rule. It asks before each step that needs your password, and it's safe to run again to update.
If you're comfortable in a terminal, [skip to the command](#step-2-copy-this-line). The steps below spell it out for anyone newer to Linux, since these pads are a lot of people's first reason to open one.
### Step 1: Open a terminal
A terminal is a window where you type commands instead of clicking. Nothing below can damage your system.
- **KDE Plasma** (CachyOS, Bazzite, Kubuntu, Fedora KDE, KDE neon): press the **Meta key** (the one with the Windows logo), type **`Konsole`**, press **Enter**.
- **GNOME** (Ubuntu, Fedora, Pop!_OS): press the **Meta key**, type **`Terminal`**, press **Enter**.
- **Almost anywhere**: try pressing **`Ctrl` + `Alt` + `T`** together.
### Step 2: Copy this line
Click the copy button on the right side of this box (or select the text and press `Ctrl+C`):
``` ```
curl -fsSL https://raw.githubusercontent.com/Probler-Yt/MacroPad/main/install.sh | bash curl -fsSL https://raw.githubusercontent.com/Probler-Yt/MacroPad/main/install.sh | bash
``` ```
<details> <details>
<summary>What does that line actually do? (optional reading)</summary> <summary>What does this command actually do?</summary>
<br>
In plain words: "download the MacroPad installer from GitHub (`curl`), and run it (`| bash`)". The installer is a normal text file, and you can [read it here](install.sh) before running it if you like. Being suspicious of random commands from the internet is a healthy instinct, and I respect it.
>`curl` downloads `install.sh` from this GitHub repo, `bash` then runs the downloaded file. The installer is a normal text file, and you can [review it here](install.sh) or in your own text editor before running it if you like. Being suspicious of random commands from the internet is a good practice.
</details> </details>
<br>
### Step 3: Paste it and press Enter The install script downloads about 100 MB on some systems, so give it a minute. After installation, you may need to replug in your pad for Linux to notice the new permission.
> [!IMPORTANT] From here, you can now open MacroPad; typically as you would any other app.
> Pasting into a terminal is **`Ctrl` + `Shift` + `V`**, not `Ctrl+V`. Right click, then Paste, also works.
### Step 4: Answer the questions
The installer says what it's doing as it goes, and asks before anything that needs your password. Pressing Enter accepts the default.
It needs the password for two things: installing Qt on systems that don't have it, and writing one permission file so the app can talk to your pad. Everything else stays in your home folder.
> [!NOTE]
> Nothing appears on screen while you type a password in a terminal. No dots, no stars. That's deliberate, not a frozen prompt.
First run downloads around 100 MB on some systems. You'll see **All done.** when it's finished.
### Step 5: Replug the pad
Unplug it and plug it back in, so Linux applies the new permission.
### Step 6: Open MacroPad
Open your app menu, type **MacroPad**, and click it.
<p align="center"> <p align="center">
<img src="docs/images/first-launch.png" width="820" alt="MacroPad on its first launch: every key is striped because the app hasn't written anything yet"> <img src="docs/images/first-launch.png" width="820" alt="MacroPad on its first launch: every key is striped because the app hasn't written anything yet">
</p> </p>
A **green dot** and **Pad ready** at the bottom left means it's working. Anything else, and the panel on the right explains it, or see [When something goes wrong](#-when-something-goes-wrong). **Everything shows as unknown the first time you use MacroPad.** The app hasn't written anything to your pad yet, and most macro pads are write only.
The app reads your pad when it opens, so the drawing should fill in with whatever is already on it. Keys still showing as hatched are ones it couldn't read; press **Read pad** to ask again. If you see a **green dot** and "**Pad ready**" in the bottom left, then everything has installed correctly and works. If you see something else, the panel on the right will tell you exactly what to do, or find more specific help [here](#-when-something-goes-wrong).
> [!TIP]
> To keep it handy: right click **MacroPad** in your app menu and choose **Pin to Task Manager** (Plasma) or **Pin to Dash** (GNOME).
--- ## 🎯 Your First Bindings
## 🎯 Your first binding First, pick any key on your pad. The panel to the right will provide writing options.
### 1. Click a key on the drawing ### Shortcuts
It gets an orange outline, and the panel on the right shows what it currently does.
### 2. Type what you want it to do
Click **Shortcut**, then type the combo into the box using `+` between keys: `ctrl+z`, `ctrl+shift+t`, `meta+e`, `f5`. Underneath, it confirms what the key will send. The key on the drawing gets a strip of orange tape to show it's changed but not sent yet. Click **Shortcut**, then type the combo into the box using `+` between keys: `ctrl+z`, `ctrl+shift+t`, `meta+e`, `f5`. Underneath, it confirms what the key will send. The key on the drawing gets a strip of orange tape to show it's changed but not sent yet.
The **Shortcut** option allows you to configure a key to send a specific keyboard key, or a combination of them. Type the key as you would expect to see it, such as `e`, `shift`, or `5`. `meta` maps to your Windows or CMD (MacOS) button
<details>
<summary>More specific keys</summary>
<br>
>- `lctrl` and `rctrl` will map to left and right control respectively
>- `capslock` will map to your Caps Lock
>- `scrolllock` will map to your Scroll Lock
>- Punction and symbols often need to be typed out
> - \` for example maps from `grave`, [ from `leftbracket`
>- `ralt` will map to the "Alt Gr" key
>- `printscreen` will map to the Print Screen key (often labeled "PrtSc")
>- `super` and `win` work as fallbacks for `meta`
</details>
<br>
<p align="center"> <p align="center">
<img src="docs/images/step-type.png" width="820" alt="Typing ctrl+z for key 2. The app says Sends Ctrl+Z and the key has orange tape on it"> <img src="docs/images/step-type.png" width="820" alt="Typing ctrl+z for key 2. The app says Sends Ctrl+Z and the key has orange tape on it">
</p> </p>
### Or press Record and just do it ### Recording Combinations
Click **Record**, then press the actual combo on your keyboard. The app catches it and fills in the box for you. It records the physical key you pressed, so the pad presses that same key whatever your keyboard layout (UK, German, French, anything). When using the **Shortcut** option, the **Record** button will capture the combination of keys you press. It records the physical key you pressed, so the pad presses that same key whatever your keyboard layout (UK, German, American, etc.).
<p align="center"> <p align="center">
<img src="docs/images/step-record.png" width="820" alt="Record mode: the box glows orange and says press the combo now"> <img src="docs/images/step-record.png" width="820" alt="Record mode: the box glows orange and says press the combo now">
</p> </p>
> [!NOTE] > [!NOTE]
> Your desktop grabs some combos (like most `Meta` shortcuts) before any app can see them. If Record doesn't catch one, just type it instead. > Your desktop grabs some combinations (such as those using the `Meta` key) before any app can see them. If Record doesn't catch one, just type it manually instead.
### Or pick a media key ### Media Keys
Click **Media key** and pick from the list. Volume and brightness on the knobs is a classic. Click **Media Key** and pick from the list.
<p align="center"> <p align="center">
<img src="docs/images/step-media.png" width="820" alt="Choosing Volume down for dial 1 turn left from the list of media keys"> <img src="docs/images/step-media.png" width="820" alt="Choosing Volume down for dial 1 turn left from the list of media keys">
</p> </p>
### Or make it do nothing ### Nothing
To clear a binding, click **Nothing** and write it. Keys set this way show **Nothing** in grey. The **Nothing** option will blank out the bindings set to that key, making it so pressing it does nothing at all.
<p align="center"> <p align="center">
<img src="docs/images/step-nothing.png" width="820" alt="Key 5 set to Nothing, waiting to be written, with key 1 already showing Nothing in grey"> <img src="docs/images/step-nothing.png" width="820" alt="Key 5 set to Nothing, waiting to be written, with key 1 already showing Nothing in grey">
</p> </p>
### 3. Write it to the pad ### Writing to the pad
Click **Write to pad**. Changed a few things? The orange **Write N changes** button at the bottom right sends them all at once. Clicking **Write to Pad** will write only the selected key to your pad. The **Write x Changes** button at the bottom right will write all changes to the pad. After writing, you should see confirmation on the bottom.
<p align="center"> <p align="center">
<img src="docs/images/step-pending.png" width="820" alt="Three keys with orange tape waiting to be written, and a Write 3 changes button"> <img src="docs/images/step-pending.png" width="820" alt="Three keys with orange tape waiting to be written, and a Write 3 changes button">
</p> </p>
The bottom bar tells you exactly what happened. Green means it worked.
<p align="center"> <p align="center">
<img src="docs/images/step-written.png" width="820" alt="After writing: the keys are solid white and the bottom bar says Wrote 3 changes to the pad"> <img src="docs/images/step-written.png" width="820" alt="After writing: the keys are solid white and the bottom bar says Wrote 3 changes to the pad">
</p> </p>
### 4. Press the key ### Done!
**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.) Once changes have been written, you can close the app. **Your bindings live on the pad itself**, so they keep working after a reboot, or even on another computer or operating system. Nothing to run in the background.
--- ## 🚀 Binding Actions
## 🚀 Make a key open a web page, an app, type text, or run a command The pad itself can only ever send key presses. While it can't store a webpage for example, your computer can. Binding an action is split in two components:
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**. Majority of keyboards do not have these keys and are unused.
- **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. - **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.
<p align="center"> <p align="center">
<img src="docs/images/action.png" width="820" alt="Key 5 set to open a web page, with background actions switched on"> <img src="docs/images/action.png" width="820" alt="Key 5 set to open a web page, with background actions switched on">
</p> </p>
Then tick **Run actions in the background**. That starts the listener now and every time you log in. It runs as you, inside your desktop session, so web pages open in your own browser and apps start the way they would from your menu. When you tick **Run actions in the background**, the listener starts now and every time you log in. It runs as your user, inside your desktop session, so web pages open in your own browser and apps start the way they would from your menu.
A few things worth knowing:
- **It's optional.** With it off, action keys send F13 to F24 and nothing happens. Every other key on the pad carries on working, because those live on the pad. <details>
- **Changing what an action does doesn't touch the pad.** The key keeps its F13 to F24 code; only the computer's half changes. <summary>Useful information regarding Actions</summary>
- **You choose the key, or let it choose.** The **Sends** box shows all twelve, which ones other controls already use, and which ones your desktop is known to act on. Left on automatic, it tries the quiet ones first. <br>
- **Twelve at most**, one per spare key. Plenty for a 12 key pad.
- **Text types a phrase wherever your cursor is**: a sign-off, an address, a reply you send twenty times a day. It can be several lines, and emoji and symbols like £ work on any keyboard layout, because it goes through the clipboard and then presses paste. That does mean it replaces whatever you'd copied. Terminals paste with Ctrl+Shift+V, so there's a tick box for that.
- **Commands run as you, in a shell.** Anything you could type in a terminal works, including scripts. Actions are kept in `~/.config/macropad/actions.json`, so treat that file like a script and don't paste in one from someone you don't trust.
- **No extra permissions.** The listener reads the pad through the same access the rest of the app already has.
Text needs two things the other actions don't: **wl-clipboard** (or xclip on X11) to set the clipboard, and permission to press the paste shortcut for you, which is the same rule Steam installs for its controllers. If either is missing, the Text page says so and gives you the commands to fix it. >- **Actions are optional.** With it off, action keys send F13 to F24 and nothing happens. Every other key on the pad carries on working, because those live on the pad.
>- **Changing what an action does doesn't touch the pad.** The key keeps its F13 to F24 code; only the what the listener does changes.
>- **You can choose which spare function key.** Some keyboards do have some of if not all the F13 to F24 keys. You can manually select a funciton key in this range, and will be shown which function keys are already in use and also which ones your desktop is known to act on. "Automatic" will have it try quieter keys first.
>- **Limit of 12 Actions.** One per key in the range of F13 to F24.
>- **Text pastes a phrase wherever your cursor is.\*** The text action will paste what is stored where your cursor (or highlighted text prompt) is. This can include multiple lines, symbols, and emoji. This *will* replace whatever is currently on your clipboard. An option allows for pasting with `Ctrl+Shift+V` to allow pasting in a terminal window.
>- **Commands run as your user, in a shell.** Anything you could type in a terminal works, including scripts. Actions are kept in `~/.config/macropad/actions.json`; treat this file like any other script and don't paste in scripts from untrusted sources.
>- **No extra permissions.** The listener reads the pad through the same access the rest of the app already has.
*Text needs two things the other actions don't: **wl-clipboard** (or xclip on X11) to set the clipboard, and permission to press the paste shortcut for you (similar to the same rule Steam installs for its controllers). If either is missing, the app will tell you and also show you the commands to fix it.
</details>
<br>
The idea of pairing F13 to F24 with a listener comes from [armas01's macropad-controller](https://github.com/armas01/macropad/tree/main/macropad-controller), which does this for the 3 and 6 key pads. The idea of pairing F13 to F24 with a listener comes from [armas01's macropad-controller](https://github.com/armas01/macropad/tree/main/macropad-controller), which does this for the 3 and 6 key pads.
## 🎛️ The knobs ## 🎛️ The knobs
Each knob does three separate things, and each gets its own binding: Each knob does three separate things, and each gets its own binding:
| Part of the drawing | What you do on the pad | | UI | Pad Action |
|---|---| |---|---|
| Left half of the ring | **Turn left** (anticlockwise), one click at a time | | Left half of the ring | **Turn left** (anticlockwise) |
| Middle circle | **Press** the knob down | | Middle circle | **Pressing** the knob down |
| Right half of the ring | **Turn right** (clockwise) | | Right half of the ring | **Turn right** (clockwise) |
You can also click the three lines of text under each knob. Every click of a turn sends the key once, so volume and brightness feel natural. Spin it fast and it keeps up. You can also click the three lines of text under each knob. Every click of a turn sends the key once.
> [!TIP] > [!IMPORTANT]
> **Screen brightness on a desktop monitor** works too, if your desktop supports it. KDE Plasma 6 does it out of the box for monitors with DDC/CI (most modern ones; it's sometimes a setting in the monitor's own menu). > **Screen brightness on a desktop monitor** works too, *if* your desktop supports it. For example, KDE Plasma 6 does it out of the box for monitors with DDC/CI (sometimes can be found as a setting in the monitor's own OEM settings menu).
---
## 📐 If the drawing doesn't match your pad ## 🎨 Visuals
Press **Edit layout** at the bottom. The keys start wobbling, and you can drag them around until the picture matches the pad in front of you. Two keys swap when you drop one onto the other, so nothing is ever lost. ### Layout Editing
The boxes along the bottom set the grid size and how many keys and knobs there are. **Done** saves it, **Cancel** puts it back. **Edit layout** at the bottom allows you to change how the UI looks to better match a compatible pad with a different layout. This maybe useful as pads only report the number of keys they have, not their layout.
Editing the layout allows you to drag keys around to match your layout. Two keys swap when you drop one onto the other. The boxes along the bottom set the grid size and how many keys and knobs there are. **Rotate view** allows you to view your pad laid horizontally, with the knobs to the right.
This only changes the UI, and writes nothing to the pad.
<p align="center"> <p align="center">
<img src="docs/images/edit-layout.png" width="820" alt="Edit layout mode: keys outlined and being dragged into a new position"> <img src="docs/images/edit-layout.png" width="820" alt="Edit layout mode: keys outlined and being dragged into a new position">
</p> </p>
This only changes the picture. It never writes anything to the pad. It's there because the pad reports how many keys it has but not how they're arranged, so on a pad we haven't seen before the first guess can be wrong.
## 🎨 Themes ### Themes
Seven of them, under **Theme** at the bottom of the window. The choice sticks. Seven of them, under **Theme** at the bottom of the window. The choice sticks.
@@ -337,80 +285,49 @@ Seven of them, under **Theme** at the bottom of the window. The choice sticks.
- **White board**: the same, on a white board, for anyone who wants a light theme. - **White board**: the same, on a white board, for anyone who wants a light theme.
- **Nord**, **Catppuccin Mocha** and **Catppuccin Latte**: the popular palettes, as their authors published them. - **Nord**, **Catppuccin Mocha** and **Catppuccin Latte**: the popular palettes, as their authors published them.
Two do more than change colour. **Blueprint** and **Sketch** are more "fun" themes compared to the others, and overhaul the entire UI.
**Blueprint** draws the pad as an engineering drawing. White linework on cyanotype blue, over a drawing grid. Unknown keys become dashed hidden lines, the way drawings show edges you can't see. Chain lines cross each knob's centre. Lettering is in capitals, changes are marked up in yellow, and the sheet has a border and a proper title block with the drawing number, scale, layout, and your username as the draughtsman.
<p align="center">
<img src="docs/images/theme-blueprint.png" width="820" alt="The Blueprint theme: the pad as a white-line engineering drawing on blue grid paper, with a title block in the corner">
</p>
**Sketch** is pencil on paper. Every line wanders slightly and is gone over twice, the way a hand draws, and unknown keys are shaded in. The wobble is seeded per key, so each one looks the same every time rather than shimmering as you move the mouse.
<p align="center">
<img src="docs/images/theme-sketch.png" width="820" alt="The Sketch theme: the pad drawn in pencil on off-white paper with handwritten labels">
</p>
## 🔄 Rotate view
Some people stand the pad up with the knobs on top. Some lay it flat with the knobs on the right. Click **Rotate view** at the bottom and the drawing turns to match. It remembers your choice.
<p align="center">
<img src="docs/images/flat-view.png" width="820" alt="The flat view: keys in three rows of four, with both knobs on the right">
</p>
---
## 📥 Already set it up with the vendor app? ## 📥 Already set it up with the vendor app?
If you configured your pad with `MINI_KEYBOARD.exe` and recorded it with the included capture tool ([how](#capture-what-the-vendor-software-sends)), click **Import capture...** and choose the file. The app reads what was saved and fills in the drawing, so those keys stop showing as unknown. If you configured your pad with `MINI_KEYBOARD.exe` and recorded it with the included capture tool ([how](#capture-what-the-vendor-software-sends)), click **Import capture...** and choose the file. The app reads what was saved and fills in the drawing, so those keys stop showing as unknown.
Only do this if nothing has changed on the pad since that capture. Only do this if nothing has changed on the pad since that capture, as this will not write these changes. It only fills in the UI.
---
## 📖 Reading your pad ## 🩹 Troubleshooting
MacroPad asks the pad what it's holding when it opens, so the drawing shows what's really on the hardware rather than what some file thinks. There's a **Read pad** button at the bottom to ask again at any time.
Anything you've changed but not written yet is left alone when it reads, since that's your intent, not the pad's state.
### So what does "Unknown" mean now?
Hatched keys are ones the app hasn't been told about: either the pad didn't answer, or you haven't pressed Read pad. Press it and they fill in.
<p align="center">
<img src="docs/images/read-pad.png" width="820" alt="The app after reading the pad: every key and dial filled in from the hardware">
</p>
The app still keeps its own notes, because a write can fail halfway. If that happens, that one control goes back to Unknown rather than claiming either the old or the new binding, and reading the pad clears it up.
> [!NOTE]
> This took a while to work out. The project was built assuming these pads were write only, because nothing documented a way to read them and the first captures only recorded traffic in one direction. They can be read. The story is in [For the nerds](#-for-the-nerds).
---
## 🩹 When something goes wrong
The app checks your pad every couple of seconds and explains any problem in the panel on the right, with the exact fix and a **Copy commands** button. Here's everything it might say. The app checks your pad every couple of seconds and explains any problem in the panel on the right, with the exact fix and a **Copy commands** button. Here's everything it might say.
If your problem isn't listed here, [open an issue](https://github.com/Probler-Yt/MacroPad/issues).
### Why does it say "Unknown"?
Striped or Unknown keys aren't necessarily broken, usually they're just keys this app hasn't touched yet. Because **these pads are write only**, this is typically seen when using this for the first time. Even the official Windows app opens with every key blank. The app keeps its own record of successfully written keys.
If a write fails before anything reaches the pad, nothing changes. <br>
If a write fails **halfway**, that key goes back to **Unknown**, because the honest answer is "no idea". Just write it again.
### "No pad connected" ### "No pad connected"
The app can't see your pad. Unplug it and plug it back in, or try another USB port. If it's a USB hub, try plugging straight into the computer. The app can't see your pad. Unplug it and plug it back in, or try another USB port. If it's a USB hub, try plugging straight into the computer.
### "No permission to write to the pad" ### "No permission to write to the pad"
<p align="center"> <p align="center">
<img src="docs/images/permission.png" width="820" alt="The permission problem panel, with the commands to fix it and a copy button"> <img src="docs/images/permission.png" width="820" alt="The permission problem panel, with the commands to fix it and a copy button">
</p> </p>
Linux protects USB devices from apps by default. The installer normally sorts this out, so the easiest fix is to **run the install line again** and say yes when it asks. Or click **Copy commands**, paste them into a terminal (`Ctrl+Shift+V`), press Enter, and replug the pad. This is due to Linux protects USB devices from apps by default. You can **run the installer again** and say yes when it asks to change permissions, or click **Copy commands** and paste them into a terminal to manually change the permissions. Make sure to unplug and plug your pad back in.
The app is quite clever here. It checks the three usual reasons this happens and tells you which one it is: Usually this happens for three reasons:
- **No rule yet.** The permission file doesn't exist. - **No rule yet.** The permission file doesn't exist.
- **Rule not loaded.** It exists, but Linux hasn't noticed. Replug the pad. - **Rule not loaded.** It exists, but Linux hasn't noticed. Unplug and plug your pad back in.
- **Rule named wrong.** If you made one yourself called something like `99-macropad.rules`, it's read *too late* to work. It needs a number below 73. The app gives you the exact rename command. ([Why?](#the-udev-rule-that-cost-me-an-hour)) - **Rule named wrong.** If you made one yourself called something like `99-macropad.rules`, it's read *too late* to work. It needs a number below 73 ([Why?](#the-udev-rule-that-cost-me-an-hour)).
### "Heads up: keyd is remapping this pad" ### "Heads up: keyd is remapping this pad"
@@ -418,7 +335,7 @@ The app is quite clever here. It checks the three usual reasons this happens and
<img src="docs/images/keyd-note.png" width="820" alt="A heads up note explaining that keyd is remapping keys from this pad"> <img src="docs/images/keyd-note.png" width="820" alt="A heads up note explaining that keyd is remapping keys from this pad">
</p> </p>
**keyd** is a program that changes keys as they travel from a keyboard to your desktop. If you set it up for this pad in the past (a common trick before this app existed), it may change what your pad sends. You don't need it for this pad any more. If you only used it for the pad, switch it off: **keyd** is a program that changes keys as they travel from a keyboard to your desktop. If you set it up for this pad in the past, it may change what your pad sends. This app makes it so this is no longer required. If you only used it for the pad, switch it off:
``` ```
sudo systemctl disable --now keyd sudo systemctl disable --now keyd
@@ -426,57 +343,40 @@ sudo systemctl disable --now keyd
Saving bindings works fine either way. keyd only affects keys *coming out* of the pad. Saving bindings works fine either way. keyd only affects keys *coming out* of the pad.
### "Found a 1189:xxxx pad, which this app doesn't know yet" ### "Found a 1189:xxxx pad, which this app doesn't know yet"
You have a sibling pad with a different layout. The app refuses to write to it on purpose, because the wrong layout could scramble it. [You can help add it.](#-other-pads-in-this-family) You have a sibling pad with a different layout. The app refuses to write to it on purpose, because the wrong layout could scramble it. [You can help add it.](#-other-pads-in-this-family)
### "Couldn't write Key 4: the pad stopped responding" ### "Couldn't write Key 4: the pad stopped responding"
The pad dropped off USB partway through a write, which can happen with a loose cable or a busy hub. Unplug it, plug it back in, and click **Write to pad** again. That key shows as Unknown until you do. The pad disconnected from USB partway through a write, often due to a loose cable or a busy hub. Unplug it, plug it back in, and click **Write to pad** again.
### An action key does nothing
Check **Run actions in the background** is ticked, and that the status under it says it's running. If it is and the key still does nothing, run this in a terminal and press the key:
```
macropad actions --debug
```
It prints every report the pad's keyboard sends. If nothing appears, the listener can't see the pad; if something appears but no action runs, the output says which key arrived, which narrows it down. Stop it with `Ctrl+C` and open an issue with what it printed.
### A text key doesn't type anything
Select the key, open its Action page, and look under the text box. If something's missing it says what, with a **Copy fix** button; paste that into a terminal. The permission rule usually needs you to unplug the pad and plug it back in, or log out and back in, before it takes effect.
If nothing's reported as missing, press **Test**, then click into a text box within three seconds. If Test types but the pad key doesn't, check background actions are running.
### An action key also does something else
Linux gives some of the spare keys a meaning of its own, so your desktop can react to them as well as MacroPad. On Plasma 6, **F13** opens System Settings, **F20** mutes the microphone and **F21** toggles the touchpad. **F22** and **F23** are touchpad on and off in the same table.
The easy fix is to pick a different key in the **Sends** box and write it again; the automatic choice already avoids these. If you'd rather keep the key, you can remove its desktop shortcut instead: in System Settings, open **Keyboard**, then **Shortcuts**, search for what it does ("Mute Microphone", "Toggle Touchpad" and so on), and clear the shortcut.
### Record doesn't catch my shortcut ### Record doesn't catch my shortcut
Your desktop keeps some combos for itself (on Plasma, most `Meta` shortcuts), so no app ever sees them. Type it into the box instead, like `meta+ctrl+right`. Your desktop keeps some combos for itself (on Plasma, most `meta` shortcuts), so no app ever sees them. Type it into the box instead, for example `meta+ctrl+right`.
### A media key does nothing ### A media key does nothing
Play, volume, mute and brightness work everywhere. **Calculator**, **Email**, **Browser** and **My computer** depend on your desktop having an app assigned to them. If one does nothing, set it up in your desktop's shortcut settings. Play, volume, mute and brightness work everywhere. **Calculator**, **Email**, **Browser** and **My Computer** depend on your desktop having an app assigned to them. If one does nothing, set it up in your desktop's shortcut settings.
### "qt.qpa.services: Failed to register with host portal" in the terminal ### "qt.qpa.services: Failed to register with host portal" in the terminal
Harmless. It only appears if you run the app before its launcher is installed. The installer adds the launcher, and the message goes away. This appears if you run the app before its launcher is installed. The installer adds the launcher, and the message goes away.
### The window looks wrong or won't open ### The window looks wrong or won't open
Run `macropad` in a terminal and read the last few lines it prints. If it mentions `xcb` or a "platform plugin", run the installer again, which adds the missing library. If you're still stuck, [open an issue](https://github.com/Probler-Yt/MacroPad/issues) and paste what it printed. Run `macropad` in a terminal and read the last few lines it prints. If it mentions `xcb` or a "platform plugin", run the installer again, which adds the missing library. If you're still stuck, [open an issue](https://github.com/Probler-Yt/MacroPad/issues) and paste what it printed.
---
## ♻️ Updating and removing ## ♻️ Updating and Removing
**To update:** run the same install line again. Your bindings and settings stay put. **To update:** Reinstall the app. Your bindings and settings stay put.
**To remove:** **To remove:**
@@ -484,68 +384,25 @@ Run `macropad` in a terminal and read the last few lines it prints. If it mentio
~/.local/share/macropad/app/uninstall.sh ~/.local/share/macropad/app/uninstall.sh
``` ```
It asks before removing the permission rule or the app's notes. Your pad keeps whatever you last wrote to it, forever, or until you change it. It asks before removing the permission rule or the app's notes. Your pad will still using the last bindings written to it until changed again.
---
## 🧩 Handy things to put on your pad
A few ideas for KDE Plasma, where these are the default shortcuts:
| Binding | What it does on Plasma |
|---|---|
| `meta+ctrl+left` / `meta+ctrl+right` | Switch virtual desktop (also works on Windows!) |
| `meta+w` | Overview of all your windows |
| `meta+d` | Show the desktop |
| `ctrl+alt+t` | Open a terminal |
| `printscreen` | Screenshot with Spectacle |
| `ctrl+shift+t` | Reopen the tab you just closed (browsers) |
| Media: Brightness down / up on a knob | Monitor brightness, silky smooth |
> [!TIP]
> Virtual desktop switching needs at least two desktops. **System Settings**, then **Virtual Desktops**, then **Add**.
---
## 🧬 Other pads in this family ## 🧬 Other pads in this family
This app is **confirmed on `1189:8840`**, the 12 key, 2 knob pad. It's the only one it knows so far. This app is **confirmed to work on `1189:8840`**, the 12 key, 2 knob pad. For now, it's the only pad it knows.
> [!TIP] > [!TIP]
> **Have a different pad right now?** [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) supports `1189:8840`, `1189:8842` and `1189:8890` in several layouts (3, 6, 9, 12 and 15 keys) from the command line, today. > **Want to change a different pad right now?** [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) supports `1189:8840`, `1189:8842` and `1189:8890` in several layouts (3, 6, 9, 12 and 15 keys) from the command line.
Siblings come in other sizes, and several share vendor ID `1189`. **They don't all speak the same language:** ch57x-keyboard-tool has separate code for different families, and rOzzy1987's Windows project lists yet more IDs (`8830`, `8831`, `8832`, `8897`, `8874`) with their own formats. That's why MacroPad won't write to a pad it doesn't know. Siblings come in other sizes, and several share vendor ID `1189`. **They don't all speak the same language:** ch57x-keyboard-tool has separate code for different families, and rOzzy1987's Windows project lists yet more IDs (`8830`, `8831`, `8832`, `8897`, `8874`) with their own formats. This is why MacroPad won't write to a pad it doesn't know.
<p align="center"> <p align="center">
<img src="docs/images/unsupported.png" width="820" alt="The app explaining that it found a 1189:8890 pad that it doesn't support yet"> <img src="docs/images/unsupported.png" width="820" alt="The app explaining that it found a 1189:8890 pad that it doesn't support yet">
</p> </p>
### Start here: ask the pad ### Adding your own Pad
Install MacroPad, plug your pad in, and run: If you'd like your pad in MacroPad too, you'll need the vendor software (`MINI_KEYBOARD.exe`) and Wine.
```
macropad detect
```
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.
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.
### How it decides
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 #### Capture what the vendor software sends
@@ -553,9 +410,9 @@ Some pads in this family speak an older protocol and won't answer. Working those
``` ```
python3 ~/.local/share/macropad/app/macropad-probe.py python3 ~/.local/share/macropad/app/macropad-probe.py
``` ```
This only reads. It lists your pad's ID and its USB interfaces. This lists your pad's ID and its USB interfaces.
2. **Start the capture** (it watches USB traffic; it never sends anything): 2. **Start the capture:**
``` ```
cd ~/.local/share/macropad/app cd ~/.local/share/macropad/app
sudo python3 macropad-capture.py sudo python3 macropad-capture.py
@@ -572,19 +429,16 @@ Some pads in this family speak an older protocol and won't answer. Working those
6. **[Open an issue](https://github.com/Probler-Yt/MacroPad/issues)** with that file, your `macropad-probe.py` output, and a photo of your pad. That's genuinely all it takes to get your pad supported. 6. **[Open an issue](https://github.com/Probler-Yt/MacroPad/issues)** with that file, your `macropad-probe.py` output, and a photo of your pad. That's genuinely all it takes to get your pad supported.
---
## 🪟 What about Windows? ## 🪟 Windows Support?
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.** Windows already works with apps from vendors shipped as `.exe` files, and [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool).
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. Windows testing is welcome once support begins development.
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.
--- ---
## 🤓 For the nerds ## 🤓 For the Nerds
<details> <details>
<summary><b>How this pad was reverse engineered</b></summary> <summary><b>How this pad was reverse engineered</b></summary>
@@ -660,41 +514,6 @@ rOzzy1987's format is for different product IDs, which is why porting it to this
</details> </details>
<details>
<summary><b>Reading the pad, and how we nearly missed it</b></summary>
The project ran for weeks on the assumption that these pads were write only. Two things caused that:
- Nothing documented a read. Neither rOzzy1987's project nor ch57x-keyboard-tool implements one.
- The capture tool only recorded **outgoing** transfers. So even though the pad had been answering all along, nothing was ever written down.
What settled it was noticing that the vendor software has a "view settings" button, and that it showed bindings written by MacroPad. It couldn't have known those from a file, so it was asking the pad. Capturing both directions gave the answer.
Two query commands, both answered on the interrupt IN endpoint of the same report id:
```
03 fb ... what are you?
03 fb 0c 02 reply: 12 keys, 2 knobs
03 fa 0f 03 01 02 ... send me layer 1
(15 key slots, 3 layers, layer 1, 2 knobs)
03 fa 02 01 01 00 ... 01 05 17 key 2 is ctrl+alt+t
03 fa 10 01 02 00 ... 01 ea 00 dial 1 left is volume down
... one report per control, then silence
```
Replies use the same layout as a config write, with `0xFA` in place of the `0xFD` magic. Media replies carry a count of 1 where writes send 2; both are accepted.
Three things fell out of it:
- **The pad reports its own layout**, so key and knob counts don't have to be guessed from the USB ID.
- **There are three layers**, and the firmware keeps 15 key slots and 3 knobs whatever the hardware has. Ours answers for 6 controls that don't physically exist.
- **The dial mapping is confirmed from the other direction.** Reading back what we had written returns exactly the mapping we assumed, which is stronger evidence than a write that appeared to work.
The vendor's request has trailing bytes that change between runs and look like uninitialised memory from the Windows program. Zeros work fine.
</details>
<details> <details>
<summary><b>usbmon only shows you 32 bytes</b></summary> <summary><b>usbmon only shows you 32 bytes</b></summary>
@@ -723,7 +542,7 @@ The app's permission check reads `udevadm info` to see whether the device got th
<details> <details>
<summary><b>Where the app keeps its notes</b></summary> <summary><b>Where the app keeps its notes</b></summary>
`~/.config/macropad/state-1189-8840.json` holds what the app last read from or wrote to the pad. Since the pad can be read, this is a cache rather than the source of truth. Every entry is exactly a command the CLI understands: `~/.config/macropad/state-1189-8840.json` holds everything the app has successfully written. Every entry is exactly a command the CLI understands:
```json ```json
{ {
@@ -780,8 +599,6 @@ macropad.py the protocol and the command line tool (no dependencies
macropad_gui/ macropad_gui/
core.py bindings, the app's notes, the permission check, writing core.py bindings, the app's notes, the permission check, writing
padview.py the drawing of the pad 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 app.py the window
keymap.py physical key to HID name, for Record keymap.py physical key to HID name, for Record
macropad-probe.py read only: what is this device? macropad-probe.py read only: what is this device?
@@ -799,21 +616,14 @@ tests/ real captures and the tests that replay them
- [x] Keys, shortcuts and media keys on `1189:8840` - [x] Keys, shortcuts and media keys on `1189:8840`
- [x] Both knobs, all three actions each - [x] Both knobs, all three actions each
- [x] Upright and flat views - [x] Upright and flat views
- [x] Reading the pad, so the app shows what's really on it
- [x] One line installer for any distro - [x] One line installer for any distro
- [ ] **Key sequences with delays**. Reading the pad shows two-key sequences stored in the layout we assumed, so this is close - [ ] **Key sequences with delays** (ch57x-keyboard-tool shows the likely format; one capture to confirm)
- [ ] **Layers 2 and 3**, which the pad turns out to have - [ ] Layers 2 and 3, and LED modes
- [ ] LED modes
- [ ] AUR package, so Arch users can install it like anything else - [ ] AUR package, so Arch users can install it like anything else
- [ ] Knob press to toggle brightness between 0% and 100% - [ ] Knob press to toggle brightness between 0% and 100%
- [ ] Save and switch between named profiles (gaming, editing, streaming) - [ ] Save and switch between named profiles (gaming, editing, streaming)
- [ ] **Windows and macOS** via a cross platform USB layer - [ ] **Windows and macOS** via a cross platform USB layer
- [x] Detecting a pad's key and knob counts by asking it - [ ] **More pads**: every capture sent in gets us closer
- [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
--- ---
@@ -821,16 +631,15 @@ 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. - **[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. - **[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. - Everyone on forums who documented running a whole VM to change a key. Your suffering was noted.
## ⚖️ Licence ## ⚖️ Licence
GPL-3.0, the same as the project it builds on. Use it, change it, share it. If you share a changed version, share the source too. GPL-3.0, the same as the project it builds on. Use it, change it, share it. If you share a changed version, share the source too.
--- <!--
<sub> <sub>
<b>Also known as:</b> macro pad software for Linux, MINI_KEYBOARD.exe alternative, mini keyboard configurator, 12 key macro keyboard with 2 knobs, USB macro keypad with rotary encoders, AliExpress macro pad driver for Linux, custom shortcut keypad for Linux, Acer Communications &amp; Multimedia USB Composite Device (1189:8840), macropad on Arch, CachyOS, Fedora, Ubuntu, Linux Mint, Pop!_OS, Bazzite, KDE Plasma and GNOME, on Wayland and X11. <b>Also known as:</b> macro pad software for Linux, MINI_KEYBOARD.exe alternative, mini keyboard configurator, 12 key macro keyboard with 2 knobs, USB macro keypad with rotary encoders, AliExpress macro pad driver for Linux, custom shortcut keypad for Linux, Acer Communications &amp; Multimedia USB Composite Device (1189:8840), macropad on Arch, CachyOS, Fedora, Ubuntu, Linux Mint, Pop!_OS, Bazzite, KDE Plasma and GNOME, on Wayland and X11.
</sub> </sub>
-->