translates SpaceController (SpaceControl GmbH & Co. KG) input into standard Linux events, creating virtual devices compatible with spacenavd for broad system use.
Find a file
2025-07-03 14:23:44 +02:00
LICENSE Initial commit 2025-06-29 21:52:32 +02:00
README.md add Readme.md 2025-07-03 14:23:44 +02:00
SpaceBridge.py use libspc_ctrl.so path the AUR package installs it in 2025-06-30 13:27:23 +02:00
spacebridge.service add systemd service 2025-07-03 13:49:49 +02:00

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 with spacenavd, allowing direct and seamless integration with popular 3D applications like Blender, FreeCAD, and other CAD/3D software that rely on spacenavd 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 the input 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 your libspc_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 to True or False to enable/disable the virtual 3D mouse.

  • ENABLE_GAMEPAD_VIRTUAL_DEVICE: Set to True or False to enable/disable the virtual gamepad.

  • AXIS_SCALE: Adjust the sensitivity of the virtual device axes.

  • LOGLEVEL: Change to logging.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 the input 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 native libspc_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. The GAMEPAD_BIT_TO_EVDEV_CODE dictionary is present for potential future Xbox-style gamepad mapping.