Is there any binary protocol documentation?

Questions and answers about 3Dconnexion devices on UNIX and Linux.

Moderator: Moderators

Post Reply
travisfw
Posts: 2
Joined: Sat Sep 24, 2016 3:12 pm

Is there any binary protocol documentation?

Post by travisfw »

I would like to parse the bytes coming over the the wire from my USB SpaceNavigator. For example, when I press the left button, I clearly see this pattern of bytes each time: 0x03, 0x01, 0x00, 0x03, 0x00, 0x00. The data from 3D translation and rotation have, so far, confounded me. Here is an example of tapping the top of the SpaceNavigator once:

Code: Select all

01 f8  ff 14  00 55  00 02  00 00  15 00  00 00  01 00
00 b0  ff 04  00 02  a5 ff  00 00  00 00  01 00  00 00
00 4b  00 02  65 00  fe ff  00 00  01 00  00 bd  ff 00
00 02  d7 ff  08 00  00 00  01 00  00 1e  00 cd  ff 02
37 00  00 00  00 00  01 00  00 f1  ff 00  00 02  b8 ff
00 00  00 00  01 00  00 2b  00 14  00 02  26 00  00 00
00 00  01 00  00 f5  ff 00  00 02  d1 ff  00 00  00 00
01 00  00 19  00 f5  ff 02  2b 00  00 00  00 00  01 00
00 eb  ff 00  00 02  d9 ff  00 00  00 00  01 00  00 04
00 00  00 02  23 00  00 00  00 00  01 00  00 fe  ff 00
00 02  f3 ff  00 00  00 00  01 00  00 00  00 00  00 02
09 00  00 00  00 00  01 00  00 00  00 00  00 02  ef ff
00 00  00 00  01 00  00 03  00 00  00 02  08 00  00 00
00 00  01 00  00 00  00 00  00 02  f5 ff  00 00  00 00
01 00  00 00  00 00  00 02  07 00  00 00  00 00  01 00
00 00  00 00  00 02  f7 ff  00 00  00 00  01 00  00 00
00 00  00 02  07 00  00 00  00 00  01 00  00 00  00 00
00 02  f8 ff  00 00  00 00  01 00  00 00  00 00  00 02
05 00  00 00  00 00  01 00  00 00  00 00  00 02  fc ff
00 00  00 00  01 00  00 00  00 00  00 02  00 00  00 00
00 00  01 00  00 00  00 00  00 02  00 00  00 00  00 00
01 00  00 00  00 00  00 02  00 00  00 00  00 00  01 00
00 00  00 00  00 02  00 00  00 00  00 00  01 00  00 00
00 00  00 02  00 00  00 00  00 00  01 00  00 00  00 00
00 02  00 00  00 00  00 00
If anyone can help me see how to build 3D transform matrices out of this data stream, or otherwise help me see how to parse each of the six degrees of freedom, that would be much appreciated. Ideally there's official documentation somewhere (I'm not feeling lucky).

Backstory: I'm playing around with JavaFX 3D, and I want to make use of this SpaceNavigator that has been gathering dust for a year or so. I'm on Fedora 24. I've tried every Java library I can, and they all fail, and none seem to have legible source code (that I have stumbled across) that parses the binary protocol. Most recently I have attempted to read the C (++?) code in svn://svn.code.sf.net/p/spacenav/code but have not found this to be enlightening, perhaps because I'm not proficient with C. I'm avoiding JNI in my own solution because headaches. I can simply pipe /dev/hidraw2 into my JVM and read it with an InputStream, and that's good enough for this hobby-level project. Who knows; the project could evolve eventually, but I'm not getting ahead of myself.
steve s
Posts: 1
Joined: Fri Sep 30, 2016 7:07 am

Re: Is there any binary protocol documentation?

Post by steve s »

I had a similar question last week, but was able to make progress (at least for my two devices: SpacePilot & SpaceNavigator, which appear to behave the same way).

I'm using HID interface on Windows to gather data (as others have suggested on this forum); looks as if you're getting a similar stream of data. Like you I'm ultimately in Java.

Here's what I'm doing; you may need to tweak a few things on Linux, but maybe not:

Group the data stream into 7-byte packets. The zeroeth byte of each seven-byte packet will be either a 1 (translations), a 2 (rotations), or a 3 (button events).

Each 1 packet (the translations) will be followed by a 2 packet (rotations); but the 3 packets (button clicks) stand alone, and I'm not going to address those button packets...each device has more or less buttons.

Once you've seen a 1 packet followed by a 2 packet, that means there's an additional 12 bytes. If we number those bytes 1, 2, 1, 2..., you can use the code below to combine them into signed shorts, yielding 6 signed short values: three for translation, and three for rotation.

Here's my Java code:

Code: Select all

	private short combine(byte b1, byte b2)
	{
		ByteBuffer bb = ByteBuffer.allocate(2);
		bb.order(ByteOrder.BIG_ENDIAN);
		bb.put(b2);
		bb.put(b1);
		return bb.getShort(0);
	}
Others on this forum have noted that the inputs are in the range +/- 512, and I've found that to be true (actually I've never seen a value beyond +/- 400 for either of my devices, but they both definitely balance on a zero-valued short, which is the important part).

If we number those shorts 0 through 5, here's the interpretation (positive direction first, then negative values):

Three Translations:
  • 0: right / left
    1: pull toward user / push away
    2: push down / pull up
Three Rotations:
  • 3: twist toward user / twist away
    4: twist left / twist right
    5: twist CW / CCW
suspect your mileage will vary if user reconfigures the device, but I'm pretty sure this is the out of the box behavior.

Hope this helps.

Steve
Post Reply