spacenavigator

SpaceNavigator and 3Dconnexion HID interface utilities.

This module provides low-level support for reading 6-DoF input devices such as the 3Dconnexion SpaceNavigator over HID. It defines device mappings, callback helpers, configuration containers, and utility functions used to decode translation, rotation, and button events from supported devices.

class robotblockset.spacenavigator.AxisSpec(channel, byte1, byte2, scale)

Bases: tuple

Create new instance of AxisSpec(channel, byte1, byte2, scale)

byte1: Alias for field number 1

byte2: Alias for field number 2

channel: Alias for field number 0

scale: Alias for field number 3

class robotblockset.spacenavigator.ButtonSpec(channel, byte, bit)

Bases: tuple

Create new instance of ButtonSpec(channel, byte, bit)

bit: Alias for field number 2

byte: Alias for field number 1

channel: Alias for field number 0

robotblockset.spacenavigator.to_int16(y1: int, y2: int) → int[source]

Convert two unsigned bytes into a signed 16-bit integer.

Parameters:

y1 (int) – Low byte of the HID value.
y2 (int) – High byte of the HID value.

Returns:

Signed 16-bit integer reconstructed from y1 and y2.

Return type:

int

class robotblockset.spacenavigator.SpaceNavigator(t, x, y, z, roll, pitch, yaw, buttons)

Bases: tuple

Create new instance of SpaceNavigator(t, x, y, z, roll, pitch, yaw, buttons)

buttons: Alias for field number 7

pitch: Alias for field number 5

roll: Alias for field number 4

t: Alias for field number 0

x: Alias for field number 1

y: Alias for field number 2

yaw: Alias for field number 6

z: Alias for field number 3

class robotblockset.spacenavigator.ButtonState(iterable=(), /)[source]

Bases: list

List-like container that stores decoded button states.

class robotblockset.spacenavigator.ButtonCallback(buttons: int | List[int], callback: Callable[[SpaceNavigator, ButtonState, int | List[int]], None])[source]

Bases: object

Configuration block for button-triggered callbacks.

Parameters:

buttons (Union[int, List[int]]) – Button index or list of button indices that must be active to trigger the callback.
callback (Callable[[SpaceNavigator, ButtonState, Union[int, List[int]]], None]) – Function called when the requested button combination is active.

Initialize a button callback configuration.

Parameters:

buttons (Union[int, List[int]]) – Button index or button combination to monitor.
callback (Callable[[SpaceNavigator, ButtonState, Union[int, List[int]]], None]) – Function invoked when the requested button state is active.

__init__(buttons: int | List[int], callback: Callable[[SpaceNavigator, ButtonState, int | List[int]], None]) → None[source]

Initialize a button callback configuration.

Parameters:

buttons (Union[int, List[int]]) – Button index or button combination to monitor.
callback (Callable[[SpaceNavigator, ButtonState, Union[int, List[int]]], None]) – Function invoked when the requested button state is active.

class robotblockset.spacenavigator.DofCallback(axis: str, callback: Callable[[SpaceNavigator, float], None], sleep: float = 0.0, callback_minus: Callable[[SpaceNavigator, float], None] | None = None, filter: float = 0.0)[source]

Bases: object

Configuration block for per-axis DoF callbacks.

Parameters:

axis (str) – Name of the monitored axis. Must be one of "x", "y", "z", "roll", "pitch", or "yaw".
callback (Callable[[SpaceNavigator, float], None]) – Function invoked when the axis exceeds the configured filter threshold in the positive direction.
sleep (float, optional) – Minimum time in seconds between consecutive callback invocations.
callback_minus (Callable[[SpaceNavigator, float], None], optional) – Optional function invoked when the axis exceeds the filter threshold in the negative direction.
filter (float, optional) – Absolute threshold that the axis value must exceed before a callback is triggered.

Initialize a DoF callback configuration.

Parameters:

axis (str) – Name of the monitored axis.
callback (Callable[[SpaceNavigator, float], None]) – Function invoked for positive axis motion.
sleep (float, optional) – Minimum delay between callback invocations.
callback_minus (Callable[[SpaceNavigator, float], None], optional) – Optional function invoked for negative axis motion.
filter (float, optional) – Absolute motion threshold used to suppress small inputs.

__init__(axis: str, callback: Callable[[SpaceNavigator, float], None], sleep: float = 0.0, callback_minus: Callable[[SpaceNavigator, float], None] | None = None, filter: float = 0.0) → None[source]

Initialize a DoF callback configuration.

Parameters:

axis (str) – Name of the monitored axis.
callback (Callable[[SpaceNavigator, float], None]) – Function invoked for positive axis motion.
sleep (float, optional) – Minimum delay between callback invocations.
callback_minus (Callable[[SpaceNavigator, float], None], optional) – Optional function invoked for negative axis motion.
filter (float, optional) – Absolute motion threshold used to suppress small inputs.

class robotblockset.spacenavigator.Config(callback: Callable[[SpaceNavigator], None] | None = None, dof_callback: Callable[[SpaceNavigator], None] | None = None, dof_callback_arr: List[DofCallback] | None = None, button_callback: Callable[[SpaceNavigator, ButtonState], None] | None = None, button_callback_arr: List[ButtonCallback] | None = None)[source]

Bases: object

Container for validated SpaceMouse callback configuration.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic callback invoked for every processed event.
dof_callback (Callable[[SpaceNavigator], None], optional) – Callback invoked when any DoF value changes.
dof_callback_arr (List[DofCallback], optional) – List of per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Callback invoked when button states change.
button_callback_arr (List[ButtonCallback], optional) – List of button-combination callback configurations.

Initialize and validate a callback configuration bundle.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic event callback.
dof_callback (Callable[[SpaceNavigator], None], optional) – Callback invoked when DoF state changes.
dof_callback_arr (List[DofCallback], optional) – Per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Callback invoked when button state changes.
button_callback_arr (List[ButtonCallback], optional) – Button callback configurations.

__init__(callback: Callable[[SpaceNavigator], None] | None = None, dof_callback: Callable[[SpaceNavigator], None] | None = None, dof_callback_arr: List[DofCallback] | None = None, button_callback: Callable[[SpaceNavigator, ButtonState], None] | None = None, button_callback_arr: List[ButtonCallback] | None = None) → None[source]

Initialize and validate a callback configuration bundle.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic event callback.
dof_callback (Callable[[SpaceNavigator], None], optional) – Callback invoked when DoF state changes.
dof_callback_arr (List[DofCallback], optional) – Per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Callback invoked when button state changes.
button_callback_arr (List[ButtonCallback], optional) – Button callback configurations.

class robotblockset.spacenavigator.DeviceSpec(name: str, hid_id: List[int], led_id: List[int] | None, mappings: Dict[str, AxisSpec], button_mapping: List[ButtonSpec], axis_scale: float = 350.0)[source]

Bases: object

Runtime representation of a supported 3Dconnexion device.

The object stores the HID identifiers, axis and button mappings, decoded state, and active callbacks associated with a single device model.

Initialize a device specification and its runtime state.

Parameters:

name (str) – Human-readable device name.
hid_id (List[int]) – Vendor and product identifier pair.
led_id (List[int], optional) – Optional LED usage identifier pair.
mappings (Dict[str, AxisSpec]) – Mapping from logical axis names to HID byte locations.
button_mapping (List[ButtonSpec]) – Mapping from logical button indices to HID message bits.
axis_scale (float, optional) – Scale factor used to normalize raw HID axis values.

__init__(name: str, hid_id: List[int], led_id: List[int] | None, mappings: Dict[str, AxisSpec], button_mapping: List[ButtonSpec], axis_scale: float = 350.0) → None[source]

Initialize a device specification and its runtime state.

Parameters:

name (str) – Human-readable device name.
hid_id (List[int]) – Vendor and product identifier pair.
led_id (List[int], optional) – Optional LED usage identifier pair.
mappings (Dict[str, AxisSpec]) – Mapping from logical axis names to HID byte locations.
button_mapping (List[ButtonSpec]) – Mapping from logical button indices to HID message bits.
axis_scale (float, optional) – Scale factor used to normalize raw HID axis values.

describe_connection() → str[source]

Return a human-readable description of the current device connection.

Returns:: Description of the device model and connection state.
Return type:: str

property mappings: Dict[str, AxisSpec]

Get the configured logical-axis mapping.

Returns:: Mapping from axis names to HID byte descriptors.
Return type:: Dict[str, AxisSpec]

property connected: bool

Check whether the HID device is currently open.

Returns:: True if a device handle is present, otherwise False.
Return type:: bool

property state: SpaceNavigator | None

Return the current device state.

Returns:: Most recent decoded state, or None if the device is not open.
Return type:: Optional[SpaceNavigator]

open() → None[source]

Open the underlying HID device and cache its metadata.

Raises:: Exception – If the HID device cannot be opened.

close() → None[source]

Close the underlying HID device if it is open.

Return type:: None

read() → SpaceNavigator | None[source]

Read and decode the current SpaceMouse state.

Returns:: Current decoded device state, or None if the device is not open.
Return type:: Optional[SpaceNavigator]

process(data: Sequence[int]) → None[source]

Update the device state from one HID report and dispatch callbacks.

Parameters:: data (Sequence[int]) – Raw HID report bytes for a single input event.
Return type:: None

config_set(config: Config) → None[source]

Apply a validated callback configuration to the device.

Parameters:: config (Config) – Callback configuration bundle to apply.

config_set_sep(callback: Callable[[SpaceNavigator], None] | None = None, dof_callback: Callable[[SpaceNavigator], None] | None = None, dof_callback_arr: List[DofCallback] | None = None, button_callback: Callable[[SpaceNavigator, ButtonState], None] | None = None, button_callback_arr: List[ButtonCallback] | None = None) → None[source]

Set and validate device callback configuration from separate arguments.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic event callback.
dof_callback (Callable[[SpaceNavigator], None], optional) – Callback invoked when DoF state changes.
dof_callback_arr (List[DofCallback], optional) – Per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Callback invoked when button state changes.
button_callback_arr (List[ButtonCallback], optional) – Button callback configurations.

config_remove() → None[source]

Remove all active callback configuration from the device.

Return type:: None

robotblockset.spacenavigator.close() → None[source]

Close the module-level active device, if one is open.

Return type:: None

robotblockset.spacenavigator.read() → SpaceNavigator | None[source]

Return the current state of the active navigation controller.

Returns:: Current SpaceNavigator state with {t, x, y, z, pitch, yaw, roll, button}, or None if no device is open.
Return type:: Optional[SpaceNavigator]

robotblockset.spacenavigator.list_devices() → List[str][source]

Return the names of connected supported devices.

Returns:: Names of connected devices known to this module.
Return type:: List[str]

robotblockset.spacenavigator.list_available_devices() → List[Tuple[str, int, int]][source]

Return all supported device definitions known to the module.

Returns:: Tuples of (device_name, vendor_id, product_id).
Return type:: List[Tuple[str, int, int]]

robotblockset.spacenavigator.list_all_hid_devices() → List[Tuple[str, str, int, int]][source]

Return all HID devices detected by the backend.

Returns:: Tuples of (product_string, manufacturer_string, vendor_id, product_id).
Return type:: List[Tuple[str, str, int, int]]

robotblockset.spacenavigator.openCfg(config: Config, set_nonblocking_loop: bool = True, device: str | None = None, DeviceNumber: int = 0) → DeviceSpec | None[source]

Open a device using a prebuilt Config instance.

Parameters:

config (Config) – Validated callback configuration bundle.
set_nonblocking_loop (bool, optional) – If True, configure the HID device for non-blocking reads.
device (str, optional) – Preferred device name. If omitted, the first supported connected device is used.
DeviceNumber (int, optional) – Index of the matching device to open when multiple devices of the same type are present.

Returns:

Opened device wrapper, or None if no supported device was opened.

Return type:

Optional[DeviceSpec]

robotblockset.spacenavigator.open(callback: Callable[[SpaceNavigator], None] | None = None, dof_callback: Callable[[SpaceNavigator], None] | None = None, dof_callback_arr: List[DofCallback] | None = None, button_callback: Callable[[SpaceNavigator, ButtonState], None] | None = None, button_callback_arr: List[ButtonCallback] | None = None, set_nonblocking_loop: bool = True, device: str | None = None, path: str | None = None, DeviceNumber: int = 0) → DeviceSpec | None[source]

Open a supported 3Dconnexion device and make it the active module device.

The returned device becomes the target of the module-level read() and close() helpers. When working with multiple devices, use the returned DeviceSpec instance directly instead of the module-level helpers.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic event callback invoked after processing an input report.
dof_callback (Callable[[SpaceNavigator], None], optional) – Callback invoked when any DoF state changes.
dof_callback_arr (List[DofCallback], optional) – Per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Callback invoked when button state changes.
button_callback_arr (List[ButtonCallback], optional) – Button callback configurations.
set_nonblocking_loop (bool, optional) – If True, configure the HID device for non-blocking reads.
device (str, optional) – Device name to open. If omitted, the first connected supported device is selected.
path (str, optional) – Optional HID path override.
DeviceNumber (int, optional) – Index of the matching device to open when multiple devices of the same type are present.

Returns:

Opened device wrapper, or None if no supported device was opened.

Return type:

Optional[DeviceSpec]

robotblockset.spacenavigator.check_config(callback: Callable[[SpaceNavigator], None] | None = None, dof_callback: Callable[[SpaceNavigator], None] | None = None, dof_callback_arr: List[DofCallback] | None = None, button_callback: Callable[[SpaceNavigator, ButtonState], None] | None = None, button_callback_arr: List[ButtonCallback] | None = None) → None[source]

Validate a callback configuration.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic event callback.
dof_callback (Callable[[SpaceNavigator], None], optional) – DoF state-change callback.
dof_callback_arr (List[DofCallback], optional) – Per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Button state-change callback.
button_callback_arr (List[ButtonCallback], optional) – Button callback configurations.

Raises:

Exception – If any callback configuration entry is invalid.

robotblockset.spacenavigator.check_button_callback_arr(button_callback_arr: List[ButtonCallback]) → List[ButtonCallback][source]

Validate a list of button callback configurations.

Parameters:: button_callback_arr (List[ButtonCallback]) – Callback configuration objects to validate.
Returns:: The validated callback list.
Return type:: List[ButtonCallback]
Raises:: Exception – If any entry has an invalid type or callback signature.

robotblockset.spacenavigator.check_dof_callback_arr(dof_callback_arr: List[DofCallback]) → List[DofCallback][source]

Validate a list of DoF callback configurations.

Parameters:: dof_callback_arr (List[DofCallback]) – Callback configuration objects to validate.
Returns:: The validated callback list.
Return type:: List[DofCallback]
Raises:: Exception – If any entry has an invalid axis, type, or callback configuration.

robotblockset.spacenavigator.config_set(config: Config) → None[source]

Apply a configuration bundle to the active module-level device.

Parameters:: config (Config) – Validated callback configuration bundle.

robotblockset.spacenavigator.config_set_sep(callback: Callable[[SpaceNavigator], None] | None = None, dof_callback: Callable[[SpaceNavigator], None] | None = None, dof_callback_arr: List[DofCallback] | None = None, button_callback: Callable[[SpaceNavigator, ButtonState], None] | None = None, button_callback_arr: List[ButtonCallback] | None = None) → None[source]

Apply callback configuration to the active device from separate arguments.

Parameters:

callback (Callable[[SpaceNavigator], None], optional) – Generic event callback.
dof_callback (Callable[[SpaceNavigator], None], optional) – DoF state-change callback.
dof_callback_arr (List[DofCallback], optional) – Per-axis callback configurations.
button_callback (Callable[[SpaceNavigator, ButtonState], None], optional) – Button state-change callback.
button_callback_arr (List[ButtonCallback], optional) – Button callback configurations.

robotblockset.spacenavigator.config_remove() → None[source]

Remove all callback configuration from the active module-level device.

Return type:: None

robotblockset.spacenavigator.print_state(state: SpaceNavigator | None) → None[source]

Print the decoded DoF state to standard output.

Parameters:: state (SpaceNavigator, optional) – Decoded SpaceMouse state to print.

robotblockset.spacenavigator.silent_callback(state: SpaceNavigator | None) → None[source]

Ignore the provided state.

Parameters:: state (SpaceNavigator, optional) – Decoded SpaceMouse state. The value is ignored.

robotblockset.spacenavigator.print_buttons(state: SpaceNavigator, buttons: ButtonState) → None[source]

Print the decoded button state to standard output.

Parameters:

state (SpaceNavigator) – Current decoded SpaceMouse state.
buttons (ButtonState) – Button-state vector to print.

class robotblockset.spacenavigator.spacenavigator(device: str | None = None, path: str | None = None, DeviceNumber: int = 0, **kwargs: Any)[source]

Bases: object

Convenience wrapper that maintains the latest SpaceMouse state in a thread.

The wrapper opens a device, polls it continuously in the background, and exposes the latest motion vector and button state through simple properties.

Open a SpaceMouse device and start the background polling thread.

Parameters:

device (str, optional) – Preferred device name. If omitted, the first supported connected device is used.
path (str, optional) – Optional HID path override.
DeviceNumber (int, optional) – Index of the matching device to open.
**kwargs (Any) – Additional keyword arguments forwarded to open().

Raises:

RuntimeError – If no supported device could be opened.

__init__(device: str | None = None, path: str | None = None, DeviceNumber: int = 0, **kwargs: Any) → None[source]

Open a SpaceMouse device and start the background polling thread.

Parameters:

device (str, optional) – Preferred device name. If omitted, the first supported connected device is used.
path (str, optional) – Optional HID path override.
DeviceNumber (int, optional) – Index of the matching device to open.
**kwargs (Any) – Additional keyword arguments forwarded to open().

Raises:

RuntimeError – If no supported device could be opened.

property t: float

Get elapsed time since the last reset.

Returns:: Elapsed time in seconds.
Return type:: float

property x: ndarray

Get the latest decoded 6-DoF motion vector.

Returns:: Vector [x, y, z, roll, pitch, yaw].
Return type:: np.ndarray

property buttons: List[int]

Get the latest decoded button states.

Returns:: Current button-state vector.
Return type:: List[int]

GetState() → None[source]

Poll the device once and update cached motion and button state.

Return type:: None

Close() → None[source]

Stop the background polling thread and close the device.

Return type:: None

ResetTime() → None[source]

Reset the wrapper time origin used by t.

Return type:: None

Functions

`check_button_callback_arr`(button_callback_arr)	Validate a list of button callback configurations.
`check_config`([callback, dof_callback, ...])	Validate a callback configuration.
`check_dof_callback_arr`(dof_callback_arr)	Validate a list of DoF callback configurations.
`close`()	Close the module-level active device, if one is open.
`config_remove`()	Remove all callback configuration from the active module-level device.
`config_set`(config)	Apply a configuration bundle to the active module-level device.
`config_set_sep`([callback, dof_callback, ...])	Apply callback configuration to the active device from separate arguments.
`list_all_hid_devices`()	Return all HID devices detected by the backend.
`list_available_devices`()	Return all supported device definitions known to the module.
`list_devices`()	Return the names of connected supported devices.
`open`([callback, dof_callback, ...])	Open a supported 3Dconnexion device and make it the active module device.
`openCfg`(config[, set_nonblocking_loop, ...])	Open a device using a prebuilt `Config` instance.
`print_buttons`(state, buttons)	Print the decoded button state to standard output.
`print_state`(state)	Print the decoded DoF state to standard output.
`read`()	Return the current state of the active navigation controller.
`silent_callback`(state)	Ignore the provided state.
`to_int16`(y1, y2)	Convert two unsigned bytes into a signed 16-bit integer.

Classes

`AxisSpec`(channel, byte1, byte2, scale)	Create new instance of AxisSpec(channel, byte1, byte2, scale)
`ButtonCallback`(buttons, callback)	Configuration block for button-triggered callbacks.
`ButtonSpec`(channel, byte, bit)	Create new instance of ButtonSpec(channel, byte, bit)
`ButtonState`([iterable])	List-like container that stores decoded button states.
`Config`([callback, dof_callback, ...])	Container for validated SpaceMouse callback configuration.
`DeviceSpec`(name, hid_id, led_id, mappings, ...)	Runtime representation of a supported 3Dconnexion device.
`DofCallback`(axis, callback[, sleep, ...])	Configuration block for per-axis DoF callbacks.
`SpaceNavigator`(t, x, y, z, roll, pitch, yaw, ...)	Create new instance of SpaceNavigator(t, x, y, z, roll, pitch, yaw, buttons)
`spacenavigator`([device, path, DeviceNumber])	Convenience wrapper that maintains the latest SpaceMouse state in a thread.