Files
PX4-Autopilot/docs/en/msg_docs/SurfaceVehicleCourseSetpoint.md
T
Michael FritscheandHamish Willee d998124a2a feat(rover): add SurfaceVehicleCourseSetpoint for course hold (#29243)
* docs(msg): clarify RoverPositionSetpoint field descriptions

* feat(rover): introduce a course parameter to get rid of the course-hold workaround hack (#29245)

* fix(ros2): update ros2 interface lib pin to include course and target_ned in RoverPositionSetpoint

* style(msg): use single space before comments in RoverPositionSetpoint

The column padding triggers the msg doc generator's multiple-whitespace
note on every field.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

* fix(msg): update RoverPositionSetpoint descriptions

* feat(msg): add SurfaceVehicleCourseSetpoint

* fix(repositories): update px4 ros2 interface lib version

* fix(msg): add comment that yaw in RoverPositionSetpoint msg is currently not used

* fix(msg): rename surface_vehicle_course_setpoint to planar_course_setpoint

* fix(rover): keep the course line while a course setpoint is streamed

A PlanarCourseSetpoint without start_ned re-anchored the line at the
vehicle position on every message. Publishers that stream the setpoint,
the usual pattern over ROS 2, therefore never got cross-track error
corrected: in SITL the rover drifted 3.8 m off course over 54 m. Keep the
current line while the same course is published without a start
position, and only re-anchor when the course changes.

Also document that a NaN course leaves the position controller idle and
that yaw is currently unused, matching RoverPositionSetpoint.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* fix(msg): rename planar_course_setpoint to ugv_usv_course_setpoint

* docs(msg): add documentation for UgvUsvCourseSetpoint

* feat(rover): proper guided course implementation

* fix(rover): rename course setpoint cruising_speed param to speed

* fix(msgs): rename ugv_usv_course_setpoint.msg to surface_vehicle_course_setpoint.msg

* docs(rover): clarify course setpoint wording

Doc review fixes for the course hold docs and message comments:
unclear antecedents, a misplaced modifier, a missing verb, and the
pure pursuit sentence separated from the course setpoint text it no
longer described. The yaw @invalid tag now matches in both messages,
since no controller reads the field.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

* Apply suggestion from @hamishwillee

* docs(rover): fix course tracking formulation for the different rover types

* fix(rover): maintain current speed upon guided course mode entry

* docs(rover): clarify guided course mode documentation.

* fix(rover): handle nav_state_land in rovers

* fix(rovers): polish the used terminology

* docs(rover): switch to list for guided course mode usable commands

---------

Signed-off-by: Hamish Willee <hamishwillee@gmail.com>
Signed-off-by: Michael Fritsche <frimi999@gmail.com>
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
2026-10-29 11:12:41 -04:00

60 lines
4.0 KiB
Markdown

---
pageClass: is-wide-page
---
# SurfaceVehicleCourseSetpoint (UORB message)
Surface Vehicle Course Setpoint.
Course setpoint for surface vehicles, on land or on water (rovers, boats).
Consumed by the position controllers of these vehicles (currently AckermannPosControl,
DifferentialPosControl and MecanumPosControl), which turn it into speed and attitude
setpoints.
Published by the Guided Course mode of rover_ackermann, rover_differential and rover_mecanum,
and can be sent from ROS 2 over uXRCE-DDS (/fmu/in/surface_vehicle_course_setpoint).
The vehicle tries to track the course over ground, as with the fixed-wing course hold: vehicles
that steer by heading correct their heading by the estimated drift angle, mecanum rovers drive
along the course setpoint directly. There is no desired track, so a sideways offset is not
corrected. To follow a desired track, publish rover_position_setpoint instead.
The position controller follows whichever of the two was published most recently.
**TOPICS:** surface_vehicle_course_setpoint
## Fields
| Name | Type | Unit [Frame] | Range/Enum | Description |
| ----------------------------------- | --------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="fld_timestamp"></a>timestamp | `uint64` | us | | Time since system start |
| <a id="fld_course"></a>course | `float32` | rad [NED] | [-pi : pi] | Course over ground to hold (Invalid: NaN No course; the position controller stays idle) |
| <a id="fld_speed"></a>speed | `float32` | m/s | [-inf : inf] | Cruising speed; a negative value drives the vehicle in reverse (rear first) along the course (Invalid: NaN Defaults to maximum speed) |
| <a id="fld_yaw"></a>yaw | `float32` | rad [NED] | [-pi : pi] | Currently unused. Only for vehicles that can move sideways (e.g. mecanum rovers): vehicle yaw while holding the course. (Invalid: NaN Not considered) |
## Source Message
[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/SurfaceVehicleCourseSetpoint.msg)
::: details Click here to see original file
```c
# Surface Vehicle Course Setpoint
#
# Course setpoint for surface vehicles, on land or on water (rovers, boats).
# Consumed by the position controllers of these vehicles (currently AckermannPosControl,
# DifferentialPosControl and MecanumPosControl), which turn it into speed and attitude
# setpoints.
# Published by the Guided Course mode of rover_ackermann, rover_differential and rover_mecanum,
# and can be sent from ROS 2 over uXRCE-DDS (/fmu/in/surface_vehicle_course_setpoint).
# The vehicle tries to track the course over ground, as with the fixed-wing course hold: vehicles
# that steer by heading correct their heading by the estimated drift angle, mecanum rovers drive
# along the course setpoint directly. There is no desired track, so a sideways offset is not
# corrected. To follow a desired track, publish rover_position_setpoint instead.
# The position controller follows whichever of the two was published most recently.
uint64 timestamp # [us] Time since system start
float32 course # [rad] [@range -pi, pi] [@frame NED] [@invalid NaN No course; the position controller stays idle] Course over ground to hold
float32 speed # [m/s] [@range -inf, inf] [@invalid NaN Defaults to maximum speed] Cruising speed; a negative value drives the vehicle in reverse (rear first) along the course
float32 yaw # [rad] [@range -pi, pi] [@frame NED] [@invalid NaN Not considered] Currently unused. Only for vehicles that can move sideways (e.g. mecanum rovers): vehicle yaw while holding the course.
```
:::