From dfe32bf6c050a386e417fb6ff4f9de33cd5b59d6 Mon Sep 17 00:00:00 2001 From: PX4 Build Bot Date: Wed, 22 Jul 2026 15:27:20 +1000 Subject: [PATCH] docs(i18n): PX4 guide translations (Crowdin) - ko (#27965) Co-authored-by: Crowdin Bot --- docs/ko/SUMMARY.md | 1 + docs/ko/advanced/rtk_gps.md | 6 +- docs/ko/advanced_features/detect_and_avoid.md | 1032 +++++++++++++++++ docs/ko/advanced_features/index.md | 1 + docs/ko/config/safety.md | 17 +- docs/ko/debug/failure_injection.md | 31 +- docs/ko/dronecan/ark_cannode.md | 2 +- docs/ko/dronecan/ark_flow.md | 2 +- docs/ko/dronecan/ark_flow_mr.md | 2 +- docs/ko/dronecan/ark_gps.md | 2 +- docs/ko/dronecan/ark_rtk_gps.md | 2 +- docs/ko/dronecan/ark_rtk_gps_l1_l2.md | 2 +- docs/ko/dronecan/ark_x20_rtk_gps.md | 2 +- docs/ko/dronecan/index.md | 25 +- docs/ko/dronecan/px4_cannode_fw.md | 2 +- docs/ko/middleware/dds_topics.md | 4 +- docs/ko/middleware/zenoh.md | 7 +- docs/ko/modules/modules_command.md | 1 + docs/ko/modules/modules_controller.md | 2 +- docs/ko/modules/modules_driver.md | 5 +- docs/ko/modules/modules_driver_camera.md | 2 +- docs/ko/modules/modules_system.md | 21 +- docs/ko/msg_docs/DetectAndAvoid.md | 93 ++ docs/ko/msg_docs/DetectAndAvoidMostUrgent.md | 77 ++ docs/ko/msg_docs/FailureInjection.md | 2 + docs/ko/msg_docs/HeaterStatus.md | 38 +- docs/ko/msg_docs/RtcmData.md | 77 ++ docs/ko/msg_docs/VehicleCommand.md | 2 + docs/ko/msg_docs/index.md | 4 +- docs/ko/peripherals/adsb_flarm.md | 211 ++-- .../test_and_ci/integration_testing_mavsdk.md | 8 +- 31 files changed, 1503 insertions(+), 180 deletions(-) create mode 100644 docs/ko/advanced_features/detect_and_avoid.md create mode 100644 docs/ko/msg_docs/DetectAndAvoid.md create mode 100644 docs/ko/msg_docs/DetectAndAvoidMostUrgent.md create mode 100644 docs/ko/msg_docs/RtcmData.md diff --git a/docs/ko/SUMMARY.md b/docs/ko/SUMMARY.md index 65e2fc1891..2ba09a4b21 100644 --- a/docs/ko/SUMMARY.md +++ b/docs/ko/SUMMARY.md @@ -884,6 +884,7 @@ - [Log Encryption](dev_log/log_encryption.md) - [고급 주제](advanced/index.md) - [PX4 Metadata](advanced/px4_metadata.md) + - [Detect and Avoid](advanced_features/detect_and_avoid.md) - [Package Delivery Architecture](advanced/package_delivery.md) - [Camera Integration/Architecture](camera/camera_architecture.md) - [컴퓨터 비전](advanced/computer_vision.md) diff --git a/docs/ko/advanced/rtk_gps.md b/docs/ko/advanced/rtk_gps.md index e28d2d81b9..5e083b704e 100644 --- a/docs/ko/advanced/rtk_gps.md +++ b/docs/ko/advanced/rtk_gps.md @@ -34,6 +34,10 @@ The PX4 GPS stack automatically sets up the GPS modules to send and receive the As soon as the autopilot receives `GPS_RTCM_DATA` MAVLink messages, it reassembles fragmented packets when needed and then forwards the RTCM data to the attached GPS module over existing data channels (a dedicated channel for correction data is not required). +:::info +Firmware built with `CONFIG_GPS_SPARTN` (default off; enabled on selected targets such as ARK GNSS nodes and SITL) also frames [SPARTN](https://www.spartnformat.org/) corrections on that same inject path — for example u-blox PointPerfect streams carried in `GPS_RTCM_DATA` / `rtcm_corrections`. PX4 does not provision SPARTN decryption keys; those must already be configured on the receiver. +::: + :::info The u-blox U-Center RTK module configuration tool is not needed/used! ::: @@ -51,7 +55,7 @@ If you are sending RTCM corrections to PX4 yourself, follow the MAVLink [`GPS_RT - If the RTCM payload exceeds 180 bytes, split it across up to 4 packets using the Fragment ID and Sequence ID (encoded in `GPS_RTCM_DATA.flags`). Every packet except the last one must be filled to its maximum 180-byte capacity; only the final packet may be partially filled. - PX4 reassembles fragmented packets according to the MAVLink rules and supports out-of-order delivery for one in-progress fragmented message at a time. -- A fragmented message is considered complete when either 4 fragments with the same Sequence ID have been received, or when you receive a partial fragment and you have already recieved all the fully-packed fragments that precede it (by Fragment ID) in the current sequence. +- A fragmented message is considered complete when either 4 fragments with the same Sequence ID have been received, or when you receive a partial fragment and you have already received all the fully-packed fragments that precede it (by Fragment ID) in the current sequence. - If the RTCM payload length is an exact multiple of 180 bytes and uses fewer than 4 fragments, the sender must still send a final zero-length fragment to mark completion. A 720-byte payload (all 4 fragments full) is complete after the last fragment is received. - As a compatibility fallback for older QGroundControl builds that omit that final zero-length fragment, PX4 also flushes a buffered RTCM message to the GNSS when a `GPS_RTCM_DATA` message with a different Sequence ID arrives, but only if the buffered fragments are a gap-free run of full 180-byte fragments starting at fragment 0. diff --git a/docs/ko/advanced_features/detect_and_avoid.md b/docs/ko/advanced_features/detect_and_avoid.md new file mode 100644 index 0000000000..5470740654 --- /dev/null +++ b/docs/ko/advanced_features/detect_and_avoid.md @@ -0,0 +1,1032 @@ +# Detect and Avoid + +Detect and Avoid (DAA) runs in the [`navigator`](../modules/modules_controller.md#navigator) module. +Its `DetectAndAvoid` component uses the `adsb` library for conflict evaluation, traffic identification, conflict tracking, and action policy (see [Implementation Structure](#implementation-structure)). +It evaluates cooperative ("transponder-equipped") traffic, such as that from ADS-B, FLARM, or UTM integrations, that is reported through the [`transponder_report`](../msg_docs/TransponderReport.md) topic. +DAA can warn the operator, request navigator actions, or block arming when a conflict requires an automatic response. + +:::tip +This page is the detailed technical reference for PX4 developers and advanced integrators looking to maintain and extend the DAA implementation. + +For basic setup and configuration of an avoidance system, see [ADS-B/FLARM/UTM Receivers: Air Traffic Avoidance](../peripherals/adsb_flarm.md). +::: + +## Scope and Context + +DAA is most relevant for operations in shared airspace, especially beyond visual line of sight (BVLOS), where an unmanned aircraft must help maintain safe separation from manned aviation without an onboard pilot performing see-and-avoid. + +PX4 currently handles only cooperative traffic: aircraft that broadcast position and related state through ADS-B, FLARM, UTM, or another compatible integration. +If you are not using one of those traffic sources, this page is mainly relevant only if you are developing or integrating DAA itself. + +This page uses _encounter_ for a received cooperative-traffic report and _conflict_ when that traffic breaches a configured alert test. + +Use this page for understanding: + +- The detailed behavior of [Conflict Standards](#conflict-standards) +- Action selection and preflight behavior in [Automated Actions](#automated-actions) and [Arming, Preflight, and Ground Behavior](#arming-preflight-and-ground-behavior) +- Message, logging, and test details in [Operator Messages](#operator-messages), [Analysing a Conflict Using the Logs](#analysing-a-conflict-using-the-logs), and [Testing and Simulation](#testing-and-simulation) +- Extension guidance in [Adding a New Standard](#adding-a-new-standard) + +## 개요 + +DAA supports two conflict models: + +- `Crosstrack` mode raises one conflict level when ownship (the current vehicle) is close to the traffic's predicted track, vertically close, and within a configured collision-time threshold. + Use it when you want one threshold driven by `NAV_TRAFF_*`. +- `F3442` mode evaluates four alert tests derived from concepts in [ASTM F3442/F3442M-23](https://store.astm.org/f3442_f3442m-23.html). + Use it when you want staged alerting and per-level actions. + +`CONFIG_NAVIGATOR_ADSB` includes DAA in the firmware. +When it is enabled, `CONFIG_NAVIGATOR_ADSB_F3442` selects F3442 mode; otherwise Crosstrack mode is built. + +:::warning +F3442 mode handles cooperative traffic only and implements selected alert concepts and thresholds. +It does not by itself establish compliance with ASTM F3442/F3442M-23, which applies to a complete DAA system and its compliance evidence. +The implementation references the 2023 edition and has not been evaluated against the later [ASTM F3442-25](https://store.astm.org/f3442-25.html) edition. +::: + +At runtime DAA can: + +- Process queued traffic reports from [`transponder_report`](../msg_docs/TransponderReport.md). +- Keep the most important active conflicts in a fixed-size buffer. +- Publish both per-traffic and most-urgent DAA status topics. +- Trigger configured navigator actions when a conflict requires more than a warning. +- Prevent arming if DAA is enabled and the current most urgent conflict requires an automatic action. + +## How It Works + +Each navigator cycle, DAA: + +1. Reads all queued `transponder_report` messages for that cycle. + - Rejects invalid or stale traffic reports. + - Filters self-detections using ownship ICAO, ADS-B callsign, and UAS ID. +2. Evaluates the conflict with the built DAA model. + - Publishes [`detect_and_avoid`](../msg_docs/DetectAndAvoid.md) for reports that create or update a tracked conflict, including the sample that clears one. + First-seen traffic evaluated at conflict level `NONE` is not published. +3. Applies the result to the active-conflict buffer (`ConflictTracker`) and selects the most urgent conflict. + - The tracker reports buffer changes (new, level changed, removed, ignored). + - Publishes the most urgent conflict summary on [`detect_and_avoid_most_urgent`](../msg_docs/DetectAndAvoidMostUrgent.md). +4. Hands the cycle's change records to the notifier (`ConflictNotifier`), which decides all operator warnings for the cycle in one place, and, if configured, requests a navigator action. + +Conflict priority is determined by: + +- Higher conflict level first. +- Shorter aircraft distance when conflict levels are equal. + +## Conflict Standards + +### Crosstrack Mode + +This mode is used by firmware built without `CONFIG_NAVIGATOR_ADSB_F3442`. + +This mode provides a single actionable threshold for track-crossing traffic. +It evaluates the traffic geometry using three gates. +If all three conditions are met, DAA publishes a single conflict level: `HIGH`. + +- The ownship must lie within `NAV_TRAFF_A_HOR` of the traffic's projected ground track. +- Vertical separation must be below `NAV_TRAFF_A_VER`. +- Estimated time to collision must be below `NAV_TRAFF_COLL_T`. + +#### Metrics and Conflict Test + +The crosstrack implementation publishes these geometry outputs in `detect_and_avoid`: + +- `aircraft_dist`: the current point-to-point 3D range. +- `aircraft_dist_hor`: the signed crosstrack distance to the projected traffic line when that line can be constructed. +- `aircraft_dist_vert`: the absolute vertical separation. +- `expected_min_dist_time`: a conservative collision-time estimate. + +:::details +Click here to view how the crosstrack metrics and gates are computed + +The crosstrack implementation computes them as follows: + +- It first computes the current point-to-point separations between the ownship and the traffic: $d_{hor}$, $d_{vert}$. + +- It projects a traffic ground-track line starting at the reported traffic position and extending in the reported traffic heading direction. + Let $d_{ext}$ denote the fixed path-extension constant `kTrafficToUavDistanceExtension`. + Heading is required for this step. + The line length is: + + $$ + d_{pred} = d_{hor} + d_{ext} + $$ + +- It then computes the signed crosstrack error $d_{xt}$ from ownship to that projected line. + The horizontal gate is: + + $$ + |d_{xt}| < \texttt{NAV\_TRAFF\_A\_HOR} + $$ + + The projected-line gate is only valid when the line solver succeeds and the ownship has not already passed the end of the projected segment. + +- Vertical separation is checked directly: + + $$ + |d_{vert}| < \texttt{NAV\_TRAFF\_A\_VER} + $$ + +- The time metric uses the current 3D separation and a conservative relative-speed assumption. + This time calculation intentionally does **not** use heading to derive closure rate. + It uses a worst-case head-on assumption and sums the ownship and traffic speed magnitudes: + + $$ + d_{xyz} = \sqrt{d_{hor}^2 + d_{vert}^2} + $$ + + $$ + v_{own} = \sqrt{v_{own,hor}^2 + v_{own,vert}^2}, \qquad + v_{traf} = \sqrt{v_{traf,hor}^2 + v_{traf,vert}^2} + $$ + + $$ + t_{est} = + \begin{cases} + \dfrac{d_{xyz}}{v_{own} + v_{traf}}, & v_{own} + v_{traf} > 0 \\ + 0, & \text{otherwise} + \end{cases} + $$ + + The time gate is only valid when the summed speed is greater than zero: + + $$ + v_{own} + v_{traf} > 0 \quad \text{and} \quad t_{est} < \texttt{NAV\_TRAFF\_COLL\_T} + $$ + +::: + +A crosstrack conflict is raised only when all three gates are true. +If the line projection is valid, `aircraft_dist_hor` publishes $d_{xt}$; otherwise it falls back to the direct horizontal range $d_{hor}$. + +#### Data Requirements + +- Valid ownship and traffic coordinates, altitude, and velocity, plus a finite traffic heading. + +#### 매개변수 + +- [NAV_TRAFF_AVOID](../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID): action requested when Crosstrack raises its single `HIGH` conflict. +- [NAV_TRAFF_A_HOR](../advanced_config/parameter_reference.md#NAV_TRAFF_A_HOR): maximum absolute crosstrack distance from the projected traffic track for the horizontal gate. +- [NAV_TRAFF_A_VER](../advanced_config/parameter_reference.md#NAV_TRAFF_A_VER): maximum absolute vertical separation for the vertical gate. +- [NAV_TRAFF_COLL_T](../advanced_config/parameter_reference.md#NAV_TRAFF_COLL_T): maximum conservative time-to-collision estimate for the time gate. + +#### Actions + +Action mapping is defined by `NAV_TRAFF_AVOID`: + +- `0`: Disabled, `1`: Warn only, `2`: Return, `3`: Land, `4`: Hold, `5`: Terminate + +### F3442 Mode + +This mode is used by firmware built with `CONFIG_NAVIGATOR_ADSB_F3442`. + +This mode uses selected alert concepts and default separation values associated with ASTM F3442/F3442M-23. + +- **NMAC** is defined as coming within 100 ft (30 m) vertically and 500 ft (153 m) horizontally from other aircraft. +- **Loss of Well Clear (LoWC)** is defined more conservatively at 250 ft (76 m) vertically and 2000 ft (610 m) horizontally from other aircraft. + +PX4 places one protective zone around the ownship and an identical zone around each detected aircraft, so the radius and height parameters below are defined _per aircraft_. +A conflict is raised when the two zones touch, which means the separation that triggers it is the **sum of both zones**. +For two identical aircraft that is simply twice the configured value, which is why the critical radius defaults to roughly half of the NMAC horizontal distance ([DAA_LVL_CRIT_RAD](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_RAD) = `77 m`, giving `2 × 77 m ≈ 153 m`). + +#### Conflict Levels + +F3442 is evaluated in four severity levels and returns the first breached level in this order: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. + +| Conflict level | Meaning in DAA | Zone | 동작 | +| -------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `CRITICAL` | Near Mid-Air Collision (NMAC) | [DAA_LVL_CRIT_RAD](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_RAD), [DAA_LVL_CRIT_HGT](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_HGT) | [DAA_LVL_CRIT_ACT](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_ACT) | +| `HIGH` | Loss of Well Clear (LoWC) | [DAA_LVL_HIGH_RAD](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_RAD), [DAA_LVL_HIGH_HGT](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_HGT) | [DAA_LVL_HIGH_ACT](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_ACT) | +| `MEDIUM` | Augmented NMAC | NMAC bounds expanded using [DAA_LVL_MED_TIME](../advanced_config/parameter_reference.md#DAA_LVL_MED_TIME) | [DAA_LVL_MED_ACT](../advanced_config/parameter_reference.md#DAA_LVL_MED_ACT) | +| `LOW` | Augmented WC | WC bounds expanded using [DAA_LVL_LOW_TIME](../advanced_config/parameter_reference.md#DAA_LVL_LOW_TIME) | [DAA_LVL_LOW_ACT](../advanced_config/parameter_reference.md#DAA_LVL_LOW_ACT) | + +The augmented `MEDIUM` and `LOW` tests enlarge each aircraft's bounds in proportion to its horizontal and vertical speed (scaled by [DAA_LVL_MED_TIME](../advanced_config/parameter_reference.md#DAA_LVL_MED_TIME) and [DAA_LVL_LOW_TIME](../advanced_config/parameter_reference.md#DAA_LVL_LOW_TIME)). +The four tests are evaluated in the priority order shown above. +Validated parameter ordering guarantees that `CRITICAL` also breaches `HIGH`, `MEDIUM`, and `LOW`; `HIGH` also breaches `LOW`; and `MEDIUM` also breaches `LOW`. +`HIGH` and `MEDIUM` are not ordered relative to each other. + +:::details +Click here to view the F3442 zone computations + +PX4 models F3442 using cylindrical horizontal and vertical bounds. +A level is breached only when both the horizontal and vertical inequalities for that level are satisfied. + +Use the following notation: + +- $d_{h}$, $d_{v}$: absolute horizontal and vertical separation between the aircraft. +- $R_{nmac}$, $H_{nmac}$: per-aircraft NMAC radius and height. +- $R_{wc}$, $H_{wc}$: per-aircraft WC radius and height. +- $t_{med}$, $t_{low}$: augmentation times for the `MEDIUM` and `LOW` levels. +- $v_{own,h}$, $v_{own,v}$: ownship absolute horizontal and vertical speed magnitudes. +- $v_{traf,h}$, $v_{traf,v}$: traffic absolute horizontal and vertical speed magnitudes. + +Parameter mapping: + +- [DAA_LVL_CRIT_RAD](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_RAD) = $R_{nmac}$ +- [DAA_LVL_CRIT_HGT](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_HGT) = $H_{nmac}$ +- [DAA_LVL_HIGH_RAD](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_RAD) = $R_{wc}$ +- [DAA_LVL_HIGH_HGT](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_HGT) = $H_{wc}$ +- [DAA_LVL_MED_TIME](../advanced_config/parameter_reference.md#DAA_LVL_MED_TIME) = $t_{med}$ +- [DAA_LVL_LOW_TIME](../advanced_config/parameter_reference.md#DAA_LVL_LOW_TIME) = $t_{low}$ + +**CRITICAL: NMAC zone** + +Per-aircraft volume: + +$$ +R = R_{nmac},\qquad H = H_{nmac} +$$ + +Combined breach condition: + +$$ +d_h \leq 2R_{nmac},\qquad d_v \leq 2H_{nmac} +$$ + +**HIGH: Loss of Well Clear (LoWC) zone** + +Per-aircraft volume: + +$$ +R = R_{wc},\qquad H = H_{wc} +$$ + +Combined breach condition: + +$$ +d_h \leq 2R_{wc},\qquad d_v \leq 2H_{wc} +$$ + +**MEDIUM: Augmented NMAC** + +Each aircraft starts with the NMAC cylinder and expands it using $t_{med}$: + +$$ +R_{own} = R_{nmac} + v_{own,h} \cdot t_{med} +$$ + +$$ +H_{own} = H_{nmac} + v_{own,v} \cdot t_{med} +$$ + +$$ +R_{traf} = R_{nmac} + v_{traf,h} \cdot t_{med} +$$ + +$$ +H_{traf} = H_{nmac} + v_{traf,v} \cdot t_{med} +$$ + +Combined breach condition: + +$$ +d_h \leq R_{own} + R_{traf} = 2R_{nmac} + (v_{own,h} + v_{traf,h}) \cdot t_{med} +$$ + +$$ +d_v \leq H_{own} + H_{traf} = 2H_{nmac} + (v_{own,v} + v_{traf,v}) \cdot t_{med} +$$ + +**LOW: Augmented WC** + +Each aircraft starts with the WC cylinder and expands it using $t_{low}$: + +$$ +R_{own} = R_{wc} + v_{own,h} \cdot t_{low} +$$ + +$$ +H_{own} = H_{wc} + v_{own,v} \cdot t_{low} +$$ + +$$ +R_{traf} = R_{wc} + v_{traf,h} \cdot t_{low} +$$ + +$$ +H_{traf} = H_{wc} + v_{traf,v} \cdot t_{low} +$$ + +Combined breach condition: + +$$ +d_h \leq R_{own} + R_{traf} = 2R_{wc} + (v_{own,h} + v_{traf,h}) \cdot t_{low} +$$ + +$$ +d_v \leq H_{own} + H_{traf} = 2H_{wc} + (v_{own,v} + v_{traf,v}) \cdot t_{low} +$$ + +PX4 validates that WC base bounds are not smaller than NMAC base bounds, both augmentation times are non-negative, and the `LOW` augmentation time is not shorter than the `MEDIUM` time. +The conflict evaluation order remains `CRITICAL`, `HIGH`, `MEDIUM`, then `LOW`. + +::: + +#### Data Requirements + +- **Mandatory:** Valid coordinates and altitude. +- **Optional:** Traffic velocity. + - If missing, F3442 is evaluated assuming zero traffic horizontal/vertical speed. + - If [DAA_EN_DFLT_VEL](../advanced_config/parameter_reference.md#DAA_EN_DFLT_VEL) is enabled, the traffic vertical speed is replaced by [DAA_DFLT_VEL](../advanced_config/parameter_reference.md#DAA_DFLT_VEL) (preserving the reported sign if known, otherwise assuming positive climb). +- **Not required:** Heading is not used. Each aircraft is wrapped in a symmetric zone, which is conservative and covers unexpected course changes. + +#### Actions + +Each level uses the action parameter listed in the table above. +If that action is `Disabled`, the policy checks only levels whose bounds are guaranteed to have been breached: + +- `CRITICAL`: `CRITICAL -> HIGH -> MEDIUM -> LOW` +- `HIGH`: `HIGH -> LOW` +- `MEDIUM`: `MEDIUM -> LOW` +- `LOW`: `LOW` + +The first action that is not `Disabled` is used. + +## Automated Actions + +The action parameter depends on the DAA model selected at build time: `NAV_TRAFF_AVOID` for Crosstrack builds and `DAA_LVL_*_ACT` for F3442 builds. + +The DAA action parameters use these values: + +- `0`: Disabled, `1`: Warn only, `2`: Return, `3`: Land, `4`: Hold, `5`: Terminate + +:::warning +The parameter values are not in severity order. +Internally, automatic-action severity is strictly ordered as: + +$$ +\texttt{Disabled} < \texttt{Warn only} < \texttt{Hold} < \texttt{Return} < \texttt{Land} < \texttt{Terminate} +$$ + +::: + +::: info + +Changing an action parameter does not immediately re-evaluate buffered conflicts. +The updated setting is considered on a later change of the overall most-urgent conflict level, and automatic mode changes are only requested when that level increases. + +::: + +#### Conflict-to-Action Mapping + +- `Crosstrack` only publishes `HIGH` conflicts, so its requested action comes directly from [NAV_TRAFF_AVOID](../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID). +- `F3442` maps each conflict level through its corresponding `DAA_LVL_*_ACT` parameter. +- In `F3442`, a disabled action falls back only to levels guaranteed to have been breached: `CRITICAL -> HIGH -> MEDIUM -> LOW`, `HIGH -> LOW`, or `MEDIUM -> LOW`. + +#### Navigator-State Equivalence + +Before sending a vehicle command, PX4 maps the current navigator state into the `DAA_ACTION` severity ladder and only triggers an automatic action when the requested action is to change to "a more severe mode" than the current navigator state: + +:::details +Click here to view the full navigator-state to DAA-action mapping + +| Current navigator state | Equivalent DAA action | Practical effect | +| ------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------- | +| `AUTO_MISSION`, `AUTO_TAKEOFF`, `AUTO_FOLLOW_TARGET`, `AUTO_VTOL_TAKEOFF`, `GUIDED_COURSE` | `DISABLED` | Any automatic DAA action may still escalate | +| `ORBIT`, `AUTO_LOITER` | `POSITION_HOLD_MODE` | Only `Return`, `Land`, or `Terminate` can escalate | +| `AUTO_RTL` | `RETURN_MODE` | Only `Land` or `Terminate` can escalate | +| `AUTO_LAND`, `DESCEND`, `AUTO_PRECLAND`, `MANUAL`, `ALTCTL`, `ALTITUDE_CRUISE`, `POSCTL`, `POSITION_SLOW`, `ACRO`, `STAB` | `LAND_MODE` | Only `Terminate` can escalate | +| `TERMINATION` | `TERMINATE` | No stronger DAA action exists | +| `OFFBOARD`, `EXTERNAL1` through `EXTERNAL8`, and unknown states | `MAX_ACTION_VALUE` | PX4 will not inject an automatic DAA mode change | + +Manual modes are intentionally treated as `LAND_MODE`. +That means DAA will not automatically switch a manually flown vehicle into Hold, Return, or Land; only `Terminate` is considered a stronger action than those modes. + +::: + +**Action behavior:** + +- DAA only triggers an automatic action when the requested action is to change to "a more severe mode" than the current navigator state. +- Warnings are evaluated separately from automatic mode changes. + A conflict configured as `Warn only` or stronger can still emit operator warnings and status messages even when DAA does not request a mode change because the current navigator state is already equivalent or more severe. +- DAA continues to publish status updates even when no automatic action is sent. +- Automatic actions are evaluated from changes in the overall most-urgent conflict level. + DAA does not retry a command while that level remains unchanged, including when a different aircraft becomes most urgent at the same level. +- Conflict de-escalation is conservative. + For example, DAA does not automatically resume the mission after a hold conflict is cleared. +- `OFFBOARD` is handled conservatively: DAA does not inject an automatic mode change there, so arming and operating procedures need to account for that. +- If the vehicle is landed, DAA warns instead of changing mode. + +## Arming, Preflight, and Ground Behavior + +The commander health check reads [`detect_and_avoid_most_urgent`](../msg_docs/DetectAndAvoidMostUrgent.md) and applies the result only while the vehicle is disarmed. + +This section covers conflict-based DAA behavior when traffic is already present. +The separate traffic-system-presence arming check is configured by [COM_ARM_TRAFF](../advanced_config/parameter_reference.md#COM_ARM_TRAFF) and described in [ADS-B/FLARM/UTM Receivers > Arming Check](../peripherals/adsb_flarm.md#arming-check). + +Preflight behavior: + +- If DAA is enabled and the most urgent conflict requires an automatic action, arming is rejected until the conflict clears. +- If the most urgent conflict is configured as `Warn only`, arming is not blocked. +- Once the vehicle is armed, commander stops emitting the prearm DAA conflict warning. + In-flight conflict handling continues through the navigator action logic and DAA status messages. + +Ground behavior: + +- If the vehicle is landed and a conflict requires an action, DAA reports a ground warning instead of changing flight mode. +- If the vehicle is disarmed, the operator is warned not to arm. +- If the vehicle is already armed on the ground, the operator is warned not to take off until the conflict is resolved. + +This is especially important for: + +- Ground operations with nearby traffic already inside an action-triggering volume. +- `OFFBOARD` use cases where arming protection may be the primary safeguard. + +## Traffic Inputs and Identification + +DAA consumes the [`transponder_report`](../msg_docs/TransponderReport.md) topic, which can be populated by ADS-B, FLARM, UTM, or another integration. +PX4 maps incoming MAVLink [`ADSB_VEHICLE`](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE) messages to this topic. +Other integrations must provide their own compatible `transponder_report` publisher. + +:::info +PX4 does not currently map incoming MAVLink [`UTM_GLOBAL_POSITION`](https://mavlink.io/en/messages/common.html#UTM_GLOBAL_POSITION) messages to `transponder_report`. +The similarly named MAVLink stream in PX4 sends ownship UTM state; it is not a traffic-input adapter. +::: + +Reports without a usable identifier are ignored before they enter the active-conflict buffer. + +DAA chooses one identifier per traffic report in this order: + +1. ICAO address +2. ADS-B callsign +3. UAS ID + +The selected identifier is published on both `detect_and_avoid` and `detect_and_avoid_most_urgent` as: + +- `unique_id`: the encoded 64-bit identifier value +- `unique_id_encoding`: `ICAO`, `ADSB_CALLSIGN`, or `UAS_ID` + +The encoding is part of the traffic key. +That means an ICAO address and a callsign can encode to the same integer and still remain separate traffic entries. +To decode a logged `unique_id` back into an ICAO address, callsign, or shortened UAS ID, see [Identifying the aircraft](#identifying-the-aircraft), which includes a Python helper. + +:::details +Click here to view how DAA accepts and encodes each identifier source + +| Identifier source | Accepted if | Stored value | +| ----------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| ICAO address | `0 < icao_address <= 0xFFFFFF` | Stored directly in the low bits of `unique_id` with `UNIQUE_ID_ENCODING_ICAO` | +| ADS-B callsign | `PX4_ADSB_FLAGS_VALID_CALLSIGN` is set and the `callsign[9]` field is null-terminated | Packs up to 8 callsign characters into a `uint64`. Byte `0` is the first character. Bytes `0-3` correspond to [ADSB_CALLSIGN_1](../advanced_config/parameter_reference.md#ADSB_CALLSIGN_1) and bytes `4-7` correspond to [ADSB_CALLSIGN_2](../advanced_config/parameter_reference.md#ADSB_CALLSIGN_2). | +| UAS ID | At least one of the final 8 bytes in `uas_id[18]` is non-zero | Packs those final 8 bytes into a `uint64` with `UNIQUE_ID_ENCODING_UAS_ID` | + +::: + +Important implications of that priority order: + +- DAA stops at the first usable identifier. + It does not compare a later callsign or UAS ID once a non-zero ICAO address has been accepted. +- Callsign self-filtering only works if the incoming report either has no ICAO address or the ICAO address is also configured as ownship. +- UAS ID self-filtering is the last fallback. + On boards that expose a PX4 UUID, DAA compares the reduced UAS ID against the reduced tail bytes of the board UUID. + +Self-filtering uses: + +- [ADSB_ICAO_ID](../advanced_config/parameter_reference.md#ADSB_ICAO_ID): primary ownship ICAO address. +- [ADSB_ICAO_ID_2](../advanced_config/parameter_reference.md#ADSB_ICAO_ID_2): optional second ownship ICAO address checked independently for self-filtering. +- [ADSB_CALLSIGN_1](../advanced_config/parameter_reference.md#ADSB_CALLSIGN_1): first 4 characters of the ownship ADS-B callsign. +- [ADSB_CALLSIGN_2](../advanced_config/parameter_reference.md#ADSB_CALLSIGN_2): last 4 characters of the same ownship ADS-B callsign. + +`ADSB_CALLSIGN_1` and `ADSB_CALLSIGN_2` together define one 8-character callsign, and both halves must match for callsign-based self-filtering. By contrast, `ADSB_ICAO_ID` and `ADSB_ICAO_ID_2` are two separate ICAO addresses that DAA checks independently. + +::: warning + +`ADSB_ICAO_ID` now defaults to `-1`, which leaves the primary self-filter unset and disables PX4-managed ADS-B Out. +Older PX4 releases defaulted this parameter to `1194684`; a vehicle that relied on that default rather than saving an explicitly assigned ICAO address will therefore stop PX4-managed ADS-B transmission after upgrading. +Configure the aircraft's assigned ICAO address and reboot before relying on ADS-B Out. + +::: + +The callsign parameters use the documented character order within each 32-bit word. +For example, `ADSB_CALLSIGN_1 = 0x50583420` (`"PX4 "`) and `ADSB_CALLSIGN_2 = 0x54455354` (`"TEST"`) identify the callsign `"PX4 TEST"`; DAA converts those words to its internal packed-ID byte order before comparing reports. + +DAA also removes conflicts that stop receiving updates after [DAA_TRAFF_TOUT](../advanced_config/parameter_reference.md#DAA_TRAFF_TOUT). + +## Key Parameters + +For the operator-facing setup flow, see [ADS-B/FLARM/UTM Receivers > Configure Traffic Avoidance](../peripherals/adsb_flarm.md#configure-traffic-avoidance). +On this page, parameters are described where their behavior matters: `NAV_TRAFF_*` in [Crosstrack Mode](#crosstrack-mode), `DAA_LVL_*`, `DAA_EN_DFLT_VEL`, and `DAA_DFLT_VEL` in [F3442 Mode](#f3442-mode), [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE) in [Operator Messages](#operator-messages), [DAA_TRAFF_TOUT](../advanced_config/parameter_reference.md#DAA_TRAFF_TOUT) in [Traffic Inputs and Identification](#traffic-inputs-and-identification), and ownship ADS-B identification parameters in the same traffic-input section. +F3442-specific parameters are only present in firmware built with `CONFIG_NAVIGATOR_ADSB_F3442`. + +## Telemetry and Logging + +The main DAA topics are: + +- [`detect_and_avoid`](../msg_docs/DetectAndAvoid.md): per-traffic assessments for reports that create, update, or clear a tracked conflict. + First-seen reports evaluated at conflict level `NONE` are omitted. +- [`detect_and_avoid_most_urgent`](../msg_docs/DetectAndAvoidMostUrgent.md): the current most urgent active conflict. +- [`transponder_report`](../msg_docs/TransponderReport.md): raw traffic input to DAA. + +`detect_and_avoid` and `detect_and_avoid_most_urgent` are logged by default. + +These topics are useful for: + +- Flight review +- Integration testing +- Preflight debugging +- Verifying conflict escalation and action selection + +## Operator Messages + +DAA talks to the operator on two channels at the same time: + +- **MAVLink STATUSTEXT** is the short, human-readable line such as `DAA Main: 6E9F7B lvl UP 3. 199 m.`. + PX4 emits these as [`mavlink_log`](../msg_docs/MavlinkLog.md) records, and the MAVLink module forwards them on its `STATUSTEXT` stream as MAVLink [`STATUSTEXT`](https://mavlink.io/en/messages/common.html#STATUSTEXT) messages to connected ground stations. + The identifier is already decoded into a readable string here, so this is the easiest channel to read while flying. +- **PX4 Events** carry the same information through the [Events Interface](../concept/events_interface.md), but as structured data: a fixed event ID plus numeric arguments (identifier, conflict level, distance, cause, notification kind). + +For levels configured as `Warn only` or stronger, messages are emitted after the queue-processing cycle when a conflict level changes. +The most urgent conflict is also reported periodically (the period is [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE)). + +### Reading the message fields + +Every conflict message refers to one traffic aircraft and reuses the same handful of fields. + +:::details +Click here to view the fields used in events + +#### ``: the traffic identifier + +DAA tracks each aircraft by the identifier selected in [Traffic Inputs and Identification](#traffic-inputs-and-identification). +The two channels show that identifier differently: + +- In **STATUSTEXT** it is already decoded to a readable string: a 6-character ICAO hex such as `6E9F7B`, an up-to-8-character callsign such as `LX00777A`, or a shortened UAS-ID hex such as `eaebecedee`. +- In **events** it is the raw 64-bit integer (`unique_id`) that DAA stores internally. + The same integer, together with its `unique_id_encoding`, is also published on the [`detect_and_avoid`](../msg_docs/DetectAndAvoid.md) and [`detect_and_avoid_most_urgent`](../msg_docs/DetectAndAvoidMostUrgent.md) topics. + +To turn that integer back into a readable identifier (for example an ICAO address) you need the encoding and the matching decode rule. +A worked example with code is in [Identifying the aircraft](#identifying-the-aircraft). + +#### ``: the conflict level + +The level is the same integer used on the uORB topics: + +| `` | 단계 | F3442 meaning | +| ----- | ---------- | ---------------------- | +| `0` | `NONE` | no conflict or cleared | +| `1` | `LOW` | augmented Well Clear | +| `2` | `MEDIUM` | augmented NMAC | +| `3` | `HIGH` | Loss of Well Clear | +| `4` | `CRITICAL` | NMAC | + +Crosstrack builds only ever publish `HIGH` (`3`). +See [Conflict Levels](#conflict-levels) for the full F3442 definitions. +In the main and secondary messages, the words `UP` and `DOWN` tell you whether the level just increased or decreased. + +#### ``: distance to the traffic + +The straight-line 3D range to that aircraft in meters, computed from the horizontal and vertical separation ($\sqrt{d_{hor}^2 + d_{vert}^2}$). + +#### Notification kind (events only) + +The `navigator_traffic_conflict_update` event carries a _notification kind_ argument that says which conflict the update is about. +It matches the prefix used in the STATUSTEXT line: + +| Notification kind | STATUSTEXT prefix | 설명 | +| ----------------- | ------------------- | ----------------------------------------------------------------------------------------- | +| `0` | `DAA Main:` | update for the conflict that is already the most urgent | +| `1` | `DAA New and Main:` | a conflict that appeared this cycle and is also now the most urgent | +| `2` | `DAA SEC:` | a secondary (non-primary) tracked conflict that is not the most urgent | + +#### Action code (events only) + +The `navigator_traffic_action` event reports which automatic response was triggered, using the same numbering as the `NAV_TRAFF_AVOID` / `DAA_LVL_*_ACT` parameters: + +| Action code | 동작 | +| ----------- | ----------- | +| `2` | `Return` | +| `3` | `Land` | +| `4` | `Hold` | +| `5` | `Terminate` | + +`0` (`Disabled`) and `1` (`Warn only`) do not generate an action event because no automatic action is requested. +See [Automated Actions](#automated-actions) for the full action parameter convention. + +::: + +:::details +Click here to view the message families and notification timing + +- **New conflict:** `DAA New lvl . m.`: emitted after the current `check_traffic()` queue drain completes when a new warning-level conflict remains in the active buffer but is not the current most urgent conflict. +- **Main conflict:** + - `DAA Main: lvl UP . m.`: emitted immediately when the most urgent conflict level increases. + - `DAA Main: lvl DOWN . m.`: emitted immediately when the most urgent conflict level decreases but remains active. + - `DAA Main: lvl . m.`: periodic message for the current most urgent conflict when its level stays unchanged. + The message period is [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE); setting it to `0` disables this periodic message. +- **New and Main conflict:** `DAA New and Main: lvl . m.`, `DAA New and Main: lvl UP . m.`, `DAA New and Main: lvl DOWN . m.`: emitted after the current `check_traffic()` queue drain completes when a new warning-level conflict is also the current most urgent conflict. +- **Secondary conflicts:** `DAA SEC: lvl UP . m.`, `DAA SEC: lvl DOWN . m.`, `DAA SEC: solved. m.`: emitted immediately for non-primary traffic whose level changes while another conflict remains most urgent. +- **Buffer handling:** + - `DAA out () lvl (s).`: emitted immediately when a previously buffered conflict is removed because it became stale or because it was evicted to make room for a more urgent conflict. + New conflicts that are inserted and then displaced within the same queue drain before any `DAA New` notification are intentionally silent. + The cause is mapped to: + - STALE_CONFLICT = 0, + - BUFFER_FULL = 1 + - `DAA ignored () lvl .`: emitted when traffic could not be inserted or updated. + This warning is rate-limited to once every `2 s`. + The cause can be: + - BUFFER_FULL = 0 +- **Actions:** `DAA : Hold!`, `Return!`, `Land!`, `Terminate!`, and the on-ground `DAA do not arm until air conflict solved!` / `DAA do not takeoff until air conflict solved!` warnings only appear when a conflict level is configured with an automatic action stronger than `Warn only`. The default DAA parameters are warn-only so by default these action messages are not emitted. +- **No more conflicts:** `DAA all conflicts solved.`: emitted immediately when the most urgent conflict clears and no warning-level conflicts remain. + +The shared fields ``, ``, and ``, plus the cause numbers above, are explained in [Reading the message fields](#reading-the-message-fields). +To turn a logged or event identifier back into an ICAO address, callsign, or UAS ID, see [Analysing a Conflict Using the Logs](#analysing-a-conflict-using-the-logs). + +::: + +## Analysing a Conflict Using the Logs + +After a flight you can reconstruct exactly what DAA saw and did from the default log. +This is the recommended way to investigate a conflict, because the logged topics carry the full identifier, encoding, geometry, and timing that the short operator messages only summarize. + +### What to look at + +- [`detect_and_avoid_most_urgent`](../msg_docs/DetectAndAvoidMostUrgent.md): the single conflict that drove the DAA status and any automatic action or prearm block. + Start here to find the worst moment of the encounter (highest `conflict_level`, smallest `aircraft_dist`) and whether `has_action` was set. +- [`detect_and_avoid`](../msg_docs/DetectAndAvoid.md): samples for traffic that creates, updates, or clears a tracked conflict, with the per-aircraft `conflict_level` and the horizontal, vertical, and time geometry. + Use it to follow one specific aircraft over time. +- [`transponder_report`](../msg_docs/TransponderReport.md): the raw input. + Match it by timestamp to see the traffic's reported position, altitude, velocity, heading, and validity flags, plus the original `icao_address`, `callsign`, and `uas_id` fields before encoding. +- Navigator state and commander messages: confirm whether a requested action actually changed the flight mode. + +You can open the log in [Flight Review](../log/flight_review.md) or plot these topics directly. +Live, the same topics can be inspected from the shell with `listener detect_and_avoid` and `listener detect_and_avoid_most_urgent`. + +### Identifying the aircraft + +Both DAA topics publish `unique_id` (the 64-bit integer) and `unique_id_encoding` (the type of ID). +Decode the integer according to the encoding: + +| `unique_id_encoding` | Source | How to decode | +| ---------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------- | +| `0` (`ICAO`) | ICAO 24-bit address | low 24 bits formatted as 6 uppercase hex digits | +| `1` (`ADSB_CALLSIGN`) | ADS-B callsign | bytes little-endian, byte `0` is the first character, stop at first `\0` | +| `2` (`UAS_ID`) | shortened UAS ID | low bytes as hex; the displayed string uses the low 5 bytes (10 hex chars) | + +The selection and storage rules behind this table are described in [Traffic Inputs and Identification](#traffic-inputs-and-identification). + +:::details +Click here to view a Python script example on how to decode `unique_id` (the 64-bit integer) +The following helper applies the same conversion DAA uses to build the STATUSTEXT string, so its output matches what you saw live: + +```python +import argparse + +def decode_daa_id(unique_id: int, encoding: int) -> str: + if encoding == 0: # ICAO + return f"{unique_id & 0xFFFFFF:06X}" + if encoding == 1: # ADS-B callsign + out = bytearray() + for i in range(8): + byte = (unique_id >> (8 * i)) & 0xFF + if byte == 0: + break + out.append(byte) + return out.decode("ascii", "replace") + if encoding == 2: # UAS ID (shortened, low 5 bytes shown) + return "".join(f"{(unique_id >> (8 * i)) & 0xFF:02x}" for i in range(5)) + return "unknown" + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description="Decode a DAA ID based on its encoding type.") + + parser.add_argument("unique_id", type=int, help="The 64-bit unique ID") + parser.add_argument( + "encoding", + type=int, + choices=[0, 1, 2], + help="Encoding type: 0 (ICAO), 1 (ADS-B), or 2 (UAS ID)", + ) + + args = parser.parse_args() + + print(decode_daa_id(args.unique_id, args.encoding)) +``` + +Example 1: Decoding an ICAO address (encoding `0`): the integer `7249787` decodes to the 6-character hex ICAO address `6E9F7B`. + +```bash +python3 decode_daa.py 7249787 0 +``` + +Example 2: Decoding an ADS-B callsign (encoding `1`): the integer `827736405` is the packed ASCII representation of the callsign `UAV1`. + +```bash +python3 decode_daa.py 827736405 1 +``` + +Example 3: Decoding a UAS ID (encoding `2`): the integer `737869762868` is unpacked into the shortened 10-character hex string `341177ccab`. + +```bash +python3 decode_daa.py 737869762868 2 +``` + +::: + +### Turning an ICAO address into a real aircraft + +When the encoding is `ICAO`, the decoded 6-digit hex (for example `6E9F7B`) is the 24-bit address reported over ADS-B or Mode S. +When the address has been assigned and transmitted correctly, an aircraft registry may map it to a tail number, type, or operator. + +This is how you confirm whether the intruder was, for instance, a helicopter, a general-aviation aircraft, or even your own second transponder. +If it turns out to be ownship, update the self-filtering parameters described in [Traffic Inputs and Identification](#traffic-inputs-and-identification). + +### 요약 + +A typical investigation: + +1. In `detect_and_avoid_most_urgent`, find when `conflict_level` peaked and `aircraft_dist` was smallest, and note `unique_id` and `unique_id_encoding`. +2. Decode the identifier; if it is an ICAO address, look up the aircraft. +3. In `detect_and_avoid`, follow that identifier to see how the horizontal, vertical, and time separation evolved and how the level escalated. +4. Cross-check `transponder_report` at the same timestamps for the raw geometry and validity flags. + Missing velocity or heading changes how the model evaluates the conflict (see the data requirements for [F3442 Mode](#f3442-mode) or [Crosstrack Mode](#crosstrack-mode)). +5. Confirm in the navigator and commander messages whether the configured action ran and whether the resulting mode change matched expectations. + +## Testing and Simulation + +Synthetic traffic generation is available when the firmware is built with `CONFIG_NAVIGATOR_ADSB_FAKE_TRAFFIC`. +This option is intended for simulation and dedicated test images; it should not be enabled in production flight firmware. + +Use the navigator shell command: + +```sh +navigator fake_traffic +``` + +Available modes: + +- `unique_ids`, `escalation`, `spam_same`, `spam_new`, `flags`, `queue_fill` + +Example: + +```sh +navigator fake_traffic escalation +``` + +Use `navigator fake_traffic help` for the short mode list and `navigator fake_traffic stop` to cancel a pending scripted run. + +:::warning +`navigator fake_traffic` injects traffic into the normal DAA pipeline. +If the configured action for the triggered conflict level is `Hold`, `Return`, `Land`, or `Terminate`, PX4 can request that action exactly as it would for real traffic. +::: + +Run these scenarios with a valid vehicle position, because the synthetic reports are generated around the current ownship latitude, longitude, and altitude. + +The command schedules a deterministic synthetic traffic sequence and returns immediately. +DAA then publishes the scripted `transponder_report` samples from its normal update loop around the current ownship latitude, longitude, and altitude. + +:::details +Click here for more details on each fake traffic scenario + +Scenario guide: + +- `unique_ids`: Publishes three isolated four-step approach sequences: about `1500 m`, `800 m`, `200 m`, then `5000 m` to clear the conflict. + The first traffic uses a valid ICAO address, the second removes ICAO so DAA must fall back to the ADS-B callsign, and the third removes ICAO plus a valid callsign so DAA must fall back to UAS ID. + Use this to verify identifier priority without overlap between the three identifier cases. +- `escalation`: Publishes one aircraft every `2 s` while its range decreases from about `3000 m` to `100 m`. + Use this to watch conflict levels rise, confirm when the most urgent conflict level changes, and verify that the configured action thresholds trigger at the expected ranges. +- `spam_same`: Publishes the same aircraft `40` times at `10 Hz` while keeping it at about `200 m`. + Use this to confirm that repeated updates from one target are not generating excessive notifications (expect a period of [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE)). +- `spam_new`: Publishes `10` different ICAO identities, one per second, with fixed distances chosen to fill the `5`-entry conflict buffer, evict the least urgent items deterministically, and exercise ignored-traffic throttling once the buffer is full. +- `flags`: Publishes one aircraft with valid position, altitude, heading, and callsign, but with the velocity-valid flag intentionally cleared. + In F3442 builds the report is still accepted because only coordinates and altitude are mandatory; the missing traffic velocity is treated as zero, and if [DAA_EN_DFLT_VEL](../advanced_config/parameter_reference.md#DAA_EN_DFLT_VEL) is enabled the vertical speed is replaced by [DAA_DFLT_VEL](../advanced_config/parameter_reference.md#DAA_DFLT_VEL). + In Crosstrack builds the same report is rejected because velocity is required there. +- `queue_fill`: Runs three consecutive batches of `ORB_QUEUE_LENGTH` reports. + Batch 1 repeats the same close critical aircraft for the full queue length. + Batch 2 publishes new lower-priority conflicts that get progressively closer so each one is accepted while the original aircraft remains the most urgent. + Batch 3 starts even closer and then gets farther away so only the first `4` entries replace the existing lower-priority traffic and the rest are ignored. + Use this to confirm DAA drains one full queued `transponder_report` burst per `check_traffic()` call and preserves the correct final priority order after each batch. + +::: + +What to watch while running a scenario: + +- [`detect_and_avoid`](../msg_docs/DetectAndAvoid.md): per-traffic output for tracker-accepted reports that create, update, or clear a conflict. +- [`detect_and_avoid_most_urgent`](../msg_docs/DetectAndAvoidMostUrgent.md): the single conflict that currently drives the main DAA status and any automatic action decision. +- [`mavlink_log`](../msg_docs/MavlinkLog.md), MAVLink `STATUSTEXT`, and PX4 Events: new conflict, escalation, reduction, ignored traffic, and stale or evicted traffic messages. + +Useful shell commands: + +```sh +listener detect_and_avoid +listener detect_and_avoid_most_urgent +``` + +### Expected Behavior + +Exact distances and message text depend on the selected parameters and vehicle state. With the default warn-only F3442 actions: + +| Scenario | Expected behavior | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| `unique_ids` | Three otherwise similar encounters are tracked by ICAO address, callsign, and UAS ID respectively. | +| `escalation` | One aircraft progresses through increasing conflict levels, then becomes stale and is removed. | +| `spam_same` | Repeated reports refresh one tracked conflict without producing a message for every sample. | +| `spam_new` | Multiple aircraft fill the conflict buffer; less urgent reports are evicted or ignored according to buffer priority. | +| `flags` | F3442 accepts missing traffic velocity and applies its configured defaults; Crosstrack rejects the report. | +| `queue_fill` | DAA drains a full queued burst and retains the highest-priority conflicts. | + +Use the uORB topics and operator messages above to verify the result. Automated-action testing should use a controlled simulation environment. + +The sequences below assume the default F3442 configuration. + +:::details +Click here to view default configuration + +- Firmware built with `CONFIG_NAVIGATOR_ADSB_F3442` +- [DAA_LVL_LOW_ACT](../advanced_config/parameter_reference.md#DAA_LVL_LOW_ACT) = `Warn only` +- [DAA_LVL_MED_ACT](../advanced_config/parameter_reference.md#DAA_LVL_MED_ACT) = `Warn only` +- [DAA_LVL_HIGH_ACT](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_ACT) = `Warn only` +- [DAA_LVL_CRIT_ACT](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_ACT) = `Warn only` +- [DAA_EN_DFLT_VEL](../advanced_config/parameter_reference.md#DAA_EN_DFLT_VEL) = `1` +- [DAA_DFLT_VEL](../advanced_config/parameter_reference.md#DAA_DFLT_VEL) = `10 m/s` +- Ownship horizontal and vertical speed = `0` +- Ownship and traffic altitude are equal + +::: + +Under those assumptions, the expected operator-visible messages for each scenario are: + +**`unique_ids`**: four-step process repeated for the three unique identifier cases. + +:::details +Click here to view the expected results + +- ICAO case `6E9F7B`: + - Step 1: `DAA New and Main: 6E9F7B lvl UP 2. 1499 m.` + - Step 2: `6E9F7B` at 800 m stays at the same conflict level (2), so it does not emit another `DAA Main` line before [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE) expires. + - Step 3: `DAA Main: 6E9F7B lvl UP 3. 199 m.` + - Step 4: move conflict 5000m away and expect: `DAA all conflicts solved.` +- Callsign case `LX00777A`: the same level sequence as above, but with `LX00777A` as the identifier. +- UAS ID fallback case: the same level sequence as above, but with the shortened board-dependent UAS ID string as the identifier e.g., `eaebecedee`. + +::: + +**`escalation`**: thirty-step conflict with a single incoming aircraft flying towards the UAV. + +:::details +Click here to view the expected results + +- Example with default warn-only parameters: + - No DAA warning is expected from `3000 m` down to about `2300 m`. + - At about `2200 m`: `DAA New and Main: 9F3FA3 lvl UP 1. 2200 m.` + - At about `1800 m`: `DAA Main: 9F3FA3 lvl UP 2. 1800 m.` + - At about `600 m`: `DAA Main: 9F3FA3 lvl UP 3. 600 m.` + - At about `100 m`: `DAA Main: 9F3FA3 lvl UP 4. 100 m.` + - After approximately [DAA_TRAFF_TOUT](../advanced_config/parameter_reference.md#DAA_TRAFF_TOUT): `DAA 9F3FA3 out (0) lvl 4 (s).` followed by `DAA all conflicts solved.` + - No `DAA SEC` or automatic-action messages are expected with the default warn-only parameters. +- Example with actions defined as Hold, Return, Land, and Terminate: `DAA: Actions lvl: low: 4, med: 2, high: 3, crit: 5`: + - `DAA New and Main: 9F3FA3 lvl UP 1. 2366 m.` + - Hold triggered on augmented WC breach: `DAA 9F3FA3: Hold! lvl 1. 2366 m.` + - `DAA Main: 9F3FA3 lvl UP 2. 1773 m.` + - Return triggered on augmented NMAC breach: `DAA 9F3FA3: Return! lvl 2. 1773 m.` + - `[commander] Returning to launch` + - `[navigator] RTL: start return at 519 m (30 m above destination)` + - `DAA Main: 9F3FA3 lvl 2. 849 m.` (the periodic most-urgent status, emitted because the level held at 2 for [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE) since the previous `9F3FA3` message) + - `DAA Main: 9F3FA3 lvl UP 3. 527 m.` + - Land triggered on WC breach: `DAA 9F3FA3: Land! lvl 3. 527 m.` + - `[commander] Landing at current position` + - `DAA Main: 9F3FA3 lvl UP 4. 124 m.` + - Terminate triggered on NMAC breach: `DAA 9F3FA3: Terminate! lvl 4. 124 m.` + - `[failsafe] Failsafe activated` + +::: + +**`spam_same`**: forty-step conflict with an aircraft spamming transponder reports from the same location. + +:::details +Click here to view the expected results + +- First sample only: `DAA New and Main: 61F77C lvl UP 3. 199 m.` +- The remaining `39` updates refresh the same conflict entry but do not emit extra status lines because the level does not change and the whole scenario finishes before [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE) elapses. Eventually the traffic becomes stale at approximately [DAA_TRAFF_TOUT](../advanced_config/parameter_reference.md#DAA_TRAFF_TOUT), followed by `DAA all conflicts solved.`. + +::: + +**`queue_fill`**: three-cycle queue-drain burst. + +:::details +Click here to view the expected results + +- **Step 1:** the first queue is filled with the same aircraft, expect a single message: `DAA New and Main: DDF0A1 lvl UP 4. 100 m.` +- **Step 2:** the second queue is filled with different aircraft getting closer and closer. DAA drains the full queue before it emits `DAA New` lines, so only the four entries that survive the batch are reported: + - `DAA New 51000D lvl 2. 680 m.`, `DAA New 51000E lvl 2. 670 m.`, `DAA New 51000F lvl 2. 660 m.`, `DAA New 510010 lvl 2. 650 m.` + - Earlier step-2 candidates `510001` through `51000C` are accepted provisionally and then replaced within the same drain, so they do not emit `out` or `ignored` operator messages. +- **Step 3:** the third queue is filled with different aircraft getting farther and farther. The first four entries are still more important than the surviving step-2 traffic, so expect: + - `DAA New 520001 lvl 3. 569 m.`, `DAA New 520002 lvl 3. 589 m.`, `DAA New 520003 lvl 3. 609 m.`, `DAA New 520004 lvl 2. 629 m.` + - Because those four replace already-known step-2 conflicts from the previous cycle, expect removals: `DAA 51000D out (1) lvl 2 (2s).`, `DAA 51000E out (1) lvl 2 (2s).`, `DAA 51000F out (1) lvl 2 (2s).`, `DAA 510010 out (1) lvl 2 (2s).` + - The remaining step-3 traffic is less important than the buffer contents, so it is ignored. Because ignored notifications are throttled, the first operator-visible message is typically `DAA 520005 ignored (0) lvl 2.` + +::: + +**`spam_new`**: ten-step multi-aircraft conflict that fills the buffer. + +:::details +Click here to view the expected results + +| Step | ICAO | Nominal range | Expected result | +| ---- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `380E97` | `1200 m` | `DAA New and Main: 380E97 lvl UP 1. 1200 m.` | +| 2 | `67F621` | `900 m` | `DAA New and Main: 67F621 lvl 1. 899 m.` | +| 3 | `ACDE77` | `700 m` | `DAA New and Main: ACDE77 lvl UP 2. 700 m.` | +| 4 | `45F276` | `500 m` | `DAA New and Main: 45F276 lvl UP 3. 500 m.` | +| 5 | `34990F` | `100 m` | `DAA New and Main: 34990F lvl UP 4. 100 m.` The buffer is now full. | +| 6 | `EB61D8` | `130 m` | New entry on a full buffer, least urgent conflict is removed first for cause: BUFFER_FULL: `DAA 380E97 out (1) lvl 1 (5s).` and then we add the new traffic: `DAA New EB61D8 lvl 4. 130 m.` | +| 7 | `A1EAB2` | `550 m` | New entry on a full buffer, least urgent conflict is removed first for cause: BUFFER_FULL: `DAA 67F621 out (1) lvl 1 (5s).` then `DAA New A1EAB2 lvl 3. 550 m.` | +| 8 | `C5ED22` | `1100 m` | `DAA C5ED22 ignored (0) lvl 1.` ignored for cause BUFFER_FULL and all other conflicts are more important. | +| 9 | `B2F854` | `750 m` | No new operator message is expected, because the traffic is ignored again while ignored-traffic warnings are still inside the `2 s` rate limit | +| 10 | `E16498` | `140 m` | New entry on a full buffer, least urgent conflict is removed first for cause: BUFFER_FULL: `DAA ACDE77 out (1) lvl 2 (7s).` then `DAA New E16498 lvl 4. 140 m.` and `DAA Main: 34990F lvl 4. 100 m.` | + +Notes: + +- The main conflict `DAA Main: 34990F lvl 4. 100 m.` appears periodically during the scenario at the rate of [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE). +- After the last step, all conflicts are eventually marked as stale and resolved: + - `DAA 34990F out (0) lvl 4 (20s).` + - `DAA 45F276 out (0) lvl 3 (21s).` + - `DAA A1EAB2 out (0) lvl 3 (20s).` + - `DAA EB61D8 out (0) lvl 4 (21s).` + - `DAA E16498 out (0) lvl 4 (21s).` + - `DAA all conflicts solved.` + +::: + +**`flags`**: one aircraft with the velocity-valid flag intentionally cleared. + +:::details +Click here to view the expected results + +- In `F3442`: `DAA New and Main: L07NOVEL lvl UP 4. 100 m.` followed by the periodic notification: `DAA Main: L07NOVEL lvl 4. 100 m.` and finally: `DAA L07NOVEL out (0) lvl 4 (20s).` and `DAA all conflicts solved.`. +- In `Crosstrack`: no DAA conflict message is expected, because the same report is rejected when the velocity-valid flag is missing. + +::: + +## Current Limitations + +- DAA handles cooperative traffic only. +- DAA does not generate lateral or vertical avoidance trajectories. +- DAA selects high-level navigator actions; it does not solve conflict geometry beyond the selected conflict model. +- Conflict handling is bounded by a fixed-size active-conflict buffer. +- Action selection and the commander arming check are driven by the single geometrically most urgent conflict. + A lower-priority buffered conflict does not independently drive an action or arming block, even if its configured action is stronger. +- DAA compares ownship altitude directly with `transponder_report.altitude` and does not use `altitude_type` to normalize pressure and geometric altitude references. + A datum mismatch can therefore bias vertical separation. +- DAA quality depends on the quality and freshness of both traffic data and vehicle state. + +## Implementation Structure + +The implementation is split between a shared PX4 library and the navigator integration: + +- `src/lib/adsb`: the DAA core, with no navigator dependency; uORB message structs and enums are only used for data types. + It contains the conflict standards (`DaaCrosstrack`, `DaaF3442`, wrapped by `AdsbConflict`), the traffic identifier encoding and self-detection (`DaaEncodedId`), the active-conflict buffer (`ConflictTracker`), and the action policy (`DaaActionPolicy`). + `ConflictTracker` owns the fixed-size conflict buffer and the priority rules: it inserts, updates, and evicts conflicts, caches the most urgent one, and reports every change that may require a user-facing message as a change record (`conflict_tracker_change_s`), without sending any notification itself. + `DaaActionPolicy` is a stateless decision function: given the most-urgent level transition, the navigation state, the landed/armed state, and the action parameter values, it returns which vehicle command to request and which action or ground message to send. It implements the level-to-action mapping (including the F3442 per-level action fallback described in [Automated Actions](#automated-actions)) and the navigator-state escalation gate. +- `src/modules/navigator/DetectAndAvoid`: the navigator integration. + It validates and identifies incoming `transponder_report` data, runs the built standard, feeds the result to the tracker, publishes the DAA topics, and executes the policy's action decisions (vehicle commands and action messages). + All operator messaging is concentrated in one class, `ConflictNotifier`: it turns the change records collected over one cycle into the messages described in [Operator Messages](#operator-messages) in a single per-cycle call (`report_cycle()`), and also owns the message formatting, severity mapping, and rate-limit timers used by the action and ground warnings. + +## Adding a New Standard + +At the library level, a DAA standard is a class that consumes one ownship state plus one traffic state and returns both a conflict level and reporting metrics. + +:::details +Click here to view an in depth guide on how to add a new standard + +```cpp +class DaaNewStandard : public ModuleParams +{ +public: + DaaNewStandard(); + + uint8_t calculate_daa_stats(const aircraft_state_s &uav_state, + const aircraft_state_s &traffic_state, + daa_stats_s &daa_stats); + + bool try_setting_params(); +}; +``` + +The shared input and output are: + +- `aircraft_state_s` input fields: + - `lat_lon`: ownship or traffic latitude/longitude in degrees. + - `altitude`: ownship or traffic altitude in meters. + - `velocity_ned`: velocity in meters per second in north-east-down frame. + In the wrapper path, traffic without a finite heading is converted to a due-north horizontal vector `(hor_speed, 0, -ver_speed_up)` so heading-agnostic standards can still use speed magnitude. + A new standard that depends on the actual traffic track direction must reject missing heading explicitly. + - `heading`: course-over-ground or track heading in radians. + A standard may ignore this field, but a standard that builds projected-track geometry must require it to be finite. +- `daa_stats_s` output fields: + - `aircraft_dist_hor`: the standard's reported horizontal-separation metric in meters. + This may be direct range, signed crosstrack distance, or another horizontal metric defined by the standard. + - `aircraft_dist_vert`: the standard's reported vertical-separation metric in meters. + - `expected_min_dist_time_sec`: the standard's reported conservative time metric in seconds. + This may be a worst-case closure-time estimate or another minimum-distance timing metric defined by the standard. +- Return value: + - one of `detect_and_avoid_s::DAA_CONFLICT_LVL_NONE`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL` + +To add a new standard end-to-end: + +1. Implement a new class with `calculate_daa_stats()` and define its runtime parameter validation. +2. Decide which `aircraft_state_s` fields are mandatory for that standard and enforce those requirements in the wrapper path (`AdsbConflict::calculate_daa_output()`) and inside the standard itself if it can be called directly. + In particular, decide whether the due-north fallback for `velocity_ned` without traffic heading is acceptable, or whether the standard requires the true traffic track direction. +3. Add a build-time config and CMake selection for the standard, including any standard-specific parameter metadata only when that config is enabled. +4. Add the class to `AdsbConflict` and update the compile-time branches that validate inputs, run `calculate_daa_stats()`, and refresh parameters. +5. Add unit tests for both the standard math and the outer `AdsbConflict` validation path, then update this documentation with the standard-specific data requirements, parameters, and action semantics. + +::: diff --git a/docs/ko/advanced_features/index.md b/docs/ko/advanced_features/index.md index c18214ee02..30c6c118d9 100644 --- a/docs/ko/advanced_features/index.md +++ b/docs/ko/advanced_features/index.md @@ -3,6 +3,7 @@ PX4 자동비행 프로그램의 고급 기능에 대하여 설명합니다. - [Air Traffic Avoidance: ADS-B/FLARM/UTM](../peripherals/adsb_flarm.md) +- [Detect And Avoid](../advanced_features/detect_and_avoid.md) - [Computer Vision](../computer_vision/index.md) - [Collision Prevention](../computer_vision/collision_prevention.md) - [Motion Capture (MoCap)](../computer_vision/motion_capture.md) diff --git a/docs/ko/config/safety.md b/docs/ko/config/safety.md index 7b41f3f2d3..82e1f959ad 100644 --- a/docs/ko/config/safety.md +++ b/docs/ko/config/safety.md @@ -276,13 +276,22 @@ The _Offboard Loss Failsafe_ is triggered if the offboard link is lost while und ## 교통 회피 안전 장치 -The Traffic Avoidance Failsafe allows PX4 to respond to transponder data (e.g. from [ADSB transponders](../advanced_features/traffic_avoidance_adsb.md)) during missions. +The Traffic Avoidance Failsafe allows PX4 to respond to [cooperative traffic reports](../peripherals/adsb_flarm.md). +The action parameters depend on the conflict model selected when the firmware is built. 관련된 매개 변수는 다음과 같습니다. -| Parameter | 설명 | -| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| [NAV_TRAFF_AVOID](../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID) | 비상 안전 장치를 설정합니다 : 비활성화, 경고, 귀환 모드, 착륙 모드. | +| Parameter | 설명 | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| [DAA_EN](../advanced_config/parameter_reference.md#DAA_EN) | Enables or disables Detect and Avoid. | +| [NAV_TRAFF_AVOID](../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID) | Action for the Crosstrack model. | +| [DAA_LVL_LOW_ACT](../advanced_config/parameter_reference.md#DAA_LVL_LOW_ACT) | F3442-mode action for a `LOW` conflict. | +| [DAA_LVL_MED_ACT](../advanced_config/parameter_reference.md#DAA_LVL_MED_ACT) | F3442-mode action for a `MEDIUM` conflict. | +| [DAA_LVL_HIGH_ACT](../advanced_config/parameter_reference.md#DAA_LVL_HIGH_ACT) | F3442-mode action for a `HIGH` conflict. | +| [DAA_LVL_CRIT_ACT](../advanced_config/parameter_reference.md#DAA_LVL_CRIT_ACT) | F3442-mode action for a `CRITICAL` conflict. | + +All action parameters use `Disabled`, `Warn only`, `Return mode`, `Land mode`, `Position Hold mode`, and `Terminate`. +See [Detect and Avoid](../advanced_features/detect_and_avoid.md) for conflict-model and action-transition details. ## Remote ID Failsafe diff --git a/docs/ko/debug/failure_injection.md b/docs/ko/debug/failure_injection.md index 15716e1e57..da02b50c0b 100644 --- a/docs/ko/debug/failure_injection.md +++ b/docs/ko/debug/failure_injection.md @@ -5,7 +5,7 @@ This enables easier testing of [safety failsafe](../config/safety.md) behaviour, Failure injection is disabled by default, and can be enabled using the [SYS_FAILURE_EN](../advanced_config/parameter_reference.md#SYS_FAILURE_EN) parameter. -Failure injection must also be be supported by the current simulator, and the set of supported failures is simulator-dependent. +Failures can be injected both in simulation and on real hardware. In simulation the available failures depend on the simulator. On hardware the `off` (stop publishing) and `stuck` (freeze the last value) types are supported for the `gyro`, `accel`, `mag`, `baro`, `distance_sensor` and `gps` components; this requires firmware built with the failure-injection module. In addition, the `battery` component supports `off` (report a depleted pack, triggering the battery failsafe). :::info PX4 may accept a command to set a particular failure mode even it that mode is not supported by your simulator. @@ -24,7 +24,7 @@ Failures can be injected using the [failure system command](../modules/modules_c The full syntax of the [failure](../modules/modules_command.md#failure) command is: ```sh -failure [-i ] +failure [-i ] [-m ] ``` 여기서: @@ -58,11 +58,23 @@ failure [-i ] - `intermittent`: Publish intermittently - _instance number_ (optional): Instance number of affected sensor. 0 (기본값) 지정된 유형의 모든 센서를 나타냅니다. +- _instance bitmask_ (optional): address several instances at once (bit 0 = first instance, bit 1 = second, …; decimal or `0x` hex). Used only when `-i` is omitted. Example: `-m 0x5` targets instances 1 and 3. :::info The simulated GPS (SITL) implements only the `off`, `stuck`, and `wrong` failure modes; the other failure types have no effect on it. ::: +## RC Switch Trigger + +A failure can also be injected from an RC switch, without a console or telemetry link. This is useful for in-flight hardware testing. It is configured with the following parameters: + +- [SYS_FAIL_RC_SRC](../advanced_config/parameter_reference.md#SYS_FAIL_RC_SRC): the auxiliary RC input that triggers the failure — `0` disables it, `1`–`6` select AUX1–AUX6 (mapped via `RC_MAP_AUXn`). +- [SYS_FAIL_RC_UNIT](../advanced_config/parameter_reference.md#SYS_FAIL_RC_UNIT): the affected component (the `FAILURE_UNIT` value; e.g. `101` = motor). +- [SYS_FAIL_RC_MODE](../advanced_config/parameter_reference.md#SYS_FAIL_RC_MODE): the failure type (the `FAILURE_TYPE` value; e.g. `1` = off). +- [SYS_FAIL_RC_INST](../advanced_config/parameter_reference.md#SYS_FAIL_RC_INST): the affected instance (1-based; `0` = all instances). + +While the selected aux switch is on the configured failure is injected; switching it back off clears the failure. The injection goes through the same path as the console/MAVLink commands, so for a motor it stops the motor exactly as `failure motor off` does (which also requires [CA_FAILURE_MODE](../advanced_config/parameter_reference.md#CA_FAILURE_MODE)). + ## MAVSDK 실패 플러그인 The [MAVSDK failure plugin](https://mavsdk.mavlink.io/main/en/cpp/api_reference/classmavsdk_1_1_failure.html) can be used to programmatically inject failures. @@ -100,3 +112,18 @@ To stop a motor mid-flight without the system anticipating it or excluding it fr # Turn it back on failure motor ok -i 1 ``` + +## Example: Battery + +To trigger the battery failsafe by reporting a depleted pack: + +1. Enable the [SYS_FAILURE_EN](../advanced_config/parameter_reference.md#SYS_FAILURE_EN) parameter. +2. Enter the following commands on the MAVLink console or SITL _pxh shell_: + + ```sh + # Report the battery as depleted (warning EMERGENCY) -> battery failsafe + failure battery off + + # Stop injecting the failure + failure battery ok + ``` diff --git a/docs/ko/dronecan/ark_cannode.md b/docs/ko/dronecan/ark_cannode.md index 92b582f93a..a5046302a4 100644 --- a/docs/ko/dronecan/ark_cannode.md +++ b/docs/ko/dronecan/ark_cannode.md @@ -85,7 +85,7 @@ On the ARK CANnode, you may need to configure the following parameters: | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. | ## LED 신호의 의미 diff --git a/docs/ko/dronecan/ark_flow.md b/docs/ko/dronecan/ark_flow.md index 5a9477f8f5..f0f558e5f7 100644 --- a/docs/ko/dronecan/ark_flow.md +++ b/docs/ko/dronecan/ark_flow.md @@ -112,7 +112,7 @@ On the ARK Flow, you may need to configure the following parameters: | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. | ## LED 신호의 의미 diff --git a/docs/ko/dronecan/ark_flow_mr.md b/docs/ko/dronecan/ark_flow_mr.md index 1dcf1e0e15..3bd65bd645 100644 --- a/docs/ko/dronecan/ark_flow_mr.md +++ b/docs/ko/dronecan/ark_flow_mr.md @@ -107,7 +107,7 @@ You may need to [configure the following parameters](../dronecan/index.md#qgc-ca | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. | ## LED 신호의 의미 diff --git a/docs/ko/dronecan/ark_gps.md b/docs/ko/dronecan/ark_gps.md index 3858413623..99533c0cab 100644 --- a/docs/ko/dronecan/ark_gps.md +++ b/docs/ko/dronecan/ark_gps.md @@ -99,7 +99,7 @@ You may need to [configure the following parameters](../dronecan/index.md#qgc-ca | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. Set to `1` if this is the last node on the CAN bus. | ## LED 신호의 의미 diff --git a/docs/ko/dronecan/ark_rtk_gps.md b/docs/ko/dronecan/ark_rtk_gps.md index 0f0cd997b1..a2b38b84de 100644 --- a/docs/ko/dronecan/ark_rtk_gps.md +++ b/docs/ko/dronecan/ark_rtk_gps.md @@ -94,7 +94,7 @@ You may need to [configure the following parameters](../dronecan/index.md#qgc-ca | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. Set to `1` if this is the last node on the CAN bus. | ### Setting Up Rover and Fixed Base diff --git a/docs/ko/dronecan/ark_rtk_gps_l1_l2.md b/docs/ko/dronecan/ark_rtk_gps_l1_l2.md index d2328bce5a..8b5f0643a6 100644 --- a/docs/ko/dronecan/ark_rtk_gps_l1_l2.md +++ b/docs/ko/dronecan/ark_rtk_gps_l1_l2.md @@ -93,7 +93,7 @@ You may need to [configure the following parameters](../dronecan/index.md#qgc-ca | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. Set to `1` if this is the last node on the CAN bus. | ### Setting Up Rover and Fixed Base diff --git a/docs/ko/dronecan/ark_x20_rtk_gps.md b/docs/ko/dronecan/ark_x20_rtk_gps.md index 30e357f484..1e3482139f 100644 --- a/docs/ko/dronecan/ark_x20_rtk_gps.md +++ b/docs/ko/dronecan/ark_x20_rtk_gps.md @@ -96,7 +96,7 @@ You may need to [configure the following parameters](../dronecan/index.md#qgc-ca | Parameter | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-127 to use a static node ID. | +| [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) | CAN node ID (0 for dynamic allocation). If set to 0 (default), dynamic node allocation is used. Set to 1-125 to use a static node ID. | | [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) | CAN built-in bus termination. Set to `1` if this is the last node on the CAN bus. | ### Setting Up Rover and Fixed Base diff --git a/docs/ko/dronecan/index.md b/docs/ko/dronecan/index.md index 8262b20f35..cf5c31cd17 100644 --- a/docs/ko/dronecan/index.md +++ b/docs/ko/dronecan/index.md @@ -109,7 +109,7 @@ The parameter is set to 1 by default. Devices running the [PX4 DroneCAN firmware](px4_cannode_fw.md) (such as [ARK CANnode](ark_cannode.md)) can use the [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) parameter to set a static node ID. -Set it to 0 (default) for dynamic allocation, or to a value between 1-127 to use a specific static node ID. +Set it to 0 (default) for dynamic allocation, or to a value between 1-125 to use a specific static node ID. ::: :::warning @@ -306,7 +306,7 @@ For example, the screenshot below shows the parameters for a CAN GPS with node i Common CANNODE parameters that you can configure include: -- [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID): Set a static node ID (1-127) or use 0 for dynamic allocation. See [PX4 DroneCAN Firmware > Static Node ID](px4_cannode_fw.md#static-node-id) for more information. +- [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID): Set a static node ID (1-125) or use 0 for dynamic allocation. See [PX4 DroneCAN Firmware > Static Node ID](px4_cannode_fw.md#static-node-id) for more information. - [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM): Enable CAN bus termination on the last node in the bus. ## Device Specific Setup @@ -334,31 +334,12 @@ On boot, PX4 scans both locations, reads the board ID from the _APDescriptor_ of The source file is then deleted. Any connected node whose running version does not match is then flashed over the CAN bus. -### Firmware Database - -A flat-file database at `/fs/microsd/ufw/FW.db` maps each board ID to the original firmware filename that was installed. -This may be queried by external tools to determine current firmware versions. - -Example entry: - -```txt -122.bin=122-1.17.63eeff1a.uavcan.bin -``` - -Entries are removed on boot if their corresponding firmware is not present. - ### Remote Update Remote updates can be made by uploading the corresponding bin files to `/fs/microsd/ufw_staging/`. PX4 will then update firmware on next boot. This approach enables efficient mass-update of binaries from archives (`.zip` or `.tar` that contains `.bin` files for the target CAN nodes). -Tools can: - -1. Read the PX4 firmware database to determine what firmware is present -2. Extract the more-recent versions of matching firmware to the staging directory - -PX4 does not provide such tools. :::info Auterion uses a form of this workflow to update CAN firmware to SkyNode based devices. @@ -372,7 +353,7 @@ The `upload_skynode.sh` script with multiple `--ext-fw` flags is used to bundle --ext-fw=build/auterion_canio_default/some_other_default.uavcan.bin ``` -Another tool then checks the firmware database and extracts just the relevant files to the PX4 firmware staging area. +Another tool then checks which files were already uploaded using a local database and extracts just the relevant files to the PX4 firmware staging area. ::: ## 문제 해결 diff --git a/docs/ko/dronecan/px4_cannode_fw.md b/docs/ko/dronecan/px4_cannode_fw.md index 3e29a57f5a..f6c62a4e80 100644 --- a/docs/ko/dronecan/px4_cannode_fw.md +++ b/docs/ko/dronecan/px4_cannode_fw.md @@ -29,7 +29,7 @@ However, you can configure a static node ID using the [CANNODE_NODE_ID](../advan To configure a static node ID: -1. Set [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) to a value between 1-127 using [QGroundControl](index.md#qgc-cannode-parameter-configuration) +1. Set [CANNODE_NODE_ID](../advanced_config/parameter_reference.md#CANNODE_NODE_ID) to a value between 1-125 using [QGroundControl](index.md#qgc-cannode-parameter-configuration) 2. Reboot the device To return to dynamic allocation, set `CANNODE_NODE_ID` back to 0. diff --git a/docs/ko/middleware/dds_topics.md b/docs/ko/middleware/dds_topics.md index 654b1fc6c1..75c585019e 100644 --- a/docs/ko/middleware/dds_topics.md +++ b/docs/ko/middleware/dds_topics.md @@ -131,6 +131,8 @@ See messages - [DebugKeyValue](../msg_docs/DebugKeyValue.md) - [DebugValue](../msg_docs/DebugValue.md) - [DebugVect](../msg_docs/DebugVect.md) +- [DetectAndAvoid](../msg_docs/DetectAndAvoid.md) +- [DetectAndAvoidMostUrgent](../msg_docs/DetectAndAvoidMostUrgent.md) - [DeviceInformation](../msg_docs/DeviceInformation.md) - [DifferentialPressure](../msg_docs/DifferentialPressure.md) - [DistanceSensorModeChangeRequest](../msg_docs/DistanceSensorModeChangeRequest.md) @@ -184,7 +186,6 @@ See messages - [GpioOut](../msg_docs/GpioOut.md) - [GpioRequest](../msg_docs/GpioRequest.md) - [GpsDump](../msg_docs/GpsDump.md) -- [GpsInjectData](../msg_docs/GpsInjectData.md) - [Gripper](../msg_docs/Gripper.md) - [HealthReport](../msg_docs/HealthReport.md) - [HeaterStatus](../msg_docs/HeaterStatus.md) @@ -254,6 +255,7 @@ See messages - [RoverRateStatus](../msg_docs/RoverRateStatus.md) - [RoverSpeedStatus](../msg_docs/RoverSpeedStatus.md) - [Rpm](../msg_docs/Rpm.md) +- [RtcmData](../msg_docs/RtcmData.md) - [RtlStatus](../msg_docs/RtlStatus.md) - [RtlTimeEstimate](../msg_docs/RtlTimeEstimate.md) - [SatelliteInfo](../msg_docs/SatelliteInfo.md) diff --git a/docs/ko/middleware/zenoh.md b/docs/ko/middleware/zenoh.md index e6fedee990..8e4c69bc0d 100644 --- a/docs/ko/middleware/zenoh.md +++ b/docs/ko/middleware/zenoh.md @@ -151,7 +151,7 @@ These are applied to all Zenoh publishers. If `CONFIG_ZENOH_PUB_OPTION_OVERRIDE=y`, individual publishers can override one or more global publisher options. Default configuration [dds_topics.yaml](../middleware/dds_topics.md) already provides overrides for several publishers. -Individual publisher options can be overriden through the mapping configuration shown in the next section +Individual publisher options can be overridden through the mapping configuration shown in the next section ### 4. Modifying Topic Mappings @@ -262,6 +262,5 @@ The PX4 ROS 2 Interface Library is not compatible with ROS 2 Humble and earlier, ERROR [zenoh] Could not create a subscriber for type *** ``` - When it happens, check if `src/modules/zenoh/Kconfig.topics` has unstaged changes. - If there are any it means that new uorb topics have been added and the previous build updated the `Kconfig.topics` file accordingly. - Please perform a clean build so that the new `Kconfig.topics` can be used. + This usually means the firmware was built with a different set of uORB topics than the peer expects. + The Zenoh topic catalog (`Kconfig.topics`) is generated automatically at configure time into the build directory, so performing a clean build picks up any newly added or changed topics. diff --git a/docs/ko/modules/modules_command.md b/docs/ko/modules/modules_command.md index 2babc8e28d..7b182ab4db 100644 --- a/docs/ko/modules/modules_command.md +++ b/docs/ko/modules/modules_command.md @@ -121,6 +121,7 @@ failure [arguments...] ok|off|... Specify failure type [-i ] sensor instance (0=all) default: 0 + [-m ] instance bitmask (bit i = instance i+1); overridden by -i ``` ## gpio diff --git a/docs/ko/modules/modules_controller.md b/docs/ko/modules/modules_controller.md index a7ae17560c..34140f6ff1 100644 --- a/docs/ko/modules/modules_controller.md +++ b/docs/ko/modules/modules_controller.md @@ -287,7 +287,7 @@ navigator [arguments...] fencefile load a geofence file from SD card, stored at etc/geofence.txt - fake_traffic publishes 24 fake transponder_report_s uORB messages + fake_traffic run synthetic DAA traffic; use 'navigator fake_traffic help' stop diff --git a/docs/ko/modules/modules_driver.md b/docs/ko/modules/modules_driver.md index fa9808ec49..197c2da217 100644 --- a/docs/ko/modules/modules_driver.md +++ b/docs/ko/modules/modules_driver.md @@ -358,7 +358,7 @@ Source: [drivers/gps](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers ### 설명 GPS driver module that handles the communication with the device and publishes the position via uORB. -It supports multiple protocols (device vendors) and by default automatically selects the correct one. +The available device protocols are selected at build time. The module supports a secondary GPS device, specified via `-e` parameter. The position will be published on the second uORB topic instance, but it's currently not used by the rest of the system (however the @@ -401,7 +401,8 @@ gps [arguments...] values: spi|uart, default: uart [-j ] secondary GPS interface values: spi|uart, default: uart - [-p ] GPS Protocol (default=auto select) + [-p ] GPS protocol (availability depends on build; default from + GPS_x_PROTOCOL) values: ubx|mtk|ash|eml|fem|nmea stop diff --git a/docs/ko/modules/modules_driver_camera.md b/docs/ko/modules/modules_driver_camera.md index 0df0f41a21..810d0332d4 100644 --- a/docs/ko/modules/modules_driver_camera.md +++ b/docs/ko/modules/modules_driver_camera.md @@ -11,7 +11,7 @@ Camera trigger driver. This module triggers cameras that are connected to the flight-controller outputs, or simple MAVLink cameras that implement the MAVLink trigger protocol. -The driver responds to the following MAVLink trigger commands being found in missions or recieved over MAVLink: +The driver responds to the following MAVLink trigger commands being found in missions or received over MAVLink: - `MAV_CMD_DO_TRIGGER_CONTROL` - `MAV_CMD_DO_DIGICAM_CONTROL` diff --git a/docs/ko/modules/modules_system.md b/docs/ko/modules/modules_system.md index 30011d9146..b5ac407b82 100644 --- a/docs/ko/modules/modules_system.md +++ b/docs/ko/modules/modules_system.md @@ -262,14 +262,21 @@ Source: [modules/failure_injection_manager](https://github.com/PX4/PX4-Autopilot ### 설명 -The failure injection manager is the single subscriber to `vehicle_command` for -`MAV_CMD_INJECT_FAILURE`. It maintains the set of currently active failures and -publishes the `failure_injection` topic, republishing only when the configuration -changes so that command spam cannot propagate to the consumers that apply the -failures. It also produces the central `vehicle_command_ack`. +Central module for handling failure injection. It collects failure requests, tracks +the set of active failures, and publishes them on the `failure_injection` topic for +the apply-sites to act on. -Failure injection is gated by the `SYS_FAILURE_EN` parameter, which the startup -script checks before starting this module. +Failures can be triggered through: + +- `MAV_CMD_INJECT_FAILURE` over MAVLink (e.g. from MAVSDK) +- the `failure` console command +- an RC switch: `SYS_FAIL_RC_SRC` selects the aux input, and `SYS_FAIL_RC_UNIT` / + `SYS_FAIL_RC_MODE` / `SYS_FAIL_RC_INST` define the failure applied while it is on + +Requires `SYS_FAILURE_EN` to be set; the startup script only starts this module when it is. + +Failures can be applied both in simulation and on real hardware, where the apply-sites are +compiled in alongside this module. ### Usage {#failure_injection_manager_usage} diff --git a/docs/ko/msg_docs/DetectAndAvoid.md b/docs/ko/msg_docs/DetectAndAvoid.md new file mode 100644 index 0000000000..e50a16f066 --- /dev/null +++ b/docs/ko/msg_docs/DetectAndAvoid.md @@ -0,0 +1,93 @@ +--- +pageClass: is-wide-page +--- + +# DetectAndAvoid (UORB message) + +Detect-and-avoid conflict assessment for one traffic aircraft. + +Detailed per-traffic output from navigator's `DetectAndAvoid` component. +A sample is published when an evaluated report indicates a conflict or updates +an aircraft already tracked as a conflict. New reports assessed at NONE are omitted. + +Unlike `detect_and_avoid_most_urgent`, this topic does not summarize the single +active conflict driving DAA actions or prearm checks. It reports the conflict level +and geometry for the specific traffic aircraft that was just evaluated. + +Published by: `navigator` (`DetectAndAvoid`) +Used by: logging and tests + +**TOPICS:** detect_and_avoid + +## Fields + +| 명칭 | 형식 | Unit [Frame] | Range/Enum | 설명 | +| ---------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | `uint64` | us | | Time since system start | +| unique_id | `uint64` | | | Encoded traffic identifier selected in priority order: ICAO address, ADS-B callsign, then reduced UAS ID tail bytes | +| unique_id_encoding | `uint8` | | | Namespace used to decode `unique_id` | +| conflict_level | `uint8` | | | Conflict level calculated for this traffic aircraft | +| aircraft_dist | `float32` | m | | Current 3D point-to-point range between ownship and the traffic aircraft | +| aircraft_dist_hor | `float32` | m [NED] | | Horizontal separation metric. In Crosstrack mode this is the signed crosstrack distance when available, otherwise direct horizontal range | +| aircraft_dist_vert | `float32` | m [NED] | | Vertical separation between ownship (the current vehicle) and the traffic aircraft | +| expected_min_dist_time | `float32` | s | | Conservative collision-time estimate from current 3D separation and the sum of ownship and traffic speed magnitudes | + +## Constants + +| 명칭 | 형식 | Value | 설명 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | ------------------------------------------------------------- | +| DAA_CONFLICT_LVL_NONE | `uint8` | 0 | | +| DAA_CONFLICT_LVL_LOW | `uint8` | 1 | | +| DAA_CONFLICT_LVL_MEDIUM | `uint8` | 2 | | +| DAA_CONFLICT_LVL_HIGH | `uint8` | 3 | | +| DAA_CONFLICT_LVL_CRITICAL | `uint8` | 4 | | +| UNIQUE_ID_ENCODING_ICAO | `uint8` | 0 | `unique_id` contains an ICAO address | +| UNIQUE_ID_ENCODING_ADSB_CALLSIGN | `uint8` | 1 | `unique_id` contains an ADS-B callsign packed into a `uint64` | +| UNIQUE_ID_ENCODING_UAS_ID | `uint8` | 2 | `unique_id` contains the reduced tail bytes of a UAS ID | +| ORB_QUEUE_LENGTH | `uint8` | 16 | | + +## Source Message + +[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/DetectAndAvoid.msg) + +:::details +Click here to see original file + +```c +# Detect-and-avoid conflict assessment for one traffic aircraft. +# +# Detailed per-traffic output from navigator's `DetectAndAvoid` component. +# A sample is published when an evaluated report indicates a conflict or updates +# an aircraft already tracked as a conflict. New reports assessed at NONE are omitted. +# +# Unlike `detect_and_avoid_most_urgent`, this topic does not summarize the single +# active conflict driving DAA actions or prearm checks. It reports the conflict level +# and geometry for the specific traffic aircraft that was just evaluated. +# +# Published by: `navigator` (`DetectAndAvoid`) +# Used by: logging and tests + +uint8 DAA_CONFLICT_LVL_NONE = 0 +uint8 DAA_CONFLICT_LVL_LOW = 1 +uint8 DAA_CONFLICT_LVL_MEDIUM = 2 +uint8 DAA_CONFLICT_LVL_HIGH = 3 +uint8 DAA_CONFLICT_LVL_CRITICAL = 4 + +uint8 UNIQUE_ID_ENCODING_ICAO = 0 # `unique_id` contains an ICAO address +uint8 UNIQUE_ID_ENCODING_ADSB_CALLSIGN = 1 # `unique_id` contains an ADS-B callsign packed into a `uint64` +uint8 UNIQUE_ID_ENCODING_UAS_ID = 2 # `unique_id` contains the reduced tail bytes of a UAS ID + +uint8 ORB_QUEUE_LENGTH = 16 + +uint64 timestamp # [us] Time since system start +uint64 unique_id # [-] Encoded traffic identifier selected in priority order: ICAO address, ADS-B callsign, then reduced UAS ID tail bytes +uint8 unique_id_encoding # [-] Namespace used to decode `unique_id` + +uint8 conflict_level # [-] Conflict level calculated for this traffic aircraft +float32 aircraft_dist # [m] Current 3D point-to-point range between ownship and the traffic aircraft +float32 aircraft_dist_hor # [m] [@frame NED] Horizontal separation metric. In Crosstrack mode this is the signed crosstrack distance when available, otherwise direct horizontal range +float32 aircraft_dist_vert # [m] [@frame NED] Vertical separation between ownship (the current vehicle) and the traffic aircraft +float32 expected_min_dist_time # [s] Conservative collision-time estimate from current 3D separation and the sum of ownship and traffic speed magnitudes +``` + +::: diff --git a/docs/ko/msg_docs/DetectAndAvoidMostUrgent.md b/docs/ko/msg_docs/DetectAndAvoidMostUrgent.md new file mode 100644 index 0000000000..924f501857 --- /dev/null +++ b/docs/ko/msg_docs/DetectAndAvoidMostUrgent.md @@ -0,0 +1,77 @@ +--- +pageClass: is-wide-page +--- + +# DetectAndAvoidMostUrgent (UORB message) + +Detect-and-avoid summary for the most urgent active conflict. + +Aggregated DAA status from navigator's `DetectAndAvoid` component. +It publishes the single active conflict that currently has the highest urgency +after the per-traffic conflict buffer has been updated. + +Unlike `detect_and_avoid`, this topic is not published for every processed +traffic report and does not include the detailed horizontal and vertical geometry. +It is the topic used for overall DAA status, automatic-action decisions, and +prearm checks. + +Published by: `navigator` (`DetectAndAvoid`) +Used by: `commander` DAA arming checks, logging, and tests + +**TOPICS:** detect_and_avoid_most_urgent + +## Fields + +| 명칭 | 형식 | Unit [Frame] | Range/Enum | 설명 | +| ----------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| timestamp | `uint64` | us | | Time since system start | +| unique_id | `uint64` | | | Encoded identifier of the current most urgent traffic aircraft, selected in priority order: ICAO address, ADS-B callsign, then reduced UAS ID tail bytes | +| unique_id_encoding | `uint8` | | | Namespace used to decode `unique_id` | +| has_action | `bool` | | | True if the configured DAA response for this most urgent conflict is stronger than Warn only | +| conflict_level | `uint8` | | | Conflict level of the current most urgent active conflict | +| aircraft_dist | `float32` | m | | Approximate 3D range to the most urgent traffic aircraft (9999 when empty) | + +## Constants + +| 명칭 | 형식 | Value | 설명 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | ------------------------------------------------------------- | +| UNIQUE_ID_ENCODING_ICAO | `uint8` | 0 | `unique_id` contains an ICAO address | +| UNIQUE_ID_ENCODING_ADSB_CALLSIGN | `uint8` | 1 | `unique_id` contains an ADS-B callsign packed into a `uint64` | +| UNIQUE_ID_ENCODING_UAS_ID | `uint8` | 2 | `unique_id` contains the reduced tail bytes of a UAS ID | + +## Source Message + +[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/DetectAndAvoidMostUrgent.msg) + +:::details +Click here to see original file + +```c +# Detect-and-avoid summary for the most urgent active conflict. +# +# Aggregated DAA status from navigator's `DetectAndAvoid` component. +# It publishes the single active conflict that currently has the highest urgency +# after the per-traffic conflict buffer has been updated. +# +# Unlike `detect_and_avoid`, this topic is not published for every processed +# traffic report and does not include the detailed horizontal and vertical geometry. +# It is the topic used for overall DAA status, automatic-action decisions, and +# prearm checks. +# +# Published by: `navigator` (`DetectAndAvoid`) +# Used by: `commander` DAA arming checks, logging, and tests + +uint8 UNIQUE_ID_ENCODING_ICAO = 0 # `unique_id` contains an ICAO address +uint8 UNIQUE_ID_ENCODING_ADSB_CALLSIGN = 1 # `unique_id` contains an ADS-B callsign packed into a `uint64` +uint8 UNIQUE_ID_ENCODING_UAS_ID = 2 # `unique_id` contains the reduced tail bytes of a UAS ID + +uint64 timestamp # [us] Time since system start +uint64 unique_id # [-] Encoded identifier of the current most urgent traffic aircraft, selected in priority order: ICAO address, ADS-B callsign, then reduced UAS ID tail bytes +uint8 unique_id_encoding # [-] Namespace used to decode `unique_id` + +bool has_action # [-] True if the configured DAA response for this most urgent conflict is stronger than Warn only +uint8 conflict_level # [-] Conflict level of the current most urgent active conflict +float32 aircraft_dist # [m] Approximate 3D range to the most urgent traffic aircraft (9999 when empty) +``` + +::: diff --git a/docs/ko/msg_docs/FailureInjection.md b/docs/ko/msg_docs/FailureInjection.md index 8bffaa8c23..83ed53430d 100644 --- a/docs/ko/msg_docs/FailureInjection.md +++ b/docs/ko/msg_docs/FailureInjection.md @@ -46,6 +46,7 @@ Used in field(s): [unit](#fld_unit) | FAILURE_UNIT_SYSTEM_AVOIDANCE | `uint8` | 103 | | | FAILURE_UNIT_SYSTEM_RC_SIGNAL | `uint8` | 104 | | | FAILURE_UNIT_SYSTEM_MAVLINK_SIGNAL | `uint8` | 105 | | +| FAILURE_UNIT_SYSTEM_ESC | `uint8` | 106 | | ### FAILURE_TYPE {#FAILURE_TYPE} @@ -107,6 +108,7 @@ uint8 FAILURE_UNIT_SYSTEM_SERVO = 102 uint8 FAILURE_UNIT_SYSTEM_AVOIDANCE = 103 uint8 FAILURE_UNIT_SYSTEM_RC_SIGNAL = 104 uint8 FAILURE_UNIT_SYSTEM_MAVLINK_SIGNAL = 105 +uint8 FAILURE_UNIT_SYSTEM_ESC = 106 uint16[4] instance_mask # Bit i targets instance (i+1); 0xFFFF = all instances diff --git a/docs/ko/msg_docs/HeaterStatus.md b/docs/ko/msg_docs/HeaterStatus.md index 246888c69b..13ca169e10 100644 --- a/docs/ko/msg_docs/HeaterStatus.md +++ b/docs/ko/msg_docs/HeaterStatus.md @@ -8,24 +8,25 @@ pageClass: is-wide-page ## Fields -| 명칭 | 형식 | Unit [Frame] | Range/Enum | 설명 | -| ------------------------------------------------------------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------- | ---------- | --------------------------------------------------------- | -| timestamp | `uint64` | | | time since system start (microseconds) | -| device_id | `uint32` | | | | -| heater_on | `bool` | | | | -| temperature_target_met | `bool` | | | | -| temperature_sensor | `float32` | | | | -| temperature_target | `float32` | | | | -| controller_period_usec | `uint32` | | | | -| controller_time_on_usec | `uint32` | | | | -| proportional_value | `float32` | | | | -| integrator_value | `float32` | | | | -| feed_forward_value | `float32` | | | | -| supply_voltage | `float32` | | | Supply voltage (V) | -| heater_current | `float32` | | | Heater current (A) | -| nominal_multiplier | `float32` | | | | -| mode | `uint8` | | | | -| temperature_source | `uint8` | | | | +| 명칭 | 형식 | Unit [Frame] | Range/Enum | 설명 | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------- | ---------- | --------------------------------------------------------- | +| timestamp | `uint64` | | | time since system start (microseconds) | +| device_id | `uint32` | | | | +| heater_on | `bool` | | | | +| temperature_target_met | `bool` | | | | +| temperature_activation_threshold_met | `bool` | | | | +| temperature_sensor | `float32` | | | | +| temperature_target | `float32` | | | | +| controller_period_usec | `uint32` | | | | +| controller_time_on_usec | `uint32` | | | | +| proportional_value | `float32` | | | | +| integrator_value | `float32` | | | | +| feed_forward_value | `float32` | | | | +| supply_voltage | `float32` | | | Supply voltage (V) | +| heater_current | `float32` | | | Heater current (A) | +| nominal_multiplier | `float32` | | | | +| mode | `uint8` | | | | +| temperature_source | `uint8` | | | | ## Constants @@ -50,6 +51,7 @@ uint32 device_id bool heater_on bool temperature_target_met +bool temperature_activation_threshold_met float32 temperature_sensor float32 temperature_target diff --git a/docs/ko/msg_docs/RtcmData.md b/docs/ko/msg_docs/RtcmData.md new file mode 100644 index 0000000000..bedf3206c3 --- /dev/null +++ b/docs/ko/msg_docs/RtcmData.md @@ -0,0 +1,77 @@ +--- +pageClass: is-wide-page +--- + +# RtcmData (UORB message) + +RTCM3 data exchanged with GNSS receivers. + +Published under two topic names that share this definition (see TOPICS below): + +rtcm_corrections - external fixed-base corrections fed into the vehicle (MAVLink +GPS_RTCM_DATA, UAVCAN RTCMStream, GPS drivers in dump mode). Multiple +sources are allowed, one uORB instance each; consumers select an instance +via their stale-link logic. + +rtcm_moving_baseline - moving-base GPS output (RTCM 4072 or equivalent) intended for a rover. +Single publisher per vehicle (on-board moving base, or a CANnode +forwarding MovingBaselineData); consumers only read instance 0. + +**TOPICS:** rtcm_corrections rtcm_moving_baseline + +## Fields + +| 명칭 | 형식 | Unit [Frame] | Range/Enum | 설명 | +| -------------------------------------------------------- | ------------ | ---------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | +| timestamp | `uint64` | us | | Time since system start | +| device_id | `uint32` | | | Unique device ID of the publisher that produced this RTCM | +| len | `uint16` | | | Length of data | +| flags | `uint8` | | | LSB: 1=fragmented | +| data | `uint8[300]` | | | Correction payload (fixed-base RTCM3 and/or SPARTN frames, or moving-baseline RTCM3) | + +## Constants + +| 명칭 | 형식 | Value | 설명 | +| ----------------------------------------------------------------------------------------- | ------- | ----- | -- | +| ORB_QUEUE_LENGTH | `uint8` | 16 | | +| MAX_INSTANCES | `uint8` | 4 | | + +## Source Message + +[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/RtcmData.msg) + +:::details +Click here to see original file + +```c +# RTCM3 data exchanged with GNSS receivers. +# +# Published under two topic names that share this definition (see TOPICS below): +# +# rtcm_corrections - external fixed-base corrections fed into the vehicle (MAVLink +# GPS_RTCM_DATA, UAVCAN RTCMStream, GPS drivers in dump mode). Multiple +# sources are allowed, one uORB instance each; consumers select an instance +# via their stale-link logic. +# +# rtcm_moving_baseline - moving-base GPS output (RTCM 4072 or equivalent) intended for a rover. +# Single publisher per vehicle (on-board moving base, or a CANnode +# forwarding MovingBaselineData); consumers only read instance 0. + +uint64 timestamp # [us] Time since system start + +uint32 device_id # [-] Unique device ID of the publisher that produced this RTCM + +uint16 len # [-] Length of data +uint8 flags # [-] LSB: 1=fragmented +uint8[300] data # Correction payload (fixed-base RTCM3 and/or SPARTN frames, or moving-baseline RTCM3) + +uint8 ORB_QUEUE_LENGTH = 16 + +# Sized for the fixed-base corrections case (up to four independent sources). The moving-baseline +# topic only uses instance 0 (single publisher per vehicle). +uint8 MAX_INSTANCES = 4 + +# TOPICS rtcm_corrections rtcm_moving_baseline +``` + +::: diff --git a/docs/ko/msg_docs/VehicleCommand.md b/docs/ko/msg_docs/VehicleCommand.md index e4425ede03..5492b1fcb7 100644 --- a/docs/ko/msg_docs/VehicleCommand.md +++ b/docs/ko/msg_docs/VehicleCommand.md @@ -1651,6 +1651,7 @@ Change heading/course. param1: heading type (0=course-over-ground, 1=heading). p | FAILURE_UNIT_SYSTEM_AVOIDANCE | `uint8` | 103 | | | FAILURE_UNIT_SYSTEM_RC_SIGNAL | `uint8` | 104 | | | FAILURE_UNIT_SYSTEM_MAVLINK_SIGNAL | `uint8` | 105 | | +| FAILURE_UNIT_SYSTEM_ESC | `uint8` | 106 | | | FAILURE_TYPE_OK | `uint8` | 0 | | | FAILURE_TYPE_OFF | `uint8` | 1 | | | FAILURE_TYPE_STUCK | `uint8` | 2 | | @@ -1854,6 +1855,7 @@ uint8 FAILURE_UNIT_SYSTEM_SERVO = 102 uint8 FAILURE_UNIT_SYSTEM_AVOIDANCE = 103 uint8 FAILURE_UNIT_SYSTEM_RC_SIGNAL = 104 uint8 FAILURE_UNIT_SYSTEM_MAVLINK_SIGNAL = 105 +uint8 FAILURE_UNIT_SYSTEM_ESC = 106 uint8 FAILURE_TYPE_OK = 0 uint8 FAILURE_TYPE_OFF = 1 diff --git a/docs/ko/msg_docs/index.md b/docs/ko/msg_docs/index.md index 400989db20..74a9cef26a 100644 --- a/docs/ko/msg_docs/index.md +++ b/docs/ko/msg_docs/index.md @@ -104,6 +104,8 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [DebugKeyValue](DebugKeyValue.md) - [DebugValue](DebugValue.md) - [DebugVect](DebugVect.md) +- [DetectAndAvoid](DetectAndAvoid.md) — Detect-and-avoid conflict assessment for one traffic aircraft. +- [DetectAndAvoidMostUrgent](DetectAndAvoidMostUrgent.md) — Detect-and-avoid summary for the most urgent active conflict. - [DeviceInformation](DeviceInformation.md) — Device information. - [DifferentialPressure](DifferentialPressure.md) — Differential-pressure (airspeed) sensor. - [DistanceSensor](DistanceSensor.md) — DISTANCE_SENSOR message data. @@ -159,7 +161,6 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [GpioOut](GpioOut.md) — GPIO mask and state. - [GpioRequest](GpioRequest.md) — Request GPIO mask to be read. - [GpsDump](GpsDump.md) — This message is used to dump the raw gps communication to the log. -- [GpsInjectData](GpsInjectData.md) - [Gripper](Gripper.md) — # Used to command an actuation in the gripper, which is mapped to a specific output in the control allocation module. - [HealthReport](HealthReport.md) - [HeaterStatus](HeaterStatus.md) @@ -237,6 +238,7 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [RoverSteeringSetpoint](RoverSteeringSetpoint.md) — Rover Steering setpoint. - [RoverThrottleSetpoint](RoverThrottleSetpoint.md) — Rover Throttle setpoint. - [Rpm](Rpm.md) +- [RtcmData](RtcmData.md) — RTCM3 data exchanged with GNSS receivers. - [RtlStatus](RtlStatus.md) - [RtlTimeEstimate](RtlTimeEstimate.md) - [SatelliteInfo](SatelliteInfo.md) diff --git a/docs/ko/peripherals/adsb_flarm.md b/docs/ko/peripherals/adsb_flarm.md index 16b5a352ab..474fb7aecc 100644 --- a/docs/ko/peripherals/adsb_flarm.md +++ b/docs/ko/peripherals/adsb_flarm.md @@ -1,12 +1,27 @@ # ADS-B/FLARM/UTM Receivers: Air Traffic Avoidance -PX4 supports simple air traffic avoidance in [missions](../flying/missions.md) using [ADS-B](https://en.wikipedia.org/wiki/Automatic_dependent_surveillance_%E2%80%93_broadcast), [FLARM](https://en.wikipedia.org/wiki/FLARM), or [UTM](https://www.faa.gov/uas/advanced_operations/traffic_management) transponders that use the standard MAVLink interfaces. +PX4 can monitor cooperative air traffic reported by [ADS-B](https://en.wikipedia.org/wiki/Automatic_dependent_surveillance_%E2%80%93_broadcast), [FLARM](https://en.wikipedia.org/wiki/FLARM), or [UTM](https://www.faa.gov/uas/advanced_operations/traffic_management) integrations. +When it detects a potential conflict, PX4 can warn the operator or request an action such as Hold, Return, Land, or Terminate. -If a potential collision is detected, PX4 can _warn_, immediately [land](../flight_modes_mc/land.md), or [return](../flight_modes_mc/return.md) (depending on the value of [NAV_TRAFF_AVOID](#NAV_TRAFF_AVOID)). +This page explains how to connect a supported receiver and configure traffic avoidance behavior. +It is most relevant for operations in shared airspace, particularly beyond visual line of sight (BVLOS), where the vehicle must maintain safe separation from manned aviation without an onboard pilot. + +:::info +PX4 can only assess _cooperative_ traffic: aircraft that actively broadcast their position via ADS-B, FLARM, UTM, or a compatible integration. +If your operation does not involve that kind of traffic data, this page is unlikely to apply. + +For details on conflict-detection logic, alert volumes, notifications, testing, and extension points, see [Detect and Avoid](../advanced_features/detect_and_avoid.md). +::: ## 지원 하드웨어 -PX4 traffic avoidance works with ADS-B or FLARM products that supply transponder data using the MAVLink [ADSB_VEHICLE](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE) message, and UTM products that supply transponder data using the MAVLink [UTM_GLOBAL_POSITION](https://mavlink.io/en/messages/common.html#UTM_GLOBAL_POSITION) message. +PX4 traffic avoidance works directly with ADS-B and FLARM products that send MAVLink [`ADSB_VEHICLE`](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE). +DAA consumes PX4's `transponder_report` topic, so other traffic sources can be supported by an adapter that publishes compatible reports. + +:::info +PX4 does not currently convert incoming MAVLink [`UTM_GLOBAL_POSITION`](https://mavlink.io/en/messages/common.html#UTM_GLOBAL_POSITION) messages into traffic reports. +A UTM integration therefore needs a separate `transponder_report` adapter. +::: It has been tested with the following devices: @@ -16,7 +31,7 @@ It has been tested with the following devices: ## 하드웨어 설정 Any of the devices can be connected to any free/unused serial port on the flight controller. -Most commonly they are connected to `TELEM2` (if this is not being use for some other purpose). +Most commonly they are connected to `TELEM2` (if this is not being used for some other purpose). ### PingRX Pro @@ -77,20 +92,97 @@ You will now find a new parameter called [SER_TEL2_BAUD](../advanced_config/para ### Configure Traffic Avoidance -Configure the action when there is a potential collision using the parameter below: +Traffic avoidance is included when the firmware is built with `CONFIG_NAVIGATOR_ADSB`. +The conflict model is also selected at build time: -| Parameter | 설명 | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [NAV_TRAFF_AVOID](../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID) | Enable traffic avoidance mode specify avoidance response. 0: Disable, 1: Warn only, 2: Return mode, 3: Land mode. | -| [NAV_TRAFF_A_HOR](../advanced_config/parameter_reference.md#NAV_TRAFF_A_HOR) | Horizontal radius of cylinder around the vehicle that defines its airspace (i.e. the airspace in the ground plane). | -| [NAV_TRAFF_A_VER](../advanced_config/parameter_reference.md#NAV_TRAFF_A_VER) | Vertical height above and below vehicle of the cylinder that defines its airspace (also see [NAV_TRAFF_A_HOR](#NAV_TRAFF_A_HOR)). | -| [NAV_TRAFF_COLL_T](../advanced_config/parameter_reference.md#NAV_TRAFF_COLL_T) | Collision time threshold. Avoidance will trigger if the estimated time until collision drops below this value (the estimated time is based on relative speed of traffic and UAV). | +- **Crosstrack mode** is used when `CONFIG_NAVIGATOR_ADSB_F3442` is disabled. + It raises one conflict level and action when the current vehicle is close to the traffic's predicted track, vertically close, and within a configured collision-time threshold. + This is the avoidance mode historically supported by PX4. +- **F3442 mode** is used when `CONFIG_NAVIGATOR_ADSB_F3442` is enabled. + It evaluates four alert tests derived from concepts in [ASTM F3442/F3442M-23](https://store.astm.org/f3442_f3442m-23.html) and supports a separate action for each result level. + +:::warning +The F3442 mode processes cooperative traffic only and implements selected alert concepts and thresholds. +It does not by itself establish compliance with ASTM F3442/F3442M-23, which applies to the complete DAA system and its compliance evidence. +The implementation references the 2023 edition and has not been evaluated against the later [ASTM F3442-25](https://store.astm.org/f3442-25.html) edition. +::: + +For the detailed behavior of each conflict model, see [Detect and Avoid > Conflict Standards](../advanced_features/detect_and_avoid.md#conflict-standards) and [Detect and Avoid > Automated Actions](../advanced_features/detect_and_avoid.md#automated-actions). + +#### Enable Avoidance + +Use [DAA_EN](../advanced_config/parameter_reference.md#DAA_EN) to enable or disable DAA at runtime. + +#### Crosstrack + +Use firmware built without `CONFIG_NAVIGATOR_ADSB_F3442` if you want the single-threshold traffic avoidance behavior. + +| Parameter | 설명 | +| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [NAV\_TRAFF\_AVOID][NAV_TRAFF_AVOID] | Action requested when the crosstrack threshold is breached. `0`: Disabled, `1`: Warn only, `2`: Return, `3`: Land, `4`: Hold, `5`: Terminate. | +| [NAV\_TRAFF\_A\_HOR][NAV_TRAFF_A_HOR] | Maximum absolute crosstrack distance from the projected traffic track. | +| [NAV\_TRAFF\_A\_VER][NAV_TRAFF_A_VER] | Maximum vertical separation from the traffic aircraft. | +| [NAV\_TRAFF\_COLL\_T][NAV_TRAFF_COLL_T] | Maximum conservative time-to-collision estimate. A conflict is raised only if the horizontal, vertical, and time conditions are all met. | + +[NAV_TRAFF_AVOID]: ../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID +[NAV_TRAFF_A_HOR]: ../advanced_config/parameter_reference.md#NAV_TRAFF_A_HOR +[NAV_TRAFF_A_VER]: ../advanced_config/parameter_reference.md#NAV_TRAFF_A_VER +[NAV_TRAFF_COLL_T]: ../advanced_config/parameter_reference.md#NAV_TRAFF_COLL_T + +#### F3442 + +Use firmware built with `CONFIG_NAVIGATOR_ADSB_F3442` for staged alerting based on selected ASTM F3442/F3442M-23 concepts. + +PX4 evaluates four conflict levels and maps each level to an action: + +| Parameter | 설명 | +| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [DAA\_LVL\_LOW\_ACT][DAA_LVL_LOW_ACT] | Action for the augmented well clear alert volume. | +| [DAA\_LVL\_MED\_ACT][DAA_LVL_MED_ACT] | Action for the augmented NMAC alert volume. | +| [DAA\_LVL\_HIGH\_ACT][DAA_LVL_HIGH_ACT] | Action for Loss of Well Clear (LoWC). | +| [DAA\_LVL\_CRIT\_ACT][DAA_LVL_CRIT_ACT] | Action for Near Mid-Air Collision (NMAC). | + +[DAA_LVL_LOW_ACT]: ../advanced_config/parameter_reference.md#DAA_LVL_LOW_ACT +[DAA_LVL_MED_ACT]: ../advanced_config/parameter_reference.md#DAA_LVL_MED_ACT +[DAA_LVL_HIGH_ACT]: ../advanced_config/parameter_reference.md#DAA_LVL_HIGH_ACT +[DAA_LVL_CRIT_ACT]: ../advanced_config/parameter_reference.md#DAA_LVL_CRIT_ACT + +F3442 mode evaluates four cylindrical alert tests in priority order. +A test is breached when both horizontal and vertical separation are inside its combined ownship (the current vehicle) plus traffic bounds. + +| 항목 | 매개변수 | 설명 | +| -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `CRITICAL` | [DAA\_LVL\_CRIT\_RAD][DAA_LVL_CRIT_RAD], [DAA\_LVL\_CRIT\_HGT][DAA_LVL_CRIT_HGT] | Per-aircraft NMAC base radius and vertical bound. | +| `HIGH` | [DAA\_LVL\_HIGH\_RAD][DAA_LVL_HIGH_RAD], [DAA\_LVL\_HIGH\_HGT][DAA_LVL_HIGH_HGT] | Per-aircraft Well Clear base radius and vertical bound. | +| `MEDIUM` | [DAA\_LVL\_MED\_TIME][DAA_LVL_MED_TIME] | Expands the NMAC base volume using aircraft speed and the configured time margin. | +| `LOW` | [DAA\_LVL\_LOW\_TIME][DAA_LVL_LOW_TIME] | Expands the Well Clear base volume using aircraft speed and the configured time margin. | +| Velocity input | [DAA\_EN\_DFLT\_VEL][DAA_EN_DFLT_VEL], [DAA\_DFLT\_VEL][DAA_DFLT_VEL] | Optional replacement for the reported traffic vertical speed. | + +[DAA_LVL_CRIT_RAD]: ../advanced_config/parameter_reference.md#DAA_LVL_CRIT_RAD +[DAA_LVL_CRIT_HGT]: ../advanced_config/parameter_reference.md#DAA_LVL_CRIT_HGT +[DAA_LVL_HIGH_RAD]: ../advanced_config/parameter_reference.md#DAA_LVL_HIGH_RAD +[DAA_LVL_HIGH_HGT]: ../advanced_config/parameter_reference.md#DAA_LVL_HIGH_HGT +[DAA_LVL_MED_TIME]: ../advanced_config/parameter_reference.md#DAA_LVL_MED_TIME +[DAA_LVL_LOW_TIME]: ../advanced_config/parameter_reference.md#DAA_LVL_LOW_TIME +[DAA_EN_DFLT_VEL]: ../advanced_config/parameter_reference.md#DAA_EN_DFLT_VEL +[DAA_DFLT_VEL]: ../advanced_config/parameter_reference.md#DAA_DFLT_VEL + +Changing an action parameter does not re-evaluate buffered conflicts immediately. +The new action is considered on a later change of the overall most-urgent conflict level, and automatic mode changes are only requested when that level increases. + +These parameters use the same action scale: +`0`: Disabled, `1`: Warn only, `2`: Return, `3`: Land, `4`: Hold, `5`: Terminate. + +Most users can start with the default F3442 volume parameters and tune them only if needed. +See [Detect and Avoid > F3442 Mode](../advanced_features/detect_and_avoid.md#f3442-mode), which also includes the zone-computation equations. ### Arming Check -PX4 can be configured to check for the presence of a traffic avoidance system (ADSB or FLARM transponder) before arming. +PX4 can be configured to check for the presence of a traffic avoidance system (for example an ADS-B or FLARM receiver) before arming. This ensures that a traffic avoidance system is connected and functioning before flight. +This check only verifies that a traffic source is present. It is separate from DAA rejecting arming because active traffic already requires an automatic action; that behavior is described in [Detect and Avoid > Arming, Preflight, and Ground Behavior](../advanced_features/detect_and_avoid.md#arming-preflight-and-ground-behavior). + The check is configured using the [COM_ARM_TRAFF](../advanced_config/parameter_reference.md#COM_ARM_TRAFF) parameter: | Value | 설명 | @@ -103,99 +195,9 @@ The check is configured using the [COM_ARM_TRAFF](../advanced_config/parameter_r When a traffic avoidance system is detected, the system tracks its presence with a 3-second timeout. If the system is lost or regained, corresponding events are logged ("Traffic avoidance system lost" / "Traffic avoidance system regained"). -## 구현 +## 시험 -### ADSB/FLARM - -PX4 listens for valid transponder reports during missions. - -If a valid transponder report is received, PX4 first uses the traffic transponder information to estimate whether the traffic heading and height indicates there will be an intersection with the airspace of the UAV. -The UAV airspace consists of a surrounding cylinder defined by the radius [NAV_TRAFF_A_HOR](#NAV_TRAFF_A_HOR) and height [NAV_TRAFF_A_VER](#NAV_TRAFF_A_VER), with the UAV at it's center. -The traffic detector then checks if the time until intersection with the UAV airspace is below the [NAV_TRAFF_COLL_T](#NAV_TRAFF_COLL_T) threshold based on the relative speed. -If the both checks are true, the [Traffic Avoidance Failsafe](../config/safety.md#traffic-avoidance-failsafe) action is started, and the vehicle will either warn, land, or return. - -The code can be found in `Navigator::check_traffic` ([/src/modules/navigator/navigator_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/navigator/navigator_main.cpp)). - -PX4 will also forward the transponder data to a GCS if this has been configured for the MAVLink instance (this is recommended). -The last 10 Digits of the GUID is displayed as Drone identification. - -### UTM - -PX4 listens for `UTM_GLOBAL_POSITION` MAVLink messages during missions. -When a valid message is received, its validity flags, position and heading are mapped into the same `transponder_report` UORB topic used for _ADS-B traffic avoidance_. - -The implementation is otherwise _exactly_ as described in the section above. - -:::info -[UTM_GLOBAL_POSITION](https://mavlink.io/en/messages/common.html#UTM_GLOBAL_POSITION) contains additional fields that are not provided by an ADSB transponder (see [ADSB_VEHICLE](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE)). -The current implementation simply drops the additional fields (including information about the vehicle's planned next waypoint). -::: - -## Testing/Simulated ADSB Traffic - -You can simulate ADS-B traffic for testing. -Note that this requires that you [Build PX4](../dev_setup/building_px4.md). - -:::info -Simulated ADS-B traffic can trigger real failsafe actions. -Use with care in real flight! -::: - -이 기능을 활성화하려면: - -1. Uncomment the code in `AdsbConflict::run_fake_traffic()`([AdsbConflict.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/adsb/AdsbConflict.cpp#L342C1-L342C1)). -2. Rebuild and run PX4. -3. Execute the [`navigator fake_traffic` command](../modules/modules_controller.md#navigator) in the [QGroundControl MAVLink Shell](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/mavlink_console.html) (or some other [PX4 Console or MAVLink shell](../debug/consoles.md), such as the PX4 simulator terminal). - -The code in `run_fake_traffic()` is then executed. -You should see ADS-B warnings in the Console/MAVLink shell, and QGC should also show an ADS-B traffic popup. - -By default `run_fake_traffic()` publishes a number of traffic messages (it calls [`AdsbConflict::fake_traffic()`](#fake-traffic-method) to emit each report). -These simulate ADS-B traffic where there may be a conflict, where there won't be a conflict, as well as spamming the traffic buffer. - -:::details -Information about the test methods - -The relevant methods are defined in [AdsbConflict.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/adsb/AdsbConflict.cpp#L342C1-L342C1). - -#### `run_fake_traffic()` method - -The `run_fake_traffic()` method is run when the `navigator fake_traffic` command is called. - -The method calls the `fake_traffic()` method to generate simulated transponder messages around the current vehicle position. -It passes in the current vehicle position, and information about the simulated traffic, such as callsign, distances, directions, altitude differences, velocities, and emitter types. - -The (commented out) code in `run_fake_traffic()` simulates a number of different scenarios, including conflicts and non-conflicts, as well as spamming the traffic buffer. - -#### `fake_traffic()` method - -`AdsbConflict::fake_traffic()` is called by the [`run_fake_traffic()`](#run-fake-traffic-method) to create individual ADS-B transponder reports. - -This takes several parameters, which specify the characteristics of the fake traffic: - -- `callsign`: Callsign of the fake transponder. -- `distance`: Horizontal distance to the fake vehicle from the current vehicle. -- `direction`: Direction in NED from this vehicle to the fake in radians. -- `traffic_heading`: Travel direction of the traffic in NED in radians. -- `altitude_diff`: Altitude difference of the fake traffic. Positive is up. -- `hor_velocity`: Horizontal velocity of fake traffic, in m/s. -- `ver_velocity`: Vertical velocity of fake traffic, in m/s. -- `emitter_type`: Type of fake vehicle, as an enumerated value. -- `icao_address`: ICAO address. -- `lat_uav`: Lat of this vehicle (used to position fake traffic around vehicle) -- `on_uav`: Lon of this vehicle (used to position fake traffic around vehicle) -- `alt_uav`: Altitude of the vehicle (as reference - used to position fake traffic around vehicle) - -The method creates a simulated transponder message near the vehicle, using following steps: - -- Calculates the latitude and longitude of the traffic based on the UAV's position, distance, and direction. -- Computes the new altitude by adding the altitude difference to the UAV's altitude. -- Populates a [TransponderReport](../msg_docs/TransponderReport.md) topic with the simulated traffic data. -- If the board supports a Universally Unique Identifier (UUID), the method retrieves the UUID using `board_get_px4_guid` and copies it to the `uas_id` field of the structure. - Otherwise, it generates a simulated GUID. -- Publishes the simulated traffic message using `orb_publish`. - -::: +To test your DAA configuration using simulated traffic, see [Detect and Avoid > Testing and Simulation](../advanced_features/detect_and_avoid.md#testing-and-simulation). @@ -203,5 +205,6 @@ The method creates a simulated transponder message near the vehicle, using follo ## 추가 정보 +- [Detect and Avoid](../advanced_features/detect_and_avoid.md) - [MAVLink Peripherals](../peripherals/mavlink_peripherals.md) - [Serial Port Configuration](../peripherals/serial_configuration.md) diff --git a/docs/ko/test_and_ci/integration_testing_mavsdk.md b/docs/ko/test_and_ci/integration_testing_mavsdk.md index e79003604c..6c7cad1503 100644 --- a/docs/ko/test_and_ci/integration_testing_mavsdk.md +++ b/docs/ko/test_and_ci/integration_testing_mavsdk.md @@ -45,10 +45,10 @@ The tests need the MAVSDK C++ library installed system-wide (e.g. in `/usr/lib` ## 모든 PX4 테스트 실행 -To run all SITL tests as defined in [sitl.json](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/configs/sitl.json), do: +To run all SITL tests using the SIH simulator as defined in [sih-sitl.json](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/configs/sih-sitl.json), do: ```sh -test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sitl.json --speed-factor 10 +test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sih-sitl.json --speed-factor 10 ``` This will list all the tests and then run them sequentially. @@ -87,10 +87,10 @@ options: ## 단일 테스트 실행 Run a single test by specifying the `model` and test `case` as command line options. -예를 들어, 임무에서 테일시터 비행을 테스트하려면, 다음을 실행합니다. +For example, to test a multicopter mission using the SIH simulator: ```sh -test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sitl.json --speed-factor 10 --model tailsitter --case 'Fly square Multicopter Missions including RTL' +test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sih-sitl.json --speed-factor 10 --model quadx --case 'Fly square Multicopter Missions including RTL' ``` The easiest way to find out the current set of models and their associated test cases is to run all PX4 tests [as shown above](#run-all-px4-tests) (note, you can then cancel the build if you wish to test just one).