This project is under active development. Contributions and feedback are welcome.
Use your 3Dconnexion SpaceMouse as a desktop input device on Linux. Tilt to scroll, push/pull to zoom, twist to switch virtual desktops — and it works natively inside Blender and FreeCAD for 3D navigation.
- Arch Linux (or Arch-based like EndeavourOS, Manjaro)
- 3Dconnexion SpaceMouse connected via USB
- yay or paru (AUR helper) — if you don't have one, install yay
git clone https://github.com/Maik-0000FF/SpaceMouse_3dconnexion.git
cd SpaceMouse_3dconnexion
./install.shThe installer takes care of everything: installing packages, setting up permissions, compiling the driver, and starting the background services. You'll be asked for your password when it needs administrator access.
After installation, plug in your SpaceMouse (or unplug and replug it) and it's ready to use.
Once installed, the SpaceMouse works on your desktop like this:
- Tilt left/right → horizontal scroll
- Tilt forward/back → vertical scroll
- Push down / pull up → zoom (Ctrl+scroll)
- Twist left/right → switch virtual desktops
- Left button → KDE Overview
- Right button → Show Desktop
When you switch to Blender or FreeCAD, the desktop driver steps aside automatically and the app's native 3D navigation takes over — no manual switching needed.
A system tray icon appears in your taskbar. Click it to open SpaceMouse Control — a settings app with three pages:
- Desktop — sensitivity, axis mapping, deadzone, button actions
- FreeCAD — SpaceMouse sensitivity, axis enable/invert, per-axis deadzone, navigation style
- Blender — NDOF sensitivity, deadzone, axis inversion, Lock Horizon toggle
| Desktop | FreeCAD | Blender |
|---|---|---|
 |
 |
 |
A live preview bar at the bottom shows real-time axis movement and button state. While the settings window is focused, desktop actions are automatically disabled so the SpaceMouse doesn't interfere while you configure it.
FreeCAD and Blender connect directly to spacenavd — they don't need the GUI or daemon running. You can close SpaceMouse Control completely and 3D navigation keeps working. Settings are written to each app's config file and persist across restarts.
Blender works out of the box — no extra setup needed.
To configure Blender's SpaceMouse settings from the GUI:
- Open SpaceMouse Control (tray icon) → Blender page
- Adjust sensitivity, deadzone, axis inversion, etc.
- Click Apply
- Click Install Startup Script (first time only)
- Restart Blender — settings are applied automatically on every launch
Tip: If pitch/tilt doesn't work in Blender, make sure Lock Horizon is OFF (Blender enables it by default, which blocks the pitch axis).
FreeCAD on Linux has several SpaceMouse issues. We've contributed fixes upstream — some are already merged, others are in progress. Until all fixes reach stable releases, you can build a fully patched version yourself.
Availability: PRs #28110 and #28181 are merged into FreeCAD
main. PR #28110 is in weekly builds since 2026-03-11, PR #28181 since 2026-04-01. Both will be in FreeCAD 1.2. PR #28915 (disconnect detection) is open with approvals. None of these fixes are in FreeCAD 1.0.x or 1.1.x (including 1.1.0).
| Fix | Issue | Status | Description |
|---|---|---|---|
| Event coalescing | PR #28110 | Merged (weekly 2026-03-11) | Fixes jerky navigation (250Hz → 60fps) |
| Batched camera updates | PR #28110 | Merged (weekly 2026-03-11) | Prevents double redraws per frame |
| Per-axis deadzone | PR #28110 | Merged (weekly 2026-03-11) | Configurable deadzone per axis via user.cfg |
| Button selection sync | PR #28181 | Merged (weekly 2026-04-01) | Fixes wrong button assignment in preferences |
| Checkable action invoke | PR #28181 | Merged (weekly 2026-04-01) | Fixes camera toggle buttons not working |
| Disconnect detection | PR #28915 | Open (approved) | Fixes 100% CPU when spacenavd stops |
| Reset button fix | #19366 | Patcher only | Fixes Spaceball button dialog reset not updating |
A single pattern-based Python patcher (freecad-patches/apply-spacemouse-fix.py) applies all seven fixes to any FreeCAD version. It finds code by pattern matching — no line numbers, no version-specific patches. Already-merged fixes are automatically skipped.
Target versions: FreeCAD 1.0.x and 1.1.x (including 1.1.0 stable) — these versions need all seven fixes. Starting with weekly 2026-04-01 (and FreeCAD 1.2), fixes 1–5 are included natively and the patcher skips them automatically. Fixes 6–7 are still applied by the patcher on all versions.
# Check what can be patched (dry-run)
python3 apply-spacemouse-fix.py --check /path/to/freecad-source
# Apply all fixes
python3 apply-spacemouse-fix.py /path/to/freecad-sourceThe patcher is a single Python file with no dependencies — it can be used standalone without installing this project:
curl -O https://raw.githubusercontent.com/Maik-0000FF/SpaceMouse_3dconnexion/main/freecad-patches/apply-spacemouse-fix.py
python3 apply-spacemouse-fix.py /path/to/freecad-sourceFor technical details, see docs/FREECAD_SPACEMOUSE_FIX.md.
Choose your version by editing freecad-pacman-build/PKGBUILD — change _build_version at the top:
| Setting | Version | Description |
|---|---|---|
_build_version="stable" |
1.1.0 | Latest stable release (needs all 7 patches) |
_build_version="weekly" |
main | Latest development build (only needs patches 6–7) |
cd freecad-pacman-build
makepkg -sfiThis downloads the source, applies the patcher, compiles, and installs as a normal Arch package. Takes 15–45 minutes depending on your CPU.
After a system update (
pacman -Syu), FreeCAD gets replaced with the stock version. Just runcd freecad-pacman-build && makepkg -sfiagain.
- Start FreeCAD once and close it (creates config files)
- Run the setup script:
./scripts/freecad-spacemouse-patch.sh - Or use SpaceMouse Control → FreeCAD page to adjust settings
Important: Always close FreeCAD before editing settings. FreeCAD overwrites its config on exit.
./uninstall.sh- Check that the device is plugged in:
lsusb | grep -i 3dconnexion - Check that the system daemon is running:
systemctl status spacenavd - Run the built-in diagnostic:
spacemouse-test --check
If spacenavd isn't running:
sudo systemctl enable --now spacenavdYou're running an unpatched FreeCAD. The fix (PR #28110) is merged but may not be in your installed version yet. Rebuild with the patcher:
cd freecad-pacman-build && makepkg -sfiKnown bug (#17809), fix submitted as PR #28915. When spacenavd crashes or stops, FreeCAD's QSocketNotifier loops on the dead socket. Build a patched version with the patcher to fix this, or restart FreeCAD after restarting spacenavd.
systemctl --user restart spacemouse-configOpen the tray icon settings and check that button actions are set (default: Left = Overview, Right = Show Desktop).
spacemouse-test --check # System checks (USB, spacenavd, uinput)
spacemouse-test --live # Real-time axis and button monitor
spacemouse-test --led # LED toggle test| Device | Status |
|---|---|
| SpaceNavigator (046d:c626) | Tested (fully working, including LED control) |
| SpaceMouse Compact | Should work (untested) |
| SpaceMouse Wireless | Should work (untested) |
| SpaceMouse Pro (Wireless) | Should work (untested) |
| SpaceMouse Enterprise | Should work (untested) |
Any 6DOF device supported by spacenavd should work. LED control currently only works for the SpaceNavigator — other models may use different HID report formats.
GPLv3 — See LICENSE for details.
This project is actively maintained. Current focus: desktop navigation and 3D app integration.
FreeCAD upstream contributions:
