From e4212fe915dcfe6f999203db4541db3ad9623eff Mon Sep 17 00:00:00 2001 From: Michael Fritsche <64464652+Frigiii@users.noreply.github.com> Date: Tue, 10 Nov 2026 10:12:17 +0100 Subject: [PATCH] docs(concept): add navigation terminology page (#29347) * docs(concept): add navigation terminology page Heading, course, track, bearing and drift have caused friction because aviation and marine navigation use the same words with different meanings, and PX4 code mixes both. Collect the official ICAO, FAA, Bowditch, IHO and NMEA definitions in one place, together with the reference frames, a precedence rule for conflicting terms, and a separate section for where PX4 represents things differently (radians, local map projection, signed cross-track error, wind vectors, deviating field names), so that new code sticks to the official terminology. Graphics are placeholders for now. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Michael Fritsche * docs(concept): add ground vehicle terms to navigation terminology ISO 8855 and SAE J670 reuse navigation words with different meanings: the course angle is the actual direction of motion, and the vehicle sideslip angle is ground-referenced, unlike the aerodynamic one. Add the ground vehicle standards as a source, extend the precedence rule and conflicts table, cover the z-up vehicle frames, and list the rover names that use "bearing" for a course setpoint. Also tone down the boat statement in the intro, as boat support is still minimal. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Michael Fritsche * Add ground vehicle references * fix(docs): add navigation nomenclature overview * fix(docs): hide not yet used nomenclature * feat(docs): navigation docs update overview image * feat(docs): split navigation terminology doc into main and advanced page * feat(docs): navigation terminology update overview image * fix(docs): navigation terminology clarify heading and desired track definitions * fix(docs): clean up navigation terminology tab * fix(docs): clean up navigation_terminology.md * fix(docs): clean up navigation_terminology_advanced.md * fix(docs): correct navigation terminology field and range claims position_controller_status.nav_bearing and xtrack_error have had no producer since the fixed-wing position controller rework, so NAV_CONTROLLER_OUTPUT forwards zeros; say so instead of describing them as live values. Not all uORB angles are wrapped to [-pi, pi] (transponder_report.heading is [0, 2pi]), Ackermann and differential rovers use bearing_setpoint as a heading setpoint, and estimator_innovations.beta is an innovation, not the sideslip angle. Drop the FLU to FRD conversion note, which was wrong for ROS yaw and does not belong on a terminology page, replace the caption of the missing track frame figure with a TODO, and apply prettier. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Michael Fritsche * docs(concept): update navigation_terminology page * docs(concept): navigation terminology add course / course setpoint distinction vs course / course over ground * docs(concept): navigation terminology - add detail images * docs(concept): fix navigation terminology review findings Fix issues found in review of the navigation terminology pages: - Figures: make the SVGs visible in dark mode, draw the course setpoint pointing back towards the desired track (as NPFG commands it) rather than along it, match the track's end direction to the course, add an illustrative future track, and fix clipped and mis-spaced labels. - Links: avoid in-page links into the collapsed details block, link the summary table fields and first uses of estimator, NPFG, pure pursuit and mecanum rovers. - Accuracy: MAVLink headings are in centidegrees, the bearing example is the current (not next) waypoint, magnetometer calibration is applied by the sensors module, and only Ackermann/mecanum use bearing_setpoint. - Style: rename "the norms" to "official definitions", remove casual bold emphasis, fix heading levels, British spelling, and one sentence per line. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Hamish Willee * docs(concept): apply suggestion on px4 path follow computation Co-authored-by: Hamish Willee * docs(concept): pull user-facing notes from advanced navigation terminology Readers operating, tuning or reading logs should not need the advanced page, so add the rover reversing case, the sideslip/drift naming hint, and the user-facing names that don't match the terminology. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Michael Fritsche * docs(concept): split local frame into tangent-plane and navigation frames Local positions are a projection in the tangent-plane frame at the estimator origin, while velocities and attitude are relative to the north-east-down frame at the vehicle. Describe both, keeping the main page short and the details on the advanced page. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Michael Fritsche * docs(agents): point to navigation terminology before naming nav fields Keep new code, uORB fields, parameters and docs from drifting away from the agreed heading/course/track/bearing definitions again. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Michael Fritsche * docs(concept): address review comments by mbjd --------- Signed-off-by: Michael Fritsche Signed-off-by: Hamish Willee Co-authored-by: Hamish Willee --- AGENTS.md | 6 + .../concepts/navigation/detail_course.svg | 1 + .../navigation/detail_course_setpoint.svg | 1 + .../navigation/detail_cross_track_error.svg | 1 + .../navigation/detail_drift_angle.svg | 1 + .../concepts/navigation/detail_heading.svg | 1 + .../navigation/detail_wind_triangle.svg | 1 + .../overview_heading_bearing_course_track.svg | 1 + docs/en/SUMMARY.md | 2 + docs/en/concept/navigation_terminology.md | 198 +++++++ .../navigation_terminology_advanced.md | 539 ++++++++++++++++++ docs/en/contribute/notation.md | 2 + 12 files changed, 754 insertions(+) create mode 100644 docs/assets/concepts/navigation/detail_course.svg create mode 100644 docs/assets/concepts/navigation/detail_course_setpoint.svg create mode 100644 docs/assets/concepts/navigation/detail_cross_track_error.svg create mode 100644 docs/assets/concepts/navigation/detail_drift_angle.svg create mode 100644 docs/assets/concepts/navigation/detail_heading.svg create mode 100644 docs/assets/concepts/navigation/detail_wind_triangle.svg create mode 100644 docs/assets/concepts/navigation/overview_heading_bearing_course_track.svg create mode 100644 docs/en/concept/navigation_terminology.md create mode 100644 docs/en/concept/navigation_terminology_advanced.md diff --git a/AGENTS.md b/AGENTS.md index 3f32755ccd9..44cd5e9109b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,12 @@ simulation and Python tooling. enforces `make check_format`. - **Docs:** edit only `docs/en`. `docs/ko`, `docs/zh` and `docs/uk` are Crowdin output regenerated from it; revert any change a sweep makes there. +- **Navigation terms:** before writing or renaming anything about yaw, + heading, course, track, bearing, cross-track or drift (code, uORB fields, + parameters, docs), read `docs/en/concept/navigation_terminology.md` and + follow its definitions. When naming code, uORB fields or parameters, also + follow "Guidelines for Contributors" in + `docs/en/concept/navigation_terminology_advanced.md`. - **Scoped guidance:** before editing or reviewing, read only the `.github/instructions/*.instructions.md` files whose `applyTo` patterns match the affected paths, plus any nested `AGENTS.md` along those paths. diff --git a/docs/assets/concepts/navigation/detail_course.svg b/docs/assets/concepts/navigation/detail_course.svg new file mode 100644 index 00000000000..78d66286956 --- /dev/null +++ b/docs/assets/concepts/navigation/detail_course.svg @@ -0,0 +1 @@ +TrackNorthCourse \ No newline at end of file diff --git a/docs/assets/concepts/navigation/detail_course_setpoint.svg b/docs/assets/concepts/navigation/detail_course_setpoint.svg new file mode 100644 index 00000000000..1cc64571568 --- /dev/null +++ b/docs/assets/concepts/navigation/detail_course_setpoint.svg @@ -0,0 +1 @@ +Desired trackPrevious WPCurrent WPNorthCourse setpointFuture track \ No newline at end of file diff --git a/docs/assets/concepts/navigation/detail_cross_track_error.svg b/docs/assets/concepts/navigation/detail_cross_track_error.svg new file mode 100644 index 00000000000..441866dd441 --- /dev/null +++ b/docs/assets/concepts/navigation/detail_cross_track_error.svg @@ -0,0 +1 @@ +Desired trackPrevious WPCurrent WPXTE > 0 (right)XTE < 0 (left) \ No newline at end of file diff --git a/docs/assets/concepts/navigation/detail_drift_angle.svg b/docs/assets/concepts/navigation/detail_drift_angle.svg new file mode 100644 index 00000000000..a2c3a617aa4 --- /dev/null +++ b/docs/assets/concepts/navigation/detail_drift_angle.svg @@ -0,0 +1 @@ +HeadingCourseDrift angleWind \ No newline at end of file diff --git a/docs/assets/concepts/navigation/detail_heading.svg b/docs/assets/concepts/navigation/detail_heading.svg new file mode 100644 index 00000000000..15f48322aed --- /dev/null +++ b/docs/assets/concepts/navigation/detail_heading.svg @@ -0,0 +1 @@ +NorthHeading \ No newline at end of file diff --git a/docs/assets/concepts/navigation/detail_wind_triangle.svg b/docs/assets/concepts/navigation/detail_wind_triangle.svg new file mode 100644 index 00000000000..193a23b5dfe --- /dev/null +++ b/docs/assets/concepts/navigation/detail_wind_triangle.svg @@ -0,0 +1 @@ +NorthvairvwindvgroundDrift angle \ No newline at end of file diff --git a/docs/assets/concepts/navigation/overview_heading_bearing_course_track.svg b/docs/assets/concepts/navigation/overview_heading_bearing_course_track.svg new file mode 100644 index 00000000000..a44e0e9588d --- /dev/null +++ b/docs/assets/concepts/navigation/overview_heading_bearing_course_track.svg @@ -0,0 +1 @@ +cross-track errorCourse setpointDesired TrackTrackPreviousWPCurrentWPNorthCourseBearing to Current WPHeadingWindAttitudeVelocityFuture track (illustrative) \ No newline at end of file diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 20cfc322920..26b2d99e928 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -488,6 +488,8 @@ - [Controller Diagrams](flight_stack/controller_diagrams.md) - [Parameters & Configs](advanced/parameters_and_configurations.md) - [Events Interface](concept/events_interface.md) + - [Navigation Terminology](concept/navigation_terminology.md) + - [Navigation Terminology (Advanced)](concept/navigation_terminology_advanced.md) - [Flight Modes](concept/flight_modes.md) - [Flight Tasks](concept/flight_tasks.md) - [Control Allocation](concept/control_allocation.md) diff --git a/docs/en/concept/navigation_terminology.md b/docs/en/concept/navigation_terminology.md new file mode 100644 index 00000000000..2b15c0cdf48 --- /dev/null +++ b/docs/en/concept/navigation_terminology.md @@ -0,0 +1,198 @@ +# Navigation Terminology + +This page explains the navigation terms you meet when operating PX4, reading logs or tuning, such as _heading_, _course_, _track_, _bearing_, _cross-track error_ and _drift angle_. + +PX4 uses the official definitions of these terms from aviation and marine navigation, with one deliberate exception: [Course](#course). + +For the official definitions quoted with their sources, how conflicting definitions are resolved, ground vehicle terms, and where PX4 represents things differently, see [Navigation Terminology (Advanced)](../concept/navigation_terminology_advanced.md). + +## Summary + +**Heading** is the direction the vehicle _points_, **course setpoint** is the direction it _should move_ over the ground, **course** is the direction it _actually moves_, and **bearing** is the direction _to_ something, such as the current waypoint. +Similarly, **desired track** and **track** are the paths the vehicle _should follow_ and _actually follows_. + +| Term | Official meaning | Example in PX4 | +| ----------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Heading](#heading) | Direction in which the body x-axis of the vehicle points. | [`vehicle_local_position.heading`](../msg_docs/VehicleLocalPosition.md#fld_heading) | +| [Course](#course) | Actual direction of motion over the ground. | [`sensor_gnss.course`](../msg_docs/SensorGnss.md#fld_course) | +| [Course setpoint](#course-setpoint) | Intended direction of motion over the ground. | [`fixed_wing_lateral_setpoint.course`](../msg_docs/FixedWingLateralSetpoint.md#fld_course) | +| [Track](#track-and-desired-track) | Actual path of the vehicle over the ground. | Path plotted from a [log](../log/flight_log_analysis.md) | +| [Desired track](#track-and-desired-track) | Intended path over the ground, such as between two waypoints. | Line from [previous](../msg_docs/PositionSetpointTriplet.md#fld_previous) to [current](../msg_docs/PositionSetpointTriplet.md#fld_current) waypoint | +| [Bearing](#bearing) | Direction from one point to another. | [`pure_pursuit_status.bearing_to_waypoint`](../msg_docs/PurePursuitStatus.md#fld_bearing_to_waypoint) | +| [Cross-track error](#cross-track-error) | Perpendicular distance from the desired track, and side. | [`pure_pursuit_status.crosstrack_error`](../msg_docs/PurePursuitStatus.md#fld_crosstrack_error) | +| [Drift angle](#drift-angle) | Angle between heading and track. | — | + +Heading, course setpoint, course and bearing can all differ: in wind the vehicle points away from where it moves, and off the desired track it should move back towards the track, not straight at the waypoint. +The diagram below shows each term. + +Navigation terms seen from above: north arrow, desired track from the previous to the current waypoint, vehicle heading, course, course setpoint pointing back towards the desired track, bearing to the current waypoint, cross-track error from the desired track, wind, and an illustrative future track that rejoins the desired track + +_Overview figure: vehicle seen from above._ + +## Directions and Frames + +All directions on this page are measured clockwise from true north: north is 0°, east is 90°, south is 180° and west is 270°. +_QGroundControl_ shows them in degrees from 0° to 360°, and MAVLink navigation fields usually in centidegrees (for example `GLOBAL_POSITION_INT.hdg`, 0 to 35999). +Internally, PX4 uses radians, usually from $-\pi$ to $\pi$ (west is $-\pi/2$), which matters when you read logs. + +PX4 uses four main frames (see [Frames and Reference Directions](../concept/navigation_terminology_advanced.md#frames-and-reference-directions) for details): + +- **Global (WGS 84):** Latitude, longitude and altitude, for example in `vehicle_global_position`. +- **Local tangent-plane (NED):** North, east, down from a fixed origin where the [estimator](../advanced_config/tuning_the_ecl_ekf.md) started; the positions in `vehicle_local_position`. +- **Local navigation (NED):** North, east, down at the vehicle; velocities and attitude are relative to it. +- **Body (FRD):** Forward, right, down, fixed to the vehicle; the [heading](#heading) is the direction of its forward axis. + +A compass measures magnetic north, which differs from true north by the _magnetic declination_. +The estimator corrects for this automatically, using the World Magnetic Model or [EKF2_MAG_DECL](../advanced_config/parameter_reference.md#EKF2_MAG_DECL) depending on [EKF2_DECL_TYPE](../advanced_config/parameter_reference.md#EKF2_DECL_TYPE). + +## Terms + +### Heading + +The heading is where the x-axis (nose, bow or front) of the vehicle points. +It says nothing about the direction in which the vehicle _moves_: a multicopter can fly sideways, a plane angles into a crosswind, and a boat is pushed off by wind and current. + +PX4 uses _heading_ and _yaw_ (the yaw angle of the vehicle attitude) as synonyms: `vehicle_local_position.heading` is the Euler yaw angle, and heading setpoints are named `yaw`. +The yaw angle is the direction of the body x-axis projected onto the horizontal plane, so the two only differ when the x-axis points (nearly) straight up or down, where the heading is undefined. +Note that _yaw_ also names the rotation about the vertical axis (yaw rate, yaw moment), which is not a direction. + +Heading: angle from north to the body x-axis + +PX4 represents the heading using: + +- [`vehicle_local_position.heading`](../msg_docs/VehicleLocalPosition.md) (estimate). +- [`trajectory_setpoint.yaw`](../msg_docs/TrajectorySetpoint.md) and [`rover_attitude_setpoint.yaw_setpoint`](../msg_docs/RoverAttitudeSetpoint.md) (setpoints). +- MAVLink [`GLOBAL_POSITION_INT.hdg`](https://mavlink.io/en/messages/common.html#GLOBAL_POSITION_INT) and [`VFR_HUD.heading`](https://mavlink.io/en/messages/common.html#VFR_HUD). + +### Course + +The course is the direction the vehicle _actually_ moves over the ground: the direction of its ground velocity. +It is also called _course over ground_ (COG) in marine navigation, and it is what a GNSS receiver reports as "course" and what avionics show as _TRK_ (track). +It is undefined when the vehicle is stationary, and noisy at low speed. +For a rover that drives without wheel slip, the course equals the heading when driving forwards, and the heading plus 180° when reversing. + +Course: angle from north to the ground velocity, tangent to the track + +PX4 represents the course using: + +- [`sensor_gnss.course`](../msg_docs/SensorGnss.md) ("Course over ground, not heading"). +- MAVLink [`GPS_RAW_INT.cog`](https://mavlink.io/en/messages/common.html#GPS_RAW_INT). + +### Course Setpoint + +The course setpoint is the direction the vehicle _should_ move over the ground. +PX4's path-following guidance calculates it from the [desired track](#track-and-desired-track): on the track it points along it, and off the track it points back towards it, so that the vehicle rejoins the track ahead. +The actual [course](#course) almost always differs from the course setpoint, often substantially. + +Course setpoint: angle from north to the commanded direction of motion, pointing back towards the desired track, with an illustrative future track that rejoins it + +PX4 represents the course setpoint using: + +- [`position_setpoint.course`](../msg_docs/PositionSetpoint.md#fld_course) (course to hold, set by the navigator). +- [`fixed_wing_lateral_setpoint.course`](../msg_docs/FixedWingLateralSetpoint.md#fld_course) (course commanded by the fixed-wing guidance). + +::: warning PX4 differs from aviation and marine navigation +In aviation and marine navigation, bare _course_ means the _intended_ direction, and the actual direction is the _course over ground_ or _track angle_. +PX4 instead uses _course_ for the measured or estimated direction and _course setpoint_ for the intended one, like _heading_ and _heading setpoint_. +Keep this in mind when you read aviation or marine sources, for example the FAA [wind correction angle](../concept/navigation_terminology_advanced.md#terms-not-yet-used-in-px4), which applies to the course setpoint in PX4 terms. +See [Course Is the Actual Direction](../concept/navigation_terminology_advanced.md#course-is-the-actual-direction) for the reasoning. +::: + +### Track and Desired Track + +- **Track:** The actual path the vehicle traced over the ground, such as the path plotted from a log. + Its direction at any point is the [course](#course). +- **Desired track:** The intended path over the ground, which the vehicle tries to follow. + This is usually the line between two waypoints, but it can also be a line along a course setpoint the vehicle holds. + +::: info +In marine navigation, bare "track" means the _intended_ path. +To avoid confusion, PX4 always writes _desired track_ for the intended path. +::: + +### Bearing + +A bearing is the direction from one point to another, for example from the vehicle to the current waypoint. +It depends only on the two positions, not on where the vehicle points or moves. + +PX4 represents the bearing using: + +- [`pure_pursuit_status.bearing_to_waypoint`](../msg_docs/PurePursuitStatus.md). + +### Cross-Track Error + +The cross-track error (XTE) is how far the vehicle is off the [desired track](#track-and-desired-track), measured perpendicular to it, and on which side. + +In PX4, the cross-track error is positive when the vehicle is to the right of the desired track, and negative when it is to the left, looking in the direction of travel. + +PX4 represents the cross-track error using: + +- [`pure_pursuit_status.crosstrack_error`](../msg_docs/PurePursuitStatus.md) (rovers). +- [`fixed_wing_lateral_guidance_status.signed_track_error`](../msg_docs/FixedWingLateralGuidanceStatus.md) (fixed-wing). + +Cross-track error: positive to the right of the desired track, negative to the left + +### Drift Angle + +The drift angle is the difference between where the vehicle points ([heading](#heading)) and where it moves ([course](#course)). +Wind causes it for aircraft, wind and current for boats, and wheel slip for rovers. +Multicopters and [mecanum rovers](../frames_rover/index.md#mecanum) can also move sideways on purpose. + +Rover and vehicle dynamics material calls this angle the _vehicle sideslip angle_, while for aircraft the _sideslip angle_ is measured against the airflow, not the ground. +In marine navigation, bare _drift_ is the speed of the current, which is why PX4 always writes _drift angle_. + +Drift angle: angle between heading and course + +### Airspeed and Ground Speed + +Ground speed (called _speed over ground_, SOG, in marine navigation) is the speed over the ground, in the direction of the course. +Airspeed is the speed through the air (see [Airspeed in PX4](../config_fw/airspeed_scale_handling.md#airspeed-in-px4) for indicated, calibrated and true airspeed). +The two differ by the wind. + +### Wind Direction + +Weather reports, aviation and marine navigation give the wind direction as the direction it blows from: a wind "from 90°" blows from the east towards the west. + +PX4 does not use this convention. +PX4 wind estimates and the wind fields it sends over MAVLink are velocity vectors of the air relative to the ground, which point where the air moves to. +A wind from the north therefore has a negative `windspeed_north` in PX4. + +PX4 represents the wind using: + +- [`wind.windspeed_north`](../msg_docs/Wind.md) and `wind.windspeed_east` (estimate, NED). +- MAVLink [`WIND_COV.wind_x`](https://mavlink.io/en/messages/common.html#WIND_COV) and `WIND_COV.wind_y` (same sign convention as `wind`). + +## Wind Triangle + +Heading and course differ because the vehicle moves through air (or water) that itself moves over the ground: + +$$ +\mathbf{v}_{ground} = \mathbf{v}_{air} + \mathbf{v}_{wind} +$$ + +- The direction of $\mathbf{v}_{ground}$ is the **course**, and its magnitude is the **ground speed**. +- For a fixed-wing aircraft, $\mathbf{v}_{air}$ points along the **heading**, and its magnitude is the **airspeed**. +- The angle between the heading and $\mathbf{v}_{ground}$ is the **drift angle**. + +Wind triangle: air velocity along the heading plus wind velocity gives the ground velocity along the course + +## Names That Don't Mean What They Say + +Some names you see when tuning, flying or reading logs predate this terminology and don't match it: + +- "Bearing" in [Rover Velocity Tuning](../config_rover/velocity_tuning.md) and [Rover Position Tuning](../config_rover/position_tuning.md) means the [course setpoint](#course-setpoint). +- MAVLink [`NAV_CONTROLLER_OUTPUT.nav_bearing`](https://mavlink.io/en/messages/common.html#NAV_CONTROLLER_OUTPUT) and `NAV_CONTROLLER_OUTPUT.xtrack_error` are always 0 in current PX4. +- The ADS-B traffic "heading" ([`transponder_report.heading`](../msg_docs/TransponderReport.md), MAVLink [`ADSB_VEHICLE.heading`](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE)) is the other aircraft's [course](#course). + +The code-level names that deviate are listed in [Field Names That Deviate](../concept/navigation_terminology_advanced.md#field-names-that-deviate). + +## Further Information + +[Navigation Terminology (Advanced)](../concept/navigation_terminology_advanced.md) covers: + +- The official definitions of each term, quoted from the aviation, marine and ground vehicle sources, and the rule PX4 uses when they disagree. +- The reference frames in detail (ECEF/WGS 84, local tangent-plane and local navigation NED, FRD, along-track/cross-track), north references and z-up conventions such as ROS and ISO 8855. +- Why PX4 uses _course_ for the actual direction, unlike aviation and marine navigation. +- Ground vehicle terms (yaw, course and sideslip angle), and why _sideslip_ means different things for planes and rovers. +- Where PX4 represents things differently from the official definitions, and existing field names that deviate. +- Guidelines for contributors, and terms PX4 does not use yet. diff --git a/docs/en/concept/navigation_terminology_advanced.md b/docs/en/concept/navigation_terminology_advanced.md new file mode 100644 index 00000000000..b93ca9b1ae8 --- /dev/null +++ b/docs/en/concept/navigation_terminology_advanced.md @@ -0,0 +1,539 @@ +# Navigation Terminology (Advanced) + +This page is the developer reference behind [Navigation Terminology](../concept/navigation_terminology.md). +It is aimed at contributors who add or change uORB fields, parameters, MAVLink handling, log analysis tools or documentation. + +PX4 flies aircraft, drives rovers, and can drive boats, so its code and documentation use the vocabulary of aviation, marine navigation and ground vehicle dynamics. +These traditions use the same words (_heading_, _course_, _track_, _bearing_, _drift_, _sideslip_), and they do not always mean the same thing. + +This page collects the official definitions, the reference frames they are measured in, and the rule PX4 applies when they conflict. +PX4 uses these definitions, with one deliberate exception: it uses _course_ for the actual direction of motion, and _course setpoint_ for the intended one (see [Course Is the Actual Direction](#course-is-the-actual-direction)). +Where PX4 represents or computes something differently from the official definitions, this is described separately in [Where PX4 Differs](#where-px4-differs). + +## Sources and Precedence + +The definitions are taken from these authorities (see [References](#references)): + +- **Aviation:** ICAO (Annex 2, Doc 9713), FAA _Pilot's Handbook of Aeronautical Knowledge_ (PHAK) and FAA _Pilot/Controller Glossary_ (P/CG). +- **Marine:** NGA _The American Practical Navigator_ (Bowditch, Pub. No. 9), IHO S-32 _Hydrographic Dictionary_, NMEA 0183. +- **Ground vehicles:** ISO 8855 (road vehicle dynamics vocabulary) and SAE J670 (vehicle dynamics terminology). +- **Frames:** WGS 84 (NGA, adopted by ICAO), ISO 1151 (flight dynamics), SNAME (marine vehicle motion) and ISO 8855 (road vehicles). + +Where definitions of the same word conflict between these traditions, PX4 applies this rule: + +1. **Aviation definitions take precedence** (ICAO first, then FAA). + They are international standards, and most existing PX4 interfaces already follow them. + The one exception is _course_ (see [Course Is the Actual Direction](#course-is-the-actual-direction)). +2. **Marine terms are used for marine concepts** that aviation does not define, such as speed through the water, leeway, and set and drift (see [Terms Not Yet Used in PX4](#terms-not-yet-used-in-px4)). +3. **Ground vehicle terms are used for vehicle dynamics concepts** that navigation does not define, such as tyre slip angle (see [Terms Not Yet Used in PX4](#terms-not-yet-used-in-px4)). + For directions (heading, course, drift angle), the navigation terms apply to rovers too. +4. **Where a word is ambiguous between traditions, use the official qualified term**: for example _desired track_ (FAA P/CG) instead of bare _track_ for an intended path, and _drift angle_ (FAA PHAK) instead of bare _drift_. + +The conflicts and the resulting choices are listed in [Terminology Conflicts](#terminology-conflicts). + +## Frames and Reference Directions + +Every position and direction is relative to a reference frame. +This section describes the frames PX4 uses, and the official convention each one is based on. + +### Global Frame (ECEF, WGS 84) + +The global frame is the Earth-centred, Earth-fixed (ECEF) frame of the World Geodetic System 1984 (WGS 84), the reference system that ICAO requires for aeronautical data and that GNSS receivers use. +Its origin is the Earth's centre of mass, and it rotates with the Earth. +Global positions are given in it as geodetic latitude, longitude and altitude on the WGS 84 ellipsoid. + +- Latitude and longitude are in degrees, positive north and east. +- Altitude has two different references, which must never be mixed up: + - Height above the WGS 84 ellipsoid, as output by GNSS receivers. + - Altitude above mean sea level (AMSL), which differs from the ellipsoid height by the local geoid height (up to about 100 m). + +In PX4, `vehicle_global_position` carries `lat`, `lon`, `alt` (AMSL) and `alt_ellipsoid`. +On MAVLink and in mission items, the reference of each altitude is given by its `MAV_FRAME`. + +### Local Tangent-Plane Frame (NED) + +ISO 1151 defines the _normal earth-fixed axis system_: an earth-fixed frame whose z-axis points vertically down. +Aviation and marine engineering conventionally align its horizontal axes with north and east, which gives the **north-east-down (NED)** frame: + +- x points to true north, y points to east, z points down. +- It is a plane tangent to the Earth at a chosen origin. +- It is right-handed, so positive rotation about z is clockwise when viewed from above. + This matches the clockwise sense of headings, courses and bearings. + +In PX4, the positions of `vehicle_local_position` (fields `x`, `y`, `z`) are in this frame. +Its origin is the position where the [estimator](../advanced_config/tuning_the_ecl_ekf.md) was initialised, or where it was set manually (`ref_lat`, `ref_lon`, `ref_alt`). +This is the same frame as MAVLink `MAV_FRAME_LOCAL_NED`. + +See [Local Frame Is a Map Projection](#local-frame-is-a-map-projection) for how PX4 relates the local tangent-plane frame to the global frame. + +### Local Navigation Frame (NED) + +The local navigation frame has the same north, east and down axes, but moves with the vehicle: + +- Its origin is the body frame origin. +- Its axes point to true north, east and down at the vehicle's current position. + +In PX4, the velocities of `vehicle_local_position` (fields `vx`, `vy`, `vz`), the attitude and the heading are relative to this frame. +Close to the local origin, its axes and those of the local tangent-plane frame are practically the same. + +### Body Frame (FRD) + +ISO 1151 (aircraft) and SNAME (ships and submarines) define the body-fixed axes the same way: + +- x points forward (nose, bow or front). +- y points to the right. +- z points down, completing a right-handed frame. + +PX4 calls this frame **FRD** (forward, right, down), which is the same frame as MAVLink `MAV_FRAME_BODY_FRD`. +Its origin is the vehicle's centre of mass. +The vehicle's attitude is the rotation from the [local navigation frame](#local-navigation-frame-ned) to FRD, and its [heading](#heading) is the direction of the body x-axis in the horizontal plane. + +::: info +Some ground vehicle and robotics conventions use z-up frames instead: + +- ISO 8855 defines the road vehicle axis system with x forward, y to the left and z up (FLU), and an earth-fixed frame with z up. + Angles about z are then positive counterclockwise when viewed from above, the opposite of navigation practice. + SAE J670 allows both the ISO z-up and the traditional SAE z-down axis systems, so check which one a source uses. +- ROS uses ENU for the local frame and FLU for the body frame. + See [ROS 2 & PX4 Frame Conventions](../ros2/user_guide.md#ros-2-px4-frame-conventions). + +::: + +### Track Frame (Along-Track and Cross-Track) + +To describe how well a vehicle follows a path, area navigation (RNAV, ICAO Doc 9613) splits the horizontal position error into two components relative to the [desired track](#track): + +- **Along-track:** along the desired track, in the direction of travel. +- **Cross-track:** perpendicular to the desired track (see [Cross-Track Error](#cross-track-error)). + +PX4 path-following controllers ([NPFG](../config_fw/position_tuning_guide_fixedwing.md#fw-path-control-tuning-position), [pure pursuit](../config_rover/position_tuning.md#pure-pursuit-guidance-logic-info-only)) work in this frame. + +### North References + +ICAO defines directions as measured "from North (true, magnetic, compass or grid)", and Bowditch uses the same four references: + +- **True north:** The direction of the geographic North Pole along the local meridian. +- **Magnetic north:** The direction of the horizontal component of the Earth's magnetic field. + The angle between true and magnetic north is called _magnetic variation_ in aviation (FAA PHAK) and _variation_ in marine navigation (Bowditch). + Geomagnetic models such as the World Magnetic Model call the same angle _magnetic declination_. +- **Compass north:** The direction an installed compass indicates. + It differs from magnetic north by the _deviation_ caused by the vehicle's own magnetic fields. +- **Grid north:** The direction of the north axis of a map projection grid. + It differs from true north away from the projection's central meridian. + +PX4 uses true north internally. +The magnetometer measures compass north, so PX4 applies the magnetometer calibration, which removes the deviation. +The estimator then applies the declination (from the World Magnetic Model, or from [EKF2_MAG_DECL](../advanced_config/parameter_reference.md#EKF2_MAG_DECL) depending on [EKF2_DECL_TYPE](../advanced_config/parameter_reference.md#EKF2_DECL_TYPE)). + +### Angle Conventions + +The official aviation and marine definitions express directions in degrees, measured clockwise from north from 000° to 360°. +East is 090°, south is 180°, west is 270°. +MAVLink follows this convention for navigation angles (for example `GPS_RAW_INT.cog` in centidegrees from 0 to 35999). + +PX4 uses the same zero and the same sense of rotation, but a different unit and range internally: see [Angles in Radians](#angles-in-radians). + +## Definitions by Tradition + +The [Navigation Terminology](../concept/navigation_terminology.md) page gives one definition per term. +This section lists the definitions, where they differ, and the choice PX4 makes. + +### Heading + +> **ICAO:** "The direction in which the longitudinal axis of an aircraft is pointed, usually expressed in degrees from North (true, magnetic, compass or grid)." +> — ICAO Doc 9713, _International Civil Aviation Vocabulary_, and Annex 2, _Rules of the Air_ + +> **FAA:** "Heading—direction in which the nose of the aircraft points during flight." +> — FAA PHAK, Chapter 16 + +> **Bowditch:** "Heading (Hdg., SH) is the direction in which a vessel is pointed at any given moment, expressed as angular distance from 000° clockwise through 360°. It is easy to confuse heading and course." +> — Bowditch (2019), Art. 107 + +Aviation and marine definitions agree, and ground vehicle dynamics (ISO 8855, SAE J670) calls the same angle the _yaw angle_ (see [Ground Vehicles](#ground-vehicles-yaw-course-and-sideslip-angle)). + +### Course + +> **FAA:** "Course—intended path of an aircraft over the ground or the direction of a line drawn on a chart representing the intended aircraft path, expressed as the angle measured from a specific reference datum clockwise from 0° through 360° to the line." +> — FAA PHAK, Chapter 16 + +> **FAA:** "COURSE - The intended direction of flight in the horizontal plane measured in degrees from north." +> — FAA P/CG + +> **Bowditch:** "Course (C, Cn) is the horizontal direction in which a vessel is intended to be steered, expressed as angular distance from north clockwise through 360°. Strictly used, the term applies to direction through the water, not the direction intended to be made good over the ground." +> — Bowditch (2019), Art. 107 + +In aviation and marine navigation, the course is an _intended_ direction. +In aviation it is intended over the ground, while in strict marine usage it is the direction steered through the water. + +PX4 deviates from both: it calls the intended direction of motion over the ground the _course setpoint_, and uses _course_ for the actual direction, the [course over ground](#course-over-ground) (see [Course Is the Actual Direction](#course-is-the-actual-direction)). + +Course setpoints in PX4: `fixed_wing_lateral_setpoint.course` and `position_setpoint.course`. + +### Course Over Ground + +> **IHO:** "course over ground: The direction of the path over the ground actually followed by a vessel. It is normally a somewhat irregular line." +> — IHO S-32 + +Course over ground (COG) is the _actual_ direction of motion over the ground: the direction of the horizontal ground velocity vector. +With $v_N$ and $v_E$ the north and east components of the ground velocity: + +$$ +\chi = \operatorname{atan2}(v_E, v_N) +$$ + +Ground vehicle dynamics (ISO 8855, SAE J670) calls the same angle the _course angle_ (see [Ground Vehicles](#ground-vehicles-yaw-course-and-sideslip-angle)). +PX4 calls it the _course_, and uses _course over ground_ as a synonym (see [Course Is the Actual Direction](#course-is-the-actual-direction)). + +It is the direction of the [track](#track) at the current point. +This is why avionics display it as _TRK_ (track angle), and why NMEA 0183 `VTG` labels it "track made good". +COG is undefined when the vehicle is stationary, and noisy at low speed, so code that uses it must check a minimum ground speed or the course accuracy. + +In PX4: `sensor_gnss.course`, MAVLink `GPS_RAW_INT.cog`, NMEA `RMC` and `VTG`. + +### Track + +> **ICAO:** "TRACK [ICAO] - The projection on the earth's surface of the path of an aircraft, the direction of which path at any point is usually expressed in degrees from North (True, Magnetic, or Grid)." +> — FAA P/CG, quoting ICAO + +> **FAA:** "Track—actual path made over the ground in flight. (If proper correction has been made for the wind, track and course are identical.)" +> — FAA PHAK, Chapter 16 + +> **FAA:** "DESIRED TRACK - The planned or intended track between two waypoints. It is measured in degrees from either magnetic or true north. The instantaneous angle may change from point to point along the great circle track between waypoints." +> — FAA P/CG + +> **Bowditch:** "Track (TR) is the intended horizontal direction of travel with respect to the Earth. The terms intended track and trackline are used to indicate the path of intended travel." +> — Bowditch (2019), Art. 107 + +In aviation the **track** is the _actual_ path over the ground, and the **desired track** is the _intended_ path between two waypoints. +In marine navigation the track is the _intended_ path. + +Following the [precedence rule](#sources-and-precedence), PX4 uses the aviation terms: + +- **Track:** The actual path over the ground. + Its direction at any point is the [course](#course-over-ground). +- **Desired track:** The intended path over the ground, from which the [cross-track error](#cross-track-error) is measured. + This is usually the line between two waypoints, but it can also be a line along a course setpoint the vehicle holds, which the FAA definition does not cover. + +Marine readers understand bare "track" as the intended path, so always write _desired track_ for the intended path. + +### Bearing + +> **FAA:** "BEARING - The horizontal direction to or from any point, usually measured clockwise from true north, magnetic north, or some other reference point through 360 degrees." +> — FAA P/CG + +> **Bowditch:** "Bearing (B, Brg.) is the direction of one terrestrial point from another, expressed as angular distance from 000° (North) clockwise through 360°." +> — Bowditch (2019), Art. 107 + +Aviation and marine definitions agree. + +::: warning +A bearing is not a commanded direction. +The direction a guidance law commands is a course (or heading) setpoint. +See [Field Names That Deviate](#field-names-that-deviate). +::: + +### Cross-Track Error + +Cross-track error (XTE) is a standard output of RNAV systems and marine navigation receivers. +Bowditch lists it alongside course over ground, speed over ground and bearing to the next waypoint (Art. 2501). +NMEA 0183 reports it in the `XTE`, `APB` and `RMB` sentences, as a distance together with the direction to steer (`L` or `R`) to return to the desired track. + +The cross-track error is the perpendicular distance of the vehicle from the [desired track](#track), together with the side of the track the vehicle is on. +The official definitions do not define a sign: see [Signed Cross-Track Error](#signed-cross-track-error) for how PX4 represents it. + +### Drift Angle + +> **FAA:** "Drift angle—angle between heading and track." +> — FAA PHAK, Chapter 16 + +The drift angle is caused by wind for aircraft, and by wind and current for vessels. +For ground vehicles, it is caused by wheel slip, and ISO 8855 calls it the _vehicle sideslip angle_ (see [Ground Vehicles](#ground-vehicles-yaw-course-and-sideslip-angle)). + +::: warning +Marine _drift_ is the speed of a current, while the aviation _drift angle_ is an angle between heading and track. +Always write _drift angle_ for the angle, and never bare _drift_. +::: + +::: info +For aircraft, the drift angle is not the _sideslip angle_ ($\beta$, see [Terminology/Notation](../contribute/notation.md)). +In flight dynamics (ISO 1151), sideslip is measured against the airflow, so a plane flying through a crosswind with its nose into the wind has a large drift angle and zero sideslip. +Ground vehicle dynamics uses the same name for a ground-referenced angle: see [Ground Vehicles](#ground-vehicles-yaw-course-and-sideslip-angle). +::: + +In PX4, the aerodynamic sideslip is used by the EKF2 synthetic sideslip fusion (`estimator_aid_src_sideslip`, `estimator_innovations.beta`). + +### Ground Vehicles: Yaw, Course and Sideslip Angle + +ISO 8855 and SAE J670 describe the horizontal motion of a ground vehicle with three angles, measured in the ground plane: + +- **Yaw angle** ($\psi$): The angle from the earth-fixed x-axis to the vehicle x-axis. + This is the [heading](#heading). +- **Course angle** ($\nu$): The angle from the earth-fixed x-axis to the horizontal velocity of the vehicle over the ground. + This is the actual direction of motion, which is the PX4 [course](#course-over-ground), not the intended [course](#course) of the FAA definition. +- **Sideslip angle** ($\beta = \nu - \psi$): The angle from the vehicle x-axis to the horizontal velocity over the ground. + This is the ground vehicle counterpart of the [drift angle](#drift-angle), and not the air-relative sideslip angle of flight dynamics. + +ISO 8855 measures these angles counterclockwise about a z-up axis, so its sideslip angle has the opposite sign of the [PX4 drift angle](#drift-angle-sign). + +Following the [precedence rule](#sources-and-precedence), use these terms for rovers: + +- _Heading_ for the yaw angle, _course_ for the course angle and _drift angle_ for the vehicle sideslip angle. +- When code or documentation follows vehicle dynamics literature, the ISO 8855 terms may be used, but write _vehicle sideslip angle_ and cite ISO 8855, so that it is not confused with aerodynamic sideslip. + +For a rover that drives without wheel slip (Ackermann or differential drive), the course equals the heading when driving forwards, and the heading plus 180° when reversing. +A drift angle appears when the wheels slip, for example on loose ground or in fast turns, and by design on [mecanum rovers](../frames_rover/index.md#mecanum). + +### Airspeed, Ground Speed and Speed Over Ground + +> **FAA:** "Airspeed—rate of the aircraft's progress through the air." "GS—rate of the aircraft's inflight progress over the ground." +> — FAA PHAK, Chapter 16 + +> **Bowditch:** "Speed over the ground (SOG) is the actual speed of the vessel over the surface of the Earth at any given time." +> — Bowditch (2019), Art. 106 + +Ground speed (aviation, FAA PHAK) and speed over ground (marine) are the same quantity: the magnitude of the horizontal ground velocity, whose direction is the course over ground. +For vessels, the water-relative counterpart of airspeed is the _speed through the water_, which a log (paddle wheel) measures and a GNSS receiver does not. + +### Wind and Current Triangle + +The [wind triangle](../concept/navigation_terminology.md#wind-triangle) has a marine counterpart for vessels: + +$$ +\mathbf{v}_{ground} = \mathbf{v}_{water} + \mathbf{v}_{current} +$$ + +The current is described by its [set and drift](#terms-not-yet-used-in-px4), and $\mathbf{v}_{water}$ is offset from the heading by [leeway](#terms-not-yet-used-in-px4). + +## Terminology Conflicts + +These are the terms where the traditions disagree, and the official term PX4 uses as a result of the [precedence rule](#sources-and-precedence). +Heading (yaw angle in ISO 8855), bearing, course over ground and cross-track error mean the same in all of them. + +| Term | Aviation (ICAO/FAA, ISO 1151) | Marine (Bowditch) | Ground vehicles (ISO 8855/SAE J670) | Term to use in PX4 | +| ---------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Track | Actual path over the ground; the intended path is _desired track_ | Intended path over the ground | — | _Track_ (actual) and _desired track_ (intended) | +| Course | Intended direction over the ground | Direction steered through the water (strict sense) | _Course angle_: actual direction of motion over the ground | _Course_ (actual, also _course over ground_) and _course setpoint_ (intended); differs from aviation, see [Course Is the Actual Direction](#course-is-the-actual-direction) | +| Drift | _Drift angle_: angle between heading and track | Speed of the current, with _set_ as its direction | — | _Drift angle_ (angle); never bare _drift_ | +| Sideslip | Angle between the body x-axis and the airflow | — | Angle between the vehicle x-axis and the velocity over the ground | _Sideslip angle_ (air-relative) and _drift angle_ or _vehicle sideslip angle_ (ground-relative) | +| True to magnetic north | _Magnetic variation_ | _Variation_ | — | _Declination_ (World Magnetic Model term, used by EKF2) | + +## Where PX4 Differs + +PX4 follows the official definitions above, except for the meaning of _course_. +The sections below describe where PX4 represents, computes or names a quantity differently from the official definitions, so that you can convert correctly. + +### Course Is the Actual Direction + +The official definitions use bare _course_ for an _intended_ direction (FAA, Bowditch), and _course over ground_ (IHO) or _track angle_ (avionics) for the _actual_ direction. +PX4 deliberately uses: + +- **Course:** The actual (measured or estimated) direction of motion over the ground. + _Course over ground_ (COG) is a synonym. +- **Course setpoint:** The intended direction of motion over the ground, which aviation calls the _course_. + +The reasons are: + +- PX4 names a quantity by its actual value and adds _setpoint_ for the commanded value, as for _heading_ and _heading setpoint_, or _velocity_ and _velocity setpoint_. + With the aviation meaning, the course setpoint would be the setpoint of an intended value, and the actual value would need a different word. +- It matches the _course angle_ of ground vehicle dynamics (ISO 8855) and what GNSS receivers report as course (`sensor_gnss.course`, NMEA `RMC` and `VTG`). +- Existing fields already fit: `sensor_gnss.course` is measured, and the `course` fields of setpoint topics (`fixed_wing_lateral_setpoint.course`, `position_setpoint.course`) are setpoints. + +When you read aviation or marine sources, translate their _course_ to the PX4 _course setpoint_. +For example, the FAA [wind correction angle](#terms-not-yet-used-in-px4) is applied to the course setpoint in PX4 terms. + +### Angles in Radians + +The official definitions express directions in degrees from 000° to 360°. +In uORB, PX4 expresses them in radians, usually wrapped to $[-\pi, \pi]$, with the same zero (true north) and the same sense (clockwise). +East is $+\pi/2$ and west is $-\pi/2$. +Some fields use another range, for example `transponder_report.heading` ($[0, 2\pi]$) and unwrapped yaw setpoints, so check the field's `[@range]`. + +Convert with `matrix::wrap_2pi()` and `math::degrees()` when you output to MAVLink or to users, as the MAVLink streams do. + +### Local Frame Is a Map Projection + +The estimator keeps the vehicle's global position (latitude and longitude), and derives the local position from it with an **azimuthal equidistant projection** centred on the local origin (`MapProjection` in `src/lib/geo`). +As a result: + +- The x-axis of `vehicle_local_position` points to true north at the origin. + At the vehicle's position it points to the grid north of the projection, which differs from true north by the meridian convergence. + The difference grows with distance from the origin, mainly east or west of it. + It is about 0.1° at 10 km east of an origin at 47° latitude. +- Heading and velocity are relative to true north at the vehicle ([local navigation frame](#local-navigation-frame-ned)), not to the projection's grid north. +- A straight line between two waypoints in the local frame is a straight line in the projection. + The FAA desired track follows the great circle between the waypoints. + The two are identical for lines through the origin, and practically identical over typical mission distances. + +For vehicles that operate tens of kilometres from the origin, take this into account when you compare local-frame directions with true directions. + +### Signed Cross-Track Error + +The official definitions express cross-track error as a distance and a side (NMEA: the direction to steer). +PX4 represents it as a single signed distance: + +- It is the shortest horizontal distance from the vehicle to the desired track. +- It is positive when the vehicle is to the right of the desired track and negative when it is to the left, looking in the direction of travel. + +With $\mathbf{t}$ the unit vector along the desired track and $\mathbf{d}$ the vector from a point on the track to the vehicle (north and east components): + +$$ +e_{xt} = t_N d_E - t_E d_N +$$ + +This is the convention used by NPFG (`fixed_wing_lateral_guidance_status.signed_track_error`) and by pure pursuit (`pure_pursuit_status.crosstrack_error`). +A vehicle with a positive cross-track error gets NMEA "steer L". + +### Drift Angle Sign + +The FAA defines the drift angle as the angle between heading and track, without a sign. +Where PX4 needs a signed value, it is `wrap_pi(course - heading)`: positive when the vehicle moves to the right of where its nose points. + +### Wind as a Velocity Vector + +The official definitions describe wind by the direction it blows _from_. +PX4 wind estimates (`wind`, `airspeed_wind`) are velocity vectors in NED (`windspeed_north`, `windspeed_east`), which point in the direction the air moves _towards_. +A wind reported as "from 360°" has `windspeed_north < 0` in PX4. + +### Field Names That Deviate + +Some existing names predate these pages or come from external protocols, and do not match the official terms. +Read them with the meaning given here, and use the official term in new code: + +| Field | Actual meaning | Official term | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| `position_setpoint.course` (comment: "desired course (bearing)") | Intended direction of motion over the ground. | Course setpoint | +| `position_controller_status.nav_bearing` (MAVLink `NAV_CONTROLLER_OUTPUT.nav_bearing`) | Intended for the direction commanded by the guidance law. Not populated by current controllers (always 0). | Course or heading setpoint | +| `position_controller_status.xtrack_error` (MAVLink `NAV_CONTROLLER_OUTPUT.xtrack_error`) | Intended for the signed cross-track error. Not populated by current controllers (always 0). | Cross-track error | +| `fixed_wing_lateral_guidance_status.bearing_feas` | Feasibility of the course commanded by NPFG (NPFG calls it "bearing"). | Course setpoint | +| `transponder_report.heading` (MAVLink `ADSB_VEHICLE.heading`) | Course over ground of the other aircraft, as reported by ADS-B. | Course | +| `bearing_setpoint` in the Ackermann and mecanum rover position controllers (`AckermannPosControl`, `MecanumPosControl`) | Course setpoint, taken from the bearing to the pure pursuit lookahead point (`PurePursuit::calcTargetBearing()`, which is a bearing). Ackermann rovers use it directly as the heading (yaw) setpoint, assuming no slip. | Course setpoint (mecanum), heading setpoint (Ackermann) | +| "Direction (bearing)" of the velocity setpoint in [Rover Velocity Tuning](../config_rover/velocity_tuning.md) and "bearing setpoints" in [Rover Position Tuning](../config_rover/position_tuning.md) | Intended direction of motion over the ground. | Course setpoint | + +## Guidelines for Contributors + +When you add or change uORB fields, parameters, MAVLink handling, log analysis tools or documentation: + +- Use the official terms on these pages. + Do not introduce new navigation terms. + If a concept is missing, look up its official name in the [references](#references) and add it here. +- Use _heading_ only for the direction the vehicle points, _course_ for the actual direction of motion over the ground, _course setpoint_ for the intended direction over the ground, and _bearing_ only for the direction from one point to another. + Do not use bare _course_ for an intended direction, even where an aviation or marine source does (see [Course Is the Actual Direction](#course-is-the-actual-direction)). +- Write _desired track_ for an intended path, and never use bare _drift_. +- Use _sideslip angle_ only for the angle against the airflow. + For the ground-relative angle, use _drift angle_, or _vehicle sideslip angle_ with a reference to ISO 8855. +- Use the PX4 [signed cross-track error](#signed-cross-track-error) convention. +- State the reference (true north), unit and range in the field comment, and add the `[@frame]` and `[@range]` tags (see [uORB Documentation Standard](../uorb/uorb_documentation.md)). +- When you convert to or from an external protocol, check that protocol's definition of each field: names alone are not reliable. + +## Terms Not Yet Used in PX4 + +These terms have official definitions, but PX4 does not use them yet. +They are kept here for reference, so that new code uses the official term when it needs one of these concepts. + +| Term | Official meaning | Source | +| --------------------- | ----------------------------------------------------------------------------------------- | ------------------ | +| Track made good | Net direction from the point of departure to the point of arrival. | Bowditch | +| Relative bearing | Bearing measured from the vehicle's heading. | Bowditch | +| Wind correction angle | Correction applied to the course setpoint to obtain a heading that keeps the track on it. | FAA | +| Tyre slip angle | Angle between the wheel plane and the direction of travel of the tyre contact patch. | ISO 8855, SAE J670 | +| Leeway | Leeward motion of a vessel due to the wind. | Bowditch | +| Set and drift | Direction (towards) and speed of a current. | Bowditch | + +Expand the block below for the official definition of each term. + +:::: details Official definitions + +### Track Made Good + +> **Bowditch:** "Track made good (TMG) is the single resultant direction from the point of departure to point of arrival at any given time. The use of this term is preferred to the use of the misnomer 'course made good.'" +> — Bowditch (2019), Art. 107 + +Track made good (also called course made good, CMG) is the net direction between two positions, not an instantaneous value. +The matching speed is the _speed made good_ (SMG): the distance between the two positions divided by the elapsed time. +PX4 controllers do not use it, but it is useful in log analysis. + +### Relative Bearing + +> **Bowditch:** "A relative bearing is measured relative to the ship's heading from 000° (dead ahead) clockwise through 360°." +> — Bowditch (2019), Art. 107 + +- **Relative bearing:** The [bearing](#bearing) measured from the vehicle's heading. + Bowditch: "True Bearing = Relative Bearing + True Heading." +- **Reciprocal bearing:** The bearing in the opposite direction, which differs by 180°. + +### Wind Correction Angle + +> **FAA:** "WCA—correction applied to the course to establish a heading so that track coincides with course." +> — FAA PHAK, Chapter 16 + +The **wind correction angle** (WCA, also called _crab angle_) is the angle by which the heading is offset from the course setpoint into the wind, so that the track follows the course setpoint. +The FAA definition calls this intended direction the _course_ (see [Course Is the Actual Direction](#course-is-the-actual-direction)). +In the [wind triangle](../concept/navigation_terminology.md#wind-triangle), it is the angle between the heading and the course setpoint. + +### Tyre Slip Angle + +ISO 8855 and SAE J670 define the _slip angle_ of each tyre: the angle between the wheel plane and the direction of travel of the wheel's contact patch. +It describes how a tyre generates lateral force, and is a vehicle dynamics term with no navigation counterpart. +Write _tyre slip angle_ for it, to distinguish it from the [vehicle sideslip angle](#ground-vehicles-yaw-course-and-sideslip-angle). + +### Leeway + +> **Bowditch:** "Leeway is the leeward motion of a vessel due to that component of the wind vector perpendicular to the vessel's track." +> — Bowditch (2019), Art. 1006 + +Leeway is the sideways push of the wind on a vessel's hull and superstructure, relative to the water. +It is the marine counterpart of an aircraft being displaced by the wind, and contributes to the drift angle. +In the [current triangle](#wind-and-current-triangle), $\mathbf{v}_{water}$ is offset from the heading by leeway. + +### Set and Drift + +> **Bowditch:** "Set refers to the current's direction, and drift refers to the current's speed." +> — Bowditch (2019), Art. 1006 + +The _set_ is the direction towards which the current flows, and the _drift_ is its speed. +When a dead reckoning (DR) position is compared with a fix, the same terms describe the total unexplained offset: "The set is the direction from the DR to the fix" (Bowditch, Art. 1008). + +This is the opposite of [wind direction](../concept/navigation_terminology.md#wind-direction), which is the direction the wind blows from. +A current with set 000° and a wind from 180° push a vehicle the same way. +PX4 wind estimates are velocity vectors, so they [point the same way as current set](#wind-as-a-velocity-vector). + +::: warning +Marine _drift_ is the speed of a current, while the aviation _drift angle_ is an angle between heading and track. +Write _drift angle_ for the angle, and _set and drift_ (of the current) for the current. +::: + +:::: + +## References + +Aviation: + +- ICAO Doc 9713, _International Civil Aviation Vocabulary_, and ICAO Annex 2, _Rules of the Air_ (heading, track). +- ICAO Doc 9613, _Performance-based Navigation (PBN) Manual_ (along-track and cross-track components). +- ICAO Doc 9674, _World Geodetic System — 1984 (WGS-84) Manual_. +- FAA, [Pilot's Handbook of Aeronautical Knowledge](https://www.faa.gov/regulations_policies/handbooks_manuals/aviation/phak) (FAA-H-8083-25), Chapter 16: Navigation. +- FAA, [Pilot/Controller Glossary](https://www.faa.gov/air_traffic/publications/atpubs/pcg_html/) (BEARING, COURSE, DESIRED TRACK, TRACK, TRACK [ICAO]). +- SKYbrary, [Heading, Track and Radial](https://skybrary.aero/articles/heading-track-and-radial) (summary of the ICAO definitions). + +Marine: + +- National Geospatial-Intelligence Agency, [The American Practical Navigator (Bowditch), Pub. No. 9](https://msi.nga.mil/Publications/APN), 2019 edition, Volume I: Art. 106 and 107 (speed and direction), Art. 1006 and 1008 (leeway, set and drift), Art. 2501 (receiver outputs, including cross-track error). +- International Hydrographic Organization, [S-32 Hydrographic Dictionary](https://portal.iho.int/iho-ohi/S32/engView.php?page=56) (course over ground, course made good). +- National Marine Electronics Association, [NMEA 0183](https://www.nmea.org/nmea-0183.html) (`RMC`, `VTG`, `HDT`, `XTE`, `APB`, `RMB`). +- SNAME, _Nomenclature for Treating the Motion of a Submerged Body Through a Fluid_ (body axes for marine vehicles). + +Ground vehicles: + +- ISO 8855:2011, [Road vehicles — Vehicle dynamics and road-holding ability — Vocabulary](https://www.iso.org/standard/51180.html) (axis systems, yaw, course and sideslip angle, tyre slip angle). +- SAE J670 (2022), [Vehicle Dynamics Terminology](https://saemobilus.sae.org/standards/j670_202206-vehicle-dynamics-terminology). + +Frames: + +- ISO 1151, _Flight dynamics — Concepts, quantities and symbols_ (earth-fixed and body axis systems, aerodynamic sideslip). +- National Geospatial-Intelligence Agency, _World Geodetic System 1984_ (NGA.STND.0036). + +PX4: + +- [Navigation Terminology](../concept/navigation_terminology.md): the commonly used terms. +- [Terminology/Notation](../contribute/notation.md): symbols, frames and acronyms. +- [uORB Documentation Standard](../uorb/uorb_documentation.md): how to document frames, units and ranges of message fields. diff --git a/docs/en/contribute/notation.md b/docs/en/contribute/notation.md index 61e137ae9f1..05af7a34751 100644 --- a/docs/en/contribute/notation.md +++ b/docs/en/contribute/notation.md @@ -2,6 +2,8 @@ The following terms, symbols, and decorators are used in text and diagrams throughout this guide. +For navigation terms such as heading, course, track, bearing and cross-track error, see [Navigation Terminology](../concept/navigation_terminology.md). + ## Notation - Bold face variables indicate vectors or matrices and non-bold face variables represent scalars.