89 lines
No EOL
4.3 KiB
Markdown
89 lines
No EOL
4.3 KiB
Markdown
# 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. |