Open Source six degree of freedom (6 DOF) mouse with keys, encoder and more

Repository for a 3D mouse, which emulates a 3Dconnexion "Space Mouse Pro wireless".

This repository is NOT affiliated with 3Dconnexion. We just reverse-engineered the USB protocol.

Newest Stable Release

<!-- This release list should hold the latest three releases. The new feature descriptions are placed up here. When the release is not so new anymore, the paragraphs with the feature should be moved down to the other features. -->

Check-out the Release Page for the newest releases and updates!

• Version 3.0:
  • Shortened config parameters reducing program size
  • ProgMode allows setting parameters remotely over a defined language.
  • Check the release page 3.0, because this major release needs a slight adjustment of your config file!
  • inserted a hysteresis into the exclusive mode to prevent immediate switching back and forth between Trans- and Rot-mod: EXCL_HYST, see Exclusive Mode.
• Version 2.1:
  • The modifier function has a html page, where you can visualize the effect of the chosen parameters.
  • Changing Sensitivity and Direction on Windows in the 3Dx Settings works. Update to 3DxWare: 10.9.7.709, 3DxWinCore: 17.9.7.21845. Tested on Win 11 24H2.
  • Added testConfigCompileSize.py to calculate the required program size for different configurations. The results can be seen here: Build report. There is no continuous integration jet. This page must be created manually.
• Version 2.0: Serial Menu, Store parameters in EEPROM, new modifierFunction and Drift-compensation
  • Generally enhanced serial menu for debug outputs
  • Changing and evaluation of parameters without recompiling and download: editing and handling the parameters on the controller via the serial (debug-)connection
  • Save those parameters permanently into the EEPROM or print them for the config.h
  • Enhancements on exclusive-mode for resistive joysticks, like prio-z-exclusive mode
  • Drift-compensation for hall-joysticks to stop movements when not touched
  • New modifier function to have better control over the form of the curve
  • CalcMinMax: no need to reset/reboot after use, you can now rerun it without reboot

Upcoming Work

For the next release, already to be found in master:

• Python API to interact witht he progMode. Check out SpaceMouseAPI.py

Shortened config parameters

To reduce the program size, the parameters in the config.h have been shortened. Therefore your old config.h will not work out of the box, but you need to rename the parameters. As a conversion is necessary, this is named release version 3.

As this may be annoying, this is supported by this script: ParameterRenamingV3.py

Complete description of the project

This repository contains the software for a 3D mouse with six degrees of freedom (6 DOF), which emulates a 3Dconnexion "Space Mouse Pro wireless".

This repository is NOT affiliated with 3Dconnexion. We just reverse-engineered the USB protocol.

The software in this repo supports two different hardware variants:

1. The usage of joysticks (either resistive joysticks or hall-effect joysticks)
2. The usage of four hall-effect sensors which directly measure the distance two four magnets.

The joysticks version gained popularity through this TeachingTech YouTube Video. To see many features in place, like the buttons and the encoder with joysticks, check out the different versions by Jose L. González, like the ErgonoMouse MK XX - 6DOF Controller Knob & Joystick with Wheel, Buttons & Keys

The Hall-Effect-Sensor + Magnet version is greatly described here by John Crombies space mouse with linear hall effect sensors and improved with TPU springs.

Other implementations, hardware or mechanic variants are linked below.

Features of this software for the 6 DOF mouse

General Features

• Source code for an Arduino Pro Micro
• Read eight analog inputs and calculate the kinematics (either based on four joysticks or eight linear hall effect sensors) with advanced modifier function.
• Emulation of the USB identification and the HID interface to behave like an original space mouse
• Advanced USB settings for linux users: Implemented jiggling or declaring the HID reports as relative or absolute values, see spacenav
• Semi-Automatic calibration methods to find the correct pin outs and measurement ranges
• Debug outputs can be requested over the serial interface from a menu for debug outputs
• Changing and evaluation of parameters without recompiling and download: editing and handling the parameters on the controller via the serial (debug-)connection
• Save those parameters permanently into the EEPROM or print them for the config.h
• Exclusive-Mode: Transmit either translation or rotation and set the other one to zero, depending on what the main motion is.-
• Drift-compensation for hall-joysticks to stop movements when not touched

Buttons

• Over ten keys may be reported to the PC via USB and may be evaluated by the original driver software
• Kill-Keys: Press one of two buttons to disable translation or rotation directly in the mouse and transmit just the other one.

Encoder / Wheel

• An encoder wheel can be used to replace one axis and allow e.g. zooming
• Check out the config_sample.h for more information about configurable elements and extensive debug outputs
• The encoder can simulate consecutively pressed buttons (e.g. volume +), see Rotary Keys

LEDs

• LED can be enabled by the PC driver
• Support for a LED ring, as supported by the FastLED library. E.g. a neopixel

Wanted features, not jet there:

• With all features enabled, the pro micro is nearly at the limits of it's flash. Reducing the flash size might be necessary in the future...
• The html page explaining the modifier function would benefit from an additional plot zooming in on zero.

Purchasing the electronics and printing some parts is not scope of this repository. We start with the software. Feel free to read some build reports:

• In the Wiki: Building an Ergonomouse based on four joysticks

Macro-Pad for CAD users

The original 3Dconnexion windows driver is very elegant to detect which program you are running and offering custom actions for the keys on a space mouse. You can utilize this behavior and build a space mouse with keys, just without the central part, the space mouse itself. You are left with keys, that you can assign to actions for your CAD program. This comes handy, if your original spacemouse doesn't have enough keys. In this case your PC will see an additional mouse where only the keystrokes are send and evaluated.

Getting Started with PlatformIO

You can use PlatformIO to flash the board with this fast steps. PlatformIO is easier than ArduinoIDE, because you don't need to change the board.txt files there.

1. Install PlatformIO.
2. Download or clone this github repository (hint for windows: network locations are not recommended)
3. Rename the config_sample.h to config.h
4. Open PlatformIO / vscode and open the newly created folder.
5. Click on the upload arrow in the IDE in the status bar or run pio run -t upload.
6. Assign the pins of the joysticks and go through the calibration
7. Use your space mouse
8. Done!

Getting Started with Arduino IDE

1. Create a custom board in your Arduino IDE, that emulates the original space mouse
2. Download or clone this github repository
3. Rename the config_sample.h to config.h
4. Try to compile and flash your board
5. Assign the pins of the joysticks and go through the calibration
6. Use your space mouse
7. Done!

Custom board to emulate the space mouse

The boards.txt file needs an additional board definition, which tells the microprocessor to report the USB identifiers correctly and emulate the 3dconnexion space-mouse. Please follow the detailed instructions on the wiki page about custom board definition.

Cloning the github repo

Clone the github repo to