Open Source Spacemouse with Keys

Repository for a space mouse, which emulates a 3Dconnexion "Space Mouse Pro wireless". It is based on four joysticks with an addition for keys.

This repository for the source code is based on the work by TeachingTech and many other contributors, as seen in the history. This is NOT affiliated with 3Dconnexion. We just reverse-engineered the USB protocoll!

Features of the space mouse

Source code for an Arduino Pro Micro to read four joysticks and calculate the kinematics
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
Semi-Automatic calibration methods to find the correct pin outs and measurement ranges
Debug outputs can be requested over the serial interface during run time, see config_sample.h
Over ten keys may be reported to the PC via USB and may be evaluated by the original driver software
"Kill-Keys" may disable translation or rotation directly in the mouse
An encoder wheel can be used to replace one axis and allow e.g. zooming
Check out the config_sample.h for more informations about configurable elements and extensive debug outputs
LED can be enabled by the PC driver

Wanted features:

Reverse Direction and Speed options in 3dConnexion Software is not working, because our spacemouse is not accepting this settings.

Purchasing the electronics and printing some parts is not scope of this repository. We start with the software.

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.

Install PlatformIO.
Clone this repo and open a terminal in the cloned directory.
Copy src/config_sample.h to src/config.h and change the values to whatever suits.
Run pio run -t upload or click on the upload arrow in the IDE.
Assign the pins of the joysticks and go through the calibration
Use your space mouse
Done!

Getting Started with Arduino IDE

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

Custom board to emulate the space mouse

The boards.txt file needs an additional Board definition, which tells the processor to report the USB identifiers correctly and immitate the 3dconnexion space-mouse.

boards.txt on linux

You find the boards.txt in ~/.arduino15/packages/SparkFun/hardware/avr/1.1.13. If this folder doesn't exist you need to install board support for SparkFun Arduinos.

boards.txt on mac

Please read https://gist.github.com/maunsen/8dbee2bddef027b04a450241c7d36668

boards.txt on windows

C:\Users\AppData\Local\Arduino15\packages\arduino\hardware

Code to add to boards.txt

Here is the addition, which needs to be copied into the boards.txt (e.g. at the bottom).

# Add this to the bottom your boards.txt

################################################################################
################################## Spacemouse based on Pro Micro ###################################
################################################################################
spacemouse.name=SpaceMouse

spacemouse.upload.tool=avrdude
spacemouse.upload.tool.default=avrdude
spacemouse.upload.protocol=avr109
spacemouse.upload.maximum_size=28672
spacemouse.upload.maximum_data_size=2560
spacemouse.upload.speed=57600
spacemouse.upload.disable_flushing=true
spacemouse.upload.use_1200bps_touch=true
spacemouse.upload.wait_for_upload_port=true

spacemouse.bootloader.tool=avrdude
spacemouse.bootloader.tool.default=avrdude
spacemouse.bootloader.unlock_bits=0x3F
spacemouse.bootloader.lock_bits=0x2F
spacemouse.bootloader.low_fuses=0xFF
spacemouse.bootloader.high_fuses=0xD8

spacemouse.build.board=AVR_PROMICRO
spacemouse.build.core=arduino:arduino
spacemouse.build.variant=promicro
spacemouse.build.mcu=atmega32u4
spacemouse.build.usb_product="Spacemouse Pro Wireless (cabled)"
spacemouse.build.usb_manufacturer="3Dconnexion"
spacemouse.build.vid=0x256f
spacemouse.build.extra_flags={build.usb_flags}

############################# Spacemouse Pro Micro 5V / 16MHz #############################
# deleted 3.3V / 8 Mhz variant to avoid bricking

spacemouse.build.pid.0=0xc631
spacemouse.build.pid.1=0xc631
spacemouse.build.pid=0xc631
spacemouse.build.f_cpu=16000000L

spacemouse.bootloader.extended_fuses=0xCB
spacemouse.bootloader.file=caterina/Caterina-promicro16.hex

Common issues with boards.txt:

TeachingTech video for proper instructions
Teaching Tech followed the instructions here from nebhead with two key differences:
- Changed the word 'DaemonBite' to 'Spacemouse' in all references.
- Changed the VID and PID values as per jfedor's instructions: vid=0x256f, pid=0xc631 (SpaceMouse Pro Wireless (cabled))

"pins_arduino.h" not found

Taken from

Windows 11, 2.3.2 Arduino IDE, AVR 1.8.6

I followed every setup step, but was getting complication error "pins_arduino.h" not found.

Checked the file - indeed, not existing, even though it is imported in core

Its the first time I interact with Arduino and I'm not sure if this was suppose to be auto copied or magic imported, but it didn't

Copying the config from variants\leonardo (in my case, I used the board TeachingTech recommended) to version root (...avr\1.8.6) solved it

Changes for Arduino 2.3.2

Check this issue. With Arduino IDE 2.3.2 and Arduino AVR board package 1.8.6 , a few changes in text pasted to boards.txt were needed

#spacemouse.build.variant=promicro
spacemouse.build.variant=leonardo 

#spacemouse.bootloader.file=caterina/Caterina-promicro16.hex
spacemouse.bootloader.file=caterina/Caterina-Leonardo.hex

Also SpaceMouse needs to be added to list of boards supported by Arduino AVR platform in package_index.json, so that you can select it in IDE.

        {
          "name": "SpaceMouse"
        },

Cloning the github repo

Clone the github repo to your computer: Scroll-Up to the green "<> Code" Button and select, if you wish to clone or just download the code.

Create your own config file

Copy the config_sample.h and rename it to config.h. This is done to avoid the personal config file being overwritten when pulling new updates from this repository. You probably have to update the config.h file with new additions from the config_sample.h, but your pin assignment will not stay.

Compiling and flashing the firmware

Open the Arduino IDE (1.8.19 and 2.3.2 are tested on Ubuntu).
Open spacemouse-keys.ino
Select Tools -> Board -> SparkFun AVR Boards -> Spacemouse.
(If you followed another boards.txt instructions, which also allow 3.3V with 8 Mhz: Make sure to select the proper processor: 5V 16MHz)
Select the correct port (see troubleshooting section, which might be necessary for first upload)
Compile the firmware

Troubleshooting uploading

Troubleshooting for uploading is explained in detail here:

Uploading firmware to the Pro Micro

Calibrate your hardware

After compiling and uploading the programm to your hardware, you can connect via the serial monitor. In the upper line, you can send the desired debug mode to the board and observe the output. "-1" stops the debug output.

Read and follow the instructions throughout the config.h file and write down your results. Recompile after every step.

This calibration is supported by various debug outputs which can toggle on or off before compiling or during run time by sending the corresponding number via the serial interface. All debug outputs are described at the top of your config_sample.h.

Check and correct your pin out -> Refer to the pictures in the Electronics section below.
Tune dead zone to avoid jittering
Getting min and max values for your joysticks
- There is a semi-automatic approach, which returns you the minimum and maximum values seen within 15s.
Adjust sensitivity
Choose modifier function:

Choose a modifier function with the help of the following picture. Note, that the Squared, Squared Tan and Cubed Tan function act like a deadzone filter, because small inputs are resulting in nearly zero output, which may reduced unwanted movements. Also note, that some of those functions are already at their maximum output (and therefore limited), before the input reaches 350.

Use the spacemouse

Download the 3dconnexion driver on windows and mac

You will also need to download and install the 3DConnexion software

If all goes well, the 3DConnexion software will show a SpaceMouse Pro wireless when the Arduino is connected.

spacenav for linux users

Checkout https://wiki.freecad.org/3Dconnexion_input_devices and https://github.com/FreeSpacenav/spacenavd.

Software Main Idea

The software reads the eight ADC values of the four joy sticks
During start-up the zero-position of the joystick is measured and subtracted from the adc-value. -> The values now range from e.g. -500 to +500
A dead zone in the middle is applied to avoid small noisy movements. (E.g. every value between +/- 3 is fixed to zero)
The movement of the joysticks is mapped from the original about ca. +/- 500 digits to exactly +/- 350. (Therefore the real min and max values will be calibrated) Now all further calculations can be done with this normalized values between +/-350.
We calculate the translation and rotation based on this.
Applying the modifiers to minimize very small rotations or translations.
Kill, swap or invert movements
Sending the velocities and keys to the PC, see also SpaceNavigator.md for further details about the emulated USB HID.

Printed parts

There are many parts and remixes available. A very good starting point is the Part Open source SpaceMouse - Space Mushroom remix by Teaching Tech. Check out the many remixes, especially if you want to use other joysticks modules!

Here are some of the remixes or additions that are used with this software:

Lid with mounting for 4 MX Switch adapter by LivingTheDream
SpaceMouse Mini - Slim profile, with easier assembly and various improvements - v3 by Doug Joseph
Hall Effect Joysticks For the Space Mouse by Kempy

Electronics and pin assignment

The spacemouse is connected to an arduino Pro Micro 16 Mhz. Check out the wiring diagram by TeachingTech or with this added keys:

The calculations in the program expect AX to be the vertical joystick in front of you and AY the horizontal in front of you. B, C and D are clockwise around the spacemouse. Maybe your joystick axis are named X and Y in an other orientation. That doesn't matter. Connect them and use the config.h file to put the pin the vertical joystick in front of you (=AX) to the first position. In teaching techs example, this is A1, even though his joystick is labeled "y".

The calculation in this programm results in X, Y and Z calculated as shown in the middle of the picture. If this doesn't suit your programm change it by using the INVX or SWITCHYZ afterwards.

Kinematics

With the axis defined as shown in the picture above, the calculations for translation and rotation are as follows:

TRANSX = -CY + AY
TRANSY = -BY + DY
TRANSZ = -AX - BX - CX - DX
ROTX = -CX + AX
ROTY = -BX + DX
ROTZ = AY + BY + CY + DY

History

This code is the combination of multiple works by others. This list summarizes what happened before this github repository was started:

Original code for the Space Mushroom by Shiura on Thingiverse: https://www.thingiverse.com/thing:5739462
The next two from the comments on the instructables page: https://www.instructables.com/Space-Mushroom-Full-6-DOFs-Controller-for-CAD-Appl/
and the comments of Thingiverse: https://www.thingiverse.com/thing:5739462/comments
Code to emulate a 3DConnexion Space Mouse by jfedor: https://pastebin.com/gQxUrScV
This code was then remixed by BennyBWalker to include the above two sketches: https://pastebin.com/erhTgRBH
Four joystick remix code by fdmakara: https://www.thingiverse.com/thing:5817728
Teaching Techs work involves mixing all of these: The basis is fdmakara's four joystick movement logic, with jfedor/BennyBWalker's HID SpaceMouse emulation. The four joystick logic sketch was setup for the joystick library instead of HID, so elements of this were omitted where not needed. The outputs were jumbled no matter how Teaching Tech plugged them in, so Teaching Tech spent a lot of time adding debugging code to track exactly what was happening. On top of this, Teching Tech has added more control of speed/direction and comments/links to informative resources to try and explain what is happening in each phase.
Code to include meassured min and max values for each Joystick by Daniel_1284580 (In Software Version V1 and newer)
Improved code to make it more userfriendly by Daniel_1284580 (In Software Version V2 and newer)
Improved Code, improved comments and added written tutorials in comments, by LivingTheDream Implemented new algorithm "modifier function" for better motioncontrol by Daniel_1284580 (In Software Version V3)
Moved the Deadzone detection into the inital ADC conversion and calculate every value everytime and use the modifier for better seperation between the access, By Andun_HH.
Added two additional buttons integrated into the knob to kill either translation or rotation at will and prevent unintended movements, by JoseLuisGZA and AndunHH.
Added Encoder to use with a wheel on top of the main knob an simulate pulls on any of the axis (main use is simulating zoom like the mouse wheel), by JoseLuizGZA and rewritten by AndunHH.

License

Because TeachingTech published his source code on Printables under this license, it also applies here:

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

AndunHH / spacemouse