mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-11-22 14:19:57 +08:00
* 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 <frimi999@gmail.com> * 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 <frimi999@gmail.com> * 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 <frimi999@gmail.com> * 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 <hamishwillee@gmail.com> * docs(concept): apply suggestion on px4 path follow computation Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * 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 <frimi999@gmail.com> * 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 <frimi999@gmail.com> * 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 <frimi999@gmail.com> * docs(concept): address review comments by mbjd --------- Signed-off-by: Michael Fritsche <frimi999@gmail.com> Signed-off-by: Hamish Willee <hamishwillee@gmail.com> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
12 KiB
12 KiB
Terminology
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.
Notation
- Bold face variables indicate vectors or matrices and non-bold face variables represent scalars.
- The default frame for each variable is the local frame:
\ell{}. Right superscripts represent the coordinate frame. If no right superscript is present, then the default frame\ell{}is assumed. An exception is given by Rotation Matrices, where the lower right subscripts indicates the current frame and the right superscripts the target frame. - Variables and subscripts can share the same letter, but they always have different meaning.
Acronyms
| Acronym | Expansion |
|---|---|
| AOA | Angle Of Attack. Also named alpha. |
| AOS | Angle Of Sideslip. Also named beta. |
| FRD | Coordinate system where the X-axis is pointing towards the Front of the vehicle, the Y-axis is pointing Right and the Z-axis is pointing Down, completing the right-hand rule. |
| FW | Fixed-wing (planes). |
| MC | MultiCopter. |
| MPC or MCPC | MultiCopter Position Controller. MPC is also used for Model Predictive Control. |
| NED | Coordinate system where the X-axis is pointing towards the true North, the Y-axis is pointing East and the Z-axis is pointing Down, completing the right-hand rule. |
| PID | Controller with Proportional, Integral and Derivative actions. |
Symbols
| Variable | Description |
|---|---|
x,y,z |
Translation along coordinate axis x,y and z respectively. |
\boldsymbol{\mathrm{r}} |
Position vector: \boldsymbol{\mathrm{r}} = [x \quad y \quad z]^{T} |
\boldsymbol{\mathrm{v}} |
Velocity vector: \boldsymbol{\mathrm{v}} = \boldsymbol{\mathrm{\dot{r}}} |
\boldsymbol{\mathrm{a}} |
Acceleration vector: \boldsymbol{\mathrm{a}} = \boldsymbol{\mathrm{\dot{v}}} = \boldsymbol{\mathrm{\ddot{r}}} |
\alpha |
Angle of attack (AOA). |
b |
Wing span (from tip to tip). |
S |
Wing area. |
AR |
Aspect ratio: AR = b^2/S |
\beta |
Angle of sideslip (AOS). |
c |
Wing chord length. |
\delta |
Aerodynamic control surface angular deflection. A positive deflection generates a negative moment. |
\phi,\theta,\psi |
Euler angles roll (=Bank), pitch and yaw (=Heading). |
\Psi |
Attitude vector: \Psi = [\phi \quad \theta \quad \psi]^T |
X,Y,Z |
Forces along coordinate axis x,y and z. |
\boldsymbol{\mathrm{F}} |
Force vector: \boldsymbol{\mathrm{F}}= [X \quad Y \quad Z]^T |
D |
Drag force. |
C |
Cross-wind force. |
L |
Lift force. |
g |
Gravity. |
l,m,n |
Moments around coordinate axis x,y and z. |
\boldsymbol{\mathrm{M}} |
Moment vector \boldsymbol{\mathrm{M}} = [l \quad m \quad n]^T |
M |
Mach number. Can be neglected for scale aircraft. |
\boldsymbol{\mathrm{q}} |
Vector part of Quaternion. |
\boldsymbol{\mathrm{\tilde{q}}} |
Hamiltonian attitude quaternion (see 1 below) |
\boldsymbol{\mathrm{R}}_\ell^b |
Rotation matrix. Rotates a vector from frame \ell{} to frame b{}. \boldsymbol{\mathrm{v}}^b = \boldsymbol{\mathrm{R}}_\ell^b \boldsymbol{\mathrm{v}}^\ell |
\Lambda |
Leading-edge sweep angle. |
\lambda |
Taper ratio: \lambda = c_{tip}/c_{root} |
w |
Wind velocity. |
p,q,r |
Angular rates around body axis x,y and z. |
\boldsymbol{\omega}^b |
Angular rate vector in body frame: \boldsymbol{\omega}^b = [p \quad q \quad r]^T |
\boldsymbol{\mathrm{x}} |
General state vector. |
1Hamiltonian attitude quaternion.\boldsymbol{\mathrm{\tilde{q}}} = (q_0, q_1, q_2, q_3) = (q_0, \boldsymbol{\mathrm{q}}).
\boldsymbol{\mathrm{\tilde{q}}}{}describes the attitude relative to the local frame\ell{}. To represent a vector in local frame given a vector in body frame, the following operation can be used:\boldsymbol{\mathrm{\tilde{v}}}^\ell = \boldsymbol{\mathrm{\tilde{q}}} \, \boldsymbol{\mathrm{\tilde{v}}}^b \, \boldsymbol{\mathrm{\tilde{q}}}^*{}(or\boldsymbol{\mathrm{\tilde{q}}}^{-1}{}instead of\boldsymbol{\mathrm{\tilde{q}}}^*{}if\boldsymbol{\mathrm{\tilde{q}}}{}is not unitary).\boldsymbol{\mathrm{\tilde{v}}}{}represents a quaternionized vector:\boldsymbol{\mathrm{\tilde{v}}} = (0,\boldsymbol{\mathrm{v}})
Subscripts / Indices
| Subscripts / Indices | Description |
|---|---|
a |
Aileron. |
e |
Elevator. |
r |
Rudder. |
Aero |
Aerodynamic. |
T |
Thrust force. |
w |
Relative airspeed. |
x,y,z |
Component of vector along coordinate axis x, y and z. |
N,E,D |
Component of vector along global north, east and down direction. |
Superscripts / Indices
| Superscripts / Indices | Description |
|---|---|
\ell |
Local-frame. Default for PX4 related variables. |
b |
Body-frame. |
w |
Wind-frame. |
Decorators
| Decorator | Description |
|---|---|
()^* |
Complex conjugate. |
\dot{()} |
Time derivative. |
\hat{()} |
Estimate. |
\bar{()} |
Mean. |
()^{-1} |
Matrix inverse. |
()^T |
Matrix transpose. |
\tilde{()} |
Quaternion. |