Protocol Documentation

The type of command being sent. This field determines which payload (if any) should be populated and how the Quest should process the command. See QuestNavCommandType enum for available command types.

Unique identifier for this command instance. This ID is used to match commands with their responses in asynchronous communication. The client should generate unique IDs for each command to avoid confusion. The Quest will echo this ID in the response message. Recommended: Use incrementing integers or timestamps for uniqueness. Note: For FRC users, the vendor dependency will handle this automatically.

Payload for POSE_RESET commands. Set this field when type = POSE_RESET.

Command ID that matches the original command. This field echoes the command_id from the original ProtobufQuestNavCommand that this response corresponds to. Clients use this to match responses with their original commands in asynchronous communication.

Indicates whether the command was executed successfully. true: Command completed successfully false: Command failed (see error_message for details) Note: A successful response means the command was processed, but doesn't necessarily guarantee the desired outcome (e.g., pose reset might succeed but tracking could still be poor due to environmental conditions).

Human-readable error message when success = false. This field provides detailed information about why a command failed. It should be empty or ignored when success = true. Error messages are intended for debugging and logging purposes. They may include technical details about the failure cause. Examples: - "Invalid pose coordinates: x value out of field bounds" - "Tracking system not initialized" - "Unknown command type"

The target pose to reset the robot to. This should represent the robot's actual position and orientation on the field in the WPILib coordinate system. The Quest will update its internal tracking to match this pose, effectively correcting any accumulated drift. Units: - Translation: meters - Rotation: radians

Count of tracking loss events since app startup. This counter increments each time the Quest's tracking system loses tracking after having established it. Tracking loss can occur due to: - Poor lighting conditions - Lack of visual features in environment - Rapid motion or acceleration - Occlusion of cameras - Hardware issues A high or rapidly increasing counter may indicate: - Environmental issues (lighting, features) - Quest mounting problems (vibration, obstruction) - Hardware degradation This metric helps assess tracking system reliability and can trigger alerts or fallback behaviors in robot code.

Current tracking status of the Quest device. true: Quest is actively tracking and pose data is reliable false: Quest has lost tracking and pose data should not be trusted When tracking is lost: - Pose data becomes stale and unreliable - Robot should switch to alternative localization methods - Movement should be limited or stopped for safety Tracking can be recovered by: - Improving lighting conditions - Moving to area with more visual features - Reducing motion to allow system to re-initialize - Performing pose reset when tracking recovers External systems should monitor this field and implement appropriate fallback behaviors when tracking is lost.

Quest device battery level as a percentage (0-100). This provides the current battery charge level of the Quest headset, allowing external systems to: - Monitor power status during operation - Implement low-battery warnings or behaviors - Plan operation duration and charging needs - Trigger graceful shutdown procedures Battery Level Guidelines: - 100%: Fully charged - 50-100%: Normal operation - 20-50%: Consider charging soon - 10-20%: Low battery warning recommended - 0-10%: Critical - plan immediate shutdown/charging Note: Battery drain rate depends on: - Processing load (tracking complexity) - Display usage (if any) - Wireless communication activity - Environmental temperature

Sequential frame counter for this tracking session. This counter increments with each frame processed by the Quest's tracking system. It can be used to: - Detect dropped messages - Calculate effective frame rate - Synchronize with other data streams The counter resets to 0 when the QuestNav app starts and increments continuously during operation. Frame drops in transmission will create gaps in the sequence.

Timestamp in seconds since QuestNav app startup. This provides timing information for the tracking data, allowing external systems to: - Calculate data age and latency - Interpolate or extrapolate poses for prediction - Synchronize with other sensor data - Implement timeout detection The timestamp is relative to app startup, not system time, to avoid clock synchronization issues between devices. Resolution: Typically sub-millisecond precision

Quest's 2D pose on the field in WPILib coordinates. This represents the Quest's position and orientation as determined by the Quest's tracking system. The pose accounts for: - Coordinate system transformation to WPILib standard - Any calibration offsets applied Note: This is the Quest's position; end user code applies mounting offset to get the robot's position. Coordinate System Details: - X: Forward direction (towards opposing alliance) - Y: Left direction (when facing forward) - Rotation: Counter-clockwise positive (radians) - Units: meters for translation, radians for rotation Accuracy depends on: - Environmental lighting and features - Quest tracking quality - Calibration accuracy - Time since last pose reset

Center pose of the ellipse. The translation component specifies the center point of the ellipse in the coordinate system. The rotation component specifies the orientation of the ellipse's local coordinate frame. The ellipse's axes are aligned with this local coordinate frame: - X semi-axis extends along local X-axis (rotated forward direction) - Y semi-axis extends along local Y-axis (rotated left direction)

Semi-axis length along the ellipse's local X-axis. This is half the width of the ellipse in the direction of the center pose's forward direction (after rotation). The ellipse extends ±xSemiAxis from the center along this axis. Units: meters Must be positive Note: This is the semi-axis, not the full width. The full width along this axis is 2 * xSemiAxis.

Semi-axis length along the ellipse's local Y-axis. This is half the height of the ellipse in the direction of the center pose's left direction (after rotation). The ellipse extends ±ySemiAxis from the center along this axis. Units: meters Must be positive Note: This is the semi-axis, not the full height. The full height along this axis is 2 * ySemiAxis.

Position component of the pose. This specifies where the robot is located on the field using the field coordinate system. The translation represents the position of the robot's coordinate frame origin (typically the robot center).

Orientation component of the pose. This specifies which direction the robot is facing on the field. The rotation represents the angle between the robot's forward direction and the field's positive X-axis (forward direction). Combined with translation, this fully defines the robot's pose and allows for coordinate transformations between robot and field frames.

Center pose of the rectangle. The translation component specifies the center point of the rectangle in the coordinate system. The rotation component specifies the orientation of the rectangle's local coordinate frame. The rectangle's edges are aligned with this local coordinate frame: - Width extends along local X-axis (rotated forward direction) - Height extends along local Y-axis (rotated left direction)

Width of the rectangle along its local X-axis. This is the dimension of the rectangle in the direction of the center pose's forward direction (after rotation). The rectangle extends ±xWidth/2 from the center along this axis. Units: meters Must be positive

Height of the rectangle along its local Y-axis. This is the dimension of the rectangle in the direction of the center pose's left direction (after rotation). The rectangle extends ±yWidth/2 from the center along this axis. Units: meters Must be positive

Rotation angle in radians. The angle is measured counter-clockwise from the positive X-axis. Range: Typically -π to π, but can represent any angle value. Examples: - 0.0: Facing forward (positive X) - π/2: Facing left (positive Y) - π: Facing backward (negative X) - -π/2 or 3π/2: Facing right (negative Y) Units: radians

Translation component of the transformation. This represents the displacement between the origins of the two coordinate frames. It specifies how far and in which direction the target frame's origin is from the source frame's origin.

Rotation component of the transformation. This represents the angular difference between the two coordinate frames. It specifies how much the target frame is rotated relative to the source frame. The rotation is applied before the translation in the transformation sequence (standard mathematical convention).

X-coordinate (forward/backward displacement). Positive values indicate forward direction (towards opposing alliance). Negative values indicate backward direction. Units: meters

Y-coordinate (left/right displacement). Positive values indicate leftward direction (when facing forward). Negative values indicate rightward direction. Units: meters

Linear velocity in X direction. Rate of change of X position over time. In field coordinates, this represents forward/backward velocity. Positive values: Moving in positive X direction (forward) Negative values: Moving in negative X direction (backward) Units: meters per second

Linear velocity in Y direction. Rate of change of Y position over time. In field coordinates, this represents left/right velocity (strafing). Positive values: Moving in positive Y direction (left) Negative values: Moving in negative Y direction (right) Units: meters per second

Angular velocity (rate of rotation). Rate of change of orientation over time. This represents how fast the object is rotating in the 2D plane. Positive values: Counter-clockwise rotation Negative values: Clockwise rotation Units: radians per second

Position component of the 3D pose. This specifies where the object is located in 3D space using the reference coordinate system. The translation represents the position of the object's coordinate frame origin relative to the reference frame.

Orientation component of the 3D pose. This specifies how the object is oriented in 3D space relative to the reference coordinate system. The rotation represents the orientation of the object's coordinate frame relative to the reference frame. Combined with translation, this fully defines the object's pose and allows for coordinate transformations between object and reference frames.

W component (scalar/real part) of the quaternion. This is the "real" or "scalar" component of the quaternion. For a rotation by angle θ around an axis, w = cos(θ/2). Range: [-1, 1] for unit quaternions Identity rotation: w = 1

X component (i coefficient) of the quaternion. This is the coefficient of the i basis quaternion. For a rotation by angle θ around axis (ax, ay, az), x = sin(θ/2) * ax (where (ax, ay, az) is unit length). Range: [-1, 1] for unit quaternions

Y component (j coefficient) of the quaternion. This is the coefficient of the j basis quaternion. For a rotation by angle θ around axis (ax, ay, az), y = sin(θ/2) * ay (where (ax, ay, az) is unit length). Range: [-1, 1] for unit quaternions

Z component (k coefficient) of the quaternion. This is the coefficient of the k basis quaternion. For a rotation by angle θ around axis (ax, ay, az), z = sin(θ/2) * az (where (ax, ay, az) is unit length). Range: [-1, 1] for unit quaternions

Quaternion representing the 3D rotation. This quaternion should be normalized (unit quaternion) to represent a valid rotation. Non-unit quaternions may lead to scaling effects in addition to rotation. The quaternion represents the rotation from the reference coordinate frame to the rotated coordinate frame.

Translation component of the 3D transformation. This represents the displacement between the origins of the two coordinate frames in 3D space. It specifies how far and in which direction the target frame's origin is from the source frame's origin.

Rotation component of the 3D transformation. This represents the angular difference between the two coordinate frames in 3D space. It specifies how the target frame is rotated relative to the source frame. The rotation is applied before the translation in the transformation sequence (standard mathematical convention for homogeneous transforms).

X-coordinate (forward/backward displacement). Positive values indicate forward direction. Negative values indicate backward direction. Units: meters

Y-coordinate (left/right displacement). Positive values indicate leftward direction. Negative values indicate rightward direction. Units: meters

Z-coordinate (up/down displacement). Positive values indicate upward direction. Negative values indicate downward direction. Units: meters

Linear velocity in X direction. Rate of change of X position over time. In world coordinates, this represents forward/backward velocity. Positive values: Moving in positive X direction (forward) Negative values: Moving in negative X direction (backward) Units: meters per second

Linear velocity in Y direction. Rate of change of Y position over time. In world coordinates, this represents left/right velocity (strafing). Positive values: Moving in positive Y direction (left) Negative values: Moving in negative Y direction (right) Units: meters per second

Linear velocity in Z direction. Rate of change of Z position over time. In world coordinates, this represents up/down velocity (climbing/descending). Positive values: Moving in positive Z direction (up) Negative values: Moving in negative Z direction (down) Units: meters per second

Angular velocity about X-axis (roll rate). Rate of rotation about the X-axis. This represents how fast the object is rolling (rotating around its forward axis). Positive values: Counter-clockwise rotation when looking down the positive X-axis Negative values: Clockwise rotation when looking down the positive X-axis Units: radians per second

Angular velocity about Y-axis (pitch rate). Rate of rotation about the Y-axis. This represents how fast the object is pitching (nose up/down motion). Positive values: Counter-clockwise rotation when looking down the positive Y-axis Negative values: Clockwise rotation when looking down the positive Y-axis Units: radians per second

Angular velocity about Z-axis (yaw rate). Rate of rotation about the Z-axis. This represents how fast the object is yawing (turning left/right). Positive values: Counter-clockwise rotation when looking down the positive Z-axis Negative values: Clockwise rotation when looking down the positive Z-axis Units: radians per second