Upright

Open-source button remapping for Logitech mice on macOS, without Logi Options+.

Website: upright.hellobasalt.dev · MX Vertical on Mac · Download

Upright is a small native SwiftUI menu-bar app. It remaps Logitech mice over HID++: the thumb buttons, the top (DPI) button, the wheel click and any other button a mouse lets software take over. It also adds pointer-speed, scrolling and battery features. It talks to the mouse directly over the publicly documented HID++ 2.0 protocol, the same approach used by Solaar, LogiOps and libratbag. It doesn't use a kernel extension or a background daemon, and it doesn't include any Logitech software.

Upright works with any Logitech HID++ 2.0 mouse that exposes programmable buttons (REPROG_CONTROLS_V4), and with several mice at once, over any mix of USB cable, Bluetooth and Unifying, Bolt or Nano receivers. It was built and tested on the MX Vertical, which is the only model verified on real hardware. Every other model is built from published device data and tested against Upright's mouse simulator only. See Supported devices.

Both pictures are rendered by Demo Mode with simulated mice (an MX Vertical, an MX Master 3S and a Lift, with made-up names and batteries). They show the real interface, not real hardware.

Features

• Remap buttons. Back, Forward, the Top (DPI) button, the Wheel Click and any other divertable button a mouse reports. Actions:
  • built-in system actions: Mission Control, App Exposé, Show Desktop, switching Spaces, Back/Forward, tabs, media keys, Spotlight, screenshots, Lock Screen, Copy/Paste/Undo/Redo, middle click and mouse buttons 4/5
  • any recorded keyboard shortcut
  • Open App, Open URL and Run Shortcut (a Shortcuts.app shortcut, by name)
  • Pointer speed: cycle through your presets, or jump to a fixed DPI (mice with ADJUSTABLE_DPI, 0x2201, only)
  • Easy-Switch: move the mouse to another paired computer (mice that report the Easy-Switch feature)
  • Do Nothing, or Default to leave the button to the mouse
• Several mice at once. Every connected mouse is listed in the menu-bar panel and in Settings → Mice, with its connection, state and battery. See Using several mice.
• Per-model mappings. Each mouse model has its own button setup and its own per-app profiles. Choose which model you are editing with the Configure picker in Settings → Buttons. You can set up a catalog model before you own it, copy a setup from another model, or use one setup for all your mice.
• Gestures. Set a button to Gestures to get five actions: a click, plus hold and move up, down, left or right. The mouse reports raw movement while the button is held, so the cursor doesn't move. If a button can't report raw movement, Upright falls back to watching the cursor, which does move during the gesture (the Buttons pane says so).
• Per-app profiles. Keep a global table and add apps (by bundle ID) that override single buttons while they are frontmost. A button without an override uses the global action, and an override can also hand a button back to the mouse in that app.
• Per-mouse settings. Give a mouse a nickname, switch Remap this mouse off to hand all its buttons back, and keep its pointer speed. Upright remembers these for each physical mouse and lists mice it has seen before under Not Connected.
• Pointer speed (DPI). Set the speed with a slider, keep a list of presets, and pick a speed to apply whenever a mouse reconnects. Speeds snap to what the mouse supports. Mice without 0x2201 don't get pointer-speed controls.
• Device info. Firmware, serial number, battery, connection type, the Easy-Switch channel (with host names when the mouse stores them), the HID++ feature table and the control list, plus a Copy Device Report button for bug reports and new-model requests.
• Battery. Reads the level when a mouse connects and about every 10 minutes. Mice that report only a coarse level (critical, low, good, full) show an approximate value such as "~50%". Low-battery notifications at 15% and 5% per mouse (on by default; macOS asks for notification permission the first time), and an optional percentage next to the menu-bar icon (with several mice it shows the lowest).
• Scrolling. Reverse the mouse wheel independently of the trackpad, change the speed (0.5x to 3x), and try the experimental smooth scrolling. All off by default. These settings apply to every mouse wheel; see Scrolling.
• Export and import of all mappings and profiles, for every model, as a JSON file.
• First-run onboarding for new installs: connect, allow Accessibility, choose a setup.
• Robust reconnection. Button diversion is reapplied after a mouse sleeps or is switched off and on, after the Mac wakes, and when a receiver or cable is replugged. Each mouse is retried on its own with backoff, so a sleeping mouse doesn't hold up another one.
• Leaves nothing behind. Buttons are only temporarily diverted. When Upright quits it hands them back, and power-cycling a mouse always restores factory behavior. Nothing is written to a mouse's memory.
• Demo Mode. --demo runs the real interface against simulated mice, and --export-snapshots renders it to PNG files. See Demo Mode.
• Feels native. A menu-bar panel, a System Settings-style window, SF Symbols, light and dark mode. Open at Login uses SMAppService.
• Explains permissions. It shows what it needs and why. Until Accessibility is granted, mappings that need it are not applied and the buttons keep their normal behavior.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗