百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
S

spacemouse

> 编程语言
开源

6自由度 (DOF) 鼠标仓库,模拟 3Dconnexion "Space Mouse Pro 无线"。它基于四个摇杆,附带额外的按键或

366 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

6自由度 (DOF) 鼠标仓库,模拟 3Dconnexion "Space Mouse Pro 无线"。它基于四个摇杆,附带额外的按键或

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

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 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 and rename config_sample.h to spacemouse-keys/config.h and change the values to whatever suits. If your are using a Hall-Effect-Sensor+Magnet approach start with config_sample_hall_effect.h

This is done to avoid the personal config file being overwritten when pulling new updates from this repository.

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 program to your hardware, you can connect via the serial monitor. Hit enter and use the serial menu to select the proper debug outputs. Make sure that your Line Ending is set to "CRLF" in PlatformIO / "Both NL & CR" in Arduino IDE (if this is not set, the command will timeout after 30s and present you the menu again).

Read and follow the instructions throughout the config.h file and write down your results. The initial parameters are hardware dependent and you need to recompile for the changes to take effect. The later parameters for sensitivities can be tuned via the menu and saved to the EEPROM (and exported back to config.h)

This calibration is supported by various debug outputs. All debug outputs are described at the top of your config_sample.h.

  1. Check and correct your pin out -> Refer to the pictures in the Electronics section below.
  2. Tune dead zone to avoid jittering
  3. 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.
  4. Adjust sensitivity
  5. Choose modifier funct

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C++

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言