Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-27 10:17:45 +08:00
Code Issues Actions 20 Packages Projects Releases Wiki Activity

Move PX4 Guide source into /docs (#24490)

Browse Source 
* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Hamish Willee
2025-03-13 16:08:27 +11:00
committed by GitHub
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/config_vtol/index.md
+11
View File
@@ -0,0 +1,11 @@
# 垂直起降（VTOL）配置
First perform the [Standard Configuration](../config/index.md).
As part of this you should calibrate the [Airspeed sensor](../config/airspeed.md) (optional, but highly recommended) and [assign a VTOL transition switch](../config/flight_mode.md#what-flight-modes-and-switches-should-i-set) to your RC controller.
Then perform VTOL-specific configuration and tuning:
- [QuadPlane Configuration](../config_vtol/vtol_quad_configuration.md)
- [Back-transition Tuning](../config_vtol/vtol_back_transition_tuning.md)
- [VTOL w/o Airspeed Sensor](../config_vtol/vtol_without_airspeed_sensor.md)
- [VTOL Weather Vane](../config_vtol/vtol_weathervane.md)
docs/zh/config_vtol/vtol_back_transition_tuning.md
+20
View File
@@ -0,0 +1,20 @@
# VTOL 后转换调参
When a VTOL performs a back-transition (transition from fixed-wing mode to multicopter) it needs to slow down before the multicopter can take proper control.
To help with braking, the controller will pitch up the vehicle if the current deceleration is below what is set in expected deceleration ([VT_B_DEC_MSS](../advanced_config/parameter_reference.md#VT_B_DEC_MSS)).
The response of this deceleration controller can be tuned through a `I` gain: [VT_B_DEC_I](../advanced_config/parameter_reference.md#VT_B_DEC_I).
Increasing the `I` will result in more aggressive pitch-up to achieve the configured deceleration setting.
The vehicle will consider the back-transition complete when the horizontal speed has reached multicopter cruise speed ([MPC_XY_CRUISE](../advanced_config/parameter_reference.md#MPC_XY_CRUISE)) or when the back-transition duration ([VT_B_TRANS_DUR](../advanced_config/parameter_reference.md#VT_B_TRANS_DUR)) has passed (whichever comes first).
## 设置期望的减速加速度
When flying missions that make use of a [VTOL_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_VTOL_LAND) waypoint, the autopilot will attempt to calculate the proper distance at which to initiate the back-transition. It does this by looking at the current velocity (comparable to ground speed) and the expected deceleration.
To get the vehicle to come out of back-transition very close to its landing point you can tune the expected deceleration ([VT_B_DEC_MSS](../advanced_config/parameter_reference.md#VT_B_DEC_MSS)) parameter.
Make sure you have a large enough back-transition duration to allow the vehicle to reach its intended position before this timeout kicks in.
## 后转换持续时间
Setting a high back-transition time ([VT_B_TRANS_DUR](../advanced_config/parameter_reference.md#VT_B_TRANS_DUR)) will give the vehicle more time to slow down.
During this period the VTOL will shut down its fixed-wing motor and slowly ramp up its MC motors while gliding.
The higher this time is set the longer the vehicle will glide in an attempt to slow down. The caveat of this behavior is that the vehicle will only control altitude and not position during this period, so some drift can occur.
docs/zh/config_vtol/vtol_quad_configuration.md
+145
View File
@@ -0,0 +1,145 @@
# Generic Standard VTOL (QuadPlane) Configuration & Tuning
This is the configuration documentation for a [Generic Standard VTOL](../airframes/airframe_reference.md#vtol_standard_vtol_generic_standard_vtol), also known as a "QuadPlane VTOL".
This is essentially a fixed-wing vehicle with the addition of quadcopter motors.
For airframe specific documentation and build instructions see [VTOL Framebuilds](../frames_vtol/index.md).
## Firmware & Basic Settings
1. Run _QGroundControl_
2. Flash the firmware for your current release or master (PX4 `main` branch build).
3. In the [Frame setup](../config/airframe.md) section select the appropriate VTOL airframe.
If your airframe is not listed select the [Generic Standard VTOL](../airframes/airframe_reference.md#vtol_standard_vtol_generic_standard_vtol) frame.
### 飞行模式/模式转换
You should assign a switch on your RC controller for switching between the multicopter- and fixed-wing modes.
:::info
While PX4 allows flight without an RC controller, you must have one when tuning/configuring up a new airframe.
:::
This is done in [Flight Mode](../config/flight_mode.md) configuration, where you [assign flight modes and other functions](../config/flight_mode.md#what-flight-modes-and-switches-should-i-set) to switches on your RC controller.
The switch can also be assigned using the parameter [RC_MAP_TRANS_SW](../advanced_config/parameter_reference.md#RC_MAP_TRANS_SW).
The switch in the off-position means that you are flying in multicopter mode.
### Multirotor / Fixed-wing Tuning
Before you attempt your first transition to fixed-wing flight you need to make absolutely sure that your VTOL is well tuned in multirotor mode.
One reason is this is the mode you will return to if something goes wrong with a transition and it could be it will be moving fairly quickly already.
If it isn’t well tuned bad things might happen.
If you have a runway available and the total weight isn’t too high you will also want to tune fixed-wing flight as well.
If not then you will be attempting this when it switches to fixed-wing mode.
If something goes wrong you need to be ready (and able) to switch back to multirotor mode.
Follow the respective tuning guides on how to tune multirotors and fixed-wings.
### 转换调参
While it might seem that you are dealing with a vehicle that can fly in two modes (multirotor for vertical takeoffs and landings and fixed-wing for forwards flight) there is an additional state you also need to tune: transition.
Getting your transition tuning right is important for obtaining a safe entry into fixed-wing mode, for example, if your airspeed is too slow when it transitions it might stall.
#### 过渡阶段油门
Parameter: [VT_F_TRANS_THR](../advanced_config/parameter_reference.md#VT_F_TRANS_THR)
Front transition throttle defines the target throttle for the pusher/puller motor during the front transition.
This must be set high enough to ensure that the transition airspeed is reached.
If your vehicle is equipped with an airspeed sensor then you can increase this parameter to make the front transition complete faster.
For your first transition you are better off setting the value higher than lower.
#### Forward Transition Pusher/Puller Slew Rate
Parameter: [VT_PSHER_SLEW](../advanced_config/parameter_reference.md#VT_PSHER_SLEW)
A forward transition refers to the transition from multirotor to fixed-wing mode.
The forward transition pusher/puller slew rate is the amount of time in seconds that should be spent ramping up the throttle to the target value (defined by `VT_F_TRANS_THR`).
A value of 0 will result in commanding the transition throttle value being set immediately.
By default the slew rate is set to 0.33, meaning that it will take 3s to ramp up to 100% throttle.
If you wish to make throttling-up smoother you can reduce this value.
Note that once the ramp up period ends throttle will be at its target setting and will remain there until (hopefully) the transition speed is reached.
#### 混合控制空速
Parameter: [VT_ARSP_BLEND](../advanced_config/parameter_reference.md#VT_ARSP_BLEND)
By default, as the airspeed gets close to the transition speed, multirotor attitude control will be reduced and fixed-wing control will start increasing continuously until the transition occurs.
Disable blending by setting this parameter to 0 which will keep full multirotor control and zero fixed-wing control until the transition occurs.
#### 转换空速
Parameter: [VT_ARSP_TRANS](../advanced_config/parameter_reference.md#VT_ARSP_TRANS)
This is the airspeed which, when reached, will trigger the transition out of multirotor mode into fixed-wing mode.
It is critical that you have properly calibrated your airspeed sensor.
It is also important that you pick an airspeed that is comfortably above your airframes stall speed (check `FW_AIRSPD_MIN`) as this is currently not checked.
### 过渡模式小提示
As already mentioned make sure you have a well tuned multirotor mode.
If during a transition something goes wrong you will switch back to this mode and it should be quite smooth.
Before you fly have a plan for what you will do in each of the three phases (multirotor, transition, fixed-wing) when you are in any of them and something goes wrong.
Battery levels: leave enough margin for a multirotor transition for landing at the end of your flight.
Don’t run your batteries too low as you will need more power in multirotor mode to land.
Be conservative.
#### 过渡模式：
Make sure you are at least 20 meters above ground and have enough room to complete a transition.
It could be that your VTOL will lose height when it switches to fixed-wing mode, especially if the airspeed isn’t high enough.
Transition into the wind, whenever possible otherwise it will travel further from you before it transitions.
Make sure the VTOL is in a stable hover before you start the transition.
#### Transition: Multirotor to Fixed-wing (Front-transition)
Start your transition.
It should transition within 50 – 100 meters.
If it doesn’t or it isn’t flying in a stable fashion abort the transition (see below) and land or hover back to the start position and land.
Try increasing the [transition throttle](#transition-throttle) (`VT_F_TRANS_THR`) value.
Also consider reducing the transition duration (`VT_F_TRANS_DUR`) if you are not using an airspeed sensor.
If you are using an airspeed sensor consider lowering the transition airspeed but stay well above the stall speed.
As soon as you notice the transition happen be ready to handle height loss which may include throttling up quickly.
:::warning
The following feature has been discussed but not implemented yet:
- Once the transition happens the multirotor motors will stop and the pusher/puller throttle will remain at the `VT_F_TRANS_THR` level until you move the throttle stick, assuming you are in manual mode.
:::
#### Transition: Fixed-wing to Multirotor (Back-transition)
When you transition back to multirotor mode bring your aircraft in on a straight level approach and reduce its speed, flip the transition switch and it will start the multirotor motors and stop the pusher/puller prop immediately and should result in a fairly smooth gliding transition.
Consider that the throttle value you have when you transition will command the amount of thrust your multirotor has at the moment of the switch.
Because the wing will still be flying you’ll find you have plenty of time to adjust your throttle to achieve/hold a hover.
For advanced tuning of the back-transition please refer to the [Back-transition Tuning Guide](vtol_back_transition_tuning.md)
#### 紧急切出过渡模式
It’s important to know what to expect when you revert a transition command _during_ a transition.
When transitioning from **multirotor to fixed-wing** (transition switch is on/fixed-wing) then reverting the switch back (off/multirotor position) _before_ the transition happens it will immediately return to multirotor mode.
When transitioning from **fixed-wing to multirotor** for this type of VTOL the switch is immediate so there isn’t really a backing out option here, unlike for tilt rotor VTOLs.
If you want it to go back into fixed-wing you will need to go through the full transition.
If it’s still travelling fast this should happen quickly.
### 技术支持
If you have any questions regarding your VTOL conversion or configuration please see [discuss.px4.io/c/px4/vtol](https://discuss.px4.io/c/px4/vtol).
docs/zh/config_vtol/vtol_weathervane.md
+41
View File
@@ -0,0 +1,41 @@
# VTOL Weather Vane Feature
The _weather vane_ feature automatically turns a VTOL vehicle to face its nose into the relative wind during hover flight.
This improves stability (reducing the chance that wind from the side will pick-up the wind-facing wing and flip the vehicle).
The feature is [enabled by default](#configuration) on VTOL hybrid vehicles flying in multicopter mode.
:::info
Weather vane functionality is not supported on pure multirotors.
:::
## Manual Mode Behaviour
The weather vane feature will only take effect in [Position mode](../flight_modes_mc/position.md) (not other manual MC modes).
The user can still use the yaw stick to demand a yaw rate even while the weather vane controller is trying to turn the nose of the vehicle into the wind.
The target yaw rate is the sum of weather vane yaw rate and user commanded yaw rate.
## Mission Mode Behaviour
In [Mission mode](../flight_modes_vtol/mission.md) the weather vane feature will always be active when the parameter is enabled.
Any yaw angle commanded in a mission will be ignored.
<a id="configuration"></a>
## 配置
This functionality is configured using the [WV\_\* parameters](../advanced_config/parameter_reference.md#WV_EN).
| 参数 | 描述 |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [WV_EN](../advanced_config/parameter_reference.md#WV_EN) | Enable weather vane. |
| [WV_ROLL_MIN](../advanced_config/parameter_reference.md#WV_ROLL_MIN) | Minimum roll angle setpoint for weathervane controller to demand a yaw-rate. |
| [WV_YRATE_MAX](../advanced_config/parameter_reference.md#WV_YRATE_MAX) | Maximum yawrate the weathervane controller is allowed to demand. |
## How Does it Work?
During hover flight the vehicle needs to overcome the drag exerted on it by the wind in order to hold its position.
The only way for it to achieve this is by tilting its thrust vector into the relative wind (it literally 'leans' against the wind).
By keeping track of the thrust vector one can estimate the wind direction.
A weathervane controller is used to command a yawrate that turns the vehicle nose into the estimated wind direction.
docs/zh/config_vtol/vtol_without_airspeed_sensor.md
+104
View File
@@ -0,0 +1,104 @@
# VTOL Without an Airspeed Sensor
<Badge type="warning" text="Experimental" />
:::warning
Support for VTOLs without an airspeed sensor is considered experimental and should only be attempted by experienced pilots.
The use of an airspeed sensor is recommended.
:::
Fixed-wing vehicles use [airspeed sensors](../sensor/airspeed.md) to determine the speed at which the airplane is moving through the air.
Depending on wind this could vary from groundspeed.
Every airplane has a minimum airspeed below which the airplane will stall.
In mild weather conditions and with settings significantly above stall speed a VTOL can operate without the use of an airspeed sensor.
This guide will outline the parameter settings required to bypass the airspeed sensor for VTOL planes.
:::info
Most settings described here should also be applicable to fixed-wing vehicles that are not VTOL, but this is currently untested.
Transition turning and quad-chute are VTOL-specific.
:::
## Preparation
Before attempting to eliminate an airspeed sensor you should first determine a safe throttle level.
Also the duration for a front transition needs to be known.
To do this you can either perform a reference flight with an airspeed sensor or fly the vehicle manually.
In both cases the reference flight should be performed in very low wind conditions.
The flight should be performed at a speed that would be sufficient to fly in high wind conditions and should consist of:
- Successful front transition
- A straight and level flight
- An aggressive turn
- A quick ascend to a higher altitude
## Examining the Log
After the reference flight download the log and use [FlightPlot](../log/flight_log_analysis.md#flightplot) (or another analysis tool) to examine the log.
Plot the altitude (`GPOS.Alt`), thrust (`ATC1.Thrust`), groundspeed (Expression: `sqrt(GPS.VelN\^2 + GPS.VelE\^2)`), pitch (`ATT.Pitch`) and roll (`AT.Roll`).
Examine the throttle level (thrust) when the vehicle is level (no or little pitch and roll), during the ascend (increasing altitude) and when the vehicle is banking (more roll).
The initial value to use as cruise speed should be the highest thrust applied during a roll or ascend, the thrust during level flight should be considered the minimum value if you decide to further tune down your speed.
Also take note of the time it took for a front transition to complete.
This will be used to set the minimum transition time.
For safety reasons you should add +- 30% to this time.
Finally take note of the groundspeed during cruise flight.
This can be used to tune your throttle setting after the first flight without an airspeed sensor.
## Setting the Parameters
To bypass the airspeed preflight check you need to set [SYS_HAS_NUM_ASPD](../advanced_config/parameter_reference.md#SYS_HAS_NUM_ASPD) to 0.
To prevent an installed airspeed sensor being used for feedback control set [FW_USE_AIRSPD](../advanced_config/parameter_reference.md#FW_USE_AIRSPD) to `False`.
This allows you to test the system's behavior in the airspeed-less setting while still having the actual airspeed reading available to check the safety margin to stall speed etc.
Set the trim throttle ([FW_THR_TRIM](../advanced_config/parameter_reference.md#FW_THR_TRIM)) to the percentage as determined from the log of the reference flight.
Note that QGC scales this from `1..100` and the thrust value from the log is scaled from `0..1`.
So a thrust of 0.65 should be entered as 65.
For safety reasons it is recommended to add +- 10% throttle to the determined value for testing a first flight.
Set the minimum front transition time ([VT_TRANS_MIN_TM](../advanced_config/parameter_reference.md#VT_TRANS_MIN_TM)) to the number of seconds determined from the reference flight and add +- 30% for safety.
### Optional Recommended Parameters
Because the risk of stalling is real, it is recommended to set the 'fixed-wing minimum altitude' (a.k.a. 'quad-chute') threshold ([VT_FW_MIN_ALT](../advanced_config/parameter_reference.md#VT_FW_MIN_ALT)).
This will cause the VTOL to transition back to multicopter mode and initiate the [Return mode](../flight_modes_vtol/return.md) below a certain altitude.
You could set this to 15 or 20 meters to give the multicopter time to recover from a stall.
The position estimator tested for this mode is EKF2, which is enabled by default (for more information see [Switching State Estimators](../advanced/switching_state_estimators.md#how-to-enable-different-estimators) and [EKF2_EN ](../advanced_config/parameter_reference.md#EKF2_EN)).
## First Flight Without Airspeed Sensor
The values apply to a position controlled flight (like [Hold mode](../flight_modes_fw/hold.md) or [Mission mode](../flight_modes_vtol/mission.md) or Mission mode).
It is therefore recommended that a mission is configured at a safe altitude, approximately 10m above the quad-chute threshold.
Like for the reference flight, this flight should be performed in very low wind conditions.
For the first flight the following is recommended:
- Stay at one altitude
- Set the waypoints wide enough and in such a fashion that no sharp turns are required
- Keep the mission small enough that it remains in sight should a manual override be required.
- If the airspeed is very high, consider performing a manual back transition by switching to Altitude mode.
If the mission finished successfully you should proceed to examine the log for the following:
- The groundspeed should be considerably above the groundspeed from the reference flight.
- The altitude should not have been significantly lower than the reference flight.
- The pitch angle should not have consistently been different from the reference flight.
If all these conditions have been met you can start to tune down the cruise throttle in small steps until the groundspeed matches that of the reference flight.
## Parameter Overview
The relevant parameters are:
- [FW_USE_AIRSPD](../advanced_config/parameter_reference.md#FW_USE_AIRSPD)
- [SYS_HAS_NUM_ASPD](../advanced_config/parameter_reference.md#SYS_HAS_NUM_ASPD)
- [EKF2_EN](../advanced_config/parameter_reference.md#EKF2_EN) (1), [ATT_EN](../advanced_config/parameter_reference.md#ATT_EN) (0), [LPE_EN](../advanced_config/parameter_reference.md#LPE_EN) (0)
- [FW_THR_TRIM](../advanced_config/parameter_reference.md#FW_THR_TRIM): determined (e.g. 70%)
- [VT_TRANS_MIN_TM](../advanced_config/parameter_reference.md#VT_TRANS_MIN_TM): determined (e.g. 10 seconds)
- [VT_FW_MIN_ALT](../advanced_config/parameter_reference.md#VT_FW_MIN_ALT): 15