3-Space Sensor Wireless 2.4GHz User`s Manual

3-Space Sensor Wireless 2.4GHz User`s Manual

User's Manual

4. 3-Space Sensor Usage/Protocol

4.1 Usage Overview

4.1.1 Protocol Overview

The 3-Space Sensor receives messages from the controlling system in the form of sequences of serial communication bytes called packets. For ease of use and flexibility of operation, two methods of encoding commands are provided: binary and text. Binary encoding is more compact, more efficient, and easier to access programmatically. ASCII text encoding is more verbose and less efficient yet is easier to read and easier to access via a traditional terminal interface.

Both binary and ASCII text encoding methods share an identical command structure and support the entire 3-Space command set.

The 3-Space Sensor buffers the incoming command stream and will only take an action once the entire packet has been received and the checksum has been verified as correct(ASCII mode commands do not use checksums for convenience).

Incomplete packets and packets with incorrect checksums will be ignored. This allows the controlling system to send command data at leisure without loss of functionality. The command buffer will, however, be cleared whenever the 3-

Space Sensor is either reset or powered off/on.

Specific details of the 3-Space Sensor protocol and its control commands are discussed in the following pages.

4.1.2 Computer Interfacing Overview(USB)

When interfacing with a computer through USB, the 3-Space Sensor presents itself as a COM port, which provides a serial interface through which host may communication with the sensor unit by using protocol messages. The name of this COM port is specific to the operating system being used. It is possible to use multiple 3-Space Sensors on a single computer. Each will be assigned its own COM port. The easiest way to find out which COM port belongs to a certain sensor is to take note of what COM port appears when that sensor is plugged in(provided the drivers have been installed on that computer already. Otherwise, find out what COM port appears once driver installation has finished.)

Additionally, each sensor can be identified programatically by reading the serial number of each attached sensor. For more information on how to install the sensor software on a computer and begin using it, see the Quick Start guide.

4.1.3 Computer Interfacing Overview(Wireless)

To interface to a sensor through a computer wirelessly, the 3-Space Dongle must be connected to the computer through

USB. The Dongle will present itself as a COM port just as the 3-Space Sensor does. Each dongle can be associated with up to 15 wireless sensor units. To associate a sensor unit with a dongle, the user must place the desired sensor's serial number in one of the dongle's 15 logical wireless table slots. Any wireless 3-Space Sensors in range that have been given an address slot on the Dongle may then be communicated to using the Dongle. For information on how to set up the Dongle's address slots, see the Quick Start guide or <Dongle slot command ##>. For information on what data to send to the Dongle to communicate with a particular sensor, see section 4.3. The wireless communication protocol and wired communication protocol support the same commands, but are not identical. This allows the wireless protocol to include features that are specific to the nature of wireless communication such as wireless addressing, wireless reliability, and packet-loss handling, etc. For more information pertaining to the wired and wireless communication protocols, see sections 4.2 and 4.3 respectively.

21

User's Manual

4.2 Wired Protocol Packet Format

4.2.1 Binary Packet Format

The binary packet size can be three or more bytes long, depending upon the nature of the command being sent to the controller. Each packet consists of an initial “start of packet” byte, followed by a “command value” specifier byte, followed by zero or more “command data” bytes, and terminated by a packet “checksum value” byte.

Each binary packet is at least 3 bytes in length and is formatted as shown in figure 1

247(0xF7) First Byte – Start of Packet

Command

Command Data

Command Data

}

Second Byte – Command Value

Selected from the command chart

Command Data

Zero or more bytes representing parameters to the command being called.

See the command chart for details.

Checksum

Last Byte – Packet Checksum

Sum of all other bytes except the first.

Figure 1 - Binary Command Packet Format

Binary Return Values:

When a 3 Space Sensor command is called in binary mode, any data it returns will also be in binary format. For example, if a floating point number is returned, it will be returned as its 4 byte binary representation.

For information on the floating point format, go here: http://en.wikipedia.org/wiki/Single_precision_floatingpoint_format

Also keep in mind that integer and floating point values coming from the sensor are stored in big-endian format.

The Checksum Value:

The checksum is computed as an arithmetic summation of all of the characters in the packet (except the checksum value itself) modulus 256. This gives a resulting checksum in the range 0 to 255. The checksum for binary packets is transmitted as a single 8-bit byte value.

22

User's Manual

4.2.2 ASCII Text Packet Format

ASCII text command packets are similar to binary command packets, but are received as a single formatted line of text.

Each text line consists of the following: an ASCII colon character followed by an integral command id in decimal, followed by a list of ASCII encoded floating-point command values, followed by a terminating newline character. The command id and command values are given in decimal. The ASCII encoded command values must be separated by an

ASCII comma character or an ASCII space character. Thus, legal command characters are: the colon, the comma, the period, the digits 0 through 9, the minus sign, the new-line, the space, and the backspace. When a command calls for an integer or byte sized parameter, the floating point number given for that parameter will be interpreted as being the appropriate data type. For simplicity, the ASCII encoded commands follow the same format as the binary encoded commands, but ASCII text encodings of values are used rather than raw binary encodings.

Each ASCII packet is formatted as shown in figure 2.

: Command , Data1 , Data2 , ... , DataN \n

End of Packet – The

ASCII newline character

Command Data Zero or more bytes representing parameters to the command being called. See the command chart for details.

Command Value – Selected from the command chart, in decimal.

Start of ASCII Packet – Indicated by the colon character

Figure 2 - ASCII Command Packet Format

Thus the ASCII packet consists of the the following characters:

: – the ASCII colon character signifies the start of an ASCII text packet.

, – the ASCII comma character acts as a value delimiter when multiple values are specified.

. – the ASCII period character is used in floating point numbers.

0~9 – the ASCII digits are used to in integer and floating point values.

- - the ASCII minus sign is used to indicate a negative number

\n – the ASCII newline character is used to signify the end of an ASCII command packet.

\b – the ASCII backspace character can be used to backup through the partially completed line to correct errors.

If a command is given in ASCII mode but does not have the right number of parameters, the entire command will be ignored. Also note that when communicating with the dongle or sensor in the 3-Space Suite, the newline is automatically appended to the input, thus it is not necessary to add it.

Sample ASCII commands:

:0\n (If connected to the sensor) Read orientation as a quaternion

:106,2\n (If connected to the sensor) Set oversample rate to 2

:214\n (If connected to the dongle) Read signal strength of most recent dongle reception

:208,5\n (If connected to the dongle) Read the serial number of the unit mapped to logical ID 5

ASCII Response:

All values are returned in ASCII text format when an ASCII-format command is issued. To read the return data, simply read data from the sensor until a Windows newline(a carriage return and a line feed) is encountered.

23

User's Manual

4.3 Wireless Protocol Packet Format

4.3.1 Wireless Communication Format

The protocol for communicating with sensors wirelessly is very similar to the wired protocol, but includes accommodations for wireless unit addressing and wireless communication failures. Thus, all wireless communication messages now also include an address specifying which sensor they are to be sent to. Additionally, each wireless protocol command returns status information pertaining to the success or failure of the wireless command.

4.3.2 Binary Packet Format

The wireless binary packet format is very similar to the wired format. Each packet consists of an initial “address” byte, followed by a “command value” specifier byte, followed by zero or more “command data” bytes, and terminated by a packet “checksum value” byte.

Each wireless binary packet is at least 3 bytes in length and is formatted as shown in figure 3

Figure 3 - Wireless Binary Command Packet Format

24

4.3.3 Binary Command Response

User's Manual

When a binary command is invoked wirelessly, before the data it would normally return in wired mode, it will return status bytes. First is the success byte, which is a 0 if the command was successful and non-0 if it was not. Some things which can cause a failure are:

The lack of corresponding wireless sensor at the specified address.

Wireless communication errors or dropped packets.

Improper command formatting or data length

Second is the address byte. This indicates which sensor sent the response. If the success byte is zero, the data length byte will be present after this byte. If the success byte is non-zero, the data length byte will not be present at all.

Assuming the command succeeded, the response data will be present directly after the data length byte.

4.3.4 Sample Binary Commands

Command

F8 01 00 01

F8 05 6A 02 71

F8 03 E6 E9

F8 00 EC EC

F8 09 77 00 00 00 00

BF 80 00 00 00 00 00

BF

Description Potential Response

Read orientation as a quaternion from sensor 1 00 01 10 00 00 00 00 00 00 00

00 00 00 00 00 3F 80 00 00

Set oversample rate to 2 on sensor 5

Read version string from sensor 3

Read clock speed from powered-off sensor 0

00 05 00

00 03 0C 54 53 53 57 49 52 30

36 30 31 31 31

01 00 (Failure)

Set accelerometer reference vector to (0.0, -1.0, 0.0) on sensor 9

00 09 00

25

User's Manual

4.3.5 ASCII Text Packet Format

Wireless ASCII packets are very similar to wired ASCII packets. Each wireless ASCII packet is formatted as shown in figure 4.

> Address, Command , Data1 , Data2 , ... , DataN \n

End of Packet – The

ASCII newline character

Command Data Zero or more bytes representing parameters to the command being called. See the command chart for details.

Command Value – Selected from the command chart, in decimal.

Address – Wireless address of the sensor to communicate with.

Start of ASCII Packet – Indicated by the greater than character.

Figure 4 - Wireless ASCII Command Packet Format

Thus the ASCII packet consists of the the following characters:

> – the ASCII greater than character signifies the start of an ASCII text packet.

, – the ASCII comma character acts as a value delimiter when multiple values are specified.

. – the ASCII period character is used in floating point numbers.

0~9 – the ASCII digits are used to in integer and floating point values.

- - the ASCII minus sign is used to indicate a negative number

\n – the ASCII newline character is used to signify the end of an ASCII command packet.

\b – the ASCII backspace character can be used to backup through the partially completed line to correct errors.

If a command is given in ASCII mode but does not have the right number of parameters, the entire command will be ignored.

26

4.3.6 ASCII Command Response

User's Manual

When an ASCII command is called wirelessly, before the data it would normally return in wired mode, it will return status values, each seperated by a comma. First is the success/failure value, which is a 0 if the command was successful and 1 if it was not. Some things which can cause a failure are:

The lack of a sensor present wirelessly

Communication interference causing the wireless sensor to not respond

Improper command formatting or data length

Second is the address byte. This indicates which sensor sent the response. If the success byte is zero, the data length byte will be present after this byte. If the success byte is non-zero, the data length byte will not be present at all.

Assuming the command succeeded, the response data will be present directly after the data length byte.

4.3.7 Sample ASCII Commands

Command

>0,0\n

Description Potential Response

Read orientation as a quaternion from sensor 0 0,0,36,-0.07354,-0.97287,-

0.03232,0.21696\r\n

>5,106,2\n

>3,230\n

>2,236\n

Set oversample rate to 2 on sensor 5

Read version string from sensor 3

Read clock speed from out-of-range sensor 2

5,0,0\r\n

0,0,14,08Jan2013K25\r\n

1,2\r\n (Failure)

Note that wireless commands that either fail or do not return data at all will still be terminated with carriage return and line feed characters, even though the data length string may be “0” or not present at all.

27

User's Manual

4.4 Response Header Format

4.4.1 Wired Response Header

The 3-Space Sensor is capable of returning additional data that can be prepended to all command responses. This capability is managed via the Response Header Bitfield, which can be configured using command 221 (0xDD). Each bit in the field, if enabled, corresponds to a different piece of information that will be output prior to the expected response data. To use the Response Header Bitfield, use the following steps:

1.) Determine which additional data you would like to have output as the response header. The list of options are:

0x1 (Bit 0) – Success/Failure; comprised of one byte with non-zero values indicating failure.

0x2 (Bit 1) – Timestamp; comprised of four bytes representing the most recent sample time in microseconds. Note that this is not a difference, but a total accumulated time.

0x4 (Bit 2) – Command echo; comprised of one byte. Echoes back the previous command.

0x8 (Bit 3) – Additive checksum; comprised of one byte summed over the response data modulus 256.

Note that this does not include the Response Header itself.

0x10 (Bit 4) – Logical ID; comprised of one byte indicating the logical ID of the received packet. For

wired communication, this always returns 0xFE.

0x20 (Bit 5) – Serial number; comprised of four bytes.

0x40 (Bit 6) – Data length; comprised of one byte. Represents the amount of response data. Note that this

does not include the Response Header itself.

For example, if you wanted all future data to be preceded with a timestamp and a data length, you would

want to use bits 1 and 6, which corresponds to the value 65 (0x00000041). This is the value that would be

passed into the Set Wired Response Header Bitfield command (Command 221).

2.) Call command 221 passing in the specified value. Keep in mind that this is a 4-byte value.

3.) Ask for data using the Response Header Start Byte.

Typical wired binary commands use 0xF7 to indicate the start of a command packet. If 0xF7 is used, response data will never contain a Response Header. Instead, the user should use 0xF9 instead of 0xF7.

This will cause the resulting command to prepend the requested Response Header to the response data.

Typical wired ascii commands use ':' to indicate the start of a typical command packet and the ';' character to indicate to the sensor that the data should have the Response Header prepended. Also note that all

Response Header data will be output in ascending order, starting with the lowest enabled bit and continuing on to the highest enabled bit.

4.) Parse the Response Header data.

Assume we wanted to ask for the raw accelerometer data along with the timestamp and data length and

that we have already called command 221 with a parameter of 65. We then send the following to the

sensor:

0xf9 0x42 0x42

We receive the following response from the sensor:

0x17 0x39 0x15 0x93 0x0c 0xc4 0x86 0x0 0x0 0xc5 0x54 0x0 0x0 0x46 0x7c 0xc0 0x0

Going in order, we used bits 1 and 6, so we can parse out the timestamp first, which is 4 bytes, and then

the data length, which is 1 byte:

Timestamp: 0x17 0x39 0x15 0x93 (389617043)

Data Length: 0x0c (12)

Data: 0xc4 0x86 0x0 0x0 0xc5 0x54 0x0 0x0 0x46 0x7c 0xc0 0x0 (-1072.0, -3392.0, 16176.0)

28

User's Manual

For the ascii version, we would send the following:

“;64\n”

We would receive the following response:

“389617043,37,-1072.00000,-3392.00000,16176.00000\r\n”

4.4.2 Wired Streaming with Response Header

Streaming data can also have Response Header data prepended to each streamed packet. This can be accomplished by calling the Start Streaming command (0x55) with the Response Header Packet Byte. Assuming that streaming has been configured properly and a non-zero Wired Response Header bitfield has been set, the following examples will start streaming with Response Headers disabled and enabled, respectively:

0xf7 0x55 0x55

0xf9 0x55 0x55

//Start streaming WITHOUT response header prepended to each

//packet

//Start streaming WITH response header prepended to each packet

Keep in mind that the actual start command will also have a Response Header attached that must be successfully parsed.

4.4.3 Wireless Response Header

Wireless response headers work similarly to their wired counterparts. The major difference is that instead of using 0xF9, the user should use 0xFA to request data with response headers prepended. The other difference is that the response header is based on a different command than wired sensors. For dongles, command 219 should be used to set the

Wireless Response Header Bitfield. Keep in mind that dongles also maintain a Wired Response Header Bitfield for commands sent directly to the dongle. All other commands sent wirelessly will use the Wireless Response Header

Bitfield. Also note that typical wireless commands (Binary 0xF8 or Ascii '>') will ALWAYS have the success/failure byte, logical ID byte and data length byte (unless the command fails) prepended as described in Section 4.3.

For the ascii version, the character ']' should be used instead of '>' if the response header is desired.

4.4.4 Wireless Streaming with Response Header

Wireless streaming data can also have Response Header data prepended to each streamed packet. This can be accomplished by calling the Start Streaming command (0x55) with the Wireless Response Header Packet Byte.

Assuming that streaming has been configured properly and a non-zero Wireless Response Header bitfield has been set, the following examples will start streaming with Response Headers disabled and enabled, respectively. We will also assume that we are communicating with the sensor mapped to logical ID 0:

0xf8 0x0 0x55 0x55 //Start streaming with only the success/failure, logical ID

//and data length bytes prepended to each packet

0xfa 0x0 0x55 0x55 //Start streaming WITH wireless response header

//prepended to each packet

Keep in mind that the actual start command will also have a Response Header attached that must be successfully parsed.

29

User's Manual

4.5 Command Overview

There are over 90 different command messages that are grouped numerically by function. Unused command message bytes are reserved for future expansion.

When looking at the following command message tables, note the following:

The “Data Len” field indicates the number of additional data-bytes the command expects to follow the command-byte itself. This number doesn't include the Start of Packet, Command, or Checksum bytes. Thus, the total message size can be calculated by adding three bytes to the “Data Len” listed in the table.

Likewise, the “Return Data Len” field indicates the number of data-bytes the command delivers back to the sender once the command has finished executing.

Under “Return Data Details”, each command lists the sort of data which is being returned and next to this in parenthesis the form this data takes. For example, a quaternion is represented by 4 floating point numbers, so a command which returns a quaternion would list “Quaternion(float x4)” for its return data details.

Command length information only applies to binary commands, as ascii commands can vary in length.

For quaternions, data is always returned in x, y, z, w order.

Euler angles are always returned in pitch, yaw, roll order.

When calling commands in ASCII mode, there is no fixed byte length for the parameter data or return data, as the length depends on the ASCII encoding.

4.5.1 Orientation Commands

Command Description

0(0x00)

1(0x01)

Get tared orientation as quaternion

Get tared orientation as euler angles

2(0x02)

3(0x03)

4 (0x04

5(0x05)

6(0x06)

7(0x07)

8(0x08)

9(0x09)

10(0x0A)

11(0x0B)

12(0x0C)

Long Description

Returns the filtered, tared orientation estimate in quaternion form

Returns the filtered, tared orientation estimate in euler angle form

Get tared orientation as rotation matrix

Get tared orientation as axis angle

Get tared orientation as two vector.

Get difference quaternion

Get untared orientation as quaternion

Get untared orientation as euler angles

Get untared orientation as rotation matrix

Get untared orientation as axis angle

Get untared orientation as two vector.

Get tared two vector in sensor frame

Get untared two vector in sensor frame

Returns the filtered, tared orientation estimate in rotation matrix form

Returns the filtered, tared orientation estimate in axis-angle form

Returns the filtered, tared orientation estimate in two vector form, where the first vector refers to forward and the second refers to down.

Returns the difference between the measured orientation from last frame and this frame.

Returns the filtered, untared orientation estimate in quaternion form.

Returns the filtered, untared orientation estimate in euler angle form

Returns the filtered, untared orientation estimate in rotation matrix form

Returns the filtered, untared orientation estimate in axis-angle form

Returns the filtered, untared orientation estimate in two vector form, where the first vector refers to north and the second refers to gravity.

Returns the filtered, tared orientation estimate in two vector form, where the first vector refers to forward and the second refers to down. These vectors are given in the sensor reference frame and not the global reference frame.

Returns the filtered, untared orientation estimate in two vector form, where the first vector refers to forward and the second refers to down. These vectors are given in the sensor reference frame and not the global reference frame.

Return

Data Len

16

12

36

16

24

16

16

12

36

16

24

24

24

Return Data Details

Quaternion (float x4)

Euler Angles (float x3)

Rotation Matrix (float x9)

Axis (float x3), Angle in

Radians (float)

Forward Vector (float x3),

Down Vector (float x3)

Quaternion (float x4)

Quaternion (float x4)

Euler Angles (float x3)

Rotation Matrix (float x9)

Axis (float x3), Angle in

Radians (float)

North Vector (float x3),

Gravity Vector (float x3)

Forward Vector (float x3),

Down Vector (float x3)

North Vector (float x3),

Gravity Vector (float x3)

Data

Len Data Details

0

0

0

0

0

0

0

0

0

0

0

0

0

30

User's Manual

4.5.2 Normalized Data Commands

Command Description

32(0x20)

Get all normalized component sensor data

Long Description

Returns the normalized gyro rate vector, accelerometer vector, and compass vector. Note that the gyro vector is in units of radians/sec, while the

Return

Data Len

accelerometer and compass are unit-length vectors indicating the direction of gravity and north, respectively. These two vectors do not have any magnitude data associated with them.

36

33(0x21)

34(0x22)

35(0x23)

Get normalized gyro rate

Get normalized accelerometer vector

Get normalized compass vector

Returns the normalized gyro rate vector, which is in units of radians/sec.

Returns the normalized accelerometer vector. Note that this is a unit-vector indicating the direction of gravity. This vector does not have any magnitude data associated with it.

Returns the normalized compass vector. Note that this is a unit-vector indicating the direction of gravity.

This vector does not have any magnitude data associated with it.

12

12

12

Return Data Details

Gyro Rate in units of radians/sec (Vector x3),

Gravity Direction (Vector x3), North Direction (Vector x3)

Gyro Rate in units of radians/sec (float x3)

Gravity Direction (Vector x3)

North Direction (Vector x3)

Data

Len Data Details

0

0

0

0

4.5.3 Corrected Data Commands

Command Description

37(0x25)

38(0x26)

39(0x27)

40(0x28)

41(0x29)

Get all corrected component sensor data

Get corrected gyro rate

Get corrected accelerometer vector

Get corrected compass vector

Get corrected linear acceleration in global space

Long Description

Returns the corrected gyro rate vector, accelerometer vector, and compass vector. Note that the gyro vector is in units of radians/sec, the accelerometer vector is in units of G, and the compass vector is in units of gauss.

Returns the corrected gyro rate vector, which is in units of radians/sec. Note that this result is the same data returned by the normalized gyro rate command.

Returns the acceleration vector in units of G. Note that this acceleration will include the static component of acceleration due to gravity.

Return

Data Len

36

Return Data Details

Gyro Rate in units of radians/sec (Vector x3),

Acceleration Vector in units of G (Vector x3), Compass

Vector in units of gauss

(Vector x3)

Data

Len

0

Data Details

12

12

12

Gyro Rate in units of radians/sec (float x3)

Acceleration Vector in units of G (float x3)

Compass Vector in units of gauss (float x3)

0

0

0 Returns the compass vector in units of gauss.

Returns the linear acceleration of the device, which is the overall acceleration which has been orientation compensated and had the component of acceleration due to gravity removed. Uses the tared orientation.

12

Acceleration Vector in units of G (float x3) 0

4.5.4 Other Data Commands

Command Description

43(0x2B)

44(0x2C)

Get temperature C

Get temperature F

45(0x2D)

Get confidence factor

Long Description

Returns the temperature of the sensor in Celsius.

Returns the temperature of the sensor in Fahrenheit

Returns a value indicating how much the sensor is being moved at the moment. This value will return 1 if the sensor is completely stationary, and will return 0 if it is in motion. This command can also return values in between indicating how much motion the sensor is experiencing.

Return

Data Len

4

4

4

Return Data Details

Temperature (float)

Temperature (float)

Confidence Factor (float)

Data

Len

0

0

Data Details

0

31

User's Manual

4.5.5 Raw Data Commands

Command Description

64(0x40)

65(0x41)

66(0x42)

67(0x43)

Get all raw component sensor data

Get raw gyroscope rate

Get raw accelerometer data

Get raw compass data

Long Description

Returns the raw gyro rate vector, accelerometer vector and compass vector as read directly from the component sensors without any additional postprocessing. The range of values is dependent on the currently selected range for each respective sensor.

Returns the raw gyro rate vector as read directly from the gyroscope without any additional postprocessing.

Returns the raw acceleration vector as read directly from the accelerometer without any additional postprocessing.

Returns the raw compass vector as read directly from the compass without any additional postprocessing.

Return

Data Len

36

Return Data Details

Gyro Rate in counts per degrees/sec (Vector x3),

Acceleration Vector in counts per g (Vector x3),

Compass Vector in counts per gauss (Vector x3)

Data

Len

0

Data Details

12

12

12

Gyro Rate in counts per degrees/sec (Vector x3)

Acceleration Vector in counts per g (Vector x3)

Compass Vector in counts per gauss (Vector x3)

0

0

0

4.5.6 Streaming Commands

Command Description

80(0x50)

81(0x51)

82(0x52)

Set streaming slots

Get streaming slots

Set streaming timing

Long Description

Configures data output slots for streaming mode.

Command accepts a list of eight bytes, where each byte corresponds to a different data command. Every streaming iteration, each command will be executed in order and the resulting data will be output in the specified slot. Valid commands are commands in

Return

Data Len

the ranges 0x0 – 0x10, 0x20 – 0x30, 0x40 – 0x50,

0xC9 – 0xCA (for battery-powered sensors) and

0xFA. A slot value of 0xFF 'clears' the slot and prevents any data from being written in that position.

This command can fail if there is an invalid command passed in as any of the parameters or if the total allotted size is exceeded. Upon failure, all slots will be reset to 0xFF. This setting can be saved to nonvolatile flash memory using the Commit Settings command. 0

8 Returns the current streaming slots configuration.

Configures timing information for a streaming session. All parameters are specified in microseconds. The first parameter is the interval, which specifies how often data will be output. A value of 0 means that data will be output at the end of every filter loop. Aside from 0, values lower than

1000 will be clamped to 1000. The second parameter is the duration, which specifies the length of the streaming session. If this value is set to

0xFFFFFFFF, streaming will continue indefinitely until it is stopped via command 0x56. The third parameter is the delay, which specifies a n amount of time the sensor will wait before outputting the first packet of streaming data. This setting can be saved to non-volatile flash memory using the Commit

Settings command.

0

Return Data Details

Commands (Byte x8)

83(0x53)

12

Interval (Unsigned int),

Duration (Unsigned int),

Delay (Unsigned int)

84(0x54)

85(0x55)

86(0x56)

95(0x5F)

Get streaming timing

Get streaming batch

Start streaming

Stop streaming

Update current timestamp

Returns the current streaming timing information.

Return a single packet of streaming data using the current slot configuration.

Start a streaming session using the current slot and timing configuration.

Stop the current streaming session.

Set the current internal timestamp to the specified value.

Varies

0

0

0

Data

Len Data Details

8 Commands (Byte x8)

0

12

Interval (Unsigned int),

Duration (Unsigned int), Delay

(Unsigned int)

0

0

0

0

4 Timestamp (Unsigned int)

32

User's Manual

4.5.7 Configuration Write Commands

Command

16(0x10)

96(0x60)

97(0x61)

98(0x62)

99(0x63)

100(0x64)

101(0x65)

102(0x66)

103(0x67)

104(0x68)

105(0x69)

106(0x6A)

107(0x6B)

Description

Set euler angle decomposition order

Tare with current orientation

Long Description

Sets the current euler angle decomposition order, which determines how the angles returned from command 0x1 are decomposed from the full quaternion orientation. Possible values are 0x0 for

XYZ, 0x1 for YZX, 0x2 for ZXY, 0x3 for ZYX, 0x4 for

XZY or 0x5 for YXZ (default).

Sets the tare orientation to be the same as the current filtered orientation.

Sets the tare orientation to be the same as the supplied orientation, which should be passed as a quaternion.

Tare with quaternion

Tare with rotation matrix

Set static accelerometer rho mode

Set confidence accelerometer rho mode

Set static compass rho mode

Set confidence compass rho mode

Sets the tare orientation to be the same as the supplied orientation, which should be passed as a rotation matrix.

Determines how trusted the accelerometer contribution is to the overall orientation estimation.

Higher values mean that the accelerometer is less trusted.

Determines how trusted the accelerometer contribution is to the overall orientation estimation.

Instead of using a single value, uses a minimum and maximum value. Rho values will be changed within this range depending on the confidence factor. This can have the effect of smoothing out the accelerometer when the sensor is in motion.

Determines how trusted the accelerometer contribution is to the overall orientation estimation.

Higher values mean that the compass is less trusted.

Determines how trusted the compass contribution is to the overall orientation estimation. Instead of using a single value, uses a minimum and maximum value.

Rho values will be changed within this range depending on the confidence factor. This can have the effect of reducing the compass's effect on the overall orientation estimation and thus reducing magnetically-induced interference.

Causes the processor to wait for the specified number of microseconds at the end of each update loop. Can be useful for bounding the overall update rate of the sensor if necessary.

Set desired update rate

Uses the current tared orientation to set up the reference vector for the nearest orthogonal orientation. This is an advanced command that is best used through 3-Space Sensor Suite calibration

Set multi reference vectors with current orientation utilities. For more information, please refer to the 3-

Space Sensor Suite Quick Start Guide.

Set the current reference vector mode. Parameter can be 0 for single static mode, which uses a certain reference vector for the compass and another certain vector for the accelerometer at all times, 1 for single auto mode, which uses (0, -1, 0) as the reference vector for the accelerometer at all times and uses the average angle between the accelerometer and compass to calculate the compass reference vector once upon initiation of this mode, 2 for single auto continuous mode, which works similarly to single

Set reference vector mode

Set oversample rate auto mode, but calculates this continuously, or 3 for multi-reference mode, which uses a collection of reference vectors for the compass and accelerometer both, and selects which ones to use before each step of the filter.

Sets the number of times to sample each component sensor for each iteration of the filter. This can smooth out readings at the cost of performance.

If this value is set to 0 or 1, no oversampling occurs

—otherwise, the number of samples per iteration depends on the specified parameter, up to a maximum of 10. This setting can be saved to nonvolatile flash memory using the Commit Settings command.

Set gyroscope enabled

Enable or disable gyroscope readings as inputs to the orientation estimation. Note that updated gyroscope readings are still accessible via commands. This setting can be saved to non-volatile flash memory using the Commit Settings command.

Return

Data Len

1

0

0

0

0

0

0

0

0

0

0

0

0

Return Data Details

Euler angle decomposition order

(byte)

Data

Len Data Details

0

0

16 Quaternion (float x4)

36 Rotation Matrix (float x9)

4

8

4 Compass rho value (float)

8

4

0

Accelerometer rho value

(float)

Minimum accelerometer rho value (float), Maximum accelerometer rho value (float)

Minimum compass rho value

(float), Maximum compass rho value (float)

Microsecond update rate

(unsigned integer)

1 Mode (Byte)

1 Samples Per Iteration (Byte)

1 Enabled (Byte)

33

User's Manual

Command

108(0x6C)

109(0x6D)

110(0x6E)

Description

Set accelerometer enabled

Set compass enabled

Reset multi-reference vectors to zero

Long Description

Enable or disable accelerometer readings as inputs to the orientation estimation. Note that updated accelerometer readings are still accessible via commands. This setting can be saved to non-volatile flash memory using the Commit Settings command.

Enable or disable compass readings as inputs to the orientation estimation. Note that compass readings are still accessible via commands. This setting can be saved to non-volatile flash memory using the

Commit Settings command.

Resets all reference vectors in the multi-reference table to zero. Intended for advanced users.

Return

Data Len

0

0

0

Return Data Details

111(0x6F)

112(0x70)

113(0x71)

114(0x72)

115(0x73)

Set multi-reference table resolution

Set compass mulfireference vector

Set compass multireference check vector

Set accelerometer multireference vector

Set accelerometer multireference check vector

Sets the number of cell dimensions and number of nearby vectors per cell for the multi-reference lookup table. First parameter indicates the number of cell divisions—as an example, multi-reference mode, by default, only handles orientations reachable by successive rotations of ninety degrees about any of the three axes, and hence, has a resolution of 4 (360

/ 4 == 90). Thus, a resolution of 8 would provide rotations of forty-five degrees about any of the three axes (360 / 8 == 45). The second parameter indicates the number of adjacent vectors that will be checked for each In addition, the number of checked vectors can be adjusted as well. The second parameters refers to the number of adjacent reference vectors that are 'averaged' to produce the final reference vector for the particular orientation, up to a maximum of 32. Intended for advanced users.

Directly set the multi-reference compass vector at the specified index. First parameter is index, second parameter is compass vector. Intended for advanced users.

Set the compass reading to be used as a check vector to determine which cell index to draw the reference vector from. First parameter is an index, second parameter is the compass vector. Intended for advanced users.

Directly set the multi-reference accelerometer vector at the specified index. First parameter is index, second parameter is compass vector. Intended for advanced users.

Set the accelerometer reading to be used as a check vector to determine which cell index to draw the reference vector from. First parameter is an index, second parameter is the accelerometer vector. Intended for advanced users.

0

0

0

0

0

Data

Len Data Details

1 Enabled (Byte)

1 Enabled (Byte)

0

2

Resolution (Byte), Number of

Check Vectors (Byte)

13

Index (Byte), Compass

Reference Vector (float x3)

13

Index (Byte), Compass

Check Vector (float x3)

13

Index (Byte), Accelerometer

Reference Vector (float x3)

13

Index (Byte), Accelerometer

Check Vector (float x3)

34

User's Manual

Command Description Long Description

116(0x74)

117(0x75)

118(0x76)

119(0x77)

120(0x78)

121(0x79)

122(0x7a)

Sets alternate directions for each of the natural axes of the sensor. The only parameter is a bitfield representing the possible combinations of axis swapping. The lower 3 bits specify where each of the natural axes appears:

000: X: Right, Y: Up, Z: Forward (left-handed system, standard operation)

001: X: Right, Y: Forward, Z: Up (right-handed system)

002: X: Up, Y: Right, Z: Forward (right-handed system)

003: X: Forward, Y: Right, Z: Up (left-handed system)

004: X: Up, Y: Forward, Z: Right (left-handed system)

005: X: Forward, Y: Up, Z: Right (right-handed system)

Set axis directions

(For example, using X: Right, Y: Forward, Z: Up means that any values that appear on the positive vertical(Up) axis of the sensor will be the third(Z) component of any vectors and will have a positive sign, and any that appear on the negative vertical axis will be the Z component and will have a negative sign.)

The 3 bits above those are used to indicate which axes, if any, should be reversed. If it is cleared, the axis will be pointing in the positive direction.

Otherwise, the axis will be pointed in the negative direction. (Note: These are applied to the axes after the previous conversion takes place).

Bit 4: Positive/Negative Z (Third resulting component)

Bit 5: Positive/Negative Y (Second resulting component)

Bit 6: Positive/Negative X (First resulting component)

Note that for each negation that is applied, the handedness of the system flips. So, if X and Z are negative and you are using a left-handed system, the system will still be left handed, but if only X is negated, the system will become right-handed.

Sets what percentage of running average to use on the sensor's orientation. This is computed as follows: total_orient = total_orient * percent total_orient = total_orient + current_orient * (1 – percent) current_orient = total_orient

Set running average percent

Set compass reference vector

Set accelerometer reference vector

Reset filter

Set accelerometer range

Set multi-reference weight power

If the percentage is 0, the running average will be shut off completely. Maximum value is 97%. This setting can be saved to non-volatile flash memory using the Commit Settings command.

Sets the static compass reference vector for Single

Reference Mode.

Sets the static accelerometer reference vector for

Single Reference Mode.

Resets the state of the currently selected filter

Only parameter is the new accelerometer range, which can be 0 for ±2g (Default range), which can be

1 for ±4g, or 2 for ±8g. Higher ranges can detect and report larger accelerations, but are not as accurate for smaller accelerations. This setting can be saved to non-volatile flash memory using the Commit

Settings command.

Set weighting power for multi reference vector weights. Multi reference vector weights are all raised to the weight power before they are summed and used in the calculation for the final reference vector.

Setting this value nearer to 0 will cause the reference vectors to overlap more, and setting it nearer to infinity will cause the reference vectors to influence a smaller set of orientations.

Return

Data Len Return Data Details

0

0

0

0

0

0

0

Data

Len Data Details

1 Axis Direction Byte (byte)

4

12

12

0

Running Average Percent

(float)

Compass Reference Vector

(float x3)

Accelerometer Reference

Vector (float x3)

1

Accelerometer range setting

(byte)

4 Weight power (float)

35

User's Manual

Command

123(0x7b)

124(0x7c)

125(0x7d)

126(0x7e)

Description

Set filter mode

Set running average mode

Set gyroscope range

Set compass range

Long Description

Used to disable the orientation filter or set the orientation filter mode. Changing this parameter can be useful for tuning filter-performance versus orientation-update rates. Passing in a parameter of 0 places the sensor into IMU mode, a 1 places the

Return

Data Len

sensor into Kalman Filtered Mode (Default mode), a

2 places the sensor into Alternating Kalman Filter

Mode, a 3 places the sensor into Complementary

Filter Mode and a 4 places the sensor into

Quaternion Gradient Descent Filter Mode. More information can be found in Section 3.1.5. This setting can be saved to non-volatile flash memory using the Commit Settings command.

0

Used to further smooth out the orientation at the cost of higher latency. Passing in a parameter of 0 places the sensor into a static running average mode, a 1 places the sensor into a confidencebased running average mode, which changes the running average factor based upon the confidence factor, which is a measure of how 'in motion' the sensor is. This setting can be saved to non-volatile flash memory using the Commit Settings command.

Only parameter is the new gyroscope range, which can be 0 for ±250 DPS, 1 for ±500 DPS, or 2 for

±2000 DPS (Default range). Higher ranges can detect and report larger angular rates, but are not as accurate for smaller angular rates. This setting can be saved to non-volatile flash memory using the

Commit Settings command.

0

0

Only parameter is the new compass range, which can be 0 for ±0.88G, 1 for ±1.3G (Default range), 2 for ±1.9G, 3 for ±2.5G, 4 for ±4.0G, 5 for ±4.7G, 6 for

±5.6G, or 7 for ±8.1G. Higher ranges can detect and report larger magnetic field strengths but are not as accurate for smaller magnetic field strengths. This setting can be saved to non-volatile flash memory using the Commit Settings command.

0

Return Data Details

Data

Len Data Details

1 Mode (Byte)

1 Mode (Byte)

1

Gyroscope range setting

(Byte)

1 Compass range setting (Byte)

36

User's Manual

4.5.8 Configuration Read Commands

Command Description

128(0x80)

129(0x81)

130(0x82)

131(0x83)

132(0x84)

133(0x85)

134(0x86)

135(0x87)

136(0x88)

137(0x89)

138(0x8a)

139(0x8b)

140(0x8c)

141(0x8d)

142(0x8e)

143(0x8f)

144(0x90)

145(0x91)

146(0x92)

148(0x94)

149(0x95)

Get tare orientation as quaternion

Get tare orientation as rotation matrix

Get accelerometer rho value

Get compass rho value

Get current update rate

Get compass reference vector

Get accelerometer reference vector

Long Description

Returns the current tare orientation as a quaternion.

Returns the current tare orientation as a rotation matrix.

Returns the current accelerometer rho mode as well as the value. If this mode is set to 0 (static), this will return the rho mode, the static rho value, and then a dummy value of 0. If this mode is set to 1, this will return the rho mode, and the minimum and maximum rho values.

Returns the current compass rho mode as well as the value. If this mode is set to 0 (static), this will return the rho mode, the static rho value, and then a dummy value of 0. If this mode is set to 1, this will return the rho mode, and the minimum and maximum rho values.

Reads the amount of time taken by the last filter update step.

Reads the current compass reference vector. Note that this is not valid if the sensor is in Multi

Reference Vector mode.

Reads the current compass reference vector. Note that this is not valid if the sensor is in Multi

Reference Vector mode.

Get reference vector mode

Get compass multireference vector

Get compass multireference check vector

Get accelerometer multireference vector

Reads the current reference vector mode. Return value can be 0 for single static, 1 for single auto, 2 for single auto continuous or 3 for multi.

Reads the multi-reference mode compass reference vector at the specified index. Intended for advanced users.

Reads the multi-reference mode compass reference check vector at the specified index. Intended for advanced users.

Reads the multi-reference mode accelerometer reference vector at the specified index. Intended for advanced users.

Reads the multi-reference mode accelerometer reference check vector at the specified index.

Intended for advanced users.

Get accelerometer multireference check vector

Get gyroscope enabled state

Returns a value indicating whether the gyroscope contribution is currently part of the orientation estimate: 0 for off, 1 for on.

Get accelerometer enabled

Returns a value indicating whether the accelerometer contribution is currently part of the orientation state estimate: 0 for off, 1 for on.

Get compass enabled state

Get axis direction

Get oversample rate

Get running average percent

Get desired update rate

Get accelerometer range

Get multi-reference mode power weight

Returns a value indicating whether the compass contribution is currently part of the orientation estimate: 0 for off, 1 for on.

Returns a value indicating the current axis direction setup. For more information on the meaning of this value, please refer to the Set Axis Direction command (116).

Returns a value indicating how many times each component sensor is sampled before being stored as raw data. A value of 1 indicates that no oversampling is taking place, while a value that is higher indicates the number of samples per component sensor per filter update step.

Returns a value indicating how heavily the orientation estimate is based upon the estimate from the previous frame. For more information on the meaning of this value, please refer to the Set Running Average

Percent command (117).

Returns the current desired update rate. Note that this value does not indicate the actual update rate, but instead indicates the value that should be spent

'idling' in the main loop. Thus, without having set a specified desired update rate, this value should read

0.

Return the current accelerometer measurement range, which can be a 0 for ±2g, 1 for ±4g or a 2 for

±8g.

Read weighting power for multi-reference vector weights. Intended for advanced users.

Return

Data Len

16

36

9

9

4

12

12

1

12

12

12

12

1

1

1

1

1

4

4

1

4

Return Data Details

Quaternion (float x4)

Rotation Matrix (float x9)

Accelerometer rho mode

(byte), Accelerometer rho values (float x2)

Compass rho mode (byte),

Compass rho values (float x2)

Last update time in microseconds (int)

Compass reference vector

(float x3)

Accelerometer reference vector (float x4)

Mode (byte)

Compass multi-reference reference vector (float x3)

Compass multi-reference reference check vector

(float x3)

Accelerometer multireference reference vector

(float x3)

Accelerometer multireference reference check vector (float x3)

Gyroscope enabled value

(byte)

Accelerometer enabled value (byte)

Compass enabled value

(byte)

Axis direction value (byte)

Oversample rate (byte)

Running average percent

(float)

Desired update rate in microseconds (int)

Accelerometer range setting (byte)

Weight (float)

Data

Len Data Details

0

0

0

0

0

0

0

0

1 Index (byte)

1 Index (byte)

1 Index (byte)

1 Index (byte)

0

0

0

0

0

0

0

0

0

37

User's Manual

Command

150(0x96)

151(0x97)

152(0x98)

153(0x99)

154(0x9a)

155(0x9b)

156(0x9c)

Description

Get multi-reference resolution

Get number of multireference cells

Get filter mode

Get running average mode

Get gyroscope range

Get compass range

Get euler angle decomposition order

Long Description

Reads number of cell divisions and number of nearby vectors per cell for the multi-reference vector lookup table. For more information on these values, please refer to the Set Multi-Reference Resolution command (111). Intended for advanced users.

Return

Data Len

2

Reads the total number of multi-reference cells.

Intended for advanced users.

Returns the current filter mode, which can be 0 for

IMU mode, 1 for Kalman, 2 for Alternating Kalman or

3 for Complementary. For more information, please refer to the Set Filter Mode command (123).

Reads the selected mode for the running average, which can be 0 for normal or 1 for confidence.

Reads the current gyroscope measurement range, which can be 0 for ±250 DPS, 1 for ±500 DPS or 2 for ±2000 DPS.

Reads the current compass measurement range, which can be 0 for ±0.88G, 1 for ±1.3G, 2 for ±1.9G,

3 for ±2.5G, 4 for ±4.0G, 5 for ±4.7G, 6 for ±5.6G or

7 for ±8.1G.

4

1

1

1

1

Reads the current euler angle decomposition order.

0

Return Data Details

Number of cell divisions

(byte), number of nearby vectors (byte)

Number of cells (int)

Filter mode (byte)

Running average mode

(byte)

Gyroscope range setting

(byte)

Compass range setting

(byte)

Data

Len Data Details

0

0

0

0

0

0

1

Euler angle decomposition order (byte)

38

User's Manual

4.5.9 Calibration Commands

Command

160(0xa0)

161(0xa1)

162(0xa2)

163(0xa3)

164(0xa4)

165(0xa5)

166(0xa6)

169(0xa9)

170(0xaa)

171(0xab)

172(0xac)

173(0xad)

174(0xae)

175(0xaf)

Description

Set compass calibration coefficients

Long Description

Sets the current compass calibration parameters to the specified values. These consist of a bias which is added to the raw data vector and a matrix by which the value is multiplied. This setting can be saved to non-volatile flash memory using the Commit

Settings command.

Sets the current accelerometer calibration parameters to the specified values. These consist of a bias which is added to the raw data vector and a matrix by which the value is multiplied. This setting can be saved to non-volatile flash memory using the

Commit Settings command.

Return

Data Len

0

0

Set accelerometer calibration coefficients

Get compass calibration coefficients

Get accelerometer calibration coefficients

Get gyroscope calibration coefficients

Return the current compass calibration parameters.

Return the current accelerometer calibration parameters.

Begin gyroscope autocalibration

Set gyroscope calibration coefficients

Set calibration mode

Get calibration mode

Set ortho-calibration data point from current orientation

Set ortho-calibration data point from vector

Return the current gyroscope calibration parameters.

Performs auto-gyroscope calibration. Sensor should remain still while samples are taken. The gyroscope bias will be automatically placed into the bias part of the gyroscope calibration coefficient list.

Sets the current gyroscope calibration parameters to the specified values. These consist of a bias which is added to the raw data vector and a matrix by which the value is multiplied. This setting can be saved to non-volatile flash memory using the Commit

Settings command.

Bias, 1 for Scale-Bias and 2 for Ortho-Calibration.

For more information, refer to section 3.1.3

Additional Calibration. This setting can be saved to non-volatile flash memory using the Commit Settings command.

Reads the current calibration mode, which can be 0 for Bias, 1 for Scale-Bias or 2 for Ortho-Calibration.

For more information, refer to section 3.1.3

Additional Calibration.

Set the ortho-calibration compass and accelerometer vectors corresponding to this orthogonal orientation. Intended for advanced users.

Directly set a vector corresponding to this orthogonal orientation. First parameter is type, where 0 is for compass and 1 is for accelerometer. Second parameter is index, which indicates the orthogonal orientation. Intended for advanced users.

Get ortho-calibration data point

Perform ortho-calibration

Clear ortho-calibration data

Return the vector corresponding to the orthogonal orientation given by index. First parameter is type, where 0 is for compass and 1 is for accelerometer.

Second parameter is index, which indicates the orthogonal orientation. Intended for advanced users.

Stores accelerometer and compass data in the ortho-lookup table for use in the orientation fusion algorithm. For best results, each of the 24 orientations should be filled in with component sensor data. Note also that ortho-calibration data will not be used unless the calibration mode is set to

Ortho-Calibration. For more information, refer to

Section 3.1.3 Additional Calibration. Intended for advanced users.

Clear out all ortho-lookup table data. Intended for advanced users.

48

48

48

0

0

0

1

0

0

12

0

0

Return Data Details

Matrix (float x9), Bias (float x3)

Matrix (float x9), Bias (float x3)

Matrix (float x9), Bias (float x3)

Mode (byte)

Accelerometer or compass vector (float x3)

Data

Len Data Details

48

48

0

48

0

0

14

Matrix (float x9), Bias (float x3)

Matrix (float x9), Bias (float x3)

Matrix (float x9), Bias (float x3)

1 Mode (Byte)

Type (Byte), Index (Byte),

Accelerometer or Compass

Vector (float x3)

2 Type (Byte), Index (Byte)

0

0

39

User's Manual

4.5.10 Dongle Commands

Command Description

176(0xb0)

177(0xb1)

Set wireless stream mode

Get wireless stream mode

Long Description

Set the wireless communication's streaming flush mode. If this value is set to 0 (default), data must be

'released' using manual flush commands. If this value is set to 1, data will be output immediately via the

Return

Data Len

dongle's USB connection. Note that this only exists for wireless communication. For more information, refer to Section 3.2.2 and 3.3.3. This setting can be set to non-volatile flash memory by using the

Commit Settings command.

Returns the wireless communication's current asynchronous flush mode, which can be 0 for auto flush and 1 for manual flush. For more information, refer to Section 3.2.2 and Section 3.3.3.

0

1

Return Data Details

Auto-flush mode (byte)

178(0xb2)

179(0xb3)

180(0xb4)

181(0xb5)

182(0xb6)

208(0xd0)

209(0xd1)

210(0xd2)

211(0xd3)

212(0xd4)

213(0xd5)

214(0xd6)

Set wireless streaming manual flush bitfield

Get async flush bitfield

Allows the dongle to control which wirelessly received data is output via manual flush mode. The parameter represents a bitfield that represents which wireless sensors' logical IDs can currently output data. If a bit for a corresponding sensor is set to 0, no data at all will be output for that sensor in any condition, even if data is received for that sensor.

This setting can be set to non-volatile flash memory by using the Commit Settings command.

Returns the current manual flush bitfield representing which logical Ids will respond to asynchronous requests.

Flush data output for a single logical ID. For more information, please refer to Section 3.2.2 and

Section 3.2.3

Manual flush single

Manual flush bulk

Flush data output for all logical Ids. For more information, please refer to Section 3.2.2 and

Section 3.2.3

Sends out a timestamp synchronization broadcast message to all wireless sensors that are listening on the same channel and PanID as the dongle. The

Broadcast synchronization message will essentially set each receiving sensor's timestamp to the same timestamp as stored in the pulse

Get serial number at logical ID dongle.

Return the mapped serial number for the given logical ID.

Set serial number at logical ID

Set the mapped serial number given by the logical

ID. This setting can be committed to non-volatile flash memory by calling the Commit Wireless

Settings command.

Return the noise levels for each of the 16 wireless channels. A higher value corresponds to a noisier

Get wireless channel noise channel, which can significantly impact wireless levels reception and throughput.

Set wireless retries

Get wireless retries

Get wireless slots open

Get signal strength

Set the number of times a dongle will attempt to retransmit a data request after timing out. Default value is 3. This setting can be committed to non-volatile flash memory by calling the Commit Wireless

Settings command.

Read the number of times a dongle will attempt to re-transmit a data request after timing out. Default value is 3.

The dongle can simultaneously service up to sixteen individual data requests to wireless sensors. As sensors respond, requests are removed from the table. In the case that too many requests are sent to the dongle in too short a period, the dongle will begin tossing them out. This value will return the number of slots currently open. If this value is 0, no more wireless requests will be handled until some are internally processed.

Returns a value indicating the reception strength of the most recently received packet. Higher values indicate a stronger link.

0

2

Varies

Varies

0

4

0

16

0

1

1

1

Manual flush bitfield (short)

Serial number (int)

Channel strengths (byte x16)

Retries (byte)

Slots open (byte)

Data

Len Data Details

1 Auto-flush mode (byte)

0

2

0

0

0

5

0

Manual flush bitfield (short)

1 Logical ID (Byte)

1 Logical ID (Byte)

Logical ID (Byte), Serial number (int)

1 Retries (byte)

0

0

Last packet signal strength

(byte) 0

40

User's Manual

Command Description

219(0xdb)

220(0xdc)

Set wireless response header bitfield

Get wireless response header bitfield

Long Description

Configures the response header for data returned over a wireless connection. The only parameter is a four-byte bitfield that determines which data is prepended to all data responses. The following bits are used:

Return

Data Len Return Data Details

0x1: (1 byte) Success/Failure, with non-zero values representing failure.

0x2: (4 bytes) Timestamp, in microseconds.

0x4: (1 byte) Command echo—outputs the called command. Returns 0xFF for streamed data.

0x8: (1 byte) Additive checksum over returned data, but not including response header.

0x10: (1 byte) Logical ID

0x20: (4 bytes) Serial number

0x40: (1 byte) Data length, returns the length of the requested data, not including response header.

This setting can be committed to non-volatile flash memory by calling the Commit Wireless Settings command.

Return the current wireless response header bitfield.

0

4

Response header bitfield

(Unsigned int)

Data

Len Data Details

4

0

Response header bitfield

(Unsigned int)

4.5.11 Wireless Sensor & Dongle Commands

Command Description

192(0xc0)

193(0xc1)

194(0xc2)

195(0xc3)

197(0xc5)

198(0xc6)

Read wireless panID

Set wireless panID

Read wireless channel

Set wireless channel

Commit wireless settings

Read wireless address

Long Description

Return the current panID for this wireless sensor or dongle. For more information, refer to Section 2.9

Wireless Terminology.

Set the current panID for this wireless sensor or dongle. Note that the panID for a wireless sensor can only be set via the USB connection. For more information, refer to Section 2.9 Wireless

Terminology. This setting can be committed to nonvolatile flash memory by calling the Commit

Wireless Settings command.

Read the current channel for this wireless sensor or dongle. For more information, refer to Section 2.9

Wireless Terminology.

Set the current channel for this wireless sensor or dongle. For more information, refer to Section 2.9

Wireless Terminology. This setting can be committed to non-volatile flash memory by calling the Commit Wireless Settings command.

Commits all current wireless settings to non-volatile flash memory, which will persist after the sensor is powered off. For more information on which parameters can be stored in this manner, refer to

Section 3.4 Sensor Settings.

Read the wireless hardware address for this sensor or dongle.

Return

Data Len

2

0

1

0

0

2

Return Data Details

PanID (short)

Channel (Byte)

Address (short)

Data

Len Data Details

0

2 PanID (short)

1 Channel (byte)

0

4.5.12 Battery Commands

Command Description

201(0xc9)

202(0xca)

203(0xcb)

Get battery voltage

Get battery percent remaining

Get battery status

Long Description

Read the current battery level in volts. Note that this value will read as slightly higher than it actually is if it is read via a USB connection.

Read the current battery lifetime as a percentage of the total. Note that this value will read as slightly higher than it actually is if it is read via a USB connection.

Returns a value indicating the current status of the battery, which can be a 3 to indicate that the battery is currently not charging, a 2 to indicate that the battery is charging and thus plugged in, or a 1 to indicate that the sensor is fully charged.

Return

Data Len

4

1

1

Return Data Details

Battery level in voltage

(float)

Battery level as percent

(byte)

Battery charge status

(byte)

Data

Len Data Details

0

0

0

41

User's Manual

4.5.13 General Commands

Command Description

196(0xc4)

Set LED Mode

Long Description

Allows finer-grained control over the sensor LED.

Accepts a single parameter that can be 0 for standard, which displays all standard LED status indicators or 1 for static, which displays only the

LED color as specified by command 238. For more information on LED status indicators, please refer to

Section 2.10.

Return

Data Len

0

Return Data Details

200(0xc8)

221(0xdd)

222(0xde)

223(0xdf)

224(0xe0)

225(0xe1)

226(0xe2)

227(0xe3)

228(0xe4)

229(0xe5)

230(0xe6)

231(0xe7)

232(0xe8)

Get LED Mode

Returns the current sensor LED mode, which can be

0 for standard or 1 for static. For more information on

LED status indicators, please refer to Section 2.10.

Configures the response header for data returned over a wired connection. The only parameter is a four-byte bitfield that determines which data is prepended to all data responses. The following bits are used:

0x1: (1 byte) Success/Failure, with non-zero values representing failure.

0x2: (4 bytes) Timestamp, in microseconds.

0x4: (1 byte) Command echo—outputs the called command. Returns 0xFF for streamed data.

0x8: (1 byte) Additive checksum over returned data, but not including response header.

0x10: (1 byte) Logical ID, returns 0xFE for wired sensors. Meant to be used with 3-Space Dongle response header (For more info, see command

0xDB).

0x20: (4 bytes) Serial number

0x40: (1 byte) Data length, returns the length of the requested data, not including response header.

Set wired response header memory by calling the Commit Settings command.

For more information on Response Headers, please bitfield

This setting can be committed to non-volatile flash refer to Section 4.4.

Get wired response header bitfield

Return the current wired response header bitfield.

For more information, please refer to Section 4.4.

Get firmware version string

Restore factory settings

Commit settings

Software reset

Set sleep mode

Get sleep mode

Enter bootloader mode

Get hardware version string

Set UART baud rate

Get UART baud rate

Returns a string indicating the current firmware version.

Return all non-volatile flash settings to their original, default settings.

Commits all current sensor settings to non-volatile flash memory, which will persist after the sensor is powered off. For more information on which parameters can be stored in this manner, refer to

Section 3.4 Sensor Settings.

Resets the sensor.

Sets the current sleep mode of the sensor.

Supported sleep modes are 0 for NONE and 1 for

IDLE. IDLE mode merely skips all filtering steps.

NONE is the default state.

Reads the current sleep mode of the sensor, which can be 0 for NONE or 1 for IDLE.

Places the sensor into a special mode that allows firmware upgrades. This will case normal operation until the firmware update mode is instructed to return the sensor to normal operation. For more information on upgrading firmware, refer to the 3-Space Sensor

Suite Quick Start Guide.

Returns a string indicating the current hardware version.

Sets the baud rate of the physical UART. This setting does not need to be committed, but will not take effect until the sensor is reset. Valid baud rates are 1200, 2400, 4800, 9600, 19200, 28800, 38400,

57600, 115200 (default), 230400, 460800 and

921600. Note that this is only applicable for sensor types that have UART interfaces.

Returns the baud rate of the physical UART. Note that this is only applicable for sensor types that have

UART interfaces.

1

0

4

12

0

0

1

0

0

0

32

0

4

LED mode (byte)

Response header configuration (Unsigned int)

Firmware version (string)

Sleep mode (byte)

Hardware version (string)

Baud rate (int)

Data

Len Data Details

1 LED mode (byte)

0

4

0

0

Response header configuration (Unsigned int)

0

0

0

1 Sleep mode (byte)

0

0

0

4 Baud rate (int)

0

42

Command Description

233(0xe9)

234(0xea)

237(0xed)

Set USB Mode

Get USB Mode

Get serial number

238(0xee)

239(0xef)

Set LED color

Get LED color

User's Manual

Long Description

Sets the communication mode for USB. Accepts one value that can be 0 for CDC (default) or 1 for

FTDI.

Returns the current USB communication mode.

Returns the serial number, which will match the value etched onto the physical sensor.

Sets the color of the LED on the sensor to the specified RGB color. This setting can be committed to non-volatile flash memory by calling the Commit

Wireless Settings command.

Returns the color of the LED on the sensor.

Return

Data Len Return Data Details

0

1

4

0

12

USB communication mode

(byte)

Serial number (int)

RGB Color (float x3)

Data

Len Data Details

1

0

0

12 RGB Color (float x3)

0

USB communication mode

(byte)

4.5.14 Wireless HID Commands

Command Description

215(0xd7)

216(0xd8)

217(0xd9)

Set wireless HID update rate

Get wireless HID update rate

Set wireless HID asynchronous mode

Long Description

Specify the interval at which HID information is requested by the dongle. The default and minimum value is 15ms in synchronous HID mode. In asynchronous HID mode, the minimum is 5ms. This setting can be committed to non-volatile flash memory by calling the Commit Wireless Settings command.

Return the interval at which HID information is requested by the dongle.

Sets the current wireless HID communication mode.

Supplying a 0 makes wireless HID communication synchronous, while a 1 makes wireless HID asynchronous. For more information, refer to Section

3.3.4 Wireless Joystick/Mouse. This setting can be committed to non-volatile flash memory by calling the Commit Wireless Settings command.

Return

Data Len

0

1

0

218(0xda)

240(0xf0)

241(0xf1)

242(0xf2)

243(0xf3)

Get wireless HID asynchronous mode

Set joystick logical ID

Set mouse logical ID

Get joystick logical ID

Get mouse logical ID

Returns the current wireless HID communication mode, which can be a 0 for synchronous wireless

HID or a 1 for asynchronous wireless HID.

Causes the sensor at the specified logical ID to return joystick HID data. Passing a -1 will disable wireless joystick data. For more information, refer to

Section 3.3.4 Wireless Joystick/Mouse.

Causes the sensor at the specified logical ID to return mouse HID data. Passing a -1 will disable wireless mouse data. For more information, refer to

Section 3.3.4 Wireless Joystick/Mouse.

Returns the current logical ID of the joystick-enabled sensor or -1 if none exists.

Returns the current logical ID of the mouse-enabled sensor or -1 if none exists.

1

0

0

1

1

Return Data Details

Last packet signal strength

(byte)

HID update rate in milliseconds

HID communication mode

Joystick-enabled logical ID

(byte)

Mouse-enabled logical ID

(byte)

Data

Len Data Details

1

0

1

0

1

1

0

0

HID update rate in milliseconds (byte)

HID communication mode

(byte)

Joystick logical ID (signed byte)

Mouse logical ID (signed byte)

4.5.15 Wired HID Commands

Command Description

240(0xf0)

241(0xf1)

242(0xf2)

243(0xf3)

Set joystick enabled

Set mouse enabled

Get joystick enabled

Get mouse enabled

Long Description

Enable or disable streaming of joystick HID data for this sensor.

Enable or disable streaming of mouse HID data for this sensor.

Read whether the sensor is currently streaming joystick HID data.

Read whether the sensor is currently streaming mouse HID data.

Return

Data Len

0

0

1

1

Return Data Details

Joystick enabled state

(byte)

Data

Len Data Details

1 Joystick enabled state (byte)

1 Mouse enabled state (byte)

0

Mouse enabled state (byte) 0

43

User's Manual

4.5.16 General HID Commands

Command Description

244(0xf4)

Set control mode

Long Description

Sets the operation mode for one of the controls. The first parameter is the control class,which can be 0 for Joystick Axis, 1 for Joystick Button, 2 for Mouse

Axis or 3 for Mouse Button. There are two axes and eight buttons on the joystick and mouse. The second parameter, the control index, selects which one of these axes or buttons you would like to modify. The third parameter, the handler index, specifies which handler you want to take care of this control. These can be the following:

Turn off this control: 255

Axes:

Global Axis: 0

Screen Point: 1

Buttons:

Hardware Button: 0

Orientation Button: 1

Shake Button: 2

Return

Data Len Return Data Details

0

245(0xf5)

246(0xf6)

247(0xf7)

248(0xf8)

249(0xf9)

Set control data

Get control mode

Get control data

Set button gyro disable length

Get button gyro disable lentgh

Sets parameters for the specified control's operation mode. The control classes and indices are the same as described in command 244. Each mode can have up to 10 data points associated with it. How many should be set and what they should be set to is entirely based on which mode is being used.

Reads the handler index of this control's mode. The control classes and indices are the same as described in command 244.

Reads the value of a certain parameter of the specified control's operation mode. The control classes and indices are the same as described in command 244.

Determines how long, in frames, the gyros should be disabled after one of the physical buttons on the sensor is pressed. A setting of 0 means they won't be disabled at all. This setting helps to alleviate gyro disturbances cause by the buttons causing small shockwaves in the sensor.

0

1

4

0

1

Handler index (byte)

Data point (float)

Number of frames (byte)

250(0xfa)

251(0xfb)

Get button state

Set mouse absolute/relative mode

Returns the current button gyro disable length.

Reads the current state of the sensor's physical buttons. This value returns a byte, where each bit represents the state of the sensor's physical buttons.

Puts the mode in absolute or relative mode. This change will not take effect immediately and the sensor must be reset before the mouse will enter this mode. The only parameter can be 0 for absolute

(default) or 1 for relative

1

0

Button state (byte)

252(0xfc)

253(0xfd)

254(0xfe)

Get mouse absolute/relative mode

Set joystick and mouse present/removed

Return the current mouse absolute/relative mode.

Note that if the sensor has not been reset since it has been put in this mode, the mouse will not reflect this change yet, even though the command will.

Sets whether the joystick and mouse are present or removed. The first parameter is for the joystick, and can be 0 for removed or 1 for present. The second parameter is for the mouse. If removed, they will not show up as devices on the target system at all. For these changes to take effect, the sensor driver may need to be reinstalled.

Get joystick and mouse present/removed

Returns whether the joystick and mouse are present or removed.

1

0

2

Absolute or relative mode

(byte)

Joystick present/removed

(byte), Mouse present/removed (byte)

Data

Len Data Details

3

Control class (byte), control index (byte), handler index

(byte)

7

Control class (byte), control index (byte), data point index

(byte), data point (float)

2

Control class (byte), control index (byte)

3

Control class (byte), control index (byte), data point index

(byte)

1 Number of frames (byte)

0

0

1

Absolute or relative mode

(byte)

0

2

Joystick present/removed

(byte), Mouse present/removed (byte)

0

44

Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement

Table of contents