3D Mouse - openantz/antz GitHub Wiki

6DOF Spacemice - Spaceball to SpaceMouse

Spacemice are a type of 3D Mouse (6DOF) device that we use to operate the camera and modify glyphs. We support the current 3Dconnexion SpaceMouse family and many legacy devices too.

  • When a supported device is detected the [3Dmouse: Orbit ] indicator will appear in the ANTz GUI.

Quick Setup

For general info on all devices we suggest:

*Tested with antz-xr_2020-11-20.zip which has a custom patched freeglut.dll (v3.2.0x) which adds support for the 2nd generation of 3Dconnexion devices, which now use VID=0x256F (ie: SpaceMouse Wireless & Enterprise). We expect that this patch will be rolled into future versions of FreeGLUT.

Tested (working) 3Dconnexion Spacemice:

  • 2nd Generation:
    • SpaceMouse Enterprise
    • SpaceMouse Wireless
  • 1st Generation:
    • Space Mouse Pro
    • Space Navigator 3D Mouse

Un-tested (likely works):

  • 2nd Generation - (new) 3Dconnexion VID = 0x256f:
    • SpaceMouse Pro Wireless
    • SpaceMouse Compact
  • 1st Generation - (original) Logitech VID = 0x046d:
    • Spacemouse Classic
    • CADman
    • Spaceball 5000
    • Space Traveller 3D Mouse
    • Space Pilot 3D Mouse
    • Space Explorer 3D Mouse
    • Space Navigator for Notebooks
    • SpacePilot Pro 3D Mouse

Unlikely to work (but maybe):

  • Spacemouse Plus XT (we suspect a different HID schema is used).
  • Other 'vintage' Spacemice, you can find here: http://spacemice.org

Controls

  • The [3Dmouse: Orbit ] indicator appears in the GUI menu when a 3D mouse device is detected.

The indicator is either BLUE in camera mode or RED in glyph edit mode. Edit mode will apply to all glyphs selected by the keyboard, system mouse/trackpad/touchscreen or zSpace Stylus.

  • LEFT button - toggles between Camera (blue) and glyph Edit (red).
  • RIGHT button - changes tool type:
    • Camera mode (blue) has two navigation tools:
      • [3Dmouse: Orbit ] - around (Twist/Tilt) and zoom in/out (Forward/Back) of currently selected object.
      • [3Dmouse: Fly ] - around the scene (6DOF).
    • Glyph mode (red) has several tools:
      • [3Dmouse: Combo ] - rotate (Twist/Tilt/Roll) and translate (Push XYZ).
      • [3Dmouse: Move ] - translate (Push XYZ).
      • [3Dmouse: Rotate] - rotate (Twist/Tilt/Roll).
      • [3Dmouse: Size ] - uniform scale (Up/Down), non-uniform (Left/Right) & (Forward/Back).
      • [3Dmouse: Color ] - alpha (Up/Down) or RGB color (Twist/Tilt/Roll).

Hint: can also L/R-click on the GUI indicator to change modes with (2D) mouse or zSpace Stylus.

For how multiple devices (keyboard, mouse, 6DOF, etc) interact together, you may want to see:

Important, you may need to disable the 3Dconnexion GUI overlay, described below.

3Dconnexion Properties!!!

You may observe strange behaviour like the SpaceMouse acting as a scrollwheel or the buttons launching popup menus. While some Spacemice models work fine with the default settings, others require configuring the 3Dconnexion Properties to get proper behavior with our app.

Two things you may NEED TO KNOW:

  • Button behavior VARIES from one device to another.
  • Property settings are APPLICATION SPECIFIC, (not global). That is, the properties have to be individually configured for each application.
    • Run ANTz and make sure it is the CURRENTLY active window.
    • Open the 3Dconnexion Properties (or 'Settings' from the 3Dconnexion Home utility).
    • Ascert that the 'antz' app name is displayed within the 3DX properties window, (see picture below). If not, you can click on the ANTz window and then click on the 3DX window (and 'antz' should now appear in the 3DX dialog).
    • Disable menu actions associated with the LEFT and RIGHT buttons (eg. MENU and FIT) used by ANTz. To set to 'Disabled' you will need to:
      • From the 3DX Properties/Settings window, click on 'Buttons' to get a list of all available buttons.
      • For each button (needed by ANTz), click its rollout, then select '3Dconnexion' (sub-rollout) and select the option 'Disabled'. See below for some device specific examples.

Example Device Configurations:

  • Space Navigator
    • For ANTz LEFT mouse action, set [Buttons] -> [Left] -> [Disabled]
    • For ANTz RIGHT mouse action, set [Buttons] -> [Right] -> [Disabled]
    • And perhaps to prevent unwanted scrollwheel behavior, deselect ALL 'Navigation' checkboxes in the 3Dconnexion Properties 'Advanced Settings'.
  • SpaceMouse Enterprise
    • For ANTz LEFT mouse action, set [Buttons] -> [MENU] -> [Disabled]
    • For ANTz RIGHT mouse action, set [Buttons] -> [FIT] -> [Disabled]

*Default settings for 3Dconnexion buttons vary with the model.

Space Navigator

Space Navigator - PROBLEM: Floating Dialog is triggered by pressing a button.

3dconnexion_Radial-Menu

Space Navigator - SOLUTION: Disabled both LEFT and RIGHT 'Buttons'.

SpaceMouse Enterprise - SOLUTION: Disabled 'MENU' and 'FIT' buttons.

3Dconnexion Disable 'MENU' and 'FIT' Buttons Enterprise

Developers

You can find links to source code here and docs (below) that can help guide open source developers in their quest to support Spacemice!

We created a FreeGLUT patch for the glutSpaceball...() methods with robust support for all current 3Dconnexion device specific events and enhanced the legacy support too, see the code here:

Also useful is the device button ID mapping found in the Blender code here: GHOST_NDOFManager.cpp

For X11 platforms you will want to checkout the Spacenav project.

Note that the 3DX SDK license requires attribution and allows for distribution of (compiled) 'object code' ONLY. However, it does contain useful information for understanding the HID events for various (newer) devices.

3Dconnexion HID Data Packets

Two Vendor ID's:

  • Logitech VID = 0x046d (legacy 3Dconnexion).
  • 3Dconnexion VID = 0x256f (new SpaceMouse family).

Device List:

Table of event Report ID's (0x01...03) with content sizes (excludes the ID in the 1st byte) and Buttons (physical + virtual).

VID PID Name 0x01 Bytes 0x02 Bytes 0x03 BITS Buttons
0x046d 0xc603 *Spacemouse Plus XT ? ? ? 10
0x046d 0xc605 CADman 6 6 16 4
0x046d 0xc606 Spacemouse Classic 6 6 16 8
0x046d 0xc621 Spaceball 5000 6 6 16 12
0x046d 0xc623 Space Traveller 3D Mouse 6 6 16 8
0x046d 0xc625 Space Pilot 3D Mouse 6 6 24 21
0x046d 0xc626 Space Navigator 3D Mouse 6 6 16 2
0x046d 0xc627 Space Explorer 3D Mouse 6 6 16 15
0x046d 0xc628 Space Navigator for Notebooks 6 6 16 2
0x046d 0xc629 SpacePilot Pro 3D Mouse 6 6 32 31
0x046d 0xc62b Space Mouse Pro (original) 6 6 32 15+4
0x256f 0xc62e SpaceMouse Wireless (cabled) 12 n/a 16 2
0x256f 0xc62f SpaceMouse Wireless 12 n/a 16 2
0x256f 0xc631 SpaceMouse Pro Wireless (cabled) 12 n/a 32 15+4
0x256f 0xc632 SpaceMouse Pro Wireless 12 n/a 32 15+4
0x256f 0xc633 SpaceMouse Enterprise 12 n/a 32 31+20
0x256f 0xc635 SpaceMouse Compact 12 n/a 16 2

*Spacemouse Plus XT likely uses a different schema, (need to verify).

Physical + Virtual

  • SM Pro's have 4 virtual (Dual Function) keys 1-4 that are used for VIRTUALLCD.
  • SM Enterprise has two categories of virtual keys:
    • Virtual keys 1-12 are akin to the SM Pro's and are also used for VIRTUALLCD.
    • There are 8 keys mapped by the (vendor) button ID key codes:
      • RIGHT -> LEFT
      • TOP -> BOTTOM
      • FRONT -> BACK
      • ROLL_CW -> ROLL_CCW
      • ISO1 -> ISO2
      • VIEW_1 -> SAVE_VIEW_1
      • VIEW_2 -> SAVE_VIEW_2
      • VIEW_3 -> SAVE_VIEW_3

NOT Spacemice:

VID PID Name
0x256f 0xc651 CadMouse Wireless
0x256f 0xc652 Universal Receiver
0x256f 0xc654 CadMouse Pro Wireless
0x256f 0xc657 CadMouse Pro Wireless Left

Data Packet Structure

The 1st byte of a data packet is the Event 'Report ID'. This is followed by 'n' bytes of the data contents (parameter values). The valid button data packet size = 1+n, and can be: 3, 4, 5, 7 or 13 Bytes.

Note that the reported (button) data packet size with (MSW hid.dwSizeHid) is not the valid data packet size: eg. Space Navigator event 0x03 will report a size of 7 bytes, but it is only has 3 bytes of valid data and the extra bytes will contain garbage, (leftover bits from the motion data).

6DOF Motion Events

Logitech VID 0x046d devices use 2 separate motion events:

Event ID Packet Bytes Word Bytes Type Range Description
0x01 7 1+2+2+2 INT16 -512 to 511 XYZ Translate
0x02 7 1+2+2+2 INT16 -512 to 511 rXrYrZ Rotate

Avoid mixing up VID families, eg:

  • Space Mouse Pro (original) VID = 0x46d and therefore has 2 separate motion events (above).
  • SpaceMouse Pro Wireless (2nd Gen) VID = 0x256f has a combined 6DOF motion event (below).

3Dconnexion VID 0x256f devices combine the 6DOF motion event:

Event ID Packet Bytes Word Bytes Type Range Description
0x01 13 1+2+2+2+2+2+2 INT16 -512 to 511 XYZrXrYrZ Translate & Rotate

All devices use 'Right Handed Coordinates' (Translate) and the 'Right Hand Rule' (Rotate).

Button Events

There are 4 device specific button Event Report ID types:

Event ID Description Devices
0x03 Bitwise buttons All devices
0x16 Bitwise 'Dual Function' Space Mouse Pro and SpaceMouse Pro Wireless
0x1c Integer key code SpaceMouse Enterprise
0x1d Integer 'Dual Function' SpaceMouse Enterprise

ALL devices have the BITWISE button Event ID 0x03:

Event ID Packet Bytes Button Bits Type Bit Range Devices
0x03 3 16 BITWISE 0-14 See Device List for 16bit models
0x03 4 24 BITWISE 0-20 Space Pilot
0x03 5 32 BITWISE 0-30 SpacePilot Pro, SpaceMouse Pro's & Enterprise

*Button Bits do not include the 1st byte of the packet (event Report ID). Bit Range is defined as bit position (eg. 0-31), versus the corresponding (key code) button number 1-32 (offset by +1).

The valid button data packet size can be 3, 4 or 5 bytes and depends on the device. The number of valid bits is described in the Device List (table above).

BITWISE button event characteristics:

  • Each bit represents one button, UP = 0 and DOWN = 1.
  • Key-combos are allowed, therefore you must mask each bit to determine the button states.
    • Devices are NOT 'N-key Rollover' capable, meaning that there is a limited range of key combo's that generate valid events:
      • eg. On SME if you press T+F+FIT you will get an erroneous button event, (value = 105, the 'V3' button).
      • In general, we have found that 2 keys are always safe, 3-4 works for most cases, and up to 8 keys for a few cases.
  • Some devices have gaps in the buttons, in use buttons include:
    • SpaceMouse Pro's: 0-9, 12-15, 22-26.
    • SpaceMouse Enterprise: 0-2, 4-5, 8, 10, 12-26 (and non-bitwise keys up to 176).
    • The Space Pilot Pro (and all earlier devices) have no gaps.
  • SpaceMouse Enterprise has a special 'Dual Function' key event (0x1d) that when held down will generate an 'all buttons UP' event 0x03 (all bits = 0), regardless of the actual button state(s).
  • Space Mouse Pro and SpaceMouse Pro Wireless (2nd gen) also have a 'Dual Function' key event (0x16) that may behave similary, TESTING NEEDED.
  • No known device uses bit 31, the last bit position (0x80000000).

Space Mouse Pro and SpaceMouse Pro Wireless have a unique event for 'Dual Function' keys:

Event ID Packet Bytes Word Bits Type Bit Range Description
0x16 5 8+32 BITWISE 12-15 For HELD keys 1, 2, 3 and 4.

Event 0x16 occurs when you HOLD down a number key (1-4) and it generates the same bitwise value as the short key press (event 0x03).

SpaceMouse Enterprise has two additional INTEGER key events:

Event ID Packet Bytes Word Bytes Type In-use Range Description
0x1c 13 1+2+2+2+2+2+2 UINT16 1-176 Key codes (up to 6 keys in a packet).
0x1d 13 1+2+2+2+2+2+2 UINT16 1-176 Dual Function key HELD down.

There are a total of 31 physical keys, which include 20 'Dual Function' (long-press) keys, for a total of 51 keys, (sort of).

Events 0x03, 0x1c and 0x1d are related:

  • Short key presses generate both a 0x03 and 0x1c button DOWN event and a button UP event (with the current state of combo keys UP or DOWN).
  • Integer based events (0x1c and 0x1d) have values that match the bitwise bit position (offset by +1), but not all keys codes are within range:
    • eg. An integer key value of 15 = bit position 14 (mask 0x00004000).
    • eg. ENTER = 36 = 0x000000000 (is outside the 32bit range).
  • The first Dual Function (DF) key DOWN event (0x1d) is immediately followed by an 'all buttons UP' 0x03 and 0x01c event (with all zero's regardless of current key states).
    • The the Dual Function key UP event does not (usually) generate the secondary events 0x03 and 0x1c.

Event 0x1c occurs for ALL keys as follows:

  • For short key presses you get a DOWN and UP event data packet:
    • Up to 6 key codes (words) in a packet with current state of pressed key(s).
    • Valid key combo's range from 2 to 6, (not an 'N-key Rollover' device).
  • The first 31 key codes match the bit position of event 0x03 bitfield (offset by +1).
  • An 'all clear' key up event occurs with the 'Dual Function' keys as outlined below.

Event 0x1d Dual Function key behavior:

  • This event ONLY happens after holding down an assigned Dual Function key for 700ms.
  • The keys have the same integer value as a short press of the same key, (event 0x1c).
  • The DOWN key event (0x1d) is immediately followed by a pair of 'ALL keys UP' events 0x03 and 0x1c, (all zero's).
  • Pressing a combo of 2 or more DF keys will start generating a pair of alternating events, toggling every 700ms.
    • Up to 6 key codes (words) can be in each event, (we have seen a valid event pair with up to 8 keys).
  • The 3DxWare driver configures the HW for Dual Function keys:
    • The default power-on state is for all keys to generate (an immediate) key DOWN and UP event (using 0x03 and 0x1c).
    • The driver re-configures the HW to generate event 0x1d, for the 'Dual Function' keys:
      • 1-12, TOP[BOTTOM], RIGHT[LEFT], FRONT[BACK], ROLL_CW[CCW], ISO1[ISO2], V1[SAVE_V1], V2[SAVE_V2], V3[SAVE_V3].
      • You can Disable the DF behavior for keys 1-12 by checking '[X] Disable On-Screen Display' in the Properties->Buttons dialog.
    • If you 'Stop 3DxWare' service, then the HW will stay in the current state, (unless rebooted).
      • While the driver is stopped, if you unplug the device and plug it back in, it will revert to the power-on default state with no DF keys, (and no lights, but it generates events).
    • There are two packets that control the Dual Function keys (LongPressButtons):
      • RPTID_LONGPRESS_MASK = 0x14
        • Data: 4 bytes. Defines which buttons produce long press events. Can be read and set.
        • Default 0x00000000 (all off). E.g., 0x0000f000 turns on long press on buttons 1-4.
      • RPTID_LONGPRESS_TIME = 0x15
        • Data: 1 byte [0,255]. Time (in 4 ms units) before long press is triggered.
        • Default 175 (700 ms). Send 0 to reset to firmware default.

Useful Resources

We plan to add device specific key lists with each event type, but meanwhile:

  • A set of (current) device specific key HID event ID types and key values are defined in the 'Base.xml' file found within the 3DX Windows driver folder at '../Program Files/3Dconnexion/3DxWare/3DxWinCore64/Base.xml'

    • Note that Base.xml does NOT include all devices, nor the event 0x03 bitmask values for the SpaceMouse Enterprise. However, you can interpret the integer value (event 0x1c) as the bitmask bit position. Also, the 'SpacePilot Pro' schema (same file) lists the key 'Mask' values for event 0x03, and they are the same values as the (subset of) keys used by SM Enterprise.
    • Also, the Base.xml file contains reference to a 'V3DK_VIRTUALLCD' key ID (V3DKID) that does NOT appear in any enumerated lists in any of the header files (eg. virutalkeys.hpp). Also, that if you hold such keys (eg. SM Pro or SM Enterprise 1, 2, 4...), that you will get the same behavior as other Dual Function keys (eg. SM Pro event 0x16 or SM Enterprise event 0x1d) with the same key value as a short press event (0x03 and/or 0x1c). Further there is no clear.

  • The app specific (user customized) XML file is at:

    • 'C:\Users(user name)\AppData\Roaming#Dconnexion\3DxWare\Cfg'

  • A complete list of all keys per device is defined in the 'virtualkeys.hpp' header file, provided with 3Dconnexion SDK (..\sdk\Inc\vurtualkeys.hpp'

    • This includes the (different) key ordering used by older devices (eg. Space Explorer).
    • The Space Pilot button list only has 20 buttons (bits 0-19), the 21st button is the 'CONFIG' key (bit 20).

  • There is also a related discussion here:

https://forum.3dconnexion.com/viewtopic.php?f=19&t=39870

3DxWare Issues

  • Lost functionality, missing config button 'App Cmd 1...':
    • Using W10 Pro 64bit, we observed with 3DxWare64_v10-6-5_r3156 that in the Properties 'Buttons' dialog, you could set the keys to a type 'Application -> App Cmd 1, 2... '. However, this option disappeared and did not come back (tried 'Reset all settings' and rebooting.)
  • Load previously saved Settings (FIXED):
    • We observed that with 3DxWare64_v10-6-5_r3156 the ability to load saved Property settings did not work. This appears to be fixed with 3DxWare64_v10-7-0_r3248.
  • Functionality Request:
    • It would be very useful if you could load the Property settings to a different app. A common use case is that every time you compile you have to manually setup all the settings for the new binary. Another thing, is that it would be helpful if you could provide the end-user with a settings file that would work on deployment (perhaps this is already possible?)

SDK:

ANTz Issues

  • Continual drift occurs if the scope of the current object(s) change while manipulating them. This is due to the velocity rates (move/rotate/scale) not being reset to zero when another object is selected. This can also be used as a feature, such as setting a continual rotation rate.

Related Issue:

ToDo:

  • 6dof camera plane object movement for sub-nodes (non-root glyph).
  • 6dof HLS color control, (custom user pallete?)

3Dconnexion (SDK) attribution:

"3D input device development tools and related technology are provided under license from 3Dconnexion. © 3Dconnexion 1992 - 2018. All rights reserved."