HID button count and values for event = 3, 28 & 29

Post questions, comments and feedback to our 3Dconnexion Windows Development Team.

Moderator: Moderators

Post Reply
openantz
Posts: 6
Joined: Wed Nov 25, 2020 12:38 pm

HID button count and values for event = 3, 28 & 29

Post by openantz » Wed Nov 25, 2020 3:23 pm

I am looking to discover a method to detect the number of buttons and a list of corresponding button (event) values using HID info.

My (personal) dev case is a 3D data viz project called ANTz (https://openantz.com) and I am in the process of patching the freeglut library to work with (hopefully) all current SpaceMouse devices and legacy ones too. Testing with the SpaceMouse Enterprise now works for all event data, but shows that the buttons are not contigous (they skip numbers).

Currently using GetRawInputDeviceInfo(... RID_DEVICE_INFO), which gives me the VID and PID of connected devices. Best guess is that perhaps I can tease out the button details from the (RID_DEVICE_INFO_HID) UsagePage(s).

I wish to support both legacy devices (VID = 0x042f) and the (newer) SpaceMouse Enterprise and Pro (including Wireless) editions using VID = 0x256f. My app uses the freeglut framework, so I am patching it!

--- Details and maybe some useful info to others below ---

At the moment, the patch works (6DOF + button events) for Space Navigator and SpaceMouse Enterprise, but the freeglut maintainer is requesting support for the function glutGet(GLUT_NUM_SPACEBALL_BUTTONS) and that the (GLUT) button events be contigous from 1 to n (# of buttons). This is sensible (for API consistancy), but poses two challenges; knowing the button count and related (button data packets) for each event type.

The button events are complex, and depending on which device, appear to have 3 packet sizes (3, 4, or 5 bytes). The first byte is the event type (3, 28 or 29) and is followed by the button value(s). It seems the valid (BITWISE/INTEGER) values can be 16bit (eg. Space Navigator), 24bit (Space Pilot) or 32bit (starting with the Space Pilot Pro and going forward). There also appears to be three fundamental types: event = 3 (BITWISE), 28 (INTEGER), 29 (only from a subset of the keys, when they are HELD down). Also, the integer events (28 and 29) can issue two words of 2 bytes each. The low word is used with a single key press and the high word only when 2 keys or more pressed. For the 'special' keys with a HELD down event = 29, you get the same value as event 28, But you can also get alternating events (of type 29) when simultaneously holding 3 keys down, ie: an event every second, one with two keys (high and low word) and the following second, a second event with a single key value (low word), and this repeats (every second) until released.

Additional discussion details are here:
https://sourceforge.net/p/freeglut/bugs/258/

Also, verbose comments in the (partially functional) code here:
http://openantz.com/code/freeglut/

My super-users love Spacemice and it would be greatlly appreciated (by the open source community) if anybody can assist in this mission!

jwick
Moderator
Moderator
Posts: 2833
Joined: Wed Dec 20, 2006 2:25 pm
Location: USA
Contact:

Re: HID button count and values for event = 3, 28 & 29

Post by jwick » Thu Nov 26, 2020 12:11 am

Yes, some of the devices have breaks in the numbering. It's unusual for us, but is not an unusual USB practice.
Had I known about it at the time I would have taken that into account when I designed the APIs.

If you download our Windows driver package, there is a file, Base.xml, that describes all the button event details.
Don't redistribute that file, but you can make use of the information to help you build your parsing code.

AFAIK, for recent devices, the USB device descriptors are correct. They were not for some of our early USB devices.
There is a lot of information in there that you can make use of.

openantz
Posts: 6
Joined: Wed Nov 25, 2020 12:38 pm

Re: HID button count and values for event = 3, 28 & 29

Post by openantz » Thu Dec 10, 2020 9:36 am

I find it preferable to match a set of static button ID's to device labels across various models, and this helps make it easier to keep it consistent for future devices as well. Though this makes it necessary to have a complete list of all device buttons to implement good code.

On this regard, the 'Base.xml' file is very helpful with it's device specific event (Report ID) types and button ID's (from Space Pilot Pro forward). Also, the 'virtualkeys.hpp' file in the SDK helps fill in the gaps for older devices, (eg. Space Pilot, Space Explorer, etc.)

In pursuit of coding support for all devices, I've updated my 3Dx HID cheatsheet here:

https://github.com/openantz/antz/wiki/3 ... developers

Please do provide any feedback as to accuracy, clarity and/or missing key information.

Lastly, it would be handy to be able to set all (SMP/SME) Dual Function keys (LongPressButtons) state to OFF (for a specific app). However, it is likely that the 3DxWare will re-configure the buttons whenever switching windows. So perhaps could reset this by checking the device state, (and to requote,) using:

> RPTID_LONGPRESS_MASK = 0x14, // Data: 4 bytes...
> Default 0x00000000 (all off). E.g., 0x0000f000 turns on long press on buttons 1-4

However, I have two problems here:

1) I have not (yet) succeeded in properly sending the HID data to configure the SME device. I only got as far as getting the device motion events to act really weird, suggesting the FileWrite() is working, but the packet is mis-configured. Perhaps you can provide some (windows C/C++) source code that demonstrates this or something similar, (like turning on the various LED's, which would be fun too)?

2) I have not (yet) thought of an efficient and reliable way to avoid fighting it out with the 3DxWare app configurations (which are helpful to the user, so a solution that allows both to co-exist would be ideal).

So, perhaps there is another approach, such as configuring the app.xml file to disable the DF keys?
And/or, maybe adding the functionality directly to the 3DxWare 'Buttons' dialog, (eg. setting [Roll -] to 'Disabled' would configure the HW to turn OFF the LONGPRESS for that key.)

BTW: I did figure out how to create custom SME lcd button icons by messing with the [app].xml file (in the users sub-folder) in conjuction with adding some [custom].PNG references in the Base.xml file. But I think this is a separate topic.

jwick
Moderator
Moderator
Posts: 2833
Joined: Wed Dec 20, 2006 2:25 pm
Location: USA
Contact:

Re: HID button count and values for event = 3, 28 & 29

Post by jwick » Fri Dec 11, 2020 1:58 am

Typo on your page: Logitech VID = 0x042d (legacy 3Dconnexion). (0x046d)

I still don't understand the scope of your project. If you are working exclusively with the Windows driver, you can do much more configuration using the capabilities of the driver and the API. With a proper cfg, you have a lot of control and cooperation.

It appears you support 3 platforms (Windows, MacOS, Linux). I still suggest building on top of our APIs on the platforms. They will be slightly different per platform but there is always a platform-specific layer somewhere in multi-platform code.

This allows users to use our GUI for configuration. Most importantly it insulates your software from changes caused by future devices. I don't want you to have to rebuild your software each time we introduce a new product.

If you want to go directly to HID, you can create a Windows cfg that tells the driver to get out of the way. It's a lot of work. And you are just redoing what I am already doing for you.

There will still undoubtedly be some app-specific configuration required in your program.

openantz
Posts: 6
Joined: Wed Nov 25, 2020 12:38 pm

Re: HID button count and values for event = 3, 28 & 29

Post by openantz » Fri Dec 11, 2020 12:19 pm

Thank you for catching the typo, (fore-mentioned wiki corrected to 0x046d).

ANTz scope:
An open source cross-framework core technology that is deployed both as a standalone app (on MSW, OSX, Linux...) and plugin component within other frameworks. Most end-users are either commercial or U.S. government with (open source directives). Some of the sponsors and dev partners are research institutes (eg. health care, education and national labs).

Note that I am not an attorney, the information provided here does not, and is not intended to, constitute legal advice; instead, all information is for general informational purposes only. The 3Dx SDK license does not appear to be compatible with open source code distribution, (object code only = compiled binary = no open source code), here is an excerpt:

"...3Dconnexion grants to you a personal limited non-exclusive, non-transferable, non-sublicensable, world-wide, royalty-free, revocable license to install, use, copy, modify and distribute in object code form the 3DCONNEXION SDK....
...Unauthorized reproduction or distribution of the 3DCONNEXION SDK is subject to civil and criminal penalties."

At this time, directly using HID appears to be the only viable option, though please do correct me if I am wrong. On this assumption, I very much encourage 3Dconnexion to consider an open source friendly approach: Eg. The Blackmagic Design license is a workable compromise that protects their broad intellectual property rights, while allowing the distribution of open source code that directly uses the proprietary SDK.

Regardless, I very much enjoy the 3DxWare functionality (as do my users) and it appears that it works very well in conjunction with direct HID events (via MSW). The only thorn in the side is the Dual Function (DF) keys, (aka LongPressButtons). From my perspective, event (Report ID) 0x03 and 0x1c work great, so long as the DF keys are disabled. While the user can selectively turn off the DF behavior for keys 1-12, the navigation keys event behavior remains inaccessible (to the user). Hence, why not build this into the existing 3Dx 'Buttons' dialog, where if the user sets a DF button (eg. ISO2) to 'Disabled' it also sets the HW to behave accordingly, akin to keys 1-12 with '[X] Disable On-Screen Display'. And ideally, this config setting would be defined within the (app).xml file.

The (app).xml file is quite handy! It not only allows the user to create custom button macros, it also can be manually edited (by a super-user) to support custom LCD button icon images specific to each unique macro action, which is cool! Going further, it appears possible to setup multiple button configs via ButtonBanks (https://forum.3dconnexion.com/viewtopic ... 706#p70706) and perhaps have the app directly set them.

jwick
Moderator
Moderator
Posts: 2833
Joined: Wed Dec 20, 2006 2:25 pm
Location: USA
Contact:

Re: HID button count and values for event = 3, 28 & 29

Post by jwick » Mon Dec 14, 2020 12:27 am

I understand. Then let's use HID. It works for the driver, it can work for you.

There is no problem using HID, but you might have to do a little bit of work as new devices appear.
We try to limit the differences. It makes our life easier too.

All what follows is limited to Windows.

99% of everything is controlled by the XML files. All the GUI (3DxSmartUI.exe) does is edit the XML files. The driver (3DxService.exe) reads them, and occasionally writes them. Notepad works too, but it's not very pretty. For the most part, the API also just edits the cfg files.

The first order of business is to get the driver helping you not hurting you. If you tell the driver that you are using HID, it will configure the device in a compatible way.

You will have to create a cfg file for this. Easy with the stand alone app, not so easy when the app is used inside another app.

1) Copy some cfg file in Program Files/3Dconnexion/3DxWare/3DxWinCore/Cfg. (e.g., Jet.xml) to AntZ.xml
2) Change the ExecutableName to your executable's name (and the ID and Name fields)
3) Change the Transport to HID

Save the file. Restart the driver. Open your app. Set focus to it. You should see AntZ.xml in the GUI and when hovering over the 3Dx systray icon.
Now you have a cfg file to work with and all the capabilities are open to you.

Yes, you can define multiple ButtonBanks in your cfg file. You can assign buttons on your device to navigate through them (forward/backward, push/pop, goto, etc).

Or you can use your code or a script to do the XML editing outside of the device buttons. You are at mercy of my changes to the cfg file format.

It's just a file. Anyone who can edit a file can make changes. Everyone who is interested will respond to the changes.
Our GUI exposes a limited selection of the capabilities (e.g., no access to the LongPressButtons).

Post Reply