In this article I show step by step how I got my 3Dconnexion SpaceMouse working in Linux with Onshape.

Introduction

If you are an engineer and interested in using Linux instead of Windows, you probably ran into the problem that a decent CAD package is not really supported. Although FreeCAD has a version 1 now, I don’t see this as a professional alternative yet. Fortunately we can use Onshape, a browser-based professional CAD package, which also runs on Linux. However, if you have invested in a SpaceMouse and got used to it, you will be quickly disappointed to find out that this doesn’t work. To me this was starting to become a deal-breaker and was on the verge of running my CAD software in a virtual machine running Windows. This would have been far from desirable and yet again shows that there is always something in the way of making the full shift to Linux. Until I found this discussion.

Very cool to see this interaction and getting to a result like this. I had to do several steps to make it work like I want it to. Just open Onshape in a tab and get right to work with my SpaceMouse in a way that I’m used to. No prior actions needed.

Installation steps

First of all, although I’m using Linux for almost 2 decades now, I’m not an expert and some steps could probably be done better or with less steps. While everything can be done using the terminal, several steps are done from the GUI. Steps formatted like this are done in the terminal. The method I’m about to describe works for me on two separate machines, both running Linux Mint 22.1, one with a SpaceMouse Wireless and the other SpaceMouse Pro Wireless Bluetooth Edition.

Tested with

• OS: Linux Mint 22.1 Cinnamon kernel 6.8.0-64-generic
• Devices: SpaceMouse Wireless, SpaceMouse Pro Wireless Bluetooth Edition
• Browser: Brave 1.80.122 installed from Software Manager

I think that this also works with other Linux versions, other devices and another browser. This happens to be my system and fortunately it is pretty common. Please let me know if you have things running on a different setup or run into issues. It would be nice if we can get more setups verified.

Install spacenavd

This is the regular driver to make the mouse work with Linux. Note that we don’t use the Linux driver from 3Dconnexion themselves. If you have already installed this, you can probably uninstall it. I don’t know if this driver will interfere with our method.

Alright, install spacenavd by sudo apt-get install spacenavd

Connect the CAD mouse. If you have a Bluetooth version, this can be done using the standard Bluetooth Devices app in settings.

The SpaceMouse should work now. To test this I installed FreeCAD from the Software manager and opened the PartDesignExample. It moves, but feels odd. Go to Tools -> Customize -> Tab: Spaceball motion and enable Flip Y/Z. It still feels laggy — it seems that only one axis can move at a time — but this will be better in Onshape.

Install spnavcfg

This is a GUI tool which we can use to configure our mouse. By default, the movements are way too sensitive in Onshape. I found parameters that “feel” very similar to what I’m used to in Fusion and SolidWORKS on Windows. I think that I got quite close.

Source: https://github.com/FreeSpacenav/spnavcfg

Dependencies

First we need to install dependencies to get this tool working.

Install libspnav

Don’t install this from the package manager! Don’t do sudo apt-get install libspnav-dev or install it using Synaptic Package manager. This doesn’t work. Instead, go to https://github.com/FreeSpacenav/libspnav and download the GitHub repository as a zip-file and extract it in the file manager. Extracting in the file manager can be done by right-clicking on the zip-file -> Extract Here.

Navigate to the libspnav-master folder, right-click on an empty patch -> Open as Root. Right-click again in the new window with elevated privileges (with visible red bar) -> Open in Terminal. I find this the easiest way to get a terminal with root privileges at the right location.

./configure

make

make install

Install Qt

apt install qttools5-dev-tools qttools5-dev

Close the Root terminal and elevated file explorer.

spnavcfg

Now we can install the actual program. Like we did before, download the zip-file from the repository https://github.com/FreeSpacenav/spnavcfg, extract it, navigate to the folder, but don’t open the Terminal yet. We first need to replace the PNG files. Right now they are text files with a hash instead of PNG files. Go back to the Internet browser and open the icons folder in the GitHub repository. Click on the first PNG file, devices.png, right-click on the image, Save image as… and overwrite the PNG file in the icons folder within the spnavcfg-master we just extracted. Do this for all the PNG files. Remember to overwrite them! It will automatically add “(1)” after the file name if it already exists. Remove that and actually overwrite the files.

Once that’s done, right click in the spnavcfg-master folder in the elevated file browser and select Open in terminal, just like we did before.

./configure

make

make install

Now it should be installed without errors and when you type spnavcfg, you should be greeted by the window as shown below. If you get this error instead: ”pnavcfg: symbol lookup error: spnavcfg: undefined symbol: spnav_cfg_set_repeat”, uninstall libspnav-dev and libspnav0. You can do this easily using the Synaptic Package Manager (can be downloaded from the Software store). Repeat the steps of installing libspnav as mentioned earlier.

The window below doesn’t show the default values, but the values that work well in Onshape.

After setting the values, click on File -> Save config and press OK. Close the dialog.

Install spacenav-ws

This is the Web socket, the tool that sits between our installed driver and Onshape.

Source: https://github.com/RmStorm/spacenav-ws

Close all terminal windows and file browsers that have the elevated privileges. Just to be sure.

Install UV

This is the Python package we need to get spacenav-ws running.

curl -LsSf https://astral.sh/uv/install.sh | sh

spacenav-ws

source $HOME/.local/bin/env

uvx spacenav-ws@latest read-mouse and wait for the message: Start moving your mouse!. Well, move your mouse and see if this works.

Hit ctrl+c to get out of this. Then enter: uvx spacenav-ws@latest serve

This should show an IP address, https://127.51.68.120:8181/. Right-click on that link in the terminal, open it and you should see the input from the CAD mouse when moving it.

Check in Onshape if it works now https://cad.onshape.com/

If it does, close the terminal. This also stops the stream, but we want this running from the start. Go to Startup Applications from the Start menu, click on the + icon.
Name: Spacenav-ws
Command: uvx spacenav-ws@latest serve
Comment: Start Spacenav Web Sockets
Startup delay: 0 seconds

After a reboot, the SpaceMouse should work now with Onshape and you never have to think about it anymore!

If you run into any issues or have suggestions, don’t hesitate to contact me through the contact page.