Websockets exposer for the spacenav driver (spacenav‑ws)

Table of Contents

• About
• Prerequisites
• Usage
• Development

About

spacenav‑ws is a tiny Python CLI that exposes your 3Dconnexion SpaceMouse over a secure WebSocket, so Onshape on Linux can finally consume it. Under the hood it reverse‑engineers the same traffic Onshape’s Windows client uses and proxies it into your browser.

This lets you use FreeSpacenav/spacenavd on Linux with Onshape.

Prerequisites

• uv/uvx or another Python env manager.
• A running instance of spacenavd
• A modern browser (Chrome/Firefox) with a userscript manager (Tampermonkey/Greasemonkey)

Usage

1. Validate spacenavd

uvx spacenav-ws@latest read-mouse
# → should print spacemouse events

2. Run the server and trust the cert

uvx spacenav-ws@latest serve

Now open: https://127.51.68.120:8181. When prompted, add a browser exception for the self‑signed cert.

3. Install Tampermonkey and add the userscript

Install Tampermonkey. After installing, click this link for one‑click install of the script.

4. Open an Onshape document and test your mouse!

Developing

git clone https://github.com/you/spacenav-ws.git
cd spacenav-ws
uv run spacenav-ws serve --hot-reload

This starts the server with Uvicorn's code watching / hot reload feature enabled. When making changes the server restarts and any websocket state is nuked, however, Onshape should immediately reconnect automatically! This makes for a very smooth and fast iteration workflow.