LICENSE | ||
README.md | ||
SpaceBridge.py | ||
spacebridge.service |
SpaceControl Virtual Device Bridge
spacecontrol-bridge.py
is a Python script that acts as an intermediary between the SpaceControl 3D mouse (SpaceControl GmbH & Co. KG) daemon and the Linux input subsystem. It enables the use of SpaceControl devices as standard virtual input devices (3D mouse and/or gamepad) across a wider range of Linux applications.
Features
-
Daemon Communication: Connects to the SpaceControl daemon (
sc_daemon
) to receive raw 6DoF motion data and button events. -
Seamless
spacenavd
Integration (Virtual 3D Mouse Emulation): Creates a virtual 3D mouse device that is fully compatible withspacenavd
, allowing direct and seamless integration with popular 3D applications like Blender, FreeCAD, and other CAD/3D software that rely onspacenavd
for SpaceMouse support. -
Virtual Gamepad Emulation: (Optional, experimental) Creates a generic virtual gamepad, mapping SpaceControl inputs to standard gamepad axes and buttons for use in games or other applications.
-
Background Service: Designed to run as a systemd service for persistent operation.
Requirements
-
SpaceControl Driver/Daemon: The official SpaceControl Linux driver (sc_daemon) must be installed and running. This script communicates with it via its native library.
-
Python 3
-
evdev
Python Library: Used for creating and sending events to virtual input devices. -
uinput
Kernel Module: The uinput kernel module must be loaded. -
Permissions: The user running the script must have write access to
/dev/uinput
(typically achieved by being in theinput
group). -
spacenavd
Installation (as part of spacecontrol-driver
package)
This script is intended to be packaged and installed as part of the spacecontrol-driver
Arch Linux package (or similar distribution package). When installed via the PKGBUILD, it will be placed at /opt/spacecontrol-driver/python_bridge/spacecontrol-bridge.py
and managed by a systemd service.
Usage
As a Systemd Service (Recommended)
Once installed via the spacecontrol-driver
package, enable and start the service:
sudo systemctl --user enable spacecontrol-bridge.service
sudo systemctl --user start spacecontrol-bridge.service
Check its status and logs:
systemctl status spacecontrol-bridge.service
journalctl -u spacecontrol-bridge.service -f
Manual Execution (for Testing/Debugging)
To run the script manually for testing (ensure the sc_daemon is running first):
/opt/spacecontrol-driver/python_bridge/spacecontrol-bridge.py
Press Ctrl+C
in the terminal to stop the script.
Configuration
-
SC_LIB_PATH
: Modify this variable in the script if yourlibspc_ctrl.so
library is located at a different path than /opt/SpaceControl/lib/libspc_ctrl.so. (Note: The PKGBUILD handles this by installing it to/usr/lib/
and setting LD_LIBRARY_PATH for the daemon wrapper). -
ENABLE_3DMOUSE_VIRTUAL_DEVICE
: Set toTrue
orFalse
to enable/disable the virtual 3D mouse. -
ENABLE_GAMEPAD_VIRTUAL_DEVICE
: Set toTrue
orFalse
to enable/disable the virtual gamepad. -
AXIS_SCALE
: Adjust the sensitivity of the virtual device axes. -
LOGLEVEL
: Change tologging.DEBUG
for verbose output during troubleshooting.
Troubleshooting
-
"Could not establish connection with SpaceControl daemon.": Ensure
sc_daemon
is running. -
"Failed to create uinput device":
-
Verify
uinput
module is loaded -
Check permissions for
/dev/uinput
. Your user needs to be in theinput
group.
-
-
No input in applications:
-
Check journal for errors.
-
For 3D mouse, ensure
spacenavd
is running and configured correctly. -
For gamepad, use
jstest /dev/input/jsX
(replace X with the correct number, usually 0 or 1) to verify input.
-
Development Notes
-
The script uses
ctypes
for FFI (Foreign Function Interface) to interact with the nativelibspc_ctrl.so
library. -
Axis values and button events are received from the daemon and mapped to
evdev
codes. -
High-level events (like "Fit View") are handled separately from low-level button bitmasks.
-
The
collections
import is currently unused and can be removed if a leaner script is desired. TheGAMEPAD_BIT_TO_EVDEV_CODE
dictionary is present for potential future Xbox-style gamepad mapping.