A Python library for 3Dconnexion SpaceMouse devices

3Dconnexion Space Mouse in Python using raw HID. Note: you don't need to install or use any of the drivers or 3Dconnexion software to use this package. It interfaces with the controller directly with hidapi and python wrapper library easyhid.

PySpaceMouse is forked from: johnhw/pyspacenavigator

Connected project PySpaceApp is a simple example of how controll your PC with SpaceMouse.

Implements a simple interface to the 6 DoF 3Dconnexion Space Mouse device as well as similar devices.

Control a robot with a Space Mouse

• SpaceNavigator
• SpaceMouse Pro
• SpaceMouse Pro Wireless
• SpaceMouse Wireless
• 3Dconnexion Universal Receiver
• SpaceMouse Compact
• SpacePilot
• SpacePilot Pro
• SpaceMouse Enterprise
• Add more devices

Use the package manager pip to install pyspacemouse. If you are using a Mac with an ARM processor, you'll need a patched version of easyhid.

# Only needed for ARM Macs
pip install git+https://github.com/bglopez/python-easyhid.git

# Install package
pip install pyspacemouse

• hidapi is C library for direct communication with HID devices

  • Linux

    • libhidapi-dev to access HID data

    • sudo apt-get install libhidapi-dev (Debian/Ubuntu)

    • Compile and install hidapi. (other Linux distributions)

    • add rules for permissions

      sudo echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' > /etc/udev/rules.d/99-hidraw-permissions.rules
      sudo usermod -aG plugdev $USER
      newgrp plugdev

      Aleternative option - with tee (RPi)

        echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-hidraw-permissions.rules
        sudo usermod -aG plugdev $USER
        newgrp plugdev
        

  • Windows

    • Install the latest release of hidapi.dll and hidapi.lib from the hidapi releases page.
    • Set system environment: add absolute path for x64 or x86 folder in Path.

  • Mac OS X (M1)

    • Install from Homebrew
    • brew install hidapi
    • Add hidapi to your DYLD_LIBRARY_PATH directory.

      export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH

    • On MacOS M1 you will need patched version of easyhid. If easyhid is already installed, please uninstall it first.

      pip install git+https://github.com/bglopez/python-easyhid.git

    • In case of problem with M1 chip, try to run you code with Rosseta 2
      • How to use Rosseta 2 - Setup Rosetta
    • Tested and developed by consi - thanks!

• easyhid is hidapi interface for Python - required on all platforms

  • pip install git+https://github.com/bglopez/python-easyhid.git
  • this fork fix problems with hidapi on MacOS.
  • on other platforms it possible works with original package pip install easyhid

If the 3Dconnexion driver is installed, please ensure to stop 3DconnexionHelper before running your python scripts.

basicExample.py

import pyspacemouse
import time

success = pyspacemouse.open()
if success:
    while 1:
        state = pyspacemouse.read()
        print(state.x, state.y, state.z)
        time.sleep(0.01)

State objects returned from read() have 7 attributes: [t,x,y,z,roll,pitch,yaw,button].

• t: timestamp in seconds since the script started.
• x,y,z: translations in the range [-1.0, 1.0]
• roll, pitch, yaw: rotations in the range [-1.0, 1.0].
• button: list of button states (0 or 1), in order specified in the device specifier

callbackExample.py

import pyspacemouse
import time


def button_0(state, buttons, pressed_buttons):
    print("Button:", pressed_buttons)


def button_0_1(state, buttons, pressed_buttons):
    print("Buttons:", pressed_buttons)


def someButton(state, buttons):
    print("Some button")


def callback():
    button_arr = [pyspacemouse.ButtonCallback(0, button_0),
                  pyspacemouse.ButtonCallback([1], lambda state, buttons, pressed_buttons: print("Button: 1")),
                  pyspacemouse.ButtonCallback([0, 1], button_0_1), ]

    success = pyspacemouse.open(dof_callback=pyspacemouse.print_state, button_callback=someButton,
                                button_callback_arr=button_arr)
    if success:
        while True:
            pyspacemouse.read()
            time.sleep(0.01)


if __name__ == '__main__':
    callback()

open(callback=None, button_callback=None, button_callback_arr=None, set_nonblocking_loop=True, device=None)
    Open a 3D space navigator device. Makes this device the current active device, which enables the module-level read() and close()
    calls. For multiple devices, use the read() and close() calls on the returned object instead, and don't use the module-level calls.

    Parameters:
        callback: If callback is provided, it is called on each HID update with a copy of the current state namedtuple
        dof_callback: If dof_callback is provided, it is called only on DOF state changes with the argument (state).
        button_callback: If button_callback is provided, it is called on each button push, with the arguments (state_tuple, button_state)
        device: name of device to open, as a string like "SpaceNavigator". Must be one of the values in `supported_devices`.
                If `None`, chooses the first supported device found.
    Returns:
        Device object if the device was opened successfully
        None if the device could not be opened

read()              Return a namedtuple giving the current device state (t,x,y,z,roll,pitch,yaw,button)
close()             Close the connection to the current device, if it is open
list_devices()      Return a list of supported devices found, or an empty list if none found

open() returns a DeviceSpec object. If you have multiple 3Dconnexion devices, you can use the object-oriented API to access them individually. Each object has the following API, which functions exactly as the above API, but on a per-device basis:

dev.open()          Opens the connection (this is always called by the module-level open command,
                    so you should not need to use it unless you have called close())
dev.read()          Return the state of the device as namedtuple [t,x,y,z,roll,pitch,yaw,button]
dev.close()         Close this device

There are also attributes:

dev.connected       True if the device is connected, False otherwise
dev.state           Convenience property which returns the same value as read()

import pyspacemouse
import time

success = pyspacemouse.open(dof_callback=pyspacemouse.print_state, button_callback=pyspacemouse.print_buttons)
if success:
    while 1:
        state = pyspacemouse.read()
        time.sleep(0.01)

Print all axis states

x +0.00    y +0.00    z +0.00 roll +0.00 pitch +0.00  yaw +0.00    t +0.0

Print all buttons states

[ 0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0, ]

• Install easyhid by pip install easyhid.

• HID library for your computer is not installed.
• Follow the instructions in requirements.