mxcontrol

KO | EN

gitlite — search

#llm #reactjs #json #graphql #artificial-intelligence #cross-platform #devops #list #svg #open-source

(★ 9)

Menu bar control for Logitech mice over HID++ 2.0. Button-combination macros for any mouse.

파일 탐색기

ZIP 다운로드

- - hardware-report.md
- - AppIcon.icns
  - MenuIcon.png
  - [email protected]
  - [email protected]
- Actions.swift
- Bindings.swift
- BindingsWindow.swift
- ButtonChips.swift
- ChordDetector.swift
- ChordEngine.swift
- DeviceSettingsView.swift
- Diagnostics.swift
- HIDPP.swift
- Info.plist
- MacroMenuRow.swift
- main.swift
- MouseDiagramView.swift
- MXController.swift
- MXDevice.swift
- SecretStore.swift
- UIDriver.swift
- - main.swift
- - main.swift
- - main.swift
- - main.swift
- gen-signing-cert.sh
- preview-diagram.sh
- preview-editor.sh
- release.sh
- unstick.sh
.gitignore
build.sh
CHANGELOG.md
HACKING.md
LICENSE
mxmaster.svg
mxprobe.swift
README.md
VERSION

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A small macOS menu bar app that controls Logitech mice directly, in place of Logi Options+.

The entire app is one ~120 KB binary and a menu, running as an ordinary userspace process. It
talks to the mouse over **HID++ 2.0**, the same protocol Logitech's own software uses, through
plain IOKit. Where Options+ installs a suite with background services, an updater and an
account, installing this is copying it, and everything it knows stays on your Mac.

It also does something Options+ doesn't: macros that fire on **button combinations**. Hold one
mouse button, click another, run anything, shell commands included. Options+ macros trigger on
a single button; combinations work with *any* mouse, from any vendor.

---

## Status: read this before filing an issue

This has been developed and tested against exactly one configuration:

| | Tested |
|---|---|
| Device | MX Master 3S |
| Transport | Bluetooth LE |
| macOS | 26 (Darwin 25.1), Apple Silicon |

Everything else (USB cable, Bolt/Unifying receiver, other Logitech models, Intel Macs, older
macOS) is written *for* but **not verified**. The code detects device capabilities at runtime
rather than assuming them, so other hardware should degrade gracefully to whatever it supports.
But "should" is doing real work in that sentence.

If it misbehaves on your device, choose **Copy Diagnostics** in the menu (see
[Diagnostics](#diagnostics)) and paste the report into an issue. It contains everything needed
to fix it.

### Written but not verified on hardware

Called out explicitly so nobody is surprised:

- **Feature `0x2202` (Extended Adjustable DPI)**, used by newer sensors. Function numbers come
  from community documentation and could not be tested here. The write path is gated on a
  successful read of the device's own advertised DPI range, and refuses any value the device
  hasn't itself reported, so if the numbers are wrong the DPI menu simply doesn't appear rather
  than writing something bad to your sensor.
- **USB and Bolt/Unifying transports**, including the receiver device-index sweep.
- **Report rate** (`0x8060`), which is absent over Bluetooth and so never exercised here.

All of these degrade to "the control doesn't show up" rather than misbehaving. Reports welcome.

---

## What it does

**Logitech devices** (feature-detected: you only see what your mouse actually supports):

- Battery level and charging state
- Scroll wheel: Ratchet / SmartShift / Freespin, plus SmartShift threshold
- Invert scroll, hi-res scroll, invert thumb wheel
- DPI, snapped to your sensor's real supported range and step
- Report rate (USB and Bolt only; the feature is absent over Bluetooth)
- Host switching for multi-host mice
- Settings reapplied automatically on reconnect and after system wake

**Any mouse:**

- Button macros → keyboard shortcut, launch app/file/URL, shell command, or system action

If MXControl isn't running, your mouse still works completely normally. You lose the
customizations, never the hardware. That property is deliberate and load-bearing in the design;
see [Why macros instead of button remapping](#why-macros-instead-of-button-remapping).

---

## Install

Requires the Xcode command line tools (`xcode-select --install`), and that is the entire
toolchain: the build is plain `swiftc` driven by one script, and every dependency is a system
framework.

```bash
git clone https://github.com/theseriouspdx/mxcontrol.git
cd mxcontrol
./scripts/gen-signing-cert.sh    # once, see Signing below
./build.sh
open MXControl.app
```

Enable **Launch at Login** from the menu once it's running.

### Signing: do not skip this

macOS ties Input Monitoring and Accessibility grants to an app's *designated requirement*. With
an ad-hoc signature that requirement is a **cdhash**, a hash of the compiled binary, so every
rebuild looks like a brand new app and silently revokes your permissions. The Settings toggle
keeps reading "on" while pointing at a binary that no longer exists. This is maddening and it
will happen to you.

`./scripts/gen-signing-cert.sh` generates a self-signed certificate, which makes the requirement
`identifier + certificate root` instead. Grant permissions once and they hold across every
future rebuild. Back up `signing/mxctl.p12`; generating a *different* certificate means
re-granting everything.

`build.sh` falls back to ad-hoc signing with a loud warning if no identity is found.

---

## Permissions

| Permission | Needed for | Asked when |
|---|---|---|
| **Input Monitoring** | Opening the HID device at all | Always |
| **Accessibility** | The macro event tap | Only once you configure a macro |

A fresh install with no macros never installs an event tap and never asks for Accessibility.

If the menu shows "Grant Input Monitoring…", click it, add `MXControl.app`, then choose
**Refresh**; it takes effect immediately.

---

## Macros

Hold one or more buttons, then click another. **You don't have to configure anything first**:
just perform a combination and MXControl offers to bind it:

> **back + left**: Assign an action to this combination?
> `[Never ask]  [Not now]  [Assign…]`

This works because detecting a combination and *acting* on one are separate problems. Noticing
that two buttons overlapped needs no interference at all, so unassigned combinations behave
completely normally and cost nothing. Only an assigned macro withholds anything.

Accidental presses are filtered by requiring ~80ms of genuine overlap, prompting on release
rather than on press, a per-combination **Never ask** list, and a **Suggest New Macros** toggle in
the menu.

**Edit Bindings…** opens the editor: a drawn mouse showing which buttons the selected macro uses
and which one you're physically pressing right now, plus one row per macro. Press **Record…** and
perform a combination rather than assembling it from popups; that is also how three-button
macros get expressed. **Save & Apply** validates every row and reports the first problem instead
of silently discarding it.

The editor is a front end onto a plain JSON file, which stays fully hand-editable:

```
~/Library/Application Support/MXControl/bindings.json
```

```json
{
  "chords": [
    {
      "buttons": ["forward", "left"],
      "action": { "type": "system", "name": "missionControl" }
    },
    {
      "buttons": ["back", "forward", "left"],
      "action": { "type": "shell", "command": "open -a Terminal", "label": "Terminal" }
    }
  ]
}
```

Every button but the last is held; the last one triggers. Older files using `{"hold": …, "press": …}`
are still read and upgraded on save.

**Buttons:** `left`, `right`, `middle`, `back`, `forward`, `extra1`, `extra2`

**Actions:**

| type | fields |
|---|---|
| `keyboard` | `key` plus optional `modifiers`: `cmd`, `shift`, `opt`, `ctrl`, `fn` |
| `text` | `text` to type, plus optional `pressReturn` |
| `menu` | `menuPath`: menu titles top-down; optional `app` (defaults to frontmost) |
| `ui` | `element`: a control's visible name; optional `role`, `matchIndex`, `app` |
| `click` | `x`, `y` plus `relativeTo`: `window` (default) or `screen`. Last resort |
| `sequence` | `steps`: an ordered list of `{text}`, `{key, modifiers}` and `{delayMs}`. JSON only |
| `launch` | `path`: app, file, or `https://` URL |
| `shell` | `command`, run through `/bin/sh -c` |
| `system` | `name`: `missionControl`, `appExpose`, `showDesktop`, `spaceLeft`, `spaceRight`, `launchpad`, `lockScreen`, `playPause`, `next`, `previous`, `volumeUp`, `volumeDown`, `mute` |

### Driving an application's menus

For a command with no keyboard shortcut (changing an Illustrator workspace, say), bind a
`menu` action:

```json
{
  "buttons": ["forward", "left"],
  "action": {
    "type": "menu",
    "app": "Adobe Illustrator",
    "menuPath": ["Window", "Workspace", "Essentials"]
  }
}
```

This presses the item **by name** through the Accessibility API. It does not move your pointer,
and it keeps working when the window moves, the display resolution changes, or the menu gains
items, none of which is true of replaying recorded pointer coordinates. Verified against
three-level paths; the whole menu tree is readable without opening anything.

Two caveats worth knowing. Titles must match exactly, and some toggle: Finder shows
`Hide Sidebar` or `Show Sidebar` depending on state, so a macro bound to one will not find the
other. And menu contents can depend on context: an item present with a document open may
vanish without one. Prefer a keyboard shortcut when the command has one.

### Pressing controls in any application

`menu` only reaches the menu bar. For anything else (a toolbar button, a palette tab, a
checkbox) use `ui`, which searches the application's whole Accessibility tree and presses the
control **by name**:

```json
{ "type": "ui", "element": "Essentials", "app": "Adobe Illustrator" }
```

Add `"role": "AXButton"` to disambiguate, or `"matchIndex": 1` when a name appears more than once.
The search is breadth-first, so the shallowest match wins: usually the control itself rather
than a label nested inside it. Your pointer never moves.

In the editor, choose `ui`, click **Pick…**, and point at the control. After a three-second
countdown MXControl reads whatever is under the cursor and fills in its name, role and owning
app, which beats guessing what a control calls itself.

### When Accessibility can't see it

Some applications draw panels that expose nothing to Accessibility; Adobe's are notorious.
That is what `click` is for, and it is a genuine last resort:

```json
{ "type": "click", "x": 240, "y": 96, "relativeTo": "window", "app": "Adobe Illustrator" }
```

Coordinates are measured from the **window's top-left corner**, not the screen's, so moving the
window does not break the binding. Resizing it still will, as will rearranging panels or
changing which panels are open. The pointer is moved, clicked, and put back where it was.

Prefer `menu` over `ui`, and `ui` over `click`. Each step down that list is more fragile.

### Typing text

```json
{ "type": "text", "text": "Best regards,\nAlex", "pressReturn": true }
```

Sent as unicode rather than simulated key codes, so any character works on any keyboard layout.

Plain `text` is stored in `bindings.json` as-is: fine for signatures and boilerplate, wrong for
anything sensitive, since that file is readable by any process running as you and goes into
Time Machine.

### Secure text

A `text` action has three protection modes:

| Mode | Stored | Prompt | Use for |
|---|---|---|---|
| Plain text | in `bindings.json` | none | text you would not mind anyone reading |
| **🔒 Keychain** | macOS Keychain | **none** | anything you would rather not leave in a readable file |
| 🔒 Touch ID / Password | macOS Keychain | on use, reusable 5 min | when you want a deliberate confirmation |

The middle one is the answer for most people. The config file then holds only a reference:

```json
{ "type": "text", "secretRef": "chord-4F2A…", "pressReturn": true }
```

Even with no prompt, that is a real improvement over plain text: the value is encrypted at rest,
the Keychain ACL is enforced by the OS against this app's code signature so other applications
cannot read it silently, and it is excluded from plaintext Time Machine backups.

Encrypting `bindings.json` itself would not have achieved any of that. The app must decrypt
unattended, so the key would have to sit on disk beside the ciphertext and anything running as
you could read both. That is obfuscation, not encryption, which is why secrets live in the
Keychain instead.

The third mode is labelled **Touch ID** only on Macs that have it. Elsewhere the same setting
prompts for the login password, and the menu says so rather than promising biometrics that do not
exist.

Entering a secret uses a secure text field, which makes macOS turn on **Secure Input Mode** while
you type it. That blocks event taps, and HID-level tools such as Karabiner-Elements, from seeing
the one time the value is actually typed by hand.

One limit worth stating plainly: whichever mode you choose, the value is emitted as synthetic key
events when the macro fires, and anything holding Input Monitoring can observe them, exactly as
it could observe you typing it yourself. Storing it reduces total exposure, since it is typed by
hand once instead of every time.

What is worth protecting is your call. The app cannot know whether a string is a signature, an
API key, a licence or a passphrase, so it offers the choice rather than guessing.

### Two honest caveats

**Held thumb and wheel buttons** have their own click deferred until release, because until then
the app cannot know whether a macro is coming. There is deliberately no timeout that delivers
the press mid-hold; take as long as you like deciding on the second button.

**Left and right are never withheld.** They pass straight through, so dragging and context menus
behave exactly as they always did. When a macro fires while one of them is held, Escape is sent
to dismiss the context menu or cancel the drag.

### Why macros instead of button remapping

HID++ can "divert" a button: the firmware stops emitting the normal event and sends it to
software instead. That is how Options+ remaps buttons, and it has a nasty failure mode: if
the controlling app dies while buttons are diverted, those buttons are **dead**, not merely
un-customized, until something restores them.

An event tap inverts that. If MXControl crashes, the tap dies with it and every button is
instantly native again. It also works on Left and Right click, which are *not* divertable at all
(they report HID++ flags `0x01`, with no `divertable` bit), and it works with non-Logitech mice.

---

## Diagnostics

The fastest way: choose **Copy Diagnostics** in the menu. It puts a full report on the
clipboard: app and macOS version, permission status, engine state, the device's transport,
HID++ version, complete feature table and decoded settings, and the shape of your macros with
their contents redacted (buttons and action types only; commands, text and secrets stay on
your machine). **Paste it into any issue**; it answers nearly every question about unfamiliar
hardware.

When the app itself will not run, `mxprobe` is the standalone fallback: a read-only HID++
dumper that never writes to the device.

```bash
swiftc -O -o mxprobe mxprobe.swift
./mxprobe
```

It prints the transport in use, the negotiated HID++ version, the device's full feature table,
and decoded state for battery, wheel, DPI and buttons.

---

## How it works

| File | Role |
|---|---|
| `HIDPP.swift` | Transport. Report descriptor parsing, request/response matching, dedicated run-loop thread |
| `MXDevice.swift` | Typed feature operations: battery, wheel, DPI, hi-res, thumb wheel, hosts, report rate |
| `MXController.swift` | Device lifecycle, reconnect/wake reapply, preference storage |
| `Bindings.swift` | Macro model and JSON config |
| `Actions.swift` | Action execution |
| `ChordEngine.swift` | CGEventTap, macro detection, suppression and replay |
| `main.swift` | Menu bar UI |

If you're extending it, read [HACKING.md](HACKING.md) first; it holds the engine safety rules
and the list of paths that lack real-world mileage. A few hardware things worth knowing:

- **Which HID++ reports exist is read from the report descriptor at runtime.** The same mouse
  declares only report `0x11` over Bluetooth LE but both `0x10` and `0x11` over USB. Hardcoding
  either one breaks the other transport.
- **Replies are zero-padded to the full report length**, so response length tells you nothing
  about which fields are populated. Discriminate on feature ID.
- **Read-back is not behavior.** On the MX Master 3S, the SmartShift threshold always reads back
  as `10` regardless of what was written, yet the written value demonstrably changes how the
  wheel feels. Don't use a register read to conclude a tactile setting has no effect, and don't
  remove user-facing options on that basis.

---

## Not implemented

- Notarized release builds. Build from source.
- An editor for `sequence` actions. They work, and survive the editor untouched, but must be
  written in JSON.

---

## Credits

The HID++ 2.0 protocol is undocumented by Logitech. Public understanding of it comes from years
of community reverse engineering, principally [Solaar](https://github.com/pwr-Solaar/Solaar) and
[libratbag](https://github.com/libratbag/libratbag). No code was taken from either project, but
the feature IDs and function numbers this app relies on are knowledge those projects established,
and it would not exist without them.

## Disclaimer

Not affiliated with, endorsed by, or connected to Logitech. "Logitech", "MX Master", "MagSpeed",
"Options+", "Unifying" and "Bolt" are trademarks of Logitech International S.A., used here only
to describe compatibility.

This software talks directly to your mouse's firmware. It only calls documented HID++ feature
functions and never touches firmware update, device reset, or manufacturing features, but it is
provided without warranty. See [LICENSE](LICENSE).

## License

mxcontrol

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README