OpenSharkMacOS

Open-source macOS configurator for the Attack Shark R1 wireless gaming mouse — a native SwiftUI app (plus a CLI) built from scratch by reverse-engineering the device protocol. No third-party software required at runtime.

The official Attack Shark software is Windows-only and there is no public protocol documentation. This project reverse-engineers the mouse's HID protocol and talks to it directly through macOS IOKit, so you get button remapping and scroll control on the Mac.

Features

• Native GUI — a SwiftUI app with a vector drawing of the R1: click a button on the mouse, pick an action. Native materials, animations, hover/selection states, keyboard navigation, VoiceOver labels.
• Button remapping — all 6 buttons (left, right, middle, DPI, the two side buttons) → mouse functions, page navigation, media keys, or any keyboard shortcut. Written to the mouse's onboard memory.
• Per-device scroll inversion — flip the mouse wheel direction while keeping the trackpad's "natural" scrolling untouched. Runs as a login agent.
• CLI — script everything (r1 set back key:cmd+left, etc.).

Out of scope for now: DPI/RGB configuration and macros.

Requirements

• macOS 14+
• Attack Shark R1 (USB-C cable or 2.4 GHz dongle — VID 0x1D57, PID 0xFA60/0xFA61)
• Xcode command line tools (Swift 5.9+)

Install

Download (easiest)

1. Grab the latest OpenShark-vX.Y.Z-macos.zip from Releases.
2. Unzip and move OpenShark.app to /Applications.
3. The app isn't notarized yet, so the first launch is blocked by Gatekeeper — right-click the app → Open → Open (only once), or run:

   xattr -dr com.apple.quarantine /Applications/OpenShark.app

4. On first use, grant Input Monitoring (System Settings → Privacy & Security → Input Monitoring → enable OpenShark) and reopen the app.

Build from source

git clone https://github.com/Pl3ntz/OpenSharkMacOS.git
cd OpenSharkMacOS
swift build -c release
bash scripts/make-app.sh release   # bundles dist/OpenShark.app (with icon)
open dist/OpenShark.app

make-app.sh wraps the SwiftPM executable into a .app (a bare SwiftPM executable won't show a window). For the CLI: swift build then .build/debug/r1 --help.

Permissions

macOS gates access to HID devices that can act as keyboards/mice.

• Input Monitoring — required to talk to the mouse (button remapping + connection detection). On first run the app/CLI requests it; grant it under System Settings → Privacy & Security → Input Monitoring, then quit and reopen the app.
• Accessibility — required only for scroll inversion (it uses a CGEventTap).

Heads-up for developers: the dev build is ad-hoc signed, so every rebuild changes the binary's hash and macOS revokes Input Monitoring. If the app stops detecting the mouse after a rebuild, reset and re-grant:

tccutil reset ListenEvent com.openshark.app
open dist/OpenShark.app   # grant the fresh prompt, then reopen

A stable code-signing certificate makes the permission persist across rebuilds.

Usage — GUI

Click a button on the mouse drawing (or use the arrow keys) to select it, then pick an action on the right. Changes apply to the mouse immediately and are saved to a profile.

Usage — CLI

r1 show                    show the current profile
r1 set <button> <action>   remap a button (applies immediately)
r1 reset                   restore factory defaults
r1 apply                   re-apply the saved profile (e.g. after reconnect)
r1 actions                 list available actions
r1 scroll-invert           invert mouse-wheel scroll (trackpad untouched)

Buttons: left right middle dpi forward back

Actions: left-click right-click middle-click back forward double-click scroll-up scroll-down dpi-cycle dpi-up dpi-down disabled page-back page-forward media-next media-prev play mute volume-up volume-down, or a keyboard shortcut via key:<combo> — e.g. key:cmd+c, key:ctrl+shift+4, key:f13.

r1 set back  key:cmd+left    # side-rear button → browser Back
r1 set forward key:cmd+right # side-front button → browser Forward
r1 set dpi   middle-click

Browser page navigation: the firmware's own "browser back/forward" codes do not trigger navigation on macOS — use the keyboard shortcuts cmd+left / cmd+right (the GUI's "Navegação" presets do this for you).

Usage — scroll inversion (permanent)

Run r1 scroll-invert once to test, then install it as a login agent so it's always on. Example LaunchAgent: ~/Library/LaunchAgents/com.r1ctl.scroll-invert.plist running the installed binary with the scroll-invert argument (RunAtLoad + KeepAlive). Grant Accessibility once. See docs/PROTOCOL.md for details.

How it works

The R1 exposes a vendor HID interface (usage page 1 / usage 0x80, 64-byte feature reports). Button mapping is written via feature report 0x08; the firmware ACKs on report 0x03. Scroll inversion is done on the macOS side with a CGEventTap because the firmware has no scroll-invert feature.

Full reverse-engineered protocol: docs/PROTOCOL.md.

Project layout

Sources/R1Kit/         protocol + IOKit transport (no UI) — Action, Button, ReportBuilder, HidTransport, ScrollInverter, Profile
Sources/r1/            CLI
Sources/OpenSharkApp/  SwiftUI app (MouseView, InspectorView, ContentView)
Tests/R1KitTests/      codec golden-vector tests
scripts/make-app.sh    bundle the GUI into a .app
docs/PROTOCOL.md       reverse-engineered HID protocol

Roadmap

• Reapply the button profile automatically on reconnect (the mouse forgets buttons when it powers off)
• Scroll-inversion toggle inside the GUI
• Stable code signing / notarized .app for distribution
• Macros (feature report 0x09)

Disclaimer

Not affiliated with, endorsed by, or sponsored by Attack Shark. "Attack Shark" and "R1" identify hardware compatibility only. The protocol was reverse-engineered for interoperability. Use at your own risk — writing to device firmware always carries some risk.

Credits

Protocol work informed by the community Linux driver xb-bx/attack-shark-r1-driver (covers DPI/polling/sleep; button remapping was reverse-engineered here).

License

MIT — see LICENSE.